<< Previous | Index | Next >>

3. Server Utility Library

This chapter is intended to be a detailed description of the resource manager, Zserver, and how it interfaces to other libraries, such as servers (HTTP, FTP etc.) and filesystems (FS2, FAT). For an overview, please see Chapter 2. "Web-Enabling Your Application."

The resource manager, 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.

In general, you do not need to know some of the details of Zserver described in this chapter if you are using the server libraries provided with Dynamic C. Such sections are marked as "advanced," and you may skip them unless you are writing a server or filesystem. Some sections are marked "historical." They are included to describe how previous versions of the library worked. These may be skipped for new code.

The basic facility provided by Zserver is the ability to translate resource names (URLs in the case of HTTP) into references to filesystem and memory objects. The term resource refers to the objects (files, functions and variables) that are manipulated by the Zserver library on behalf of the server. A file resource refers specifically to a resource of type file, as opposed to the actual file that is manipulated by an underlying filesystem (which may not be a resource as such).

Support for HTML forms is also included in Zserver.lib. Starting with Dynamic C 8.50, an enhanced HTTP server (RabbitWeb) is available that has an easy-to-use interface for form generation and no limitations on the form layout. See Chapter 5 for more information on this enhanced HTTP server.

Zserver supports the concept of a virtual file system. This is modeled on the Unix directory structure.

3.1 Data Structures for Zserver.lib

There are several data structures in this library that servers with Zserver functionality must use, and may need to be manipulated or initialized by the application program:

Use of the following structures is considered advanced:

The following structures are documented for historical reasons:

3.1.1 MIMETypeMap Structure

This structure, organized into a table, associates a file extension with a MIME type (Multipurpose Internet Mail Extension) and a function that handles the MIME type. Users can override HTTP_MAXNAME (defaults to 20 characters) in their source file. If the function pointer given is NULL, then the default handler (which sends the content verbatim) is used. 


typedef struct {
   char extension[10];
   char type[HTTP_MAXNAME];
   int (*fptr)(/* HttpState* */);
} MIMETypeMap;

For example, to create an HTTP server that can serve files with html or gif extensions, the following declaration is required in the application code: 


SSPEC_MIMETABLE_START
  SSPEC_MIME(".html", "text/html"),
  SSPEC_MIME(".gif", "image/gif"),
SSPEC_MIMETABLE_END

Use of the above macros is the recommended method for maintaining forward compatibility. For more information, see Section 3.2.5.2 "Static MIME Type Table." All these macros are doing is generating the correct C syntax for a static constant initializer.

Note that servers that do not implement MIME, such as FTP, do not require a MIME table to be defined. Currently, this table is required only for HTTP.

3.1.2 ServerSpec Structure

This structure is used for both the static and dynamic resource tables. The only difference between these two tables is that one is a constant (initialized at compile-time) and the other is created at runtime in RAM, and thus modifiable.

Historical note: The HttpSpec data structure in HTTP.lib used prior to Dynamic C 8.50 is now synonymous with this structure, ServerSpec. 

typedef struct {
   word type;
   char name[SSPEC_MAXNAME];
   long data;
   void *addr;
   word vartype;
   char *format;
   ServerPermissions perm;


   #ifdef FORM_ERROR_BUF
   ...
   #endif
} ServerSpec;

The structure fields are described below. The #ifdef expression adds some fields to the ServerSpec structure if the HTML form functionality provided by Zserver is included by the web server application. These fields are not described below. For more details, Section 4.5.4 "HTML Forms Using Zserver.lib."

Starting with Dynamic C 8.50, enhanced support is provided for HTML forms with the Dynamic C RabbitWeb software. RabbitWeb provides an easy to develop web interface for your embedded device and allows for complete flexibility in form layout. See Chapter 5 for more information on this enhanced HTTP server.

In older versions of Dynamic C, it was necessary to explicitly create the static resource table by doing something like this: 


const HttpSpec http_flashspec[] = {
  ...
};

in your main application code (filling in the entries, of course). Starting with Dynamic C 8.50, there is new recommended syntax for creating these resources, using the SSPEC_RESOURCETABLE* series of macros. This new method is recommended for maintaining future compatibility. For more information, see Section 3.2.5.3 "Static Resource Table."

3.1.2.1 ServerSpec Fields

The fields in each resource table (static or dynamic) are usually manipulated via Zserver functions, or by using the SSPEC_RESOURCE* macros. The field descriptions below are for reference only.

type

This field tells the server if the entry is a file, variable or function (SSPEC_FILE, SSPEC_VARIABLE, SSPEC_FUNCTION, etc.).

name

This field contains the resource name, as a null-terminated string.

data

Location of data (when *FILE is the type of data), or maximum number of variables in a form (when SSPEC_FORM is the type of data)

addr

Address of function or variable (when SSPEC_FUNCTION, SSPEC_CGI or SSPEC_VARIABLE is the type of data). Address of form struct for SSPEC_FORM.

vartype

Type of variable (when SSPEC_VARIABLE is the type of data), or length of data (when *FILE is the type of data and the length is needed e.g., a root file). For SSPEC_HARDLINK, contains the sspec index number of a http_flashspec or server_spec entry.

format

sprintf() format for a variable, or form title for a form, or base address for SSPEC_ROOTFILE. For SSPEC_LINK, points to a string containing the linked-to resource name.

perm

Permissions associated with this resource. If realm subfield is NULL, then the permissions table is consulted as for filesystem resources. Note: this field used to be char* for the realm string (only). Programs that used this feature need to be modified. This structure is detailed under ServerPermissions.

There are some other fields that are conditionally included if HTTP forms are in use. These are not generally relevant. See the library source for details.

3.1.3 ServerAuth Structure

This structure defines a global array that is a list of user name/password pairs. 


ServerAuth server_auth[SAUTH_MAXUSERS];

Throughout this manual, this array is called the user table. The fields in the ServerAuth struct are manipulated using the sauth_*() functions. The description below is for reference only.

username

Name of user, or ""

password

Password, or ""

mask

Group mask

writeaccess

Which servers this user has write access to

servermask

Which servers this user is visible to

data

Arbitrary data (application-dependent)

3.1.4 ServerPermissions Structure

This data structure holds access permissions for a resource or a group of resources. An instance of ServerPermissions is contained in each ServerSpec structure, as well as within each rule table entry. The fields for the ServerPermissions struct are:

realm

Pointer to realm string of the resource. It is only used by HTTP servers, but can be used for other purposes.

readgroups

Read permission is granted if the current ServerAuth.mask value matches in at least one bit position.

writegroups

Write permissions is granted if the current ServerAuth.mask value matches in at least one bit position and ServerAuth.writeaccess is set.

servermask

A 16-bit mask with a bit set for each server that can access this resource. NB: for backwards compatibility, if this is set to zero then all servers are allowed.

method

Authentication method(s) allowed: combination of SERVER_AUTH_* bits. Note that Zserver.lib does not directly support anything other than basic authentication, that is SERVER_AUTH_BASIC; however, the required information is stored here so that servers can access it as needed in a consistent manner.

mimetype

MIME type for this resource, or NULL. If NULL, the MIME type will be derived from the file name using the MIMETypeMap table called http_types. If not found in that table, the first entry in that table will be used (for backward compatibility.)

Historical note: Prior to Dynamic C 8.50, HttpRealm was used in place of ServerPermissions. If you have used HttpRealm for password protection in existing code and are upgrading to Dynamic C 8.50 or later, you must rewrite any code that used this old structure. For an example of the new way to password protect an entity, see the sample program samples\tcpip\http\authentication.c.

3.1.5 RuleEntry Structure

This structure associates a resource name prefix with a ServerPermissions structure. The rule table is an array of these structures.

prefix

Prefix of resource name(s) which are associated with this rule table entry. If there are multiple entries which match a resource name, then the rule with the longest matching prefix is used.

perm

ServerPermissions to use for this entry.

3.1.6 ServerContext Structure

Starting with Dynamic C 8.50, context information must be maintained by each server that wants Zserver functionality. Therefore, servers must provide a ServerContext struct when required. The fields of ServerContext are:

userid

This field identifies the current user.

server

This field identifies the server, for example, SERVER_HTTP. This is one of the few cases where only a single server bit should be set.

rootdir

This field is a pointer to the root directory This is usually "/" if the whole namespace is to be accessible. Otherwise, it may be, for example, "/A" to restrict access to just the first DOS FAT partition. The first and last character must be "/"!

cwd[]

This field is an array containing the current working directory. This would normally contain the root directory as a prefix. The first and last character must be "/"!

dfltname

This field points to a file name to be used as a resource name suffix when the first parameter refers to a directory name.

The ServerContext structure helps support more powerful resource access control. It is needed by several of the new API functions that deal with resource retrieval and control, as well as functions that perform directory navigation.

There are two functions that return a ServerContext struct: http_getcontext() and http_getContext(). The latter is for use in CGI functions.

These functions can be used with other API functions that need the context structure. For example: 


sspec_open("MyFile", http_getcontext(servno), O_READ, 0);

will open "MyFile" for reading for the server instance identified by servno.

3.1.7 SSpecStat Structure

This structure holds status information about a file resource. It is filled in by the function sspec_stat().

The fields of SSpecStat are:

flags

A 16-bit mask that passes information about the file resource. The flags field can be any number of the following:

  • SSPEC_ATTR_MDTM - have modification date/time
  • SSPEC_ATTR_LENGTH - have current length
  • SSPEC_ATTR_WRITE - file is writable
  • SSPEC_ATTR_EXEC - file is "executable"
  • SSPEC_ATTR_HIDDEN - "Hidden" attribute bit
  • SSPEC_ATTR_SYSTEM - "System" attribute bit
  • SSPEC_ATTR_ARCHIVE - "Archive" attribute bit
  • SSPEC_ATTR_DIR - directory name
  • SSPEC_ATTR_COMPRESSED - stored in compressed format
  • SSPEC_ATTR_MAXLENGTH - have maximum length
  • SSPEC_ATTR_SEEKABLE - resource is randomly accessible
  • SSPEC_ATTR_EXTENSIBLE - File may be expanded at end

mdtm

Modification date/time (SEC_TIMER format), this field is only valid if SSPEC_ATTR_MDTM is set.

length

The current file size; this field is only valid if SSPEC_ATTR_LENGTH is set.

maxlength

The maximum allowable file size; this field is only valid if SSPEC_ATTR_MAXLENGTH is set.

perm

Pointer to ServerPermissions struct. This structure is described above.

3.1.8 sspec_fatinfo Structure

This structure is only relevant if you are using the FAT filesystem. It allows the sspec_automount() function to return some FAT-related information to your application. The fields in this structure are:

ctrl

Pointer to dos_ctrl (controller) structure.

drive

Pointer to mbr_drive structure.

part[4]

4 pointers to fat_part (partition) structures. Only the mounted partitions are returned.

Note that when used with sspec_automount(), some of the above fields may be set to non-NULL in order to indicate to sspec_automount() that the application has already initialized some or all of the FAT.

3.1.9 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:

The developer can specify whether the variable is 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 for these FormVar entries (for example, the integrity-checking properties) 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.1.10 SSpecFileHandle Structure

This structure is used internally by Zserver, and is only of interest to developers of new filesystems which may be incorporated into Zserver.

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.5, some as function parameters and some as return values.

3.2.1 ServerSpec Type Field

This field describes the resource in the server spec list. The possible values are:

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 ServerPermissions Servermask Field

The type of server (HTTP and/or FTP) that has access to a particular resource is determined by the servermask field in the ServerPermissions structure.

3.2.4 Configuration Macros

There are several configuration macros that may be set up by the application to control the memory usage and behavior of Zserver. These should be defined before #use Zserver.lib, unless otherwise noted.

HTTP_NO_FLASHSPEC
SSPEC_NO_STATIC

When defined, these macros saves space by not compiling in code that supports a static resource table. Presumably the application is using only the dynamic resource table, or filesystems are in use. Historical note: the name of HTTP_NO_FLASHSPEC implies HTTP, however it actually applies to Zserver as a whole, not any specific server. Dynamic C 8.50 introduces SSPEC_NO_STATIC, an alias for HTTP_NO_FLASHSPEC.
SAUTH_MAXNAME

Maximum length of the name and password strings in the 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

Define the maximum number of unique users. Defaults to 4. This determines the size of the userid table. Each table entry takes up 2*SAUTH_MAXNAME + 8 bytes of root storage.
SERVER_PASSWORD_ONLY

This is set to a bitmask of the server mask bits for each server that supports the concept of a password-only user, that is, no user name. Defaults to zero since currently no servers are implemented that use this facility.
SSPEC_DEFAULT_READGROUPS
SSPEC_DEFAULT_WRITEGROUPS
SSPEC_DEFAULT_SERVERMASK
SSPEC_DEFAULT_REALM
SSPEC_DEFAULT_METHOD

This group of macros establishes global default permissions for resources that do not have a rule associated. SSPEC_DEFAULT_READGROUPS is "0xFFFF" which means "all users." For writegroups, this is "0" meaning "no users." The servermask defaults to SERVER_ANY (all servers can access). realm defaults to "" that is, an empty string, or no realm. SSPEC_DEFAULT_METHOD defaults to no authentication method required.
SSPEC_MAX_FATDRIVES

Determine the maximum number of independent FAT filesystem "drives." Defaults to 1. Each drive takes 8 bytes of root storage (plus whatever is required by the filesystem itself). Each drive can have up to 4 partitions. This macro is only relevant if you use the FAT library.
SSPEC_MAXNAME

Define the maximum name length of each dynamic or static resource. Defaults to 20. You can minimize memory usage by choosing short names for all resources, and reducing the value of this macro.
SSPEC_MAXRULES

Define the maximum number of dynamically added "rules." Defaults to 10, but you can explicitly define it to zero if all the rule table entries are static (see SSPEC_RULETABLE_* macros). Each rule takes up 13 bytes of root storage, plus whatever storage is required for the realm and prefix strings (which must be null-terminated, and in static storage, since pointers to these are stored in the rule table).
SSPEC_MAXSPEC

Define to the number of dynamic (RAM) resource table entries to allocate for the global array, server_spec. Each entry takes SSPEC_MAXNAME + 23 bytes of root memory (or SSPEC_MAXNAME + 33 if FORM_ERROR_BUF is defined).

Defaults to 10 entries (approximately 530 bytes). Do not set higher than 511.
SSPEC_MAX_OPEN

Determine the maximum number of simultaneously open resources. Defaults to 4. Choose this number carefully, since each entry can take up a fairly large amount of root storage, depending on the mix of filesystems in use. Unless you are anticipating a very busy server, 4 should be enough.

If you increase the default value of HTTP_MAXSERVERS from 4, you may experience 404 or 503 messages. The solution is to increase SSPEC_MAX_OPEN. Ideally, this value should be HTTP_MAXSERVERS + FTP_MAXSERVERS + any special use of zserver.lib that you create.
SSPEC_XMEMVARLEN

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

3.2.5 Macros for Control Data Initialization

As of Dynamic C 8.50, the following macros are available for building the static tables used by the servers.

3.2.5.1 Static Rule Table

Resource rules are used to associate access information with resource names. The following macros define and initialize a static rule table. If using a static rule table, the dynamically added entries will be searched before the static ones.

SSPEC_FLASHRULES

Define this if your application is using static rules. You must define this if you want to use the macro SSPEC_RULETABLE_START. If you define SSPEC_FLASHRULES, and you do not need dynamic rules, you can define the macro SSPEC_MAXRULES to zero to recover the root memory that would be wasted otherwise.

SSPEC_RULETABLE_START
SSPEC_RULE(prefix, realm, rg, wg, sm)
SSPEC_MM_RULE(prefix, realm, rg, wg, sm, method, mimetype)
SSPEC_RULETABLE_END

This sequence of macros is used to define static rules. See the documentation with the sspec_addrule() function for more information. You must define SSPEC_FLASHRULES to use these macros.

3.2.5.2 Static MIME Type Table

This table maps file extensions and MIME types. You only need such a table if using a server that requires MIME types. Currently, only the HTTP server needs this.

SSPEC_MIMETABLE_START
SSPEC_MIME(extension, type)
SSPEC_MIME_FUNC(extension, type, function)
SSPEC_MIMETABLE_END

This sequence sets up the MIME type mapping table. Currently only a static MIME table is supported. Though you cannot dynamically add new MIME types to this table, it is possible to allocate new MIMETypeMap structures in RAM and assign them to specific resources using sspec_addrule() or sspec_setpermissions(). Such entries will not be accessed using the default resource name extension method.

3.2.5.3 Static Resource Table

The static resource table associates the names of web server resources (files, functions, and variables) to references to memory objects.

HTTP_NO_FLASHSPEC

Define if there is to be NO static resource table, that is, all resources are in the dynamic (RAM) table or in the filesystem(s). If you define this, then there is no point in using the SSPEC_RESOURCE_* series of macros below.
SSPEC_RESOURCETABLE_START
SSPEC_RESOURCE_ROOTFILE(name, addr, len)
SSPEC_RESOURCE_XMEMFILE(name, addr)
SSPEC_RESOURCE_ZMEMFILE(name, addr)
SSPEC_RESOURCE_FSFILE(name, fnum)
SSPEC_RESOURCE_ROOTVAR(name, addr, type, format)
SSPEC_RESOURCE_XMEMVAR(name, addr, type, format)
SSPEC_RESOURCE_FUNCTION(name, addr)
SSPEC_RESOURCE_CGI(name, addr)
SSPEC_RESOURCE_P_ROOTFILE(name, addr, len, realm, rg, wg, sm, meth)
SSPEC_RESOURCE_P_XMEMFILE(name, addr, realm, rg, wg, sm, meth)
SSPEC_RESOURCE_P_ZMEMFILE(name, addr, realm, rg, wg, sm, meth)
SSPEC_RESOURCE_P_FSFILE(name, fnum, realm, rg, wg, sm, meth)
SSPEC_RESOURCE_P_ROOTVAR(name, addr, type, format, realm, rg, wg, sm, meth)
SSPEC_RESOURCE_P_XMEMVAR(name, addr, type, format, realm, rg, wg, sm, meth)
SSPEC_RESOURCE_P_FUNCTION(name, addr, realm, rg, wg, sm, meth)
SSPEC_RESOURCE_P_CGI(name, addr, realm, rg, wg, sm, meth)
SSPEC_RESOURCETABLE_END

These macros are used to initialize the static resource table. Prior to Dynamic C 8.50 this had to be done by explicitly using C language initialization of a table declared as:

 

const HttpSpec http_spec[]

These macros perform the same function. It is recommended to use them instead of static initializers in order to maintain forward compatibility.

The macros with _P_ in the name are the same as the others, except that they explicitly allow all the server permissions information (except for the MIME type mapping) to be initialized. See sspec_addrule() for more information on the parameters.

The name parameter to all these macros is the resource name. This usually starts with a "/" for files, but not for variables. The string length should be less than or equal to SSPEC_MAXNAME.

The other parameters depend on the resource type being created:

ROOTFILE: addr = root memory address of first byte of file, len = length of file (0..32767).

XMEMFILE: addr = longword (physical address) of the length word of the file. The length word (4 bytes) is followed by the first byte of data.

ZMEMFILE: as for XMEMFILE, except the file is compressed and imported using #zimport instead of #ximport.

FSFILE: fnum = FS2 file number of file (1..255)

ROOTVAR: addr = root memory address of data, type = type of data, as documented with sspec_addvariable(), format = char * format, as used by printf(). For example, "%d" for a decimal number.

XMEMVAR: as for ROOTVAR except the address is a longword physical address.

FUNCTION or CGI: addr = address of C function.

Note that a maximum of 511 static resource table entries can be defined.

3.3 File Compression Support

Dynamic C 8.50 introduces file compression support. The sample program /samples/tcpip/http/zimport.c demonstrates how to use this functionality. This sample is oriented towards the HTTP server; however, under the covers, HTTP is relying on Zserver to perform the compressed file handling.

In the sample program, notice that the statement "#use zimport.lib" comes before the statement "#use http.lib" in the code. This is required to have file compression support in Zserver and the web server. The next thing to notice is the use of the compiler directive #zimport instead of #ximport. #zimport performs a standard #ximport, but compresses the file by invoking a compression utility before emitting the file to the target.

When adding a compressed file to the static resource table, use the macro SSPEC_RESOURCE_ZMEMFILE instead of SSPEC_RESOURCE_XMEMFILE. When you add a compressed file to the dynamic resource table using the sspec_addxmemfile() function, it will be recognized as a compressed file automatically. sspec_addxmemfile() is thus used for both compressed and uncompressed imported files.

Each instance of a server will use a buffer for decompression--this is necessary since multiple server instances can be decompressing files at the same time. Make sure that the buffer macro INPUT_COMPRESSION_BUFFERS is at least as large as the number of servers which may need concurrently to decompress a compressed resource. The buffer macro describes the number of 4KB xmem RAM buffers used for decompression. This definition is used by the zimport.lib library.

For details on compression ratios, memory usage and performance, please see Technical Note 234, "File Compression." For more information on using #zimport and the support libraries, please see the Dynamic C User's Manual and the Dynamic C Function Reference Manual.

All of these documents are available on our website: rabbit.com.

3.4 HTML Forms

This facility is oriented towards the HTTP server, however it is Zserver that actually handles the form data (as a special resource type in the dynamic resource table only).

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.5.4 on page 160 for an example program.

Starting with Dynamic C 8.50, a more flexible way of supporting form generation is available with RabbitWeb. See Chapter 5 for more information on this enhanced HTTP server.

3.5 API Functions

The resource manager API functions are described in this section. These functions give servers a consistent interface to files, variables and client information.

sauth_adduser
sauth_authenticate
sauth_getpassword
sauth_getserver
sauth_getuserid
sauth_getusermask
sauth_getusername
sauth_getwriteaccess
sauth_removeuser
sauth_setpassword
sauth_setserver
sauth_setusermask
sauth_setwriteaccess
sspec_access
sspec_addform
sspec_addfsfile
sspec_addfunction
sspec_addfv
sspec_addrootfile
sspec_addrule
sspec_adduser
sspec_addvariable
sspec_addxmemfile
sspec_addxmemvar
sspec_aliasspec
sspec_automount
sspec_cd
sspec_checkaccess
sspec_checkpermissions
sspec_close
sspec_delete
sspec_dirlist
sspec_fatregister
sspec_fatregistered

sspec_findfv
sspec_findname
sspec_findfsname
sspec_findnextfile
sspec_getfileloc
sspec_getfiletype
sspec_getformtitle
sspec_getfunction
sspec_getfvdesc
sspec_getfventrytype
sspec_getfvlen
sspec_getfvname
sspec_getfvnum
sspec_getfvopt
sspec_getfvoptlistlen
sspec_getfvreadonly
sspec_getfvspec
sspec_getlength
sspec_getMIMEtype
sspec_getname
sspec_getpermissions
sspec_getpreformfunction
sspec_getrealm
sspec_getservermask
sspec_gettype
sspec_getuserid
sspec_getusername
sspec_getvaraddr
sspec_getvarkind
sspec_getvartype
sspec_getxvaraddr
sspec_mkdir
sspec_needsauthentication
sspec_open

sspec_pwd
sspec_read
sspec_readfile
sspec_readvariable
sspec_remove
sspec_removerule
sspec_removeuser
sspec_resizerootfile
sspec_restore
sspec_rmdir
sspec_save
sspec_seek
sspec_setformepilog
sspec_setformfunction
sspec_setformprolog
sspec_setformtitle
sspec_setfvcheck
sspec_setfvdesc
sspec_setfventrytype
sspec_setfvfloatrange
sspec_setfvlen
sspec_setfvname
sspec_setfvoptlist
sspec_setfvrange
sspec_setfvreadonly
sspec_setpermissions
sspec_setpreformfunction
sspec_setrealm
sspec_setsavedata
sspec_setuser
sspec_stat
sspec_tell
sspec_write


sauth_adduser

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

Description

This function adds a user to the user table. It fills in the fields of the ServerAuth structure associated with this user. Three of the fields are specified by the parameters passed into the function. Two other fields, one for the user group mask and the other for the write access mask, are given default values.

The default for the user group mask is the assigned index number (0 to SAUTH_MAXNAME-1) as a bit number; that is, 1<<index. This effectively creates each user in a unique (single) group. Since this does not offer any real control over the assigned group mask, it is recommended to use sauth_setusermask() after this to assign the correct access masks.

The default for the write access mask is the user has no write access to any server. To assign this permission, call the function sauth_setwriteaccess() with the user table index returned by sauth_adduser().

Parameters

username
Name of the user, a character string up to SAUTH_MAXNAME characters.

password
Password for the user, another character string up to SAUTH_MAXNAME characters.

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

Return value

-1: Failure.
≥0: Success; index into user table (id passed to sauth_getusername()).

See also

sauth_authenticate, sauth_getwriteaccess, sauth_setusermask, sauth_setwriteaccess, sauth_removeuser

sauth_authenticate

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

Description

Authenticate user and return the user index representing the authenticated user, that is, the user table index. This performs only a plaintext comparison of the userid and password. Servers probably will have their own, more sophisticated, checks.

If username is NULL, or empty string, then password-only matching is attempted for servers who allow this type of authentication (as defined by the SERVER_PASSWORD_ONLY macro).

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 or user not authorized.
≥0: Success, array index of the ServerAuth structure for authenticated user.

See also

sauth_adduser

sauth_getpassword

sauth_getpassword( int userid );

Description

Get the password for a user.

Parameter

userid
user index

Return Value

!=NULL: password string
  NULL: Failure

See Also

sauth_setpassword

sauth_getserver

int sauth_getserver( int sauth );

Description

Returns whether or not a user is visible to particular server(s).

Parameter

sauth
user index

Return Value

 0: This user is visible to all servers
>0: Visible to select servers. One bit is set for each server that knows about this user.
-1: Failure; for example, sauth is an invalid index into the user table.

See also

sauth_setserver

sauth_getuserid

int sauth_getuserid( char *username, word server );

Description

Gets the user index for a user.

Parameters

username
User's name. If this name is not found, then the list is re-scanned looking for an entry with an empty user name ("") and a password that matches username. The second pass is only done for servers that allow password-only matching. Such servers must be specified by defining a symbol SERVER_PASSWORD_ONLY to be a bitmask of such servers.

server
Server(s) for which we are looking up. Use SERVER_ANY if not concerned with the server mask.

Return value

≥0: Success, index of user in the user table.
-1: Failure.

sauth_getusermask

int sauth_getusermask(int userid, word *groupbits, void **authdata);

Description

Get the group access bit(s) and/or authorization data for a given user ID.

Parameters

userid
User index

groupbits
Pointer to bitmask that will be set to group(s) of which this user is a member. If NULL, this information is not retrieved.

authdata
Pointer to void* that is set to arbitrary server data. If NULL, this information is not retrieved.

Return Value

0: OK
-1: Failed: userid not valid.

sauth_getusername

char *sauth_getusername( int userid );

Description

Returns the name of the user, a character string from the ServerAuth structure associated with userid.

Parameters

userid
The user's id, that is, the index into the user table.

Return value

 NULL: Failure.
!NULL: Success, pointer to the user's name string.

See also

sspec_getusername

sauth_getwriteaccess

int sauth_getwriteaccess( int sauth );

Description

Checks whether or not a user has write access to any server's resources. This is an "in principle" test. Each resource is individually protected from write access: this is not checked. In other words, this function may return TRUE even when none of the resources are writable to this user.

Parameters

sauth
Index into the user table.

Return value

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

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 user table.

Return value

 0: Success.
-1: Failure.

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 user table.

password
User's new password.

Return value

 0: Success.
-1: Failure.

See Also

sauth_getpassword

sauth_setserver

int sauth_setserver( int sauth, int server );

Description

Sets whether a user is visible to the specified server(s).

Parameters

sauth
User index

server
Server bitmask, with bit set to 1 to make this user "known" to the server. If this parameter is zero, then the user is visible to ALL servers, however it is recommended to pass the value SERVER_ANY in this case.

Return Value

 0: Success
-1: Failure

See also

sauth_getserver

sauth_setusermask

int sauth_setusermask( int userid, word userid, void * authdata );

Description

Set the group access bit(s) and authorization data for a given user ID.

Parameters

userid
User index

userid
Bitmask of group(s) of which this user is a member. This should be non-zero, otherwise the user will not have access to any resources.

authdata
Arbitrary data that can be used by specific servers.

Return Value

 0: OK
-1: Failed: userid not valid.

sauth_setwriteaccess

int sauth_setwriteaccess( int sauth, int writeaccess );

Description

Set whether or not a user has write access with the specified server(s).

Parameters

sauth
Index of the user in the user table.

writeaccess
Server bitmask, with bit set to 1 for write access, 0 for no write access. This is a bitwise OR of the server macros, SERVER_HTTP, etc., that you want the user to have write access to.

Return value

 0: Success.
-1: Failure.

See also

sauth_getwriteaccess

sspec_access

int sspec_access( char * name, ServerContext * context );

Description

Test access to a given resource by a specified user. The userid is set in
context->userid, or -1 for testing access by the server in general.
NOTE sspec_checkpermissions() performs a similar function, except on a resource handle rather than a resource name.

Parameters

name
Resource name, as a null-terminated string. This name is assumed to be relative to context->cwd if it does not begin with a "/" character. Otherwise, the name is assumed to be relative to context->rootdir.

context
Additional context information. The ServerContext structure is set up by the caller. See sspec_open() for documentation on this structure. For this function, context->userid should be set to the current user whose access is being tested, or may be set to -1 to test access by the server in general.

Return Value

≥0: Success. The return value is a bitmask of the following values:
    • O_READ - user+server has read access
    • O_WRITE - user+server has write access
    • 0 (zero) - no access

The following return values are negatives of the values defined in errno.lib.
    • -ENOENT - The resource was not found.
    • -EINVAL - The resource name was malformed (e.g., too long), or context was NULL, or the resource was not a file type.

See also

sspec_read, sspec_write, sspec_seek, sspec_tell, sspec_close, sspec_checkpermissions

sspec_addCGI

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

Description

Add a CGI function to the RAM resource list. This function is currently only useful for the HTTP server, in which case the function is registered as a CGI processor. Make sure that SSPEC_MAXSPEC is large enough to hold this new entry.

Parameters

name
URL name of the new function, for example, myCGI.cgi

fptr

Pointer to the function. The prototype for this function is: 

int (*fptr)(HttpState * state);
There is a specific documented interface that must be used when specifying this type of CGI handler function. See the manual for details.

servermask
Bitmask representing valid servers (currently only useful with SERVER_HTTP)

Return value

≥0: Successfully added spec index
-1: Failed to add function.

See Also

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

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 server spec list.
-1: Failed to add form.

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 FS2 filesystem, to the RAM resource list. Make sure that SSPEC_MAXSPEC is large enough to hold this new entry. This function associates a name with the file.

This creates an alias entry for /fs2/file<n>.

Note that all FS2 files are automatically accessible. There is no need to call this function unless it is desired to assign a name to an FS2 file other than the default, which is file1, file2 etc.

For more information regarding the FS2 filesystem, please see the Dynamic C User's Manual.

Parameters

name
Name of the new file.

filenum
Number of the file in the file system (1-255). This is the number passed in as the second parameter to fcreate() or the return value from fcreate_unused().

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 file in TCP/IP servers' object list.

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 RAM resource list. Make sure that SSPEC_MAXSPEC is large enough to hold this new entry. This function is currently only useful for HTTP servers.
NOTE If using HTTP upload facility and/or the new CGI interface, use sspec_addCGI() instead.

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.

See also

sspec_addform, sspec_addfsfile, sspec_addrootfile, sspec_addvariable, sspec_addxmemvar, sspec_addxmemfile, sspec_aliasspec

sspec_addfv

int sspec_addfv( int form, int var );

Description

Adds a variable to a form.

Parameters

form
spec index of the form (previously returned by sspec_addform()).

var
spec index of the variable to add (which must have been previously created using sspec_addvariable())

Return value

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

See Also

sspec_addform

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 dynamic resource table. Make sure that SSPEC_MAXSPEC is large enough to hold this new entry.

Parameters

name

Name of the new file. This must be unique, but this function does not check. The name should not conflict with the virtual filesystem hierarchy. That is, it should not start with /fs2/, /A/, /B/ etc.

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; file index into the resource list.

See also

sspec_addfsfile, sspec_addxmemfile, sspec_addxmemvar, sspec_addvariable, sspec_addfunction, sspec_addform, sspec_aliasspec, sspec_resizerootfile

sspec_addrule

int sspec_addrule( char * pfx, char * realm, word readgroups, word writegroups, word servermask, word method, MIMETypeMap * mimetype);

Description

Add a rule to the dynamic resource rule table. Resource rules are used to associate access information with resource names matching the specified prefix string. The most specific, that is, the longest, matching string is used.

Normally, the rule table is consulted only for resource names that belong in a file system (FS2 or FAT). You can also cause the rule table to be consulted for flash- or RAM-table entries if you leave the realm field as NULL in the entry. If the realm field is not NULL, then the rule table is not consulted for that entry. If the realm field was NULL, and there was no applicable entry in the rule table, then the resource table permissions are used (with NULL realm).

Do not attempt to use a very large number of rule table entries, since the table must be searched exhaustively for each initial resource access. There should be no need for a large number of entries provided that the resource name hierarchy is organized in a reasonably efficient manner. For example, keep the resources for a particular user or realm in one directory, and just add an entry for that directory instead of an entry for each resource. This works because the full path name is always used for matching, and the directory will always be a prefix string of the files that reside in that directory.

As an alternative to this function, you can statically initialize a rule table using the following macros:

 

#define SSPEC_FLASHRULES           // Required.
#use "zserver.lib"                // this lib


SSPEC_RULETABLE_START
SSPEC_RULE("prefix", realm, rg, wg, sm)
SSPEC_RULE("prefix", realm, rg, wg, sm)
SSPEC_MM_RULE("prefix", realm, rg, wg, sm, meth, mime)
SSPEC_MM_RULE("prefix", realm, rg, wg, sm, meth, mime)
 ...
SSPEC_RULETABLE_END

The SSPEC_MM_RULE macro parameters are basically the same parameters as would be passed to this function. These macros define and initialize a constant rule table named f_rule_table. SSPEC_RULE just omits the (rarely used) method and mimetype fields.

When using a static rule table, the dynamically added entries are searched before the static ones.

Parameter

pfx
Prefix of resource name. This must include the initial "/" character, since all matching is done using absolute path names. If this prefix string exactly matches an existing entry in the table, that entry is replaced. Otherwise, a new entry is created (if possible). This string is not copied, only the pointer is stored. Thus, pfx must point to static storage, that is, a string constant or a global variable. Initial characters other than "/" are reserved for future use.

realm
If not NULL, is an arbitrary null-terminated string that may be used by the server. For HTTP, this is used as the "realm" of the resource. This string is not copied, only the pointer is stored. Thus, the parameter must point to static storage.

readgroups
A word with a bit set for each group that can access this resource for reading. A maximum of 16 different user groups can exist.

writegroups
A word with a bit set for each group that can access this resource for writing. The user must also be given write permission to resources in the userid table entry for the appropriate server(s).

servermask
The server(s) that are allowed to access this resource. Servers have predefined bits. This parameter should be a combination of
  • SERVER_HTTP: web server
  • SERVER_FTP: file transfer protocol server
  • SERVER_SMTP: email
  • SERVER_HTTPS: secure web server
  • SERVER_SNMP: SNMP agent
  • SERVER_USER: user-defined server
  • SERVER_ANY: for all servers.

method
Allowable authentication method(s) to be used when accessing this resource. If zero, then the resource has no particular authentication method requirements. This is a bitwise combination of:
  • SERVER_AUTH_BASIC: plaintext userid/password
  • SERVER_AUTH_DIGEST: challenge-response protocol
  • SERVER_AUTH_PK: public key (such as SSL/TLS)

mimetype
An appropriate MIME type to use. If NULL, then the default table (called http_types) will be consulted.

Return Value

≥0: OK
-1: Error. For example, out of space in rule table; increase SSPEC_MAXRULES.

See also

sspec_removerule, sspec_getMIMEtype

sspec_adduser

int sspec_adduser( int sspec, int userid );

Description

Add to the read permission mask for the given resource. The groups that userid is a member of are ORed into the existing permission mask for the resource. The write permissions are not modified.
NOTE This is not used to create new userids. For that, see sauth_adduser().

Adds a user to the list of users that have access to the given spec entry. Up to SSPEC_USERSPERRESOURCE users can be added. Any more than that will result in this function returning -1.

This function is deprecated as of Dynamic C 8.50. Use the more general sspec_setpermissions() function instead.

Parameters

sspec
Spec index.

userid
User index.

Return Value

≥0: Success, index of userid added for given spec entry.
-1: Failure.

SEE ALSO

sspec_setuser, sspec_getusername, sspec_getuserid, sspec_removeuser, sspec_setpermissions

sspec_addvariable

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

Description

Adds a variable to the dynamic resource table (aka, the RAM resource list). Make sure that SSPEC_MAXSPEC is large enough to hold this new spec entry. This function is currently only useful for the HTTP server.

Parameters

name
Name of the new variable. This must be unique, but this function does not check. The name should not conflict with the virtual filesystem hierarchy. That is, it should not start with /fs2/, /A/, /B/ etc. Variables appear in a directory listing of the root directory "/" however, they cannot be opened using sspec_open().

variable
Address of actual variable.

type
Variable type, one of:
  • INT8 - single character
  • INT16 - 2-byte integer
  • PTR16 - string in root memory
  • INT32 - 4-byte (long) integer
  • FLOAT32 - floating point variable

format
Output format of the variable as a printf() conversion specifier, e.g., "%d."

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

Return value

-1: Failure.
≥0: Success, the index of the variable in the resource list.

See also

sspec_addfsfile, sspec_addrootfile, sspec_addxmemfile, sspec_addxmemvar, 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 RAM resource list. Make sure that SSPEC_MAXSPEC is large enough to hold this new entry.

Parameters

name
Name of the new file. This must be unique, but this function does not check. The name should not conflict with the virtual filesystem hierarchy. That is, it should not start with /fs2/, /A/, /B/ etc.

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).