WINGs/WINGs/WUtil.h

   1 #ifndef _WUTIL_H_
   2 #define _WUTIL_H_
   3
   4 #include <X11/Xlib.h>
   5 #include <limits.h>
   6 #include <sys/types.h>
   7
   8 /* SunOS 4.x Blargh.... */
   9 #ifndef NULL
  10 #define NULL ((void*)0)
  11 #endif
  12
  13
  14 #ifndef WMAX
  15 # define WMAX(a,b)      ((a)>(b) ? (a) : (b))
  16 #endif
  17 #ifndef WMIN
  18 # define WMIN(a,b)      ((a)<(b) ? (a) : (b))
  19 #endif
  20
  21
  22 #ifndef __ASSERT_FUNCTION
  23 # if (!defined (__GNUC__) || (__GNUC__ < 2 && \
  24       __GNUC_MINOR__ < (defined (__cplusplus) ? 6 : 4)))
  25 #  define __ASSERT_FUNCTION       ((char *) 0)
  26 # else
  27 #  define __ASSERT_FUNCTION       __PRETTY_FUNCTION__
  28 # endif
  29 #endif
  30
  31
  32 #ifdef NDEBUG
  33
  34 #define wassertr(expr)          {}
  35 #define wassertrv(expr, val)    {}
  36
  37 #else /* !NDEBUG */
  38
  39 #ifdef DEBUG
  40
  41 #include <assert.h>
  42
  43 #define wassertr(expr)  assert(expr)
  44
  45 #define wassertrv(expr, val)    assert(expr)
  46
  47 #else /* !DEBUG */
  48
  49 #define wassertr(expr) \
  50     if (!(expr)) { \
  51         wwarning("%s line %i (%s): assertion %s failed",\
  52                  __FILE__, __LINE__, __ASSERT_FUNCTION, #expr);\
  53         return;\
  54     }
  55
  56 #define wassertrv(expr, val) \
  57     if (!(expr)) { \
  58         wwarning("%s line %i (%s): assertion %s failed",\
  59                  __FILE__, __LINE__, __ASSERT_FUNCTION, #expr);\
  60         return (val);\
  61     }
  62 #endif /* !DEBUG */
  63
  64 #endif /* !NDEBUG */
  65
  66
  67 #ifdef __cplusplus
  68 extern "C" {
  69 #endif /* __cplusplus */
  70
  71
  72 typedef enum {
  73     WMPostWhenIdle = 1,
  74     WMPostASAP = 2,
  75     WMPostNow = 3
  76 } WMPostingStyle;
  77
  78
  79 typedef enum {
  80     WNCNone = 0,
  81     WNCOnName = 1,
  82     WNCOnSender = 2
  83 } WMNotificationCoalescing;
  84
  85
  86 /* The possible states for connections */
  87 typedef enum {
  88     WCNotConnected=0,
  89     WCListening,
  90     WCInProgress,
  91     WCFailed,
  92     WCConnected,
  93     WCTimedOut,
  94     WCDied,
  95     WCClosed
  96 } WMConnectionState;
  97
  98
  99 /* The possible states for connection timeouts */
 100 typedef enum {
 101     WCTNone=0,
 102     WCTWhileOpening,
 103     WCTWhileSending
 104 } WMConnectionTimeoutState;
 105
 106
 107
 108 enum {
 109     WBNotFound = INT_MIN, /* element was not found in WMBag   */
 110     WANotFound = -1       /* element was not found in WMArray */
 111 };
 112
 113
 114 typedef struct W_Array WMArray;
 115 typedef struct W_Bag WMBag;
 116 typedef struct W_Data WMData;
 117 typedef struct W_TreeNode WMTreeNode;
 118 typedef struct W_HashTable WMHashTable;
 119 typedef struct W_UserDefaults WMUserDefaults;
 120 typedef struct W_Notification WMNotification;
 121 typedef struct W_NotificationQueue WMNotificationQueue;
 122 typedef struct W_Host WMHost;
 123 typedef struct W_Connection WMConnection;
 124 typedef struct W_PropList WMPropList;
 125
 126
 127
 128 /* Some typedefs for the handler stuff */
 129 typedef void *WMHandlerID;
 130
 131 typedef void WMCallback(void *data);
 132
 133 typedef void WMInputProc(int fd, int mask, void *clientData);
 134
 135
 136
 137 typedef int WMCompareDataProc(const void *item1, const void *item2);
 138
 139 typedef void WMFreeDataProc(void *data);
 140
 141 /* Used by WMBag or WMArray for matching data */
 142 typedef int WMMatchDataProc(void *item, void *cdata);
 143
 144
 145
 146 typedef struct {
 147     int position;
 148     int count;
 149 } WMRange;
 150
 151
 152
 153 /* DO NOT ACCESS THE CONTENTS OF THIS STRUCT */
 154 typedef struct {
 155     void *table;
 156     void *nextItem;
 157     int index;
 158 } WMHashEnumerator;
 159
 160
 161 typedef struct {
 162     /* NULL is pointer hash */
 163     unsigned    (*hash)(const void *);
 164     /* NULL is pointer compare */
 165     Bool        (*keyIsEqual)(const void *, const void *);
 166     /* NULL does nothing */
 167     void*       (*retainKey)(const void *);
 168     /* NULL does nothing */
 169     void        (*releaseKey)(const void *);
 170 } WMHashTableCallbacks;
 171
 172
 173 typedef int WMArrayIterator;
 174 typedef void *WMBagIterator;
 175
 176
 177 #if 0
 178 typedef struct {
 179     char character;                    /* the escape character */
 180     char *value;                       /* value to place */
 181 } WMSEscapes;
 182 #endif
 183
 184
 185 /* The connection callbacks */
 186 typedef struct ConnectionDelegate {
 187     void *data;
 188
 189     void (*canResumeSending)(struct ConnectionDelegate *self, WMConnection *cPtr);
 190
 191     void (*didCatchException)(struct ConnectionDelegate *self, WMConnection *cPtr);
 192
 193     void (*didDie)(struct ConnectionDelegate *self, WMConnection *cPtr);
 194
 195     void (*didInitialize)(struct ConnectionDelegate *self, WMConnection *cPtr);
 196
 197     void (*didReceiveInput)(struct ConnectionDelegate *self, WMConnection *cPtr);
 198
 199     void (*didTimeout)(struct ConnectionDelegate *self, WMConnection *cPtr);
 200
 201 } ConnectionDelegate;
 202
 203
 204 typedef void WMNotificationObserverAction(void *observerData,
 205                                           WMNotification *notification);
 206
 207
 208
 209 /*......................................................................*/
 210
 211 typedef void waborthandler(int);
 212
 213 waborthandler* wsetabort(waborthandler* handler);
 214
 215
 216 /* don't free the returned string */
 217 char* wstrerror(int errnum);
 218
 219 void wmessage(const char *msg, ...);
 220 void wwarning(const char *msg, ...);
 221 void wfatal(const char *msg, ...);
 222 void wsyserror(const char *msg, ...);
 223 void wsyserrorwithcode(int error, const char *msg, ...);
 224
 225 char* wfindfile(char *paths, char *file);
 226
 227 char* wfindfileinlist(char **path_list, char *file);
 228
 229 char* wfindfileinarray(WMPropList* array, char *file);
 230
 231 char* wexpandpath(char *path);
 232
 233 /* don't free the returned string */
 234 char* wgethomedir();
 235
 236 void* wmalloc(size_t size);
 237 void* wmalloc0(size_t size);
 238 void* wrealloc(void *ptr, size_t newsize);
 239 void wfree(void *ptr);
 240
 241 #define wnew(type, count) wmalloc(sizeof(type)*count)
 242 #define wnew0(type, count) wmalloc0(sizeof(type)*count)
 243
 244 void wrelease(void *ptr);
 245 void* wretain(void *ptr);
 246
 247 char* wstrdup(char *str);
 248 char* wstrndup(char *str, size_t len);
 249
 250 /* Concatenate str1 with str2 and return that in a newly malloc'ed string.
 251  * str1 and str2 can be any strings including static and constant strings.
 252  * str1 and str2 will not be modified.
 253  * Free the returned string when you're done with it. */
 254 char* wstrconcat(char *str1, char *str2);
 255
 256 /* This will append src to dst, and return dst. dst MUST be either NULL
 257  * or a string that was a result of a dynamic allocation (malloc, realloc
 258  * wmalloc, wrealloc, ...). dst CANNOT be a static or a constant string!
 259  * Modifies dst (no new string is created except if dst==NULL in which case
 260  * it is equivalent to calling wstrdup(src) ).
 261  * The returned address may be different from the original address of dst,
 262  * so always assign the returned address to avoid dangling pointers. */
 263 char* wstrappend(char *dst, char *src);
 264
 265
 266 void wtokensplit(char *command, char ***argv, int *argc);
 267
 268 char* wtokennext(char *word, char **next);
 269
 270 char* wtokenjoin(char **list, int count);
 271
 272 void wtokenfree(char **tokens, int count);
 273
 274 char* wtrimspace(char *s);
 275
 276
 277 WMRange wmkrange(int start, int count);
 278 #ifdef ANSI_C_DOESNT_LIKE_IT_THIS_WAY
 279 #define wmkrange(position, count) (WMRange){(position), (count)}
 280 #endif
 281
 282
 283 char* wusergnusteppath();
 284
 285 char* wdefaultspathfordomain(char *domain);
 286
 287 void wusleep(unsigned int microsec);
 288
 289 #if 0
 290 int wsprintesc(char *buffer, int length, char *format, WMSEscapes **escapes,
 291                int count);
 292 #endif
 293
 294 /*......................................................................*/
 295
 296 /* Event handlers: timer, idle, input */
 297
 298 WMHandlerID WMAddTimerHandler(int milliseconds, WMCallback *callback,
 299                               void *cdata);
 300
 301 WMHandlerID WMAddPersistentTimerHandler(int milliseconds, WMCallback *callback,
 302                                         void *cdata);
 303
 304 void WMDeleteTimerWithClientData(void *cdata);
 305
 306 void WMDeleteTimerHandler(WMHandlerID handlerID);
 307
 308 WMHandlerID WMAddIdleHandler(WMCallback *callback, void *cdata);
 309
 310 void WMDeleteIdleHandler(WMHandlerID handlerID);
 311
 312 WMHandlerID WMAddInputHandler(int fd, int condition, WMInputProc *proc,
 313                               void *clientData);
 314
 315 void WMDeleteInputHandler(WMHandlerID handlerID);
 316
 317
 318 /* This function is used _only_ if you create a non-GUI program.
 319  * For GUI based programs use WMNextEvent()/WMHandleEvent() instead.
 320  * This function will handle all input/timer/idle events, then return.
 321  */
 322
 323 void WHandleEvents();
 324
 325 /*......................................................................*/
 326
 327
 328 WMHashTable* WMCreateHashTable(WMHashTableCallbacks callbacks);
 329
 330 void WMFreeHashTable(WMHashTable *table);
 331
 332 void WMResetHashTable(WMHashTable *table);
 333
 334 unsigned WMCountHashTable(WMHashTable *table);
 335
 336 void* WMHashGet(WMHashTable *table, const void *key);
 337
 338 /* Returns True if there is a value associated with <key> in the table, in
 339  * which case <retKey> and <retItem> will contain the item's internal key
 340  * address and the item's value respectively.
 341  * If there is no value associated with <key> it will return False and in
 342  * this case <retKey> and <retItem> will be undefined.
 343  * Use this when you need to perform your own custom retain/release mechanism
 344  * which requires access to the keys too.
 345  */
 346 Bool WMHashGetItemAndKey(WMHashTable *table, const void *key,
 347                          void **retItem, void **retKey);
 348
 349 /* put data in table, replacing already existing data and returning
 350  * the old value */
 351 void* WMHashInsert(WMHashTable *table, const void *key, const void *data);
 352
 353 void WMHashRemove(WMHashTable *table, const void *key);
 354
 355 /* warning: do not manipulate the table while using the enumerator functions */
 356 WMHashEnumerator WMEnumerateHashTable(WMHashTable *table);
 357
 358 void* WMNextHashEnumeratorItem(WMHashEnumerator *enumerator);
 359
 360 void* WMNextHashEnumeratorKey(WMHashEnumerator *enumerator);
 361
 362 /* Returns True if there is a next element, in which case key and item
 363  * will contain the next element's key and value respectively.
 364  * If there is no next element available it will return False and in this
 365  * case key and item will be undefined.
 366  */
 367 Bool WMNextHashEnumeratorItemAndKey(WMHashEnumerator *enumerator,
 368                                     void **item, void **key);
 369
 370
 371
 372
 373 /* some predefined callback sets */
 374
 375 extern const WMHashTableCallbacks WMIntHashCallbacks;
 376 /* sizeof(keys) are <= sizeof(void*) */
 377
 378 extern const WMHashTableCallbacks WMStringHashCallbacks;
 379 /* keys are strings. Strings will be copied with wstrdup()
 380  * and freed with wfree() */
 381
 382 extern const WMHashTableCallbacks WMStringPointerHashCallbacks;
 383 /* keys are strings, but they are not copied */
 384
 385
 386 /*......................................................................*/
 387
 388 /*
 389  * WMArray use an array to store the elements.
 390  * Item indexes may be only positive integer numbers.
 391  * The array cannot contain holes in it.
 392  *
 393  * Pros:
 394  * Fast [O(1)] access to elements
 395  * Fast [O(1)] push/pop
 396  *
 397  * Cons:
 398  * A little slower [O(n)] for insertion/deletion of elements that
 399  *      aren't in the end
 400  */
 401
 402 WMArray* WMCreateArray(int initialSize);
 403
 404 WMArray* WMCreateArrayWithDestructor(int initialSize, WMFreeDataProc *destructor);
 405
 406 WMArray* WMCreateArrayWithArray(WMArray *array);
 407
 408 #define WMDuplicateArray(array) WMCreateArrayWithArray(array)
 409
 410 void WMEmptyArray(WMArray *array);
 411
 412 void WMFreeArray(WMArray *array);
 413
 414 int WMGetArrayItemCount(WMArray *array);
 415
 416 /* appends other to array. other remains unchanged */
 417 void WMAppendArray(WMArray *array, WMArray *other);
 418
 419 /* add will place the element at the end of the array */
 420 void WMAddToArray(WMArray *array, void *item);
 421
 422 #define WMPushInArray(array, item) WMAddToArray(array, item)
 423
 424 /* insert will increment the index of elements after it by 1 */
 425 void WMInsertInArray(WMArray *array, int index, void *item);
 426
 427 /* replace and set will return the old item WITHOUT calling the
 428  * destructor on it even if its available. Free the returned item yourself.
 429  */
 430 void* WMReplaceInArray(WMArray *array, int index, void *item);
 431
 432 #define WMSetInArray(array, index, item) WMReplaceInArray(array, index, item)
 433
 434 /* delete and remove will remove the elements and cause the elements
 435  * after them to decrement their indexes by 1. Also will call the
 436  * destructor on the deleted element if there's one available.
 437  */
 438 int WMDeleteFromArray(WMArray *array, int index);
 439
 440 #define WMRemoveFromArray(array, item) WMRemoveFromArrayMatching(array, NULL, item)
 441
 442 int WMRemoveFromArrayMatching(WMArray *array, WMMatchDataProc *match, void *cdata);
 443
 444 void* WMGetFromArray(WMArray *array, int index);
 445
 446 #define WMGetFirstInArray(array, item) WMFindInArray(array, NULL, item)
 447
 448 /* pop will return the last element from the array, also removing it
 449  * from the array. The destructor is NOT called, even if available.
 450  * Free the returned element if needed by yourself
 451  */
 452 void* WMPopFromArray(WMArray *array);
 453
 454 int WMFindInArray(WMArray *array, WMMatchDataProc *match, void *cdata);
 455
 456 int WMCountInArray(WMArray *array, void *item);
 457
 458 /* comparer must return:
 459  * < 0 if a < b
 460  * > 0 if a > b
 461  * = 0 if a = b
 462  */
 463 void WMSortArray(WMArray *array, WMCompareDataProc *comparer);
 464
 465 void WMMapArray(WMArray *array, void (*function)(void*, void*), void *data);
 466
 467 WMArray* WMGetSubarrayWithRange(WMArray* array, WMRange aRange);
 468
 469 void* WMArrayFirst(WMArray *array, WMArrayIterator *iter);
 470
 471 void* WMArrayLast(WMArray *array, WMArrayIterator *iter);
 472
 473 /* The following 2 functions assume that the array doesn't change between calls */
 474 void* WMArrayNext(WMArray *array, WMArrayIterator *iter);
 475
 476 void* WMArrayPrevious(WMArray *array, WMArrayIterator *iter);
 477
 478
 479 /* The following 2 macros assume that the array doesn't change in the for loop */
 480 #define WM_ITERATE_ARRAY(array, var, i) \
 481     for (var = WMArrayFirst(array, &(i)); (i) != WANotFound; \
 482     var = WMArrayNext(array, &(i)))
 483
 484 #define WM_ETARETI_ARRAY(array, var, i) \
 485     for (var = WMArrayLast(array, &(i)); (i) != WANotFound; \
 486     var = WMArrayPrevious(array, &(i)))
 487
 488 /*..........................................................................*/
 489
 490 /*
 491  * Tree bags use a red-black tree for storage.
 492  * Item indexes may be any integer number.
 493  *
 494  * Pros:
 495  * O(lg n) insertion/deletion/search
 496  * Good for large numbers of elements with sparse indexes
 497  *
 498  * Cons:
 499  * O(lg n) insertion/deletion/search
 500  * Slow for storing small numbers of elements
 501  */
 502
 503 #define WMCreateBag(size) WMCreateTreeBag()
 504
 505 #define WMCreateBagWithDestructor(size, d) WMCreateTreeBagWithDestructor(d)
 506
 507 WMBag* WMCreateTreeBag(void);
 508
 509 WMBag* WMCreateTreeBagWithDestructor(WMFreeDataProc *destructor);
 510
 511 int WMGetBagItemCount(WMBag *bag);
 512
 513 void WMAppendBag(WMBag *bag, WMBag *other);
 514
 515 void WMPutInBag(WMBag *bag, void *item);
 516
 517 /* insert will increment the index of elements after it by 1 */
 518 void WMInsertInBag(WMBag *bag, int index, void *item);
 519
 520 /* erase will remove the element from the bag,
 521  * but will keep the index of the other elements unchanged */
 522 int WMEraseFromBag(WMBag *bag, int index);
 523
 524 /* delete and remove will remove the elements and cause the elements
 525  * after them to decrement their indexes by 1 */
 526 int WMDeleteFromBag(WMBag *bag, int index);
 527
 528 int WMRemoveFromBag(WMBag *bag, void *item);
 529
 530 void* WMGetFromBag(WMBag *bag, int index);
 531
 532 void* WMReplaceInBag(WMBag *bag, int index, void *item);
 533
 534 #define WMSetInBag(bag, index, item) WMReplaceInBag(bag, index, item)
 535
 536 /* comparer must return:
 537  * < 0 if a < b
 538  * > 0 if a > b
 539  * = 0 if a = b
 540  */
 541 void WMSortBag(WMBag *bag, WMCompareDataProc *comparer);
 542
 543 void WMEmptyBag(WMBag *bag);
 544
 545 void WMFreeBag(WMBag *bag);
 546
 547 void WMMapBag(WMBag *bag, void (*function)(void*, void*), void *data);
 548
 549 int WMGetFirstInBag(WMBag *bag, void *item);
 550
 551 int WMCountInBag(WMBag *bag, void *item);
 552
 553 int WMFindInBag(WMBag *bag, WMMatchDataProc *match, void *cdata);
 554
 555 void* WMBagFirst(WMBag *bag, WMBagIterator *ptr);
 556
 557 void* WMBagLast(WMBag *bag, WMBagIterator *ptr);
 558
 559 /* The following 4 functions assume that the bag doesn't change between calls */
 560 void* WMBagNext(WMBag *bag, WMBagIterator *ptr);
 561
 562 void* WMBagPrevious(WMBag *bag, WMBagIterator *ptr);
 563
 564 void* WMBagIteratorAtIndex(WMBag *bag, int index, WMBagIterator *ptr);
 565
 566 int WMBagIndexForIterator(WMBag *bag, WMBagIterator ptr);
 567
 568
 569 /* The following 2 macros assume that the bag doesn't change in the for loop */
 570 #define WM_ITERATE_BAG(bag, var, i) \
 571     for (var = WMBagFirst(bag, &(i)); (i) != NULL; \
 572     var = WMBagNext(bag, &(i)))
 573
 574 #define WM_ETARETI_BAG(bag, var, i) \
 575     for (var = WMBagLast(bag, &(i)); (i) != NULL; \
 576     var = WMBagPrevious(bag, &(i)))
 577
 578
 579
 580 /*-------------------------------------------------------------------------*/
 581
 582 /* WMData handling */
 583
 584 /* Creating/destroying data */
 585
 586 WMData* WMCreateDataWithCapacity(unsigned capacity);
 587
 588 WMData* WMCreateDataWithLength(unsigned length);
 589
 590 WMData* WMCreateDataWithBytes(void *bytes, unsigned length);
 591
 592 /* destructor is a function called to free the data when releasing the data
 593  * object, or NULL if no freeing of data is necesary. */
 594 WMData* WMCreateDataWithBytesNoCopy(void *bytes, unsigned length,
 595                                     WMFreeDataProc *destructor);
 596
 597 WMData* WMCreateDataWithData(WMData *aData);
 598
 599 WMData* WMRetainData(WMData *aData);
 600
 601 void WMReleaseData(WMData *aData);
 602
 603 /* Adjusting capacity */
 604
 605 void WMSetDataCapacity(WMData *aData, unsigned capacity);
 606
 607 void WMSetDataLength(WMData *aData, unsigned length);
 608
 609 void WMIncreaseDataLengthBy(WMData *aData, unsigned extraLength);
 610
 611 /* Accessing data */
 612
 613 const void* WMDataBytes(WMData *aData);
 614
 615 void WMGetDataBytes(WMData *aData, void *buffer);
 616
 617 void WMGetDataBytesWithLength(WMData *aData, void *buffer, unsigned length);
 618
 619 void WMGetDataBytesWithRange(WMData *aData, void *buffer, WMRange aRange);
 620
 621 WMData* WMGetSubdataWithRange(WMData *aData, WMRange aRange);
 622
 623 /* Testing data */
 624
 625 Bool WMIsDataEqualToData(WMData *aData, WMData *anotherData);
 626
 627 unsigned WMGetDataLength(WMData *aData);
 628
 629 /* Adding data */
 630
 631 void WMAppendDataBytes(WMData *aData, void *bytes, unsigned length);
 632
 633 void WMAppendData(WMData *aData, WMData *anotherData);
 634
 635 /* Modifying data */
 636
 637 void WMReplaceDataBytesInRange(WMData *aData, WMRange aRange, void *bytes);
 638
 639 void WMResetDataBytesInRange(WMData *aData, WMRange aRange);
 640
 641 void WMSetData(WMData *aData, WMData *anotherData);
 642
 643
 644 void WMSetDataFormat(WMData *aData, unsigned format);
 645
 646 unsigned WMGetDataFormat(WMData *aData);
 647 /* Storing data */
 648
 649
 650 /*--------------------------------------------------------------------------*/
 651
 652 /* Generic Tree and TreeNode */
 653
 654 WMTreeNode* WMCreateTreeNode(void *data);
 655
 656 WMTreeNode* WMCreateTreeNodeWithDestructor(void *data, WMFreeDataProc *destructor);
 657
 658 WMTreeNode* WMInsertItemInTree(WMTreeNode *parent, int index, void *item);
 659
 660 #define WMAddItemToTree(parent, item)  WMInsertItemInTree(parent, -1, item)
 661
 662 WMTreeNode* WMInsertNodeInTree(WMTreeNode *parent, int index, WMTreeNode *aNode);
 663
 664 #define WMAddNodeToTree(parent, aNode)  WMInsertNodeInTree(parent, -1, aNode)
 665
 666 void WMDestroyTreeNode(WMTreeNode *aNode);
 667
 668 void WMDeleteLeafForTreeNode(WMTreeNode *aNode, int index);
 669
 670 void WMRemoveLeafForTreeNode(WMTreeNode *aNode, void *leaf);
 671
 672 void* WMReplaceDataForTreeNode(WMTreeNode *aNode, void *newData);
 673
 674 void* WMGetDataForTreeNode(WMTreeNode *aNode);
 675
 676 int WMGetTreeNodeDepth(WMTreeNode *aNode);
 677
 678 WMTreeNode* WMGetParentForTreeNode(WMTreeNode *aNode);
 679
 680 /* Sort only the leaves of the passed node */
 681 void WMSortLeavesForTreeNode(WMTreeNode *aNode, WMCompareDataProc *comparer);
 682
 683 /* Sort all tree recursively starting from the passed node */
 684 void WMSortTree(WMTreeNode *aNode, WMCompareDataProc *comparer);
 685
 686 /* Returns the first node which matches node's data with cdata by 'match' */
 687 WMTreeNode* WMFindInTree(WMTreeNode *aTree, WMMatchDataProc *match, void *cdata);
 688
 689 /* Returns first tree node that has data == cdata */
 690 #define WMGetFirstInTree(aTree, cdata) WMFindInTree(aTree, NULL, cdata)
 691
 692
 693 /*--------------------------------------------------------------------------*/
 694
 695
 696 WMNotification* WMCreateNotification(const char *name, void *object, void *clientData);
 697
 698 void WMReleaseNotification(WMNotification *notification);
 699
 700 WMNotification* WMRetainNotification(WMNotification *notification);
 701
 702 void* WMGetNotificationClientData(WMNotification *notification);
 703
 704 void* WMGetNotificationObject(WMNotification *notification);
 705
 706 const char* WMGetNotificationName(WMNotification *notification);
 707
 708
 709 void WMAddNotificationObserver(WMNotificationObserverAction *observerAction,
 710                                void *observer, const char *name, void *object);
 711
 712 void WMPostNotification(WMNotification *notification);
 713
 714 void WMRemoveNotificationObserver(void *observer);
 715
 716 void WMRemoveNotificationObserverWithName(void *observer, const char *name,
 717                                           void *object);
 718
 719 void WMPostNotificationName(const char *name, void *object, void *clientData);
 720
 721 WMNotificationQueue* WMGetDefaultNotificationQueue(void);
 722
 723 WMNotificationQueue* WMCreateNotificationQueue(void);
 724
 725 void WMDequeueNotificationMatching(WMNotificationQueue *queue,
 726                                    WMNotification *notification,
 727                                    unsigned mask);
 728
 729 void WMEnqueueNotification(WMNotificationQueue *queue,
 730                            WMNotification *notification,
 731                            WMPostingStyle postingStyle);
 732
 733 void WMEnqueueCoalesceNotification(WMNotificationQueue *queue,
 734                                    WMNotification *notification,
 735                                    WMPostingStyle postingStyle,
 736                                    unsigned coalesceMask);
 737
 738
 739 /*......................................................................*/
 740
 741 /* Property Lists handling */
 742
 743 void WMPLSetCaseSensitive(Bool caseSensitive);
 744
 745 WMPropList* WMCreatePLString(char *str);
 746
 747 WMPropList* WMCreatePLData(WMData *data);
 748
 749 WMPropList* WMCreatePLDataWithBytes(unsigned char *bytes, unsigned int length);
 750
 751 WMPropList* WMCreatePLDataWithBytesNoCopy(unsigned char *bytes,
 752                                           unsigned int length,
 753                                           WMFreeDataProc *destructor);
 754
 755 WMPropList* WMCreatePLArray(WMPropList *elem, ...);
 756
 757 WMPropList* WMCreatePLDictionary(WMPropList *key, WMPropList *value, ...);
 758
 759 WMPropList* WMRetainPropList(WMPropList *plist);
 760
 761 void WMReleasePropList(WMPropList *plist);
 762
 763 /* Objects inserted in arrays and dictionaries will be retained,
 764  * so you can safely release them after insertion.
 765  * For dictionaries both the key and value are retained.
 766  * Objects removed from arrays or dictionaries are released */
 767 void WMInsertInPLArray(WMPropList *plist, int index, WMPropList *item);
 768
 769 void WMAddToPLArray(WMPropList *plist, WMPropList *item);
 770
 771 void WMDeleteFromPLArray(WMPropList *plist, int index);
 772
 773 void WMRemoveFromPLArray(WMPropList *plist, WMPropList *item);
 774
 775 void WMPutInPLDictionary(WMPropList *plist, WMPropList *key, WMPropList *value);
 776
 777 void WMRemoveFromPLDictionary(WMPropList *plist, WMPropList *key);
 778
 779 /* It will insert all key/value pairs from source into dest, overwriting
 780  * the values with the same keys from dest, keeping all values with keys
 781  * only present in dest unchanged */
 782 WMPropList* WMMergePLDictionaries(WMPropList *dest, WMPropList *source,
 783                                   Bool recursive);
 784
 785 /* It will remove all key/value pairs from dest for which there is an
 786  * identical key/value present in source. Entires only present in dest, or
 787  * which have different values in dest than in source will be preserved. */
 788 WMPropList* WMSubtractPLDictionaries(WMPropList *dest, WMPropList *source,
 789                                      Bool recursive);
 790
 791 int WMGetPropListItemCount(WMPropList *plist);
 792
 793 Bool WMIsPLString(WMPropList *plist);
 794
 795 Bool WMIsPLData(WMPropList *plist);
 796
 797 Bool WMIsPLArray(WMPropList *plist);
 798
 799 Bool WMIsPLDictionary(WMPropList *plist);
 800
 801 Bool WMIsPropListEqualTo(WMPropList *plist, WMPropList *other);
 802
 803 /* Returns a reference. Do not free it! */
 804 char* WMGetFromPLString(WMPropList *plist);
 805
 806 /* Returns a reference. Do not free it! */
 807 WMData* WMGetFromPLData(WMPropList *plist);
 808
 809 /* Returns a reference. Do not free it! */
 810 const unsigned char* WMGetPLDataBytes(WMPropList *plist);
 811
 812 int WMGetPLDataLength(WMPropList *plist);
 813
 814 /* Returns a reference. */
 815 WMPropList* WMGetFromPLArray(WMPropList *plist, int index);
 816
 817 /* Returns a reference. */
 818 WMPropList* WMGetFromPLDictionary(WMPropList *plist, WMPropList *key);
 819
 820 /* Returns a PropList array with all the dictionary keys. Release it when
 821  * you're done. Keys in array are retained from the original dictionary
 822  * not copied and need NOT to be released individually. */
 823 WMPropList* WMGetPLDictionaryKeys(WMPropList *plist);
 824
 825 /* Creates only the first level deep object. All the elements inside are
 826  * retained from the original */
 827 WMPropList* WMShallowCopyPropList(WMPropList *plist);
 828
 829 /* Makes a completely separate replica of the original proplist */
 830 WMPropList* WMDeepCopyPropList(WMPropList *plist);
 831
 832 WMPropList* WMCreatePropListFromDescription(char *desc);
 833
 834 /* Free the returned string when you no longer need it */
 835 char* WMGetPropListDescription(WMPropList *plist, Bool indented);
 836
 837 WMPropList* WMReadPropListFromFile(char *file);
 838
 839 Bool WMWritePropListToFile(WMPropList *plist, char *path, Bool atomically);
 840
 841 /*......................................................................*/
 842
 843 WMUserDefaults* WMGetStandardUserDefaults(void);
 844
 845 WMUserDefaults* WMGetDefaultsFromPath(char *path);
 846
 847 void WMSynchronizeUserDefaults(WMUserDefaults *database);
 848
 849 void WMSaveUserDefaults(WMUserDefaults *database);
 850
 851 void WMEnableUDPeriodicSynchronization(WMUserDefaults *database, Bool enable);
 852
 853 /* Returns a WMPropList array with all the keys in the user defaults database.
 854  * Free the array with WMReleasePropList() when no longer needed.
 855  * Keys in array are just retained references to the original keys */
 856 WMPropList* WMGetUDKeys(WMUserDefaults *database);
 857
 858 WMPropList* WMGetUDObjectForKey(WMUserDefaults *database, char *defaultName);
 859
 860 void WMSetUDObjectForKey(WMUserDefaults *database, WMPropList *object,
 861                          char *defaultName);
 862
 863 void WMRemoveUDObjectForKey(WMUserDefaults *database, char *defaultName);
 864
 865 char* WMGetUDStringForKey(WMUserDefaults *database, char *defaultName);
 866
 867 int WMGetUDIntegerForKey(WMUserDefaults *database, char *defaultName);
 868
 869 float WMGetUDFloatForKey(WMUserDefaults *database, char *defaultName);
 870
 871 Bool WMGetUDBoolForKey(WMUserDefaults *database, char *defaultName);
 872
 873 void WMSetUDStringForKey(WMUserDefaults *database, char *value,
 874                          char *defaultName);
 875
 876 void WMSetUDIntegerForKey(WMUserDefaults *database, int value,
 877                           char *defaultName);
 878
 879 void WMSetUDFloatForKey(WMUserDefaults *database, float value,
 880                         char *defaultName);
 881
 882 void WMSetUDBoolForKey(WMUserDefaults *database, Bool value,
 883                        char *defaultName);
 884
 885 WMPropList* WMGetUDSearchList(WMUserDefaults *database);
 886
 887 void WMSetUDSearchList(WMUserDefaults *database, WMPropList *list);
 888
 889 extern char *WMUserDefaultsDidChangeNotification;
 890
 891
 892 /*-------------------------------------------------------------------------*/
 893
 894 /* WMHost: host handling */
 895
 896 WMHost* WMGetCurrentHost();
 897
 898 WMHost* WMGetHostWithName(char* name);
 899
 900 WMHost* WMGetHostWithAddress(char* address);
 901
 902 WMHost* WMRetainHost(WMHost *hPtr);
 903
 904 void WMReleaseHost(WMHost *hPtr);
 905
 906 /*
 907  * Host cache management
 908  * If enabled, only one object representing each host will be created, and
 909  * a shared instance will be returned by all methods that return a host.
 910  * Enabled by default.
 911  */
 912 void WMSetHostCacheEnabled(Bool flag);
 913
 914 Bool WMIsHostCacheEnabled();
 915
 916 void WMFlushHostCache();
 917
 918 /*
 919  * Compare hosts: Hosts are equal if they share at least one address
 920  */
 921 Bool WMIsHostEqualToHost(WMHost* hPtr, WMHost* anotherHost);
 922
 923 /*
 924  * Host names.
 925  * WMGetHostName() will return first name (official) if a host has several.
 926  * WMGetHostNames() will return a R/O WMArray with all the names of the host.
 927  */
 928 char* WMGetHostName(WMHost* hPtr);
 929
 930 /* The returned array is R/O. Do not modify it, and do not free it! */
 931 WMArray* WMGetHostNames(WMHost* hPtr);
 932
 933 /*
 934  * Host addresses.
 935  * Addresses are represented as "Dotted Decimal" strings, e.g. "192.42.172.1"
 936  * WMGetHostAddress() will return an arbitrary address if a host has several.
 937  * WMGetHostAddresses() will return a R/O WMArray with all addresses of the host.
 938  */
 939 char* WMGetHostAddress(WMHost* hPtr);
 940
 941 /* The returned array is R/O. Do not modify it, and do not free it! */
 942 WMArray* WMGetHostAddresses(WMHost* hPtr);
 943
 944
 945 /*-------------------------------------------------------------------------*/
 946
 947 /* WMConnection functions */
 948
 949 WMConnection* WMCreateConnectionAsServerAtAddress(char *host, char *service,
 950                                                   char *protocol);
 951
 952 WMConnection* WMCreateConnectionToAddress(char *host, char *service,
 953                                           char *protocol);
 954
 955 WMConnection* WMCreateConnectionToAddressAndNotify(char *host, char *service,
 956                                                    char *protocol);
 957
 958 void WMCloseConnection(WMConnection *cPtr);
 959
 960 void WMDestroyConnection(WMConnection *cPtr);
 961
 962 WMConnection* WMAcceptConnection(WMConnection *listener);
 963
 964 /* Release the returned data! */
 965 WMData* WMGetConnectionAvailableData(WMConnection *cPtr);
 966
 967 int WMSendConnectionData(WMConnection *cPtr, WMData *data);
 968
 969 Bool WMEnqueueConnectionData(WMConnection *cPtr, WMData *data);
 970
 971 #define WMFlushConnection(cPtr)  WMSendConnectionData((cPtr), NULL)
 972
 973 void WMSetConnectionDelegate(WMConnection *cPtr, ConnectionDelegate *delegate);
 974
 975 /* Connection info */
 976
 977 char* WMGetConnectionAddress(WMConnection *cPtr);
 978
 979 char* WMGetConnectionService(WMConnection *cPtr);
 980
 981 char* WMGetConnectionProtocol(WMConnection *cPtr);
 982
 983 Bool WMSetConnectionNonBlocking(WMConnection *cPtr, Bool flag);
 984
 985 Bool WMSetConnectionCloseOnExec(WMConnection *cPtr, Bool flag);
 986
 987 void WMSetConnectionShutdownOnClose(WMConnection *cPtr, Bool flag);
 988
 989 void* WMGetConnectionClientData(WMConnection *cPtr);
 990
 991 void WMSetConnectionClientData(WMConnection *cPtr, void *data);
 992
 993 unsigned int WMGetConnectionFlags(WMConnection *cPtr);
 994
 995 void WMSetConnectionFlags(WMConnection *cPtr, unsigned int flags);
 996
 997 int WMGetConnectionSocket(WMConnection *cPtr);
 998
 999 WMConnectionState WMGetConnectionState(WMConnection *cPtr);
1000
1001 WMConnectionTimeoutState WMGetConnectionTimeoutState(WMConnection *cPtr);
1002
1003 WMArray* WMGetConnectionUnsentData(WMConnection *cPtr);
1004
1005 #define WMGetConnectionQueuedData(cPtr) WMGetConnectionUnsentData(cPtr)
1006
1007
1008 /*
1009  * Passing timeout==0 in the SetTimeout functions below, will reset that
1010  * timeout to its default value.
1011  */
1012
1013 /* The default timeout inherited by all WMConnection operations, if none set */
1014 void WMSetConnectionDefaultTimeout(unsigned int timeout);
1015
1016 /* Global timeout for all WMConnection objects, for opening a new connection */
1017 void WMSetConnectionOpenTimeout(unsigned int timeout);
1018
1019 /* Connection specific timeout for sending out data */
1020 void WMSetConnectionSendTimeout(WMConnection *cPtr, unsigned int timeout);
1021
1022
1023 /* Global variables */
1024
1025 extern int WCErrorCode;
1026
1027
1028 /*-------------------------------------------------------------------------*/
1029
1030
1031
1032 #ifdef __cplusplus
1033 }
1034 #endif /* __cplusplus */
1035
1036
1037 #endif