Appendix B   Server Data Structures


The server plug-in API uses many data structures. All their definitions are gathered here for your convenience.

The Session Data Structure

---

A session is the time between the opening and the 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 in this code. It is defined in the base/session.h file.

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;

The Parameter Block (pblock) Data Structure

---

The parameter block is the hash table that holds pb_entry structures. Its contents are transparent to most code. It is defined in the base/pblock.h file.

#include "base/pblock.h"

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

The Pb_entry Data Structure

The pb_entry data structure is a single element in the parameter block. It is defined in the base/pblock.h file.

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

The Pb_param Data Structure

The pb_param data structure represents a name-value pair, as stored in a pb_entry. It is defined in the base/pblock.h file.

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

The Client Parameter Block

---

The Session->client parameter block structure, defined in the base/session.h file, 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);

The Request Data Structure

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). It is declared in the frame/req.h file.

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 */
   pblock *srvhdrs;

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

   /* The stat last returned by request_stat_path */
   char *statpath;
   struct stat *finfo;
} Request;

The Stat Data Structure

When the 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 must be obtained from your own 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.

The Shared Memory Structure, Shmem_s

typedef struct {
void *data; /* the data */
   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;

The Netbuf Data Structure

The netbuf data structure is a platform-independent network-buffering structure that maintains such members as buffer address, position in buffer, current file size, maximum file size, and so on. Details of its structure vary between implementations. It is defined in buffer.h.

The Filebuffer Data Structure

The filebuffer data structure is a platform-independent file-buffering structure that maintains such members as buffer address, file position, current file size, and so on. Details of its structure vary between implementations. It is defined in buffer.h.

The Cinfo Data Structure

The cinfo data structure records the content information for a file. It is defined in cinfo.h.

typedef struct {
   char *type;         /* Identifies what kind of data is in the file*/
   char *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;

The SYS_NETFD Data Structure

The SYS_NETFD data structure is a platform-independent socket descriptor. Details of its structure vary between implementations.

The SYS_FILE Data Structure

The SYS_FILE data structure is a platform-independent file descriptor. Details of its structure vary between implementations.

The SEMAPHORE Data Structure

The SEMAPHORE data structure is a platform-independent implementation of semaphores. Details of its structure vary between implementations. It is defined in sem.h.

The Sockaddr_in Data Structure

The socaddr_in data structure is a platform-dependent socket address. For Unix proxies, go to netinet/in.h.

The CONDVAR Data Structure

The CONDVAR data structure is a platform-independent implementation of a condition variable. Details of its structure may vary between implementations. It is defined in crit.h.

The CRITICAL Data Structure

The CRITICAL data structure is a platform-independent implementation of a critical-section variable. Details of its structure may vary between implementations. It is defined in crit.h.

The SYS_THREAD Data Structure

The SYS_THREAD data structure is a platform-independent implementation of a system-thread variable. Details of its structure may vary between implementations. It is defined in systhr.h.

The CacheEntry Data Structure

The CacheEntry data structure holds all the information about one cache entry. It is created by the ce_lookup function and destroyed by the ce_free function. It is defined in the libproxy/cache.h file.

typedef struct _CacheEntry {
   CacheState state;   /* state of the cache file; DO NOT refer to any
             * of the other fields in this C struct if state
             * is other than
             *      CACHE_REFRESH or
             *      CACHE_RETURN_FROM_CACHE
             */
SYS_FILE fd_in;   /* do not use: open cache file for reading */
int fd_out;   /* do not use: open (locked) cache file for writing */
struct stat finfo;   /* stat info for the cache file */
unsigned char digest[CACHE_DIGEST_LEN];   /* MD5 for the URL */
char *       url_dig;         /* URL used to for digest; field #8 in CIF */
char *      url_cif;         /* URL read from CIF file */
char *      filname;         /* Relative cache file name */
char *      dirname;         /* Absolute cache directory name */
char *      absname;         /* Absolute cache file path */
char *      lckname;         /* Absolute locked cache file path */
char *      cifname;         /* Absolute CIF path */
int      sect_idx;         /* Cache section index */
int      part_idx;         /* Cache partition index */
CSect *      section;         /* Cache section that this file belongs to */
CPart *      partition;         /* Cache partition that this file belongs to */
int       xfer_time;         /* secs */         /* Field #2 in CIF */
time_t       last_modified;         /* GMT */         /* Field #3 in CIF */
time_t       expires;         /* GMT */         /* Field #4 in CIF */
time_t       last_checked;         /* GMT */         /* Field #5 in CIF */
long       content_length;                  /* Field #6 in CIF */
char *      content_type;                  /* Field #7 in CIF */
int      is_auth;         /* Authenticated data -- always do recheck */
int      auth_sent;         /* Client did send the Authorization header */
long   min_size;            /* Min size for a cache file (in KB) */
long   max_size;            /* Max size for a cache file (in KB) */
time_t       last_accessed;         /* GMT for proxy, local for gc */
time_t      created;         /* localtime (only used by gc, st_mtime) */
int      removed;         /* gc only; file was removed from disk */
long      bytes;         /* from stat(), using this we get hdr len */
long      bytes_written;         /* Number of bytes written to disk */
long      bytes_in_media;   /* real fs size taken up */
long      blks;         /* size in 512 byte blocks */
int      category;         /* Value category; bigger is better */
int      cif_entry_ok;         /* CIF entry found and ok */
time_t ims_c;               /* GMT; Client -> proxy if-modified-since */
time_t      start_time;         /* Transfer start time */
int       inhibit_caching;/* Bad expires/other reason not to cache */
int corrupt_cache_file;   /* Cache file gone corrupt => remove */
int    write_aborted;         /* True if the cache file write was aborted */
int batch_update;   /* We're doing batch update (no real user) */
char *      cache_exclude;         /* Hdrs not to write to cache (RE) */
char *      cache_replace;         /* Hdrs to replace with fresh ones from 304 response (RE) */
char *      cache_nomerge;         /* Hdrs not to merge with the cached ones (RE) */
Session *    sn;
Request *    rq;
} CacheEntry;

The CacheState Data Structure

The CacheState data structure is actually an enumerated list of constants. Aways use their names because values are subject to implementation change.

typedef enum {
CACHE_EXISTS_NOT = 0,               /* Internal flag -- do not use! */
CACHE_EXISTS,               /* Internal flag -- do not use! */
CACHE_NO,               /* No caching: don't read, don't write cache */
CACHE_CREATE,               /* Create cache; don't read */
CACHE_REFRESH,               /* Refresh cache; read if not modified */
CACHE_RETURN_FROM_CACHE,               /* Return directly, no check */
CACHE_RETURN_ERROR               /* With connect-mode=never when not in cache */
} CacheState;

The ConnectMode Data Structure

The ConnectMode data structure is actually an enumerated list of constants. Aways use their names because values are subject to implementation change.

typedef enum {
CM_NORMAL = 0,         /* normal -- retrieve/refresh when necessary */
CM_FAST_DEMO,         /* fast -- retrieve only if not in cache already */
CM_NEVER         /* never -- never connect to network */
} ConnectMode;