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  * Warning: proplist.h #defines BOOL which will clash with the
  15  * typedef BOOL in Xmd.h
  16  * proplist.h should use Bool (which is a #define in Xlib.h) instead.
  17  *
  18  */
  19 #include <proplist.h>
  20
  21
  22 #ifndef WMAX
  23 # define WMAX(a,b)      ((a)>(b) ? (a) : (b))
  24 #endif
  25 #ifndef WMIN
  26 # define WMIN(a,b)      ((a)<(b) ? (a) : (b))
  27 #endif
  28
  29
  30 #if (!defined (__GNUC__) || __GNUC__ < 2 || \
  31      __GNUC_MINOR__ < (defined (__cplusplus) ? 6 : 4))
  32 #define __ASSERT_FUNCTION       ((char *) 0)
  33 #else
  34 #define __ASSERT_FUNCTION       __PRETTY_FUNCTION__
  35 #endif
  36
  37
  38 #ifdef NDEBUG
  39
  40 #define wassertr(expr)          {}
  41 #define wassertrv(expr, val)    {}
  42
  43 #else /* !NDEBUG */
  44
  45 #ifdef DEBUG
  46
  47 #include <assert.h>
  48
  49 #define wassertr(expr)  assert(expr)
  50
  51 #define wassertrv(expr, val)    assert(expr)
  52
  53 #else /* !DEBUG */
  54
  55 #define wassertr(expr) \
  56         if (!(expr)) { \
  57                 wwarning("%s line %i (%s): assertion %s failed",\
  58                         __FILE__, __LINE__, __ASSERT_FUNCTION, #expr);\
  59                 return;\
  60         }
  61
  62 #define wassertrv(expr, val) \
  63         if (!(expr)) { \
  64                 wwarning("%s line %i (%s): assertion %s failed",\
  65                         __FILE__, __LINE__, __ASSERT_FUNCTION, #expr);\
  66                 return (val);\
  67         }
  68 #endif /* !DEBUG */
  69
  70 #endif /* !NDEBUG */
  71
  72
  73 #ifdef __cplusplus
  74 extern "C" {
  75 #endif /* __cplusplus */
  76
  77
  78 typedef enum {
  79     WMPostWhenIdle = 1,
  80         WMPostASAP = 2,
  81         WMPostNow = 3
  82 } WMPostingStyle;
  83
  84
  85 typedef enum {
  86     WNCNone = 0,
  87         WNCOnName = 1,
  88         WNCOnSender = 2
  89 } WMNotificationCoalescing;
  90
  91
  92 /* The possible states for connections */
  93 typedef enum {
  94     WCNotConnected=0,
  95     WCListening,
  96     WCInProgress,
  97     WCFailed,
  98     WCConnected,
  99     WCTimedOut,
 100     WCDied,
 101     WCClosed
 102 } WMConnectionState;
 103
 104
 105 /* The possible states for connection timeouts */
 106 typedef enum {
 107     WCTNone=0,
 108     WCTWhileOpening,
 109     WCTWhileSending
 110 } WMConnectionTimeoutState;
 111
 112
 113
 114 enum {
 115     WBNotFound = INT_MIN /* element was not found in bag */
 116 };
 117
 118
 119 typedef struct W_Array WMArray;
 120 typedef struct W_Bag WMBag;
 121 typedef struct W_Data WMData;
 122 typedef struct W_HashTable WMHashTable;
 123 typedef struct W_UserDefaults WMUserDefaults;
 124 typedef struct W_Notification WMNotification;
 125 typedef struct W_NotificationQueue WMNotificationQueue;
 126 typedef struct W_Host WMHost;
 127 typedef struct W_Connection WMConnection;
 128
 129
 130
 131 typedef void WMFreeDataProc(void *data);
 132
 133
 134
 135 typedef struct {
 136     int position;
 137     int count;
 138 } WMRange;
 139
 140
 141
 142 /* DO NOT ACCESS THE CONTENTS OF THIS STRUCT */
 143 typedef struct {
 144     void *table;
 145     void *nextItem;
 146     int index;
 147 } WMHashEnumerator;
 148
 149
 150 typedef struct {
 151     /* NULL is pointer hash */
 152     unsigned    (*hash)(const void *);
 153     /* NULL is pointer compare */
 154     Bool        (*keyIsEqual)(const void *, const void *);
 155     /* NULL does nothing */
 156     void*       (*retainKey)(const void *);
 157     /* NULL does nothing */
 158     void        (*releaseKey)(const void *);
 159 } WMHashTableCallbacks;
 160
 161
 162 typedef void *WMBagIterator;
 163
 164
 165 #if 0
 166 struct W_Bag {
 167     void *data;
 168
 169     void (*destructor)(void *item);
 170
 171     W_BagFunctions func;
 172 };
 173 #endif
 174
 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 (*didCatchException)(struct ConnectionDelegate *self,
 190                               WMConnection *cPtr);
 191
 192     void (*didDie)(struct ConnectionDelegate *self, WMConnection *cPtr);
 193
 194     void (*didInitialize)(struct ConnectionDelegate *self, WMConnection *cPtr);
 195
 196     void (*didReceiveInput)(struct ConnectionDelegate *self, WMConnection *cPtr);
 197
 198     void (*didTimeout)(struct ConnectionDelegate *self, WMConnection *cPtr);
 199
 200 } ConnectionDelegate;
 201
 202
 203 typedef void WMNotificationObserverAction(void *observerData,
 204                                           WMNotification *notification);
 205
 206
 207
 208 /*......................................................................*/
 209
 210 typedef void (waborthandler)(int);
 211
 212 waborthandler *wsetabort(waborthandler*);
 213
 214
 215 /* don't free the returned string */
 216 char *wstrerror(int errnum);
 217
 218 void wfatal(const char *msg, ...);
 219 void wwarning(const char *msg, ...);
 220 void wsyserror(const char *msg, ...);
 221 void wsyserrorwithcode(int error, const char *msg, ...);
 222
 223 char *wfindfile(char *paths, char *file);
 224
 225 char *wfindfileinlist(char **path_list, char *file);
 226
 227 char *wfindfileinarray(proplist_t array, char *file);
 228
 229 char *wexpandpath(char *path);
 230
 231 /* don't free the returned string */
 232 char *wgethomedir();
 233
 234 void *wmalloc(size_t size);
 235 void *wrealloc(void *ptr, size_t newsize);
 236 void wfree(void *ptr);
 237
 238
 239 void wrelease(void *ptr);
 240 void *wretain(void *ptr);
 241
 242 char *wstrdup(char *str);
 243
 244 char *wstrappend(char *dst, char *src);
 245
 246
 247
 248 void wtokensplit(char *command, char ***argv, int *argc);
 249
 250 char *wtokenjoin(char **list, int count);
 251
 252 void wtokenfree(char **tokens, int count);
 253
 254 char *wtrimspace(char *s);
 255
 256
 257
 258 char *wusergnusteppath();
 259
 260 char *wdefaultspathfordomain(char *domain);
 261
 262 void wusleep(unsigned int microsec);
 263
 264 #if 0
 265 int wsprintesc(char *buffer, int length, char *format, WMSEscapes **escapes,
 266                int count);
 267 #endif
 268
 269 /*......................................................................*/
 270
 271 /* This function is used _only_ if you create a NON-GUI program.
 272  * For GUI based programs use WMNextEvent()/WMHandleEvent() instead.
 273  * This function will handle all input/timer/idle events, then return.
 274  */
 275
 276 void WHandleEvents();
 277
 278 /*......................................................................*/
 279
 280
 281 WMHashTable *WMCreateHashTable(WMHashTableCallbacks callbacks);
 282
 283 void WMFreeHashTable(WMHashTable *table);
 284
 285 void WMResetHashTable(WMHashTable *table);
 286
 287 void *WMHashGet(WMHashTable *table, const void *key);
 288
 289 /* put data in table, replacing already existing data and returning
 290  * the old value */
 291 void *WMHashInsert(WMHashTable *table, void *key, void *data);
 292
 293 void WMHashRemove(WMHashTable *table, const void *key);
 294
 295 /* warning: do not manipulate the table while using these functions */
 296 WMHashEnumerator WMEnumerateHashTable(WMHashTable *table);
 297
 298 void *WMNextHashEnumeratorItem(WMHashEnumerator *enumerator);
 299
 300 unsigned WMCountHashTable(WMHashTable *table);
 301
 302
 303
 304
 305 /* some predefined callback sets */
 306
 307 extern const WMHashTableCallbacks WMIntHashCallbacks;
 308 /* sizeof(keys) are <= sizeof(void*) */
 309
 310 extern const WMHashTableCallbacks WMStringHashCallbacks;
 311 /* keys are strings. Strings will be copied with wstrdup()
 312  * and freed with wfree() */
 313
 314 extern const WMHashTableCallbacks WMStringPointerHashCallbacks;
 315 /* keys are strings, bug they are not copied */
 316
 317
 318 /*......................................................................*/
 319
 320
 321 /*
 322  * Array bags use an array to store the elements.
 323  * Item indexes may be any integer number.
 324  *
 325  * Pros:
 326  * Fast [O(1)] access to elements
 327  * Fast [O(1)] push/pop
 328  *
 329  * Cons:
 330  * A little slower [O(n)] for insertion/deletion of elements that
 331  *      aren't in the end
 332  * Element indexes with large difference will cause large holes
 333  */
 334
 335 /*
 336  * Tree bags use a red-black tree for storage.
 337  * Item indexes may be any integer number.
 338  *
 339  * Pros:
 340  * O(lg n) insertion/deletion/search
 341  * Good for large numbers of elements with sparse indexes
 342  *
 343  * Cons:
 344  * O(lg n) insertion/deletion/search
 345  * Slow for storing small numbers of elements
 346  */
 347
 348 #define WMCreateBag(size) WMCreateTreeBag()
 349
 350 #define WMCreateBagWithDestructor(size, d) WMCreateTreeBagWithDestructor(d)
 351
 352 WMBag* WMCreateTreeBag(void);
 353
 354 WMBag* WMCreateTreeBagWithDestructor(void (*destructor)(void*));
 355
 356 int WMGetBagItemCount(WMBag *self);
 357
 358 int WMAppendBag(WMBag *self, WMBag *bag);
 359
 360 int WMPutInBag(WMBag *self, void *item);
 361
 362 /* insert will increment the index of elements after it by 1 */
 363 int WMInsertInBag(WMBag *self, int index, void *item);
 364
 365 /* this is slow */
 366 /* erase will remove the element from the bag,
 367  * but will keep the index of the other elements unchanged */
 368 int WMEraseFromBag(WMBag *self, int index);
 369
 370 /* delete and remove will remove the elements and cause the elements
 371  * after them to decrement their indexes by 1 */
 372 int WMRemoveFromBag(WMBag *self, void *item);
 373
 374 int WMDeleteFromBag(WMBag *self, int index);
 375
 376 void* WMGetFromBag(WMBag *self, int index);
 377
 378 void* WMReplaceInBag(WMBag *self, int index, void *item);
 379
 380 #define WMSetInBag(bag, index, item) WMReplaceInBag(bag, index, item)
 381
 382 /* comparer must return:
 383  * < 0 if a < b
 384  * > 0 if a > b
 385  * = 0 if a = b
 386  */
 387 int WMSortBag(WMBag *self, int (*comparer)(const void*, const void*));
 388
 389 void WMEmptyBag(WMBag *self);
 390
 391 void WMFreeBag(WMBag *self);
 392
 393 void WMMapBag(WMBag *self, void (*function)(void*, void*), void *data);
 394
 395 int WMGetFirstInBag(WMBag *self, void *item);
 396
 397 int WMCountInBag(WMBag *self, void *item);
 398
 399 int WMFindInBag(WMBag *self, int (*match)(void*,void*), void *cdata);
 400
 401 void* WMBagFirst(WMBag *self, WMBagIterator *ptr);
 402
 403 void* WMBagLast(WMBag *self, WMBagIterator *ptr);
 404
 405 void* WMBagNext(WMBag *self, WMBagIterator *ptr);
 406
 407 void* WMBagPrevious(WMBag *self, WMBagIterator *ptr);
 408
 409 void* WMBagIteratorAtIndex(WMBag *self, int index, WMBagIterator *ptr);
 410
 411 int WMBagIndexForIterator(WMBag *bag, WMBagIterator ptr);
 412
 413
 414 #define WM_ITERATE_BAG(bag, var, i) \
 415         for (var = WMBagFirst(bag, &(i)); (i) != NULL; \
 416                 var = WMBagNext(bag, &(i)))
 417
 418 #define WM_ETARETI_BAG(bag, var, i) \
 419         for (var = WMBagLast(bag, &(i)); (i) != NULL; \
 420                 var = WMBagPrevious(bag, &(i)))
 421
 422
 423
 424 /*-------------------------------------------------------------------------*/
 425
 426 /* WMData handling */
 427
 428 /* Creating/destroying data */
 429
 430 WMData* WMCreateDataWithCapacity(unsigned capacity);
 431
 432 WMData* WMCreateDataWithLength(unsigned length);
 433
 434 WMData* WMCreateDataWithBytes(void *bytes, unsigned length);
 435
 436 /* destructor is a function called to free the data when releasing the data
 437  * object, or NULL if no freeing of data is necesary. */
 438 WMData* WMCreateDataWithBytesNoCopy(void *bytes, unsigned length,
 439                                     WMFreeDataProc *destructor);
 440
 441 WMData* WMCreateDataWithData(WMData *aData);
 442
 443 WMData* WMRetainData(WMData *aData);
 444
 445 void WMReleaseData(WMData *aData);
 446
 447 /* Adjusting capacity */
 448
 449 void WMSetDataCapacity(WMData *aData, unsigned capacity);
 450
 451 void WMSetDataLength(WMData *aData, unsigned length);
 452
 453 void WMIncreaseDataLengthBy(WMData *aData, unsigned extraLength);
 454
 455 /* Accessing data */
 456
 457 const void* WMDataBytes(WMData *aData);
 458
 459 void WMGetDataBytes(WMData *aData, void *buffer);
 460
 461 void WMGetDataBytesWithLength(WMData *aData, void *buffer, unsigned length);
 462
 463 void WMGetDataBytesWithRange(WMData *aData, void *buffer, WMRange aRange);
 464
 465 WMData* WMGetSubdataWithRange(WMData *aData, WMRange aRange);
 466
 467 /* Testing data */
 468
 469 Bool WMIsDataEqualToData(WMData *aData, WMData *anotherData);
 470
 471 unsigned WMGetDataLength(WMData *aData);
 472
 473 /* Adding data */
 474
 475 void WMAppendDataBytes(WMData *aData, void *bytes, unsigned length);
 476
 477 void WMAppendData(WMData *aData, WMData *anotherData);
 478
 479 /* Modifying data */
 480
 481 void WMReplaceDataBytesInRange(WMData *aData, WMRange aRange, void *bytes);
 482
 483 void WMResetDataBytesInRange(WMData *aData, WMRange aRange);
 484
 485 void WMSetData(WMData *aData, WMData *anotherData);
 486
 487
 488 void WMSetDataFormat(WMData *aData, unsigned format);
 489
 490 unsigned WMGetDataFormat(WMData *aData);
 491 /* Storing data */
 492
 493
 494 /*--------------------------------------------------------------------------*/
 495
 496
 497 WMNotification *WMCreateNotification(char *name, void *object, void *clientData);
 498
 499 void WMReleaseNotification(WMNotification *notification);
 500
 501 WMNotification *WMRetainNotification(WMNotification *notification);
 502
 503 void *WMGetNotificationClientData(WMNotification *notification);
 504
 505 void *WMGetNotificationObject(WMNotification *notification);
 506
 507 char *WMGetNotificationName(WMNotification *notification);
 508
 509
 510 void WMAddNotificationObserver(WMNotificationObserverAction *observerAction,
 511                                void *observer, char *name, void *object);
 512
 513 void WMPostNotification(WMNotification *notification);
 514
 515 void WMRemoveNotificationObserver(void *observer);
 516
 517 void WMRemoveNotificationObserverWithName(void *observer, char *name,
 518                                           void *object);
 519
 520 void WMPostNotificationName(char *name, void *object, void *clientData);
 521
 522 WMNotificationQueue *WMGetDefaultNotificationQueue(void);
 523
 524 WMNotificationQueue *WMCreateNotificationQueue(void);
 525
 526 void WMDequeueNotificationMatching(WMNotificationQueue *queue,
 527                                    WMNotification *notification,
 528                                    unsigned mask);
 529
 530 void WMEnqueueNotification(WMNotificationQueue *queue,
 531                            WMNotification *notification,
 532                            WMPostingStyle postingStyle);
 533
 534 void WMEnqueueCoalesceNotification(WMNotificationQueue *queue,
 535                                    WMNotification *notification,
 536                                    WMPostingStyle postingStyle,
 537                                    unsigned coalesceMask);
 538
 539
 540 /*......................................................................*/
 541
 542 WMUserDefaults *WMGetStandardUserDefaults(void);
 543
 544 WMUserDefaults *WMGetDefaultsFromPath(char *path);
 545
 546 void WMSynchronizeUserDefaults(WMUserDefaults *database);
 547
 548 void WMSaveUserDefaults(WMUserDefaults *database);
 549
 550 void WMEnableUDPeriodicSynchronization(WMUserDefaults *database, Bool enable);
 551
 552 /* Returns a PLArray with all keys in the user defaults database.
 553  * Free the returned array with PLRelease() when no longer needed,
 554  * but do not free the elements of the array! They're just references. */
 555 proplist_t WMGetUDAllKeys(WMUserDefaults *database);
 556
 557 proplist_t WMGetUDObjectForKey(WMUserDefaults *database, char *defaultName);
 558
 559 void WMSetUDObjectForKey(WMUserDefaults *database, proplist_t object,
 560                          char *defaultName);
 561
 562 void WMRemoveUDObjectForKey(WMUserDefaults *database, char *defaultName);
 563
 564 char *WMGetUDStringForKey(WMUserDefaults *database, char *defaultName);
 565
 566 int WMGetUDIntegerForKey(WMUserDefaults *database, char *defaultName);
 567
 568 float WMGetUDFloatForKey(WMUserDefaults *database, char *defaultName);
 569
 570 Bool WMGetUDBoolForKey(WMUserDefaults *database, char *defaultName);
 571
 572 void WMSetUDStringForKey(WMUserDefaults *database, char *value,
 573                          char *defaultName);
 574
 575 void WMSetUDIntegerForKey(WMUserDefaults *database, int value,
 576                           char *defaultName);
 577
 578 void WMSetUDFloatForKey(WMUserDefaults *database, float value,
 579                         char *defaultName);
 580
 581 void WMSetUDBoolForKey(WMUserDefaults *database, Bool value,
 582                        char *defaultName);
 583
 584 proplist_t WMGetUDSearchList(WMUserDefaults *database);
 585
 586 void WMSetUDSearchList(WMUserDefaults *database, proplist_t list);
 587
 588 extern char *WMUserDefaultsDidChangeNotification;
 589
 590
 591 /*-------------------------------------------------------------------------*/
 592
 593 /* WMHost: host handling */
 594
 595 WMHost* WMGetCurrentHost();
 596
 597 WMHost* WMGetHostWithName(char* name);
 598
 599 WMHost* WMGetHostWithAddress(char* address);
 600
 601 WMHost* WMRetainHost(WMHost *hPtr);
 602
 603 void WMReleaseHost(WMHost *hPtr);
 604
 605 /*
 606  * Host cache management
 607  * If enabled, only one object representing each host will be created, and
 608  * a shared instance will be returned by all methods that return a host.
 609  * Enabled by default.
 610  */
 611 void WMSetHostCacheEnabled(Bool flag);
 612
 613 Bool WMIsHostCacheEnabled();
 614
 615 void WMFlushHostCache();
 616
 617 /*
 618  * Compare hosts: Hosts are equal if they share at least one address
 619  */
 620 Bool WMIsHostEqualToHost(WMHost* hPtr, WMHost* anotherHost);
 621
 622 /*
 623  * Host names.
 624  * WMGetHostName() will return first name (official) if a host has several.
 625  * WMGetHostNames() will return a R/O WMBag with all the names of the host.
 626  */
 627 char* WMGetHostName(WMHost* hPtr);
 628
 629 /* The returned bag is R/O. Do not modify it, and do not free it! */
 630 WMBag* WMGetHostNames(WMHost* hPtr);
 631
 632 /*
 633  * Host addresses.
 634  * Addresses are represented as "Dotted Decimal" strings, e.g. "192.42.172.1"
 635  * WMGetHostAddress() will return an arbitrary address if a host has several.
 636  * WMGetHostAddresses() will return a R/O WMBag with all addresses of the host.
 637  */
 638 char* WMGetHostAddress(WMHost* hPtr);
 639
 640 /* The returned bag is R/O. Do not modify it, and do not free it! */
 641 WMBag* WMGetHostAddresses(WMHost* hPtr);
 642
 643
 644 /*-------------------------------------------------------------------------*/
 645
 646 /* WMConnection functions */
 647
 648 WMConnection* WMCreateConnectionAsServerAtAddress(char *host, char *service,
 649                                                   char *protocol);
 650
 651 WMConnection* WMCreateConnectionToAddress(char *host, char *service,
 652                                           char *protocol);
 653
 654 WMConnection* WMCreateConnectionToAddressAndNotify(char *host, char *service,
 655                                                    char *protocol);
 656
 657 void WMCloseConnection(WMConnection *cPtr);
 658
 659 void WMDestroyConnection(WMConnection *cPtr);
 660
 661 WMConnection* WMAcceptConnection(WMConnection *listener);
 662
 663 /* Release the returned data! */
 664 WMData* WMGetConnectionAvailableData(WMConnection *cPtr);
 665
 666 int WMSendConnectionData(WMConnection *cPtr, WMData *data);
 667
 668 Bool WMEnqueueConnectionData(WMConnection *cPtr, WMData *data);
 669
 670 #define WMFlushConnection(cPtr)  WMSendConnectionData((cPtr), NULL)
 671
 672 void WMSetConnectionDelegate(WMConnection *cPtr, ConnectionDelegate *delegate);
 673
 674 /* Connection info */
 675
 676 char* WMGetConnectionAddress(WMConnection *cPtr);
 677
 678 char* WMGetConnectionService(WMConnection *cPtr);
 679
 680 char* WMGetConnectionProtocol(WMConnection *cPtr);
 681
 682 void WMSetConnectionNonBlocking(WMConnection *cPtr, Bool flag);
 683
 684 void* WMGetConnectionClientData(WMConnection *cPtr);
 685
 686 void WMSetConnectionClientData(WMConnection *cPtr, void *data);
 687
 688 unsigned int WMGetConnectionFlags(WMConnection *cPtr);
 689
 690 void WMSetConnectionFlags(WMConnection *cPtr, unsigned int flags);
 691
 692 int WMGetConnectionSocket(WMConnection *cPtr);
 693
 694 WMConnectionState WMGetConnectionState(WMConnection *cPtr);
 695
 696 WMConnectionTimeoutState WMGetConnectionTimeoutState(WMConnection *cPtr);
 697
 698 /*
 699  * Passing timeout==0 in the SetTimeout functions below, will reset that
 700  * timeout to its default value.
 701  */
 702
 703 /* The default timeout inherited by all WMConnection operations, if none set */
 704 void WMSetConnectionDefaultTimeout(unsigned int timeout);
 705
 706 /* Global timeout for all WMConnection objects, for opening a new connection */
 707 void WMSetConnectionOpenTimeout(unsigned int timeout);
 708
 709 /* Connection specific timeout for sending out data */
 710 void WMSetConnectionSendTimeout(WMConnection *cPtr, unsigned int timeout);
 711
 712
 713 /* Global variables */
 714
 715 extern int WCErrorCode;
 716
 717
 718 /*-------------------------------------------------------------------------*/
 719
 720
 721
 722 #ifdef __cplusplus
 723 }
 724 #endif /* __cplusplus */
 725
 726
 727 #endif