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