ACE/apps/JAWS/clients/WebSTONE/src/nsapi-includes/base/pblock.h

   1 /*
   2  * Copyright (c) 1994, 1995.  Netscape Communications Corporation.  All
   3  * rights reserved.
   4  *
   5  * Use of this software is governed by the terms of the license agreement for
   6  * the Netscape Communications or Netscape Comemrce Server between the
   7  * parties.
   8  */
   9
  10
  11 /* ------------------------------------------------------------------------ */
  12
  13
  14 /*
  15  * pblock.h: Header for Parameter Block handling functions
  16  *
  17  * A parameter block is a set of name=value pairs which are generally used
  18  * as parameters, but can be anything. They are kept in a hash table for
  19  * reasonable speed, but if you are doing any intensive modification or
  20  * access of them you should probably make a local copy of each parameter
  21  * while working.
  22  *
  23  * When creating a pblock, you specify the hash table size for that pblock.
  24  * You should set this size larger if you know that many items will be in
  25  * that pblock, and smaller if only a few will be used or if speed is not
  26  * a concern.
  27  *
  28  * The hashing function is very simple right now, and only looks at the
  29  * first character of name.
  30  *
  31  * Rob McCool
  32  */
  33
  34 #ifndef PBLOCK_H
  35 #define PBLOCK_H
  36
  37 /*
  38  * Requires that the macros MALLOC and STRDUP be set to "safe" versions that
  39  * will exit if no memory is available. If not under MCC httpd, define
  40  * them to be the real functions and play with fire, or make your own
  41  * function.
  42  */
  43
  44 #include "../netsite.h"
  45
  46 #include <ctype.h>  /* isspace */
  47 #include <stdio.h>  /* sprintf */
  48 #include <string.h> /* strlen, strcmp */
  49
  50
  51 /* ------------------------------ Structures ------------------------------ */
  52
  53
  54 typedef struct {
  55     char *name,*value;
  56 } pb_param;
  57
  58 struct pb_entry {
  59     pb_param *param;
  60     struct pb_entry *next;
  61 };
  62
  63 typedef struct {
  64     int hsize;
  65     struct pb_entry **ht;
  66 } pblock;
  67
  68
  69 /* ------------------------------ Prototypes ------------------------------ */
  70
  71
  72 /*
  73  * param_create creates a parameter with the given name and value. If name
  74  * and value are non-NULL, they are copied and placed into the new pb_param
  75  * struct.
  76  */
  77
  78 pb_param *param_create(char *name, char *value);
  79
  80 /*
  81  * param_free frees a given parameter if it's non-NULL, and returns 1 if
  82  * p was non-NULL, and 0 if p was NULL.
  83  *
  84  * Useful for error checking pblock_remove.
  85  */
  86
  87 int param_free(pb_param *pp);
  88
  89 /*
  90  * pblock_create creates a new pblock with hash table size n.
  91  *
  92  * It returns the newly allocated pblock.
  93  */
  94
  95 pblock *pblock_create(int n);
  96
  97 /*
  98  * pblock_free frees the given pblock and any entries inside it.
  99  *
 100  * If you want to save anything in a pblock, remove its entities with
 101  * pblock_remove first and save the pointers you get.
 102  */
 103
 104 void pblock_free(pblock *pb);
 105
 106 /*
 107  * pblock_find finds the entry with the given name in pblock pb.
 108  *
 109  * If it is successful, it returns the param block. If not, it returns NULL.
 110  */
 111
 112 #define pblock_find(name, pb) (_pblock_fr(name,pb,0))
 113
 114 /*
 115  * pblock_findval finds the entry with the given name in pblock pb, and
 116  * returns its value, otherwise returns NULL.
 117  */
 118
 119 char *pblock_findval(char *name, pblock *pb);
 120
 121 /*
 122  * pblock_remove behaves exactly like pblock_find, but removes the given
 123  * entry from pb.
 124  */
 125
 126 #define pblock_remove(name, pb) (_pblock_fr(name,pb,1))
 127
 128 /*
 129  * pblock_nvinsert creates a new parameter with the given name and value
 130  * and inserts it into pblock pb. The name and value in the parameter are
 131  * also newly allocated. Returns the pb_param it allocated (in case you
 132  * need it).
 133  *
 134  * pblock_nninsert inserts a numerical value.
 135  */
 136
 137 pb_param *pblock_nvinsert(char *name, char *value, pblock *pb);
 138 pb_param *pblock_nninsert(char *name, int value, pblock *pb);
 139
 140 /*
 141  * pblock_pinsert inserts a pb_param into a pblock.
 142  */
 143
 144 void pblock_pinsert(pb_param *pp, pblock *pb);
 145
 146 /*
 147  * pblock_str2pblock scans the given string str for parameter pairs
 148  * name=value, or name="value". Any \ must be followed by a literal
 149  * character. If a string value is found, with no unescaped = signs, it
 150  * will be added with the name 1, 2, 3, etc. depending on whether it was
 151  * first, second, third, etc. in the stream (zero doesn't count).
 152  *
 153  * Returns the number of parameters added to the table, or -1 upon error.
 154  */
 155
 156 int pblock_str2pblock(char *str, pblock *pb);
 157
 158 /*
 159  * pblock_pblock2str places all of the parameters in the given pblock
 160  * into the given string (NULL if it needs creation). It will re-allocate
 161  * more space for the string. Each parameter is separated by a space and of
 162  * the form name="value"
 163  */
 164
 165 char *pblock_pblock2str(pblock *pb, char *str);
 166
 167 /*
 168  * pblock_copy copies the entries in the given source pblock to the
 169  * destination one. The entries are newly allocated so that the original
 170  * pblock may be freed or the new one changed without affecting the other.
 171  */
 172
 173 void pblock_copy(pblock *src, pblock *dst);
 174
 175 /*
 176  * pblock_pb2env copies the given pblock into the given environment, with
 177  * one new env entry for each name/value pair in the pblock.
 178  */
 179
 180 char **pblock_pb2env(pblock *pb, char **env);
 181
 182
 183 /* --------------------------- Internal things ---------------------------- */
 184
 185
 186 pb_param *_pblock_fr(char *name, pblock *pb, int remove);
 187
 188
 189 #endif