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