Appendix A   Data Structure Reference


NSAPI uses many data structures which are defined in the nsapi.h header file, which is in the directory server-root/plugins/include.

The NSAPI functions described in Chapter 5 "NSAPI Function Reference," provide access to most of the data structures and data fields. Before directly accessing a data structure in naspi.h, check if an accessor function exists for it.

For information about the privatization of some data structures in iPlanet Web Server 4.x, see "Privatization of Some Data Structures."

The rest of this chapter describes some of the frequently used public data structures in nsapi.h for your convenience. Note that only the most commonly used fields are documented here for each data structure; for complete details look in nsapi.h.

• session

• pblock

• pb_entry

• pb_param

• Session->client

• request

• stat

• shmem_s

• cinfo

Privatization of Some Data Structures

---

In iPlanet Web Server 4.x, some data structures were moved from nsapi.h to nsapi_pvt.h. The data structures in nsapi_pvt.h are now considered to be private data structures, and you should not write code that accesses them directly. Instead, use accessor functions. We expect that very few people have written plugins that access these data structures directly, so this change should have very little impact on customer-defined plugins. Look in nsapi_pvt.h to see which data structures have been removed from the public domain and to see the accessor functions you can use to access them from now on.

Plugins written for Enterprise Server 3.x that access contents of data structures defined in nsapi_pvt.h will not be source compatible with In iPlanet Web Server 4.x and 6.x, that is, it will be necessary to #include "nsapi_pvt.h" in order to build such plugins from source. There is also a small chance that these programs will not be binary compatible with iPlanet Web Server 4.x and 6.x, because some of the data structures in nsapi_pvt.h have changed size. In particular, the directive structure is larger, which means that a plugin that indexes through the directives in a dtable will not work without being rebuilt (with nsapi_pvt.h included).

We hope that the majority of plugins do not reference the internals of data structures in nsapi_pvt.h, and therefore that most existing NSAPI plugins will be both binary and source compatible with iPlanet Web Server 6.0.

session

---

A session is the time between the opening and closing of the connection between the client and the server. The Session data structure holds variables that apply session wide, regardless of the requests being sent, as shown here:

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;    /* Raw socket information about the remote */    /* client (for internal use) */    struct in_addr iaddr; } Session;

pblock

---

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; it provides the basic mechanism for packaging up parameters and values. There are many functions for creating and managing parameter blocks, and for extracting, adding, and deleting entries. See the functions whose names start with pblock_ in Chapter 5 "NSAPI Function Reference." You should not need to write code that access pblock data fields directly.

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

pb_entry

---

The pb_entry is a single element in the parameter block.

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

pb_param

---

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

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

Session->client

---

The Session->client parameter block structure contains two entries:

• The ip entry is the IP address of the client machine.

• The dns entry is the DNS name of the remote machine. This member must be accessed through the session_dns function call:

  /* * session_dns returns the DNS host name of the client for this * session and inserts it into the client pblock. Returns NULL if * unavailable. */ char *session_dns(Session *sn);

request

---

Under HTTP protocol, there is only one request per session. The Request structure contains the variables that apply to the request in that session (for example, the variables include the client's HTTP headers).

typedef struct {    /* Server working variables */    pblock *vars;    /* The method, URI, and protocol revision of this request */    block *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;    /* Array of objects that were created from .nsconfig files */    httpd_objset *tmpos;    /* The stat last returned by request_stat_path */    char *statpath;    char *staterr;    struct stat *finfo;    /* access control state */    /* ACL decision state */    int aclstate;    /* deciding ACL directive number */    int acldirno;    /* name of deciding ACL */    char *aclname;    /* parameter block for ACL PathCheck */    pblock *aclpb;    /* 3.0 ACL list pointer */    ACLListHandle *acllist;

/* default NSAPICacheAccelSafe */    int request_is_cacheable;    int directive_is_cacheable;    char *cached_headers;    /* length of the valid headers */    int cached_headers_len;    char *unused;    /* HTTP/1.1 features */    #define REQ_TIME(x) (x)->req_start    /* time request arrived - used for selecting weak or strong    cache validation */    time_t req_start;    /* protocol version number */    short protv_num;    /* method number */    short method_num;    struct rq_attr {    /* set if absolute URI was used */    RQATTR abs_uri:1;    /* chunked transfer-coding */    RQATTR chunked:1;    /* connection keep-alive */    RQATTR keep_alive:1;    /* request packet is pipelined */    RQATTR pipelined:1;    /* this was an internal request */    RQATTR internal_req:1;    /* don't FREE() this request */    RQATTR perm_req:1;    /* a header file was present */    RQATTR header_file_present:1;    /* a footer file was present */    RQATTR footer_file_present:1;    /* JVM thread has been attached */    RQATTR jvm_attached:1;    /* request was restarted */    RQATTR req_restarted:1;    /* used for first-request serialization on some platforms */    RQATTR jvm_request_locked:1;    /* set if default types were set using set-default-type    objecttype function */    RQATTR default_type_set:1;

* set if this request refers to a web application */    RQATTR is_web_app:1;    /* set if browser requires unclean SSL shutdown */    RQATTR ssl_unclean_shutdown:1;    /* set if absolute URI was used */    RQATTR abs_uri:1;    /* if you add a flag, make sure to subtract from this */    RQATTR reserved:18;    } rq_attr;    /* not NULL if abs_uri set */    char *hostname;    /* allowed METHODs for this server */    int allowed;    /* number of byte ranges */    int byterange;    /* HTTP status code */    short status_num;    /* used for rqstat */    int staterrno;    /* original Request - used for internal redirects */    Request *orig_rq;    };

stat

---

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 your platform's implementation, 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

---

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

---

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;