Chapter 7 Data Structure Reference

NSAPI uses many data structures that are defined in the nsapi.h header file, which is in the install-dir/include directory.

This chapter describes public data structures in nsapi.h.

The data structures in nsapi.h that are not described in this chapter are considered private and could change incompatibly in future releases. Some of the data structures described in this chapter might contain additional, undocumented fields. These fields are also considered private and might change incompatibly in future releases. Additional fields may be added in future release, so do not make assumptions regarding the size of data structures.

This chapter has the following sections:

• Session Data Structure

• pblock Data Structure

• pb_entry Data Structure

• pb_param Data Structure

• Request Data Structure

• stat Data Structure

• shmem_s Data Structure

• cinfo Data Structure

• sendfiledata Data Structure

• Filter Data Structure

• FilterContext Data Structure

• FilterLayer Data Structure

• FilterMethods Data Structure

Public Data Structures

This section describes public data structures in nsapi.h.

Session Data Structure

A session is the time between the opening and closing of the connection between the client and the server.

The following list describes the most important fields in this data structure:

• sn->client— Pointer to a pblock containing information about the client such as its IP address, DNS name, or certificate.

• sn->csd— Platform-independent client socket descriptor. This pointer is passed to the routines for reading from and writing to the client.

The Session data structure holds variables that apply to a client, regardless of the requests being sent.

typedef struct {
    /* Information about the remote client */
    pblock *client;

    /* The socket descriptor to the remote client */
    SYS_NETFD csd;

    /* The input buffer for that socket descriptor */
    netbuf *inbuf;
} Session;

  

The following list describes the most important fields in the Session data structure:

• client — Pointer to a pblock containing information about the client such as its IP address, DNS name, or SSL certificate. The ip parameter contains the client's IP address. Do not modify the contents of this pblock.

• csd — The platform-independent client socket descriptor used to communicate with the client. This descriptor can be passed to routines such as net_write to send output to the client.

• inbuf — Pointer to the input buffer for the client socket descriptor. This pointer can be passed to routines such as netbuf_grab or netbuf_getc to receive input from the client.

The Session NSAPI data structure cannot be used concurrently by multiple threads. Do not retain any reference to a Session or its contents after processing of the current request is complete.

pblock Data Structure

The parameter block is the hash table that holds pb_entry structures. Its contents are transparent to most code. This data structure is frequently used in NSAPI, pblock provides the basic mechanism for packaging up parameters and values. Many functions exist for creating and managing parameter blocks, and for extracting, adding, and deleting entries. See the functions whose names start with pblock_ in Chapter 6, NSAPI Function and Macro Reference. You do not need to write code that accesses pblock data fields directly.

typedef struct {
    int hsize;
    struct pb_entry **ht;
} pblock;

      

The pblock NSAPI data structure can not be used concurrently by multiple threads. Do not retain any reference to a pblock or its contents after processing of the current request is complete.

pb_entry Data Structure

The pb_entry is a single element in the parameter block.

struct pb_entry {
    pb_param *param;
    struct pb_entry *next;
}; 

pb_param Data Structure

The pb_param represents a name-value pair, as stored in a pb_entry.

typedef struct {
    char *name,*value;
} pb_param;

Request Data Structure

The Request data structure describes an HTTP transaction, for example, the variables include the client's HTTP request headers.

typedef struct{
    */Server working variables */
    pblock *vars;

    /* The method, URI, and protocol revision of this request */
    pblock *reqpb;

    /* Protocol specific headers */
    int loadhdrs;
    pblock *headers;

    /* Server's response headers */
    int senthdrs;
    pblock *srvhdrs;

    /* The object set constructed to fulfill this request */
    httpd_objset *os;
} Request;

The following list describes the most important fields in the Request data structure:

• vars— Pointer to a pblock containing information about request-response processing. SAFs may modify the contents of this pblock according to the rules established in Required Behavior of SAFs for Each Directive.

• reqpb — Pointer to a pblock containing information about the client's HTTP request. The method parameter contains the HTTP request method, the uri parameter contains the path portion of the requested URI, the optional query parameter contains any query string from the requested URI, and the protocol parameter contains the HTTP protocol version. Do not modify the contents of this pblock.

• headers — Pointer to a pblock containing the client's HTTP request headers. By convention, all parameter names are lowercase. Do not modify the contents of this pblock.

• senthdrs — Indicates whether the server has sent HTTP response headers. Service SAFs may set rq->senthdrs = 1 to prevent the server from sending HTTP response headers.

• srvhdrs — Pointer to a pblock containing the server's HTTP response headers. By convention, all parameter names are lowercase. SAFs and filters may modify the contents of this pblock.

The Request NSAPI data structure cannot be used concurrently by multiple threads. Do not retain any references to a Request or its contents after processing of the current request.

stat Data Structure

When a program calls the stat( ) function for a given file, the system returns a structure that provides information about the file. The specific details of the structure should be obtained from the implementation of your platform, but the basic outline of the structure is as follows:

struct stat {
    dev_t      st_dev;     /* device of inode */
    inot_t     st_ino;     /* inode number */
    short      st_mode;    /* mode bits */
    short      st_nlink;   /* number of links to file /*
    short      st_uid;     /* owner’s user id */
    short      st_gid;     /* owner’s group id */
    dev_t      st_rdev;    /* for special files */
    off_t      st_size;    /* file size in characters */
    time_t     st_atime;   /* time last accessed */
    time_t     st_mtime;   /* time last modified */
    time_t     st_ctime;   /* time inode last changed*/
}

      

The elements that are most significant for server plug-in API activities are st_size, st_atime, st_mtime, and st_ctime.

shmem_s Data Structure

typedef struct {
    void       *data;   /* the data */
    HANDLE     fdmap;
    int        size;    /* the maximum length of the data */
    char       *name;   /* internal use: filename to unlink if exposed */
    SYS_FILE   fd;      /* internal use: file descriptor for region */
} shmem_s;

      

cinfo Data Structure

The cinfo data structure records the content information for a file.

typedef struct {
    char    *type;
            /* Identifies what kind of data is in the file*/
    char    *encoding;
             /* encoding identifies any compression or other /*
            /* content-independent transformation that’s been /*
            /* applied to the file, such as uuencode)*/
    char    *language;            
            /* Identifies the language a text document is in. */
} cinfo;

      

sendfiledata Data Structure

The sendfiledata data structure is used to pass parameters to the net_sendfile function. The parameters are also passed to the sendfile method in an installed filter in response to a net_sendfile call.

typedef struct {
    SYS_FILE fd;         /* file to send */
    size_t offset;       /* offset in file to start sending from */
    size_t len;          /* number of bytes to send from file */
    const void *header;  /* data to send before file */
    int hlen;            /* number of bytes to send before file */
    const void *trailer; /* data to send after file */
    int tlen;            /* number of bytes to send after file */
} sendfiledata;

      

Filter Data Structure

The Filter data structure is an opaque representation of a filter. A Filter structure is created by calling filter_create() Function.

typedef struct Filter Filter;
      

FilterContext Data Structure

The FilterContext data structure stores the context associated with a particular filter layer. Filter layers are created by calling filter_insert() Function.

Filter developers may use the data member to store filter-specific context information.

typedef struct {
    pool_handle_t *pool; /* pool context was allocated from */
    Session *sn;         /* session being processed */
    Request *rq;         /* request being processed */
    void *data;          /* filter-defined private data */
} FilterContext;

FilterLayer Data Structure

The FilterLayer data structure represents one layer in a filter stack. The FilterLayer structure identifies the filter installed at that layer. This structure provides pointers to layer-specific context and a filter stack that represents the layer immediately below it in the filter stack.

typedef struct {
    Filter *filter; /* the filter at this layer in the filter stack */
    FilterContext *context; /* context for the filter */
    SYS_NETFD lower; /* access to the next filter layer in the stack */
} FilterLayer;

FilterMethods Data Structure

The FilterMethods data structure is passed to filter_create to define the filter methods that a filter supports. Each new FilterMethods instance must be initialized with the FILTER_METHODS_INITIALIZER macro. For each filter method that a filter supports, the corresponding FilterMethods member should point to a function that implements that filter method.

typedef struct {
    size_t size;
    FilterInsertFunc *insert;
    FilterRemoveFunc *remove;
    FilterFlushFunc *flush;
    FilterReadFunc *read;
    FilterWriteFunc *write;
    FilterWritevFunc *writev;
    FilterSendfileFunc *sendfile;
} FilterMethods;