home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / lib / libpics / cslutils.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  11.9 KB  |  419 lines
  1.  
  2. /*  W3 Copyright statement 
  3. Copyright 1995 by: Massachusetts Institute of Technology (MIT), INRIA</H2>
  4.  
  5. This W3C software is being provided by the copyright holders under the
  6. following license. By obtaining, using and/or copying this software,
  7. you agree that you have read, understood, and will comply with the
  8. following terms and conditions: 
  9.  
  10. Permission to use, copy, modify, and distribute this software and its
  11. documentation for any purpose and without fee or royalty is hereby
  12. granted, provided that the full text of this NOTICE appears on
  13. <EM>ALL</EM> copies of the software and documentation or portions
  14. thereof, including modifications, that you make. 
  15.  
  16. <B>THIS SOFTWARE IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO
  17. REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF EXAMPLE,
  18. BUT NOT LIMITATION, COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR
  19. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR
  20. THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY
  21. THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
  22. COPYRIGHT HOLDERS WILL BEAR NO LIABILITY FOR ANY USE OF THIS SOFTWARE
  23. OR DOCUMENTATION.
  24.  
  25. The name and trademarks of copyright holders may NOT be used
  26. in advertising or publicity pertaining to the software without
  27. specific, written prior permission.  Title to copyright in this
  28. software and any associated documentation will at all times remain
  29. with copyright holders. 
  30. */
  31. /*                                                                     PICS library utilities
  32.                                   PICS LIBRARY UTILITIES
  33.                                              
  34.  */
  35. /*
  36. **      (c) COPYRIGHT MIT 1996.
  37. **      Please first read the full copyright statement in the file COPYRIGH.
  38. */
  39. /*
  40.  
  41.    This module defines the PICS library interface.
  42.    
  43.  */
  44. #ifndef CSLUTILS_H
  45. #define CSLUTILS_H
  46. /*
  47.  
  48.  */
  49. #include "htutils.h"
  50. #include "htlist.h"
  51. /*
  52.  
  53.                                 PRIMITAVE DATA STRUCTURES
  54.                                              
  55.    BVal_t, FVal_t, SVal_t, DVal_t - hold a boolean, float (not double), string, or date
  56.    value (respectively). These data structures are designed so that they may be
  57.    initialized to all 0s (and hence included directly within larger structures, rather
  58.    than allocated and initialized individually). You must, however, call their clear
  59.    method to deallocate any additional memory used to store the actual value once they
  60.    have been initialized. The following methods are defined on all four data types ("X"
  61.    should be either "B" "F" "S" or "D", XType is "BOOL" "float" "char *" or "char *",
  62.    respectively):
  63.    
  64.       BOOL XVal_readVal(XVal_t, char *), etc. - convert the string to a value of the
  65.       specified type. Returns TRUE on success, FALSE on failure. If successful, may
  66.       allocate additional storage.
  67.       
  68.       BOOL XVal_initialized(XVal_t) - Returns TRUE if the value has been initialized
  69.       (hence contains a legitimate value and may have additional storage allocated
  70.       internally), FALSE otherwise.
  71.       
  72.       XType XVal_value(XVal_t) -- Returns the value stored in the object.
  73.       
  74.       void XVal_clear(XVal_t) -- Mark the object as uninitialized and release any memory
  75.       associated with the value currently stored in the object.
  76.       
  77. BVAL
  78.  
  79.    - Boolean value.
  80.    
  81.   definition
  82.   
  83.  */
  84. typedef struct {
  85.     enum {BVal_UNINITIALIZED = 0,BVal_YES = 1, BVal_INITIALIZED = 2} state;
  86.     } BVal_t;
  87.  
  88. extern BOOL BVal_readVal(BVal_t * pBVal, const char * valueStr);
  89. extern BOOL BVal_initialized(const BVal_t * pBVal);
  90. extern BOOL BVal_value(const BVal_t * pBVal);
  91. extern void BVal_clear(BVal_t * pBVal);
  92. /*
  93.  
  94.   additional methods
  95.   
  96.       void set - assign value
  97.       
  98.  */
  99. extern void BVal_set(BVal_t * pBVal, BOOL value);
  100. /*
  101.  
  102. FVAL
  103.  
  104.    - Float value with negative and positive infinity values
  105.    
  106.   definition
  107.   
  108.  */
  109. typedef struct {
  110.     float value;
  111.     enum {FVal_UNINITIALIZED = 0, FVal_VALUE = 1, FVal_NEGATIVE_INF = 2,
  112.           FVal_POSITIVE_INF = 3} stat;
  113.     } FVal_t;
  114.  
  115. extern BOOL FVal_readVal(FVal_t * pFVal, const char * valueStr);
  116. extern BOOL FVal_initialized(const FVal_t * pFVal);
  117. extern float FVal_value(const FVal_t * pFVal);
  118. extern void FVal_clear(FVal_t * pFVal);
  119. /*
  120.  
  121.   additional methods
  122.   
  123.       void set - assign a float value
  124.       
  125.       void setInfinite - set to negative or positive infinity
  126.       
  127.       BOOL isZero - see if value is zero
  128.       
  129.       int isInfinite - -1 or 1 for negative or positive infinity
  130.       
  131.       BOOL nearerZero - see if check is nearer zero than check
  132.       
  133.       FVal_t FVal_minus - subtract small from big
  134.       
  135.       char * FVal_toStr - convert to allocated CString, caller must free
  136.       
  137.  */
  138. extern void FVal_set(FVal_t * pFVal, float value);
  139. extern void FVal_setInfinite(FVal_t * pFVal, BOOL negative);
  140. extern BOOL FVal_isZero(const FVal_t * pFVal);
  141. extern int FVal_isInfinite(const FVal_t * pFVal);
  142. extern BOOL FVal_nearerZero(const FVal_t * pRef, const FVal_t * pCheck);
  143. extern FVal_t FVal_minus(const FVal_t * pBig, const FVal_t * pSmall);
  144. extern char * FVal_toStr(FVal_t * pFVal);
  145. /*
  146.  
  147.   initializers
  148.   
  149.    FVal intializers may be used when creating an FVal
  150.    eg. FVal_t localFVal = FVal_NEGATIVE_INF;
  151.    
  152.  */
  153. #define FVal_NEW_UNINITIALIZED {(float) 0.0, FVal_UNINITIALIZED}
  154. #define FVal_NEW_NEGATIVE_INF {(float) 0.0, FVal_NEGATIVE_INF}
  155. #define FVal_NEW_POSITIVE_INF {(float) 0.0, FVal_POSITIVE_INF}
  156. #define FVal_NEW_ZERO {(float) 0.0, FVal_VALUE}
  157.  
  158. /*
  159.  
  160. SVAL
  161.  
  162.    - String value.
  163.    
  164.   definition
  165.   
  166.  */
  167. typedef struct {
  168.     char * value;
  169.     BOOL initialized;
  170.     } SVal_t;
  171.  
  172. extern BOOL SVal_readVal(SVal_t * pSVal, const char * valueStr);
  173. extern BOOL SVal_initialized(const SVal_t * pSVal);
  174. extern char * SVal_value(const SVal_t * pSVal);
  175. extern void SVal_clear(SVal_t * pSVal);
  176. /*
  177.  
  178. DVAL
  179.  
  180.    - Date value.
  181.    
  182.   definition
  183.   
  184.  */
  185. typedef struct {
  186.     char * value; /* keep the string around for debugging and output */
  187.     BOOL initialized;
  188.     int year;
  189.     int month;
  190.     int day;
  191.     int hour;
  192.     int minute;
  193.     int timeZoneHours;
  194.     int timeZoneMinutes;
  195.     } DVal_t;
  196.  
  197. extern BOOL DVal_readVal(DVal_t * pDVal, const char * valueStr);
  198. extern BOOL DVal_initialized(const DVal_t * pDVal);
  199. extern char * DVal_value(const DVal_t * pDVal);
  200. extern void DVal_clear(DVal_t * pDVal);
  201. /*
  202.  
  203.   additional methods
  204.   
  205.       int compare - -1 or 1 for a before or after b, 0 for equivilence
  206.       
  207.  */
  208. extern int DVal_compare(const DVal_t * a, const DVal_t * b);
  209. /*
  210.  
  211. RANGE
  212.  
  213.    - Range of FVals.
  214.    
  215.   definition
  216.   
  217.  */
  218. typedef struct {
  219.     FVal_t min;
  220.     FVal_t max;
  221.     } Range_t;
  222. /*
  223.  
  224.   methods
  225.   
  226.       rangeToStr - print range to malloced string. This string must be freed by caller
  227.       
  228.       gap - find the difference between a and b
  229.       
  230.  */
  231. extern char * Range_toStr(Range_t * pRange);
  232. extern FVal_t Range_gap(Range_t * a, Range_t * b);
  233. /*
  234.  
  235.   initializers
  236.   
  237.  */
  238. #define Range_NEW_UNINITIALIZED {FVal_NEW_UNINITIALIZED, \
  239.                                  FVal_NEW_UNINITIALIZED}
  240.  
  241. /*
  242.  
  243.                                           PARSER
  244.                                              
  245. CSPARSE_PARSECHUNK
  246.  
  247.    CSParse_t - ephemeral parser data, the CSParse structure is defined in CSParse.html.
  248.    CSDoMore_t - tells caller whether parseChunk expects more or encountered an error
  249.    
  250.  */
  251. typedef struct CSParse_s CSParse_t;
  252. typedef enum {CSDoMore_more, CSDoMore_done, CSDoMore_error} CSDoMore_t;
  253. extern CSDoMore_t CSParse_parseChunk (CSParse_t * pCSParse, const char * ptr,
  254.                                       int len, void * pVoid);
  255. /*
  256.  
  257.                                      PARSE CALLBACKS
  258.                                              
  259.    During parsing, the parser makes callbacks to tell the caller that an error has been
  260.    encountered or that the parser is reading into a new data structure.
  261.    
  262. CSPARSETC
  263.  
  264.    The TC, or TargetChange, type is a way of itemizing the different targets in a parsable
  265.    object. It is used in the TargetChangeCallback
  266.    
  267.  */
  268. typedef unsigned int CSParseTC_t;
  269. /*
  270.  
  271. STATERET
  272.  
  273.  */
  274. typedef enum {StateRet_OK = 0, StateRet_DONE = 1, StateRet_WARN = 0x10,
  275.               StateRet_WARN_NO_MATCH = 0x11, StateRet_WARN_BAD_PUNCT = 0x12,
  276.               StateRet_ERROR = 0x100, StateRet_ERROR_BAD_CHAR = 0x101
  277. } StateRet_t;
  278.  
  279. /*
  280.  
  281. TARGETCHANGECALLBACK
  282.  
  283.    These callbacks keep the caller abreast of what type of object the parser is currently
  284.    reading. TargetChangeCallbacks are made whenever the parser starts or finishes reading
  285.    one of these objects. The actual values of targetChange, and what objects they
  286.    correlate to, can be found in the modules for the object being parsed.
  287.    
  288.       CSLL.html for PICS labels.
  289.       
  290.       CSMR.html for machine-readable service descriptions.
  291.       
  292.       CSUser.html for PICS user profiles.
  293.       
  294.    Example: When reading a CSLabel, the callback will be called with pTargetObject =
  295.    CSLLTC_SERVICE when reading a service, CSLLTC_LABEL when reading a label, etc.
  296.    
  297.  */
  298. typedef struct TargetObject_s TargetObject_t;
  299. typedef StateRet_t TargetChangeCallback_t(CSParse_t * pCSParse,
  300.                                          TargetObject_t * pTargetObject,
  301.                                          CSParseTC_t targetChange, BOOL closed,
  302.                                          void * pVoid);
  303. /*
  304.  
  305. PARSEERRORHANDLER
  306.  
  307.  */
  308. typedef StateRet_t ParseErrorHandler_t(CSParse_t * pCSParse,
  309.                                        const char * token,
  310.                                        char demark, StateRet_t errorCode);
  311.  
  312. /*
  313.  
  314. CSLIST_ACCEPTLABELS
  315.  
  316.    get a malloced HTTP Protocol-Request string requesting PICS labels for all services in
  317.    pServiceList
  318.    
  319.  */
  320. typedef enum {CSCompleteness_minimal, CSCompleteness_short,
  321.               CSCompleteness_full, CSCompleteness_signed} CSCompleteness_t;
  322. extern char * CSList_acceptLabels(HTList * pServiceList,
  323.                                   CSCompleteness_t completeness);
  324.  
  325. /*
  326.  
  327. CSLIST_GETLABELS
  328.  
  329.    get a malloced HTTP GET string requesting PICS labels for all services in pServiceList
  330.    
  331.  */
  332. typedef enum {CSOption_generic, CSOption_normal, CSOption_tree,
  333.               CSOption_genericTree} CSOption_t;
  334. extern char * CSList_getLabels(HTList * pServiceList, CSOption_t option,
  335.                                CSCompleteness_t completeness);
  336. /*
  337.  
  338. CSLIST_POSTLABELS
  339.  
  340.    get a malloced HTTP GET string requesting PICS labels for all services in pServiceList
  341.    
  342.  */
  343. extern char * CSList_postLabels(HTList * pServiceList, char * url,
  344.                                 CSOption_t option,
  345.                                 CSCompleteness_t completeness);
  346. /*
  347.  
  348. INDIVIDUAL PARSERS
  349.  
  350. CSLABEL
  351.  
  352.    PICS label list
  353.    
  354.  */
  355. typedef struct CSLabel_s CSLabel_t;
  356. /*
  357.  
  358. CSUSER
  359.  
  360.    PICS user profile
  361.    
  362.  */
  363. typedef struct CSUser_s CSUser_t;
  364. /*
  365.  
  366. CSMACHREAD
  367.  
  368.    PICS machine readable system description
  369.    
  370.  */
  371. typedef struct CSMachRead_s CSMachRead_t;
  372. /*
  373.  
  374.    for reading label error codes
  375.    
  376.  */
  377. typedef enum {
  378.     labelError_NA = 0,
  379.     labelError_NO_RATINGS,
  380.     labelError_UNAVAILABLE,
  381.     labelError_DENIED,
  382.     labelError_NOT_LABELED,
  383.     labelError_UNKNOWN
  384.     } LabelErrorCode_t;
  385.  
  386. /*
  387.  
  388.    State_Parms - obsolete parameter exchange for iterators
  389.    
  390.  */
  391. typedef struct State_Parms_s State_Parms_t;
  392.  
  393. typedef enum {
  394.     CSError_OK = 0,
  395.     CSError_YES = 0,
  396.     CSError_NO = 1,
  397.     CSError_BUREAU_NONE,
  398.     CSError_RATING_VALUE,
  399.     CSError_RATING_RANGE,
  400.     CSError_RATING_MISSING,
  401.     CSError_SINGLELABEL_MISSING,
  402.     CSError_LABEL_MISSING,
  403.     CSError_SERVICE_MISSING,
  404.     CSError_CATEGORY_MISSING,
  405.     CSError_ENUM_MISSING,
  406.     CSError_BAD_PARAM,
  407.     CSError_BAD_DATE,
  408.     CSError_SERVICE_NONE,
  409.     CSError_RATING_NONE,
  410.     CSError_APP
  411.     } CSError_t;
  412. /*
  413.  
  414.  */
  415. #endif /* CSLUTILS_H */
  416. /*
  417.  
  418.    End of Declaration */
  419.