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