> ## 3. Server Utility Library

> The server utility library, `ZSERVER.LIB`, contains the structures, functions, and constants to allow HTTP (Hypertext Transfer Protocol) and FTP (File Transfer Protocol) servers to share data and user authentication information while running concurrently.

> HTML form functionality is included in `ZSERVER.LIB`.

> ### 3.1 Data Structures for Zserver.lib

> There are several data structures in this library of interest to developers of HTTP or FTP servers.

> #### 3.1.1 ServerSpec Structure

> A file transfer server has access to a list of objects: files, functions and variables. This list is defined as a global array in `ZSERVER.LIB`.``

>     ServerSpec server_spec[SSPEC_MAXSPEC];

> Throughout this manual, this array will be called the TCP/IP servers' object list or sometimes the server spec list.

> #### 3.1.2 ServerAuth Structure

> `ZSERVER.LIB` also defines a global array that is a list of user name/password pairs.

>     ServerAuth server_auth[SAUTH_MAXUSERS];

> Throughout this manual, this array will be called the TCP/IP users list or sometimes just users list.

> #### 3.1.3 FormVar Structure

> An array of `FormVar` structures represent the variables in an HTML form. The developer will declare an array of these structures, with the size needed to hold all variables for a particular form. The `FormVar` structure contains:

> - A `server_spec` index that references the variable to be modified. This is the location of the form variable in the TCP/IP servers' object list.
> - An integrity-checking function pointer that ensures that the variables are set to valid values.
> - High and low values (for numerical types).
> - Length (for the string type, and for the maximum length of the string representations of values).
> - A Pointer to an array of values (for when the value must be one of a specific, and probably short, list).

> The developer can specify whether she wants the variable to be set through a text entry field or a pull-down menu, and if the variable should be considered read-only.

> This `FormVar` array is placed in a `ServerSpec` structure using the function `sspec_addform`. `ServerSpec` entries that represent variables will be added to the `FormVar` array using `sspec_addfv`. Properties (e.g., the integrity-checking properties) for these `FormVar` entries can be set with various other functions. Hence, there is a level of indirection between the variables in the forms and the actual variables themselves. This allows the same variable to be included in multiple forms with different ranges for each form, and perhaps be read-only in one form and modifiable in another.

> ### 3.2 Constants Used in Zserver.lib

> The constants in this section are values assigned to the fields of the structures `ServerSpec` and `ServerAuth`. They are used in the functions described in Section 3.4, some as function parameters and some as return values.

> #### 3.2.1 ServerSpec Type Field

> This field describes the objects in the TCP/IP servers' object list.

>     SSPEC_ERROR	 // Error condition
>     SSPEC_FILE	 // Data resides in a file
>     SSPEC_FSFILE	 // The data resides in a file system file
>     SSPEC_FORM	 // Set of modifiable variables
>     SSPEC_FUNCTION	 // Data is a function
>     SSPEC_ROOTFILE	 // Data resides in root memory
>     SSPEC_UNUSED	 // Indicates an unused entry
>     SSPEC_VARIABLE	 // Data is a variable (for HTTP)
>     SSPEC_XMEMFILE	 // Data resides in extended memory
>     SSPEC_ROOTVAR	 // Data is a variable in root memory
>     SSPEC_XMEMVAR	 // Data is a variable in xmem

> #### 3.2.2 ServerSpec Vartype Field

> If the object is a variable, then this field will tell you what type of variable it is:

>     INT8, INT16, INT32, PTR16, FLOAT32

> #### 3.2.3 Servermask field

> The type of server (HTTP and/or FTP) that has access to a particular data structure is determined by the servermask field. Both `ServerSpec` and `ServerAuth` have this field. It must be set when adding the structure to its array. The default is that no server has access. `servermask` can be one of the following, or any bitwise inclusive OR of these values:

>     SERVER_FTP
>     SERVER_HTTP
>     SERVER_USER        // for use with the flash file system.
>     SERVER_WRITABLE    // server will allow client(s) to write to its files.

> #### 3.2.4 Configuration Macros

> These constants define system limits on various data lengths and array sizes.

> #### SSPEC_MAXNAME

> Maximum length of strings in a `ServerSpec` structure entry. Default is 20.

> #### SSPEC_MAXSPEC

> Sets the maximum number of entries in the global array, `server_spec`. `HTTP_MAXRAMSPEC` (from `HTTP.LIB`) should override `SSPEC_MAXSPEC`. If you attempt to use both you may not get the desired results, therefore, the use of `HTTP_MAXRAMSPEC` should be deprecated. If both `HTTP_MAXRAMSPEC` and `SSPEC_MAXSPEC` are not defined, `SSPEC_MAXSPEC` defaults to 10.

> #### SSPEC_XMEMVARLEN

> Defines the size of the stack-allocated buffer used by `sspec_readvariable()` when reading a variable in xmem. It defaults to 20.

> #### SAUTH_MAXNAME

> Maximum length of strings in `ServerAuth` structure. Default is 20. Strings must include a null character, so with its default value of 20, strings in this structure may be at most 19 characters long

> #### SAUTH_MAXUSERS

> Maximum number of users for a TCP/IP users list. Default is 10.

> ### 3.3 HTML Forms

> Defining `FORM_ERROR_BUF` is required to use the HTML form functionality in `Zserver.lib`. The value assigned to this macro is the number of bytes to reserve in root memory for the buffer used for form processing. This buffer must be large enough to hold the name and value for each variable, plus four bytes for each variable.

> An array of type `FormVar` must be declared to hold information about the form variables. Be sure to allocate enough entries in the array to hold all of the variables that will go in the form. If more forms are needed, then more of these arrays can be allocated. Please see Section 4.3.4 on page 192 for an example program.

> ### 3.4 Function Reference

> The server utility API functions are described in this section. The functions give servers a consistent interface to files, variables and client information.

> ## sauth_adduser

>     int sauth_adduser(char* username, char* password, word servermask);

> ### Description

> Adds a user to the TCP/IP users list.

> ### Parameters

> #### username

> Name of the user.

> #### password

> Password of the user.

> #### servermask

> Bitmask representing valid servers (e.g. `SERVER_HTTP`, `SERVER_FTP`).

> ### Return value

> `-1`: Failure.
> ≥`0`: Success; index in TCP/IP users list (id passed to `sauth_getusername()`).

> ### Library

> ZSERVER.LIB

> ### See also

> sauth_authenticate, sauth_getwriteaccess, sauth_setwriteaccess, sauth_removeuser

> ## sauth_authenticate

>     int sauth_authenticate(char* username, char* password, word server);

> ### Description

> Authenticate a user.

> ### Parameters

> #### username

> Name of user.

> #### password

> Password for the user.

> #### server

> The server for which this function is authenticating (e.g. `SERVER_HTTP`, `SERVER_FTP`).

> ### Return value

> `-1`: Failure, user not valid.
> ≥`0`: Success, array index of the `ServerAuth` structure for authenticated user.

> ### Library

> ZSERVER.LIB

> ### See also

> sauth_adduser

> ## sauth_getuserid

>     int sauth_getuserid(char* username, word server);

> ### Description

> Gets the user index for a user.

> ### Parameters

> #### username

> User's name.

> #### server

> Server for which we are looking up.

> ### Return value

> ≥`0`: Success, index of user in the TCP/IP users list.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sauth_getusername

>     char* sauth_getusername(int uid);

> ### Description

> Gets a pointer to `username` from the `ServerAuth` structure.

> ### Parameters

> #### uid

> The user's id, i.e., the array index in the TCP/IP users list.

> ### Return value

> `NULL`: Failure.
> `!NULL`: Success, pointer to the `username` string.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getusername

> ## sauth_getwriteaccess

>     int sauth_getwriteaccess(int sauth);

> ### Description

> Checks whether or not a user has write access.

> ### Parameters

> #### sauth

> Index of the user in the TCP/IP users list.

> ### Return value

> `0`: User does not have write access.
> `1`: User has write access.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sauth_setwriteaccess

> ## sauth_removeuser

>     int sauth_removeuser(int userid);

> ### Description

> Remove the given user from the user list. IMPORTANT: Any associations of the given user with web pages should be changed. Otherwise, no one will have access to the unchanged web pages. Authentication can be turned off for a page with `sspec_setrealm(sspec, "")`.

> ### Parameters

> #### userid

> Index in TCP/IP users list.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sauth_adduser

> ## sauth_setpassword

>     int sauth_setpassword(int userid, char* password);

> ### Description

> Sets the password for a user.

> ### Parameters

> #### userid

> Index of user in TCP/IP users list.

> #### password

> User's new password

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sauth_setwriteaccess

>     int sauth_setwriteaccess(int sauth, int writeaccess);

> ### Description

> Sets the write accessibility of a user.

> ### Parameters

> #### sauth

> Index of the user in the TCP/IP users list.

> #### writeaccess

> Set to `1` to give write access, `0` to deny write access.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sauth_getwriteaccess

> ## sspec_addform

>     int sspec_addform(char* name, FormVar* form, int formsize, word servermask);

> ### Description

> Adds a form (set of modifiable variables) to the TCP/IP servers' object list. Make sure that `SSPEC_MAXSPEC` is large enough to hold this new entry`.` This function is currently only useful for the HTTP server.

> ### Parameters

> #### name

> Name of the new form.

> #### form

> Pointer to the form array. This is a user-defined array to hold information about form variables.

> #### formsize

> Size of the form array

> #### servermask

> Bitmask representing valid servers (currently only useful with `SERVER_HTTP`)

> ### Return value

> ≥`0`: Success; location of form in TCP/IP servers' object list.
> `-1`: Failed to add form.

> ### Library

> ZSERVER.LIB

> ### SEE ALSO

> sspec_addfsfile, sspec_addfunction, sspec_addrootfile, sspec_addvariable, sspec_addxmemvar, sspec_addxmemfile sspec_aliasspec, sspec_addfv

> ## sspec_addfsfile

>     int sspec_addfsfile(char* name, byte filenum, word servermask);

> ### Description

> Adds a file located in the file system to the TCP/IP servers' object list. Make sure that `SSPEC_MAXSPEC` is large enough to hold this new entry`.`

> ### Parameters

> #### name

> Name of the new file.

> #### filenum

> Number of the file in the file system.

> #### servermask

> Bitmask representing valid servers.

> ### Return value

> `-1`: Failure.
> ≥`0`: Success; location of file in TCP/IP servers' object list.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_addrootfile, sspec_addfunction, sspec_addvariable, sspec_addxmemfile, sspec_addform, sspec_aliasspec

> ## sspec_addfunction

>     int sspec_addfunction(char* name, void (*fptr)(), word servermask);

> ### Description

> Adds a function to the list of objects recognized by the server. Make sure that `SSPEC_MAXSPEC` is large enough to hold this new entry`.` This function is currently only useful for HTTP servers.

> ### Parameters

> #### name

> Name of the function.

> #### (*ftpr)()

> Pointer to the function.

> #### servermask

> Bitmask representing servers for which this function will be valid (currently only useful with `SERVER_HTTP`).

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, location of the function in the TCP/IP servers' object list.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_addform, sspec_addfsfile, sspec_addrootfile, sspec_addvariable, sspec_addxmemfile, sspec_aliasspec

> ## sspec_addfv

>     int sspec_addfv(int form, int var);

> ### Description

> Adds a variable to a form.

> ### Parameters

> #### form

> Index of the form in the TCP/IP servers' object list.

> #### var

> Index of the variable in the TCP/IP servers' object list.

> ### Return value

> `-1`: Failure.
> ≥`0`: Success; next available index into the `FormVar` array.

> ### Library

> ZSERVER.LIB

> ## sspec_addrootfile

>     int sspec_addrootfile(char* name, char* fileloc, int len, word servermask);

> ### Description

> Adds a file that is located in root memory to the TCP/IP servers' object list. Make sure that `SSPEC_MAXSPEC` is large enough to hold this new entry`.`

> ### Parameters

> #### name

> Name of the new file.

> #### fileloc

> Pointer to the beginning of the file.

> #### len

> Length of the file in bytes.

> #### servermask

> Bitmask representing servers for which this entry will be valid (e.g. `SERVER_HTTP`, `SERVER_FTP`).

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, location of the file in the TCP/IP servers' object list.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_addfsfile, sspec_addxmemfile, sspec_addvariable, sspec_addfunction sspec_addform, sspec_aliasspec

> ## sspec_addvariable

>     int sspec_addvariable(char* name, void* variable, word type, char* format, word servermask);

> ### Description

> Adds a variable to the TCP/IP servers' object list. Make sure that `SSPEC_MAXSPEC` is large enough to hold this new entry`.` This function is currently only useful for the HTTP server.

> ### Parameters

> #### name

> Name of the new variable.

> #### variable

> Address of actual variable.

> #### type

> Type of the variable (e.g., `INT8`, `INT16`, `PTR16`, etc.).

> #### format

> Output format of the variable.

> #### servermask

> Bitmask representing servers for which this function will be valid (currently only useful with `SERVER_HTTP`).

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, the location of the variable in the TCP/IP servers' object list.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_addfsfile, sspec_addrootfile, sspec_addxmemfile, sspec_addfunction sspec_addform, sspec_aliasspec

> ## sspec_addxmemfile

>     int sspec_addxmemfile(char* name, long fileloc, word servermask);

> ### Description

> Adds a file, located in extended memory, to the TCP/IP servers' object list. Make sure that `SSPEC_MAXSPEC` is large enough to hold this new entry`.`

> ### Parameters

> #### name

> Name of the new file.

> #### fileloc

> Location of the beginning of the file. The first 4 bytes of the file must represent the length of the file (`#ximport` does this automatically).

> #### servermask

> Bitmask representing servers for which this entry will be valid (e.g. `SERVER_HTTP`, `SERVER_FTP`).

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, the location of the file in the TCP/IP servers' object list.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_addfsfile, sspec_addrootfile, sspec_addvariable, sspec_addxmemvar, sspec_addfunction, sspec_addform, sspec_aliasspec

> ## sspec_addxmemvar

>     int sspec_addxmemvar(char* name, long variable, word type, char* format, word servermask);

> ### Description

> Add a variable located in extended memory to the TCP/IP servers' object list. Make sure that `SSPEC_MAXSPEC` is large enough to hold this new entry`.` Currently, this function is useful only for the HTTP server.

> ### Parameters

> #### name

> Name of the new variable.

> #### variable

> Address of the variable in extended memory.

> #### type

> Variable type (e.g., `INT8`, `INT16`, `PTR16`, etc.).

> #### format

> Output format of the variable.

> #### servermask

> Bitmask representing valid servers (currently only useful with `SERVER_HTTP`).

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, the location of the variable in the TCP/IP servers' object list.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_addfsfile, sspec_addrootfile, sspec_addvariable, sspec_addfunction, sspec_addform, sspec_addxmemfile, sspec_aliasspec

> ## sspec_aliasspec

>     int sspec_aliasspec(int sspec, char* name);

> ### Description

> Creates an alias to an existing object in the TCP/IP servers' object list. Make sure that `SSPEC_MAXSPEC` is large enough to hold this new entry`.` Please note, this is NOT a deep copy. That is, any file, variable, or form that the alias references will be the same copy of the file, variable, or form that already exists in the TCP/IP servers' object list. This should be called only when the original entry has been completely set up.

> ### Parameters

> #### sspec

> Location of the object in the TCP/IP servers' object list that will be aliased.

> #### name

> Name field of the `ServerSpec` structure that will be aliased.

> ### Return value

> `-1`: Failure.
> ≥`0`: Success; return location of alias, i.e., new index

> ### Library

> ZSERVER.LIB

> #### See also

> sspec_addform, sspec_addfsfile, sspec_addfunction, sspec_addrootfile, sspec_addvariable, sspec_addxmemfile

> ## sspec_checkaccess

>     int sspec_checkaccess(int sspec, int uid);

> ### Description

> This function checks whether or not the specified user has permission to access the specified object in the TCP/IP servers' object list.

> ### Parameters

> #### sspec

> Location of object in TCP/IP servers' object list.

> #### uid

> Location of the user in the TCP/IP users list.

> ### Return value

> `0`: User does not have access.
> `1`: User has access.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_needsauthentication

> ## sspec_findfv

>     int sspec_findfv(int form, char* varname);

> ### Description

> Finds the index in the array of type `FormVar` of a form variable in a given form.

> ### Parameters

> #### form

> Location of the form in the TCP/IP servers' object list.

> #### varname

> Name of the variable to find.

> ### Return value

> `-1`: Failure.
> ≥`0`: Success; the index of the form variable in the array of type `FormVar`.

> ### Library

> ZSERVER.LIB

> ## sspec_findname

>     int sspec_findname(char* name, word server);

> ### Description

> Finds the location of the object associated with `name` and returns the location (index into the `server_spec` array) of the object if the server is allowed access to it. (Access is determined by the `servermask` field in the `ServerSpec` structure for the object.)

> ### Parameters

> #### name

> Name to search for in the TCP/IP servers' object list.

> #### server

> The server making the request (e.g. `SERVER_HTTP`).

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, location of the object in the TCP/IP servers' object list.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_findnextfile

> ## sspec_findnextfile

>     int sspec_findnextfile(int start, word server);

> ### Description

> Finds the first `ServerSpec` structure in the array, at or following the structure indexed by `start,` that is associated with a file and that is accessible by the server.

> ### Parameters

> #### start

> The array index at which to begin the search.

> #### server

> The server making the request (e.g. `SERVER_HTTP`).

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, index of requested `ServerSpec` structure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_findname

> ## sspec_getfileloc

>     long sspec_getfileloc(int sspec);

> ### Description

> Gets the location in memory or in the file system of a file represented by a `ServerSpec` structure. Note that the location of the file is returned as a long; the return value should be cast to the appropriate type (`char*` for a root file, `FileNum` for the file system) by the user. `sspec_getfiletype()` can be used to find the file type.

> ### Parameters

> #### sspec

> Index into the array of `ServerSpec` structures.

> ### Return value

> ≥`0`: Success, location of the file.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getfiletype, sspec_getlength

> ## sspec_getfiletype

>     word sspec_getfiletype(int sspec);

> ### Description

> Gets the type of a file represented by a `ServerSpec` structure.

> ### Parameters

> #### sspec

> Index into the array of `ServerSpec` structures.

> ### Return value

> `SSPEC_ERROR`: Failure.
> `!=SSPEC_ERROR`: Success, the type of file.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getfileloc, sspec_gettype

> ## sspec_getformtitle

>     char* sspec_getformtitle(int form);

> ### Description

> Gets the title for an automatically generated form.

> ### Parameters

> #### form

> `server_spec` index of the form.

> ### Return value

> `NULL`: Failure.
> `!NULL`: Success, title string.

> ### Library

> ZSERVER.LIB

> ## sspec_getfunction

>     void* sspec_getfunction(int sspec);

> ### Description

> Accesses the array of `ServerSpec` structures to get a pointer to the requested function.

> ### Parameters

> #### sspec

> Index into the array of `ServerSpec` structures.

> ### Return value

> `NULL`: Failure.
> `!NULL`: Success, pointer to requested function.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_addfunction

> ## sspec_getfvdesc

>     char* sspec_getfvdesc(int form, int var);

> ### Description

> Gets the description of a variable that is displayed in the HTML form table.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> ### Return value

> `NULL`: Failure.
> `!NULL`: Success, description string.

> ### Library

> ZSERVER.LIB

> ## sspec_getfventrytype

>     int sspec_getfventrytype(int form, int var);

> ### Description

> Gets the type of form entry element that should be used for the given variable.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> ### Return value

> `-1`: Failure;
> Type of form entry element on success:
> `HTML_FORM_TEXT` is a text box.
> `HTML_FORM_PULLDOWN` is a pull-down menu.

> ### Library

> ZSERVER.LIB

> ## sspec_getfvlen

>     int sspec_getfvlen(int form, int var);

> ### Description

> Gets the length of a form variable (the maximum length of the string representation of the variable).

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> ### Return value

> `-1`: Failure.
> `>0`: Success, length of the variable.

> ### Library

> ZSERVER.LIB

> ## sspec_getfvname

>     char* sspec_getfvname(int form, int var);

> ### Description

> Gets the name of a variable that is displayed in the HTML form table.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index into the array of `FormVar` structures of the variable.

> ### Return value

> `NULL`: Failure.
> `!NULL`, name of the form variable.

> ### Library

> ZSERVER.LIB

> ## sspec_getfvnum

>     int sspec_getfvnum(int form);

> ### Description

> Gets the number of variables in a form.

> ### Parameters

> #### form

> `server_spec` index of the form.

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, number of form variables.

> ### Library

> ZSERVER.LIB

> ## sspec_getfvopt

>     char* sspec_getfvopt(int form, int var, int option);

> ### Description

> Gets the numbered option (starting from 0) of the form variable. This function is only valid if the form variable has the option list set.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index into the array of `FormVar` structures of the variable.

> #### option

> Index of the form variable option.

> ### Return value

> `NULL`: Failure.
> `!NULL`: Success, form variable option.

> ### Library

> ZSERVER.LIB

> ## sspec_getfvoptlistlen

>     int sspec_getfvoptlistlen(int form, int var);

> ### Description

> Gets the length of the options list of the form variable. This function is only valid if the form variable has the option list set.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> ### Return value

> `-1`: Failure.
> `>0`: Success, length of the options list.

> ### Library

> ZSERVER.LIB

> ## sspec_getfvreadonly

>     int sspec_getfvreadonly(int form, int var);

> ### Description

> Checks if a form variable is read-only.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> ### Return value

> `0`: Read-only.
> `1`: Not read-only.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_getfvspec

>     int sspec_getfvspec(int form, int var);

> ### Description

> Gets the `server_spec` index of a variable in a form.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index into the array of `FormVar` structures of the variable.

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, location of the form variable in the TCP/IP servers' object list.

> ### Library

> ZSERVER.LIB

> ## sspec_getlength

>     long sspec_getlength(int sspec);

> ### Description

> Gets the length of the file associated with the specified `ServerSpec` structure.

> ### Parameters

> #### sspec

> Location of file in TCP/IP servers' object list.

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, length of the file in bytes.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_readfile, sspec_getfileloc

> ## sspec_getname

>     char* sspec_getname(int sspec);

> ### Description

> Accesses the array of `ServerSpec` structures and returns a pointer to the object's name.

> ### Parameters

> #### sspec

> Location of object in TCP/IP servers' object list.

> ### Return value

> `NULL`: Failure.
> !`NULL`: Success, pointer to name string.

> ### Library

> ZSERVER.LIB

> ## sspec_getpreformfunction

>     void* sspec_getpreformfunction(int form);

> ### Description

> Gets the user function that will be called just before HTML form generation. This function is useful mainly for custom form generation functions.

> ### Parameters

> #### form

> spec index of the form

> ### Return value

> `NULL`: No user function.
> `!NULL`: Pointer to user function.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_setpreformfunction, sspec_setformfunction

> ## sspec_getrealm

>     char* sspec_getrealm(int sspec);

> ### Description

> Returns the realm for the object.

> ### Parameters

> #### sspec

> Location of the object in the TCP/IP servers' object list.

> ### Return value

> `NULL`: Failure.
> `!NULL`: Success, pointer to the realm string.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_setrealm

> ## sspec_gettype

>     word sspec_gettype(int sspec);

> ### Description

> Gets the `type` field of a `ServerSpec` structure.

> ### Parameters

> #### sspec

> Location of the object in the TCP/IP servers' object list.

> ### Return value

> `SSPEC_ERROR`: Failure.
> `type` field: Success (See Constants Used in Zserver.lib). For files and variables, it returns the generic type `SSPEC_FILE` or `SSPEC_VARIABLE`, respectively.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getfiletype, sspec_getvartype

> ## sspec_getusername

>     char* sspec_getusername(int sspec);

> ### Description

> Gets the username field of a `ServerAuth` structure.

> ### Parameters

> #### sspec

> Location of user in TCP/IP users list.

> ### Return value

> `NULL`: Failure.
> `!NULL`: Success, pointer to `username`.

> ### Library

> ZSERVER.LIB

> ### See also

> sauth_adduser, sspec_setuser

> ## sspec_getvaraddr

>     void* sspec_getvaraddr(int sspec);

> ### Description

> Returns a pointer to the requested variable in the TCP/IP servers' object list.

> ### Parameters

> #### sspec

> Location of the variable in the TCP/IP servers' object list.

> ### Return value

> `NULL`: Failure.
> `!NULL`: Success, pointer to variable.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_readvariable

> ## sspec_getvarkind

>     word sspec_getvarkind(int sspec);

> ### Description

> Returns the kind of variable represented by `sspec` (`INT8`, `INT16`, `INT32`, `FLOAT32`, or `PTR16`).

> ### Parameters

> #### sspec

> Location of the variable in the TCP/IP servers' object list.

> ### Return value

> `0`: Failure.
> `INT8|INT16|INT32|FLOAT32|PTR16`: Success.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getvaraddr, sspec_getvartype, sspec_gettype

> ## sspec_getvartype

>     word sspec_getvartype(int sspec);

> ### Description

> Gets the type of the variable in the TCP/IP servers' object list.

> ### Parameters

> #### sspec

> Location of the variable in the TCP/IP servers' object list.

> ### Return value

> `SSPEC_ERROR`: Failure.
> `SSPEC_ROOTVAR` or `SSPEC_XMEMVAR`: Success.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getvaraddr, sspec_getvarkind, sspec_gettype

> ## sspec_needsauthentication

>     int sspec_needsauthentication(int sspec);

> ### Description

> Checks if an object in the TCP/IP servers' object list needs user authentication to permit access. There is a field in the `ServerSpec` structure that is an index into the array of `ServerAuth` structures (list of valid users). If this field has a value, access to the object is limited to the one user specified.

> ### Parameters

> #### sspec

> Index into the array of `ServerSpec` structures.

> ### Return value

> `0`: Does not need authentication.
> `1`: Does need authentication.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getrealm

> ## sspec_readfile

>     int sspec_readfile(int sspec, char* buffer, long offset, int len);

> ### Description

> Read a file represented by the `sspec` index into `buffer`, starting at `offset`, and only copying `len``` bytes. For xmem files, this function automatically skips the first 4 bytes. Hence, an offset of 0 marks the beginning of the file contents, not the file length.

> ### Parameters

> #### sspec

> Index into the array of `ServerSpec` structures.

> #### buffer

> The buffer to put the file contents into.

> #### offset

> The offset from the start of the file, in bytes, at which copying should begin.

> #### len

> The number of bytes to copy.

> ### Return value

> `-1`: Failure.
> ≥`0`: Success, number of bytes copied.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getlength, sspec_getfileloc

> ## sspec_readvariable

>     int sspec_readvariable(int sspec, char* buffer);

> ### Description

> Formats the variable associated with the specified `ServerSpec` structure, and puts a `NULL`-terminated string representation of it in `buffer`. The macro `SSPEC_XMEMVARLEN` (default is 20) defines the size of the stack-allocated buffer when reading a variable in xmem.

> ### Parameters

> #### sspec

> Index into the array of `ServerSpec` structures.

> #### buffer

> The buffer in which to put the variable.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getvaraddr

> ## sspec_remove

>     int sspec_remove(int sspec);

> ### Description

> Removes an object from the TCP/IP servers' object list.

> ### Parameters

> #### sspec

> Index into the array of `ServerSpec` structures.

> ### Return value

> `0`: Success.
> `-1`: Failure (i.e. the index is already unused).

> ### Library

> ZSERVER.LIB

> ## sspec_restore

>     int sspec_restore(void);

> ### Description

> Restores the TCP/IP servers' object list and the TCP/IP users list (and some user-specified data if set up with `sspec_setsavedata()`) from the file system. This does not restore the actual files and variables, but only the structures that reference them. If the files are stored in flash, then the references will still be valid. Files in volatile RAM and variables must be rebuilt through other means.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_save, sspec_setsavedata

> ## sspec_save

>     int sspec_save(void);

> ### Description

> Saves the servers' object list and server authorization list (along with some user-specified data if set up with `sspec_setsavedata()`) to the file system. This does not save the actual files and variables, but only the structures that reference them. If the files are stored in flash, then the references will still be valid. Files in volatile RAM and variables must be rebuilt through other means.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_restore, sspec_setsavedata

> ## sspec_setformepilog

>     int sspec_setformepilog(int form, int function);

> ### Description

> Sets the user-specified function that will be called when the form has been successfully submitted. This function can, for example, execute a `cgi_redirectto` to redirect to a specific page. It should accept "HttpState* state" as an argument, return 0 when it is not finished, and 1 when it is finished (i.e., behave like a normal CGI function).

> ### Parameters

> #### form

> Index into the array of `ServerSpec` structures.

> #### function

> Index into the array of `ServerSpec` structures. This is the return value of the function `sspec_addfunction()`.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_addfunction

> ## sspec_setformfunction

>     int sspec_setformfunction(int form, void (*fptr)());

> ### Description

> Sets the function that will generate the form.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### fptr

> Form generation function (`NULL` for the default function).

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setformprolog

>     int sspec_setformprolog(int form, int function);

> ### Description

> Allows a user-specified function to be called just before form variables are updated. This is useful for implementing locking on the form variables (which can then be unlocked in the epilog function), so that other code will not update the variables during form processing. The user-specified function`` should accept "HttpState* state" as an argument, return 0 when it is not finished, and 1 when it is finished (i.e., behave like a normal CGI function).

> ### Parameters

> #### form

> Index into the array of `ServerSpec` structures.

> #### function

> Index into the array of `ServerSpec` structures. This is the return value of `sspec_addfunction()`.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_addfunction

> ## sspec_setformtitle

>     int sspec_setformtitle(int form, char* title);

> ### Description

> Sets the title for an automatically generated form.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### title

> Title of the HTML page.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setfvcheck

>     int sspec_setfvcheck(int form, int var, int (*varcheck)());

> ### Description

> Sets a function that can be used to check the integrity of a variable. The function should return 0 if there is no error, or !0 if there is an error.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> #### varcheck

> Pointer to integrity-checking function.

> ### Return value

> `>0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setfvdesc

>     int sspec_setfvdesc(int form, int var, char* desc);

> ### Description

> Sets the description of a variable that is displayed in the HTML form table.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> #### desc

> Description of the variable. This text will display on the html page.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setfventrytype

>     int sspec_setfventrytype(int form, int var, int entrytype);

> ### Description

> Sets the type of form entry element that should be used for the given variable.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> #### entrytype

> `HTML_FORM_TEXT` for a text box, `HTML_FORM_PULLDOWN` for a pull-down menu. The default is `HTML_FORM_TEXT`.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setfvfloatrange

>     int sspec_setfvfloatrange(int form, int var, float low, float high);

> ### Description

> Sets the range of a float.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> #### low

> Minimum value of the variable.

> #### high

> Maximum value of the variable.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setfvlen

>     int sspec_setfvlen(int form, int var, int len);

> ### Description

> Sets the length of a form variable (the maximum length of the string representation of the variable).

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> #### len

> Length of the variable.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setfvname

>     int sspec_setfvname(int form, int var, char* name);

> ### Description

> Sets the name of a variable that is displayed in the HTML form table.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> #### name

> Display name of the variable.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setfvoptlist

>     int sspec_setfvoptlist(int form, int var, char* list[], int listlen);

> ### Description

> Sets an enumerated list of possible values for a string variable.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> #### list[]

> Array of string values that the variable can assume.

> #### listlen

> Length of the array.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setfvrange

>     int sspec_setfvrange(int form, int var, long low, long high);

> ### Description

> Sets the range of an integer.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> #### low

> Minimum value of the variable.

> #### high

> Maximum value of the variable.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setfvreadonly

>     int sspec_setfvreadonly(int form, int var, int readonly);

> ### Description

> Sets the form variable to be read-only.

> ### Parameters

> #### form

> `server_spec` index of the form.

> #### var

> Index (into the `FormVar` array) of the variable.

> #### readonly

> `0``` for read/write (this is the default);
> `1` for read-only.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ## sspec_setpreformfunction

>     int sspec_setpreformfunction(int form, void (*fptr)());

> ### Description

> Sets a user function that will be called just before form generation. The user function is not called when the form is being generated because of errors in the form input. The user function must have the following prototype:

>     void userfunction(int form);

> The function may not use the parameter, but it is useful if the same user function is used for multiple forms.

> ### Parameters

> #### form

> Spec index of the form.

> #### fptr

> Pointer to user function to be called just before form generation

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getpreformfunction

> ## sspec_setrealm

>     int sspec_setrealm(int sspec, char* realm);

> ### Description

> Sets the realm field of a `ServerSpec` structure for HTTP authentication purposes. Setting this field enables authentication for the given entry in the TCP/IP servers' object list. Authentication can be turned off again by passing "" as the realm parameter to this function.

> ### Parameters

> #### sspec

> Index into the array of `ServerSpec` structures.

> #### realm

> Name of the realm.

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sspec_getrealm

> ## sspec_setsavedata

>     int sspec_setsavedata(char* data, unsigned long len, void* fptr);

> ### Description

> Sets user-supplied data that will be saved in addition to the spec and user authentication tables when `sspec_save()` is called.

> ### Parameters

> #### data

> Pointer to location of user-supplied data.

> #### len

> Length of the user-supplied data in bytes.

> #### fptr

> Pointer to a function that will be called when the user-supplied data has been restored

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> `sspec_save`, `sspec_restore`

> ## sspec_setuser

>     int sspec_setuser(int sspec, int uid);

> ### Description

> Sets the user (owner) of a `ServerSpec` structure.

> ### Parameters

> #### sspec

> Index into the array of `ServerSpec` structures.

> #### uid

> Index into the array of `ServerAuth` structures (identifies user).

> ### Return value

> `0`: Success.
> `-1`: Failure.

> ### Library

> ZSERVER.LIB

> ### See also

> sauth_adduser, sspec_getusername

Z-World http://www.zworld.com Voice: 530.757.3737 Fax: 530.757.3792 or 530.753.5141 sales@zworld.com