WINGs/WUtil.h

   1 #ifndef _WUTIL_H_
   2 #define _WUTIL_H_
   3
   4 #include <X11/Xlib.h>
   5
   6 #include <sys/types.h>
   7
   8 /* SunOS 4.x Blargh.... */
   9 #ifndef NULL
  10 #define NULL ((void*)0)
  11 #endif
  12
  13
  14 /*
  15  * Warning: proplist.h #defines BOOL which will clash with the
  16  * typedef BOOL in Xmd.h
  17  * proplist.h should use Bool (which is a #define in Xlib.h) instead.
  18  *
  19  */
  20 #include <proplist.h>
  21
  22
  23 #ifndef WMAX
  24 # define WMAX(a,b)      ((a)>(b) ? (a) : (b))
  25 #endif
  26 #ifndef WMIN
  27 # define WMIN(a,b)      ((a)<(b) ? (a) : (b))
  28 #endif
  29
  30
  31 #if (!defined (__GNUC__) || __GNUC__ < 2 || \
  32      __GNUC_MINOR__ < (defined (__cplusplus) ? 6 : 4))
  33 #define __ASSERT_FUNCTION       ((char *) 0)
  34 #else
  35 #define __ASSERT_FUNCTION       __PRETTY_FUNCTION__
  36 #endif
  37
  38
  39 #ifdef NDEBUG
  40
  41 #define wassertr(expr)          {}
  42 #define wassertrv(expr, val)    {}
  43
  44 #else /* !NDEBUG */
  45
  46 #ifdef DEBUG
  47
  48 #include <assert.h>
  49
  50 #define wassertr(expr)  assert(expr)
  51
  52 #define wassertrv(expr, val)    assert(expr)
  53
  54 #else /* !DEBUG */
  55
  56 #define wassertr(expr) \
  57         if (!(expr)) { \
  58                 wwarning("%s line %i (%s): assertion %s failed",\
  59                         __FILE__, __LINE__, __ASSERT_FUNCTION, #expr);\
  60                 return;\
  61         }
  62
  63 #define wassertrv(expr, val) \
  64         if (!(expr)) { \
  65                 wwarning("%s line %i (%s): assertion %s failed",\
  66                         __FILE__, __LINE__, __ASSERT_FUNCTION, #expr);\
  67                 return (val);\
  68         }
  69 #endif /* !DEBUG */
  70
  71 #endif /* !NDEBUG */
  72
  73
  74 #ifdef __cplusplus
  75 extern "C" {
  76 #endif /* __cplusplus */
  77
  78
  79 typedef enum {
  80     WMPostWhenIdle = 1,
  81         WMPostASAP = 2,
  82         WMPostNow = 3
  83 } WMPostingStyle;
  84
  85
  86 typedef enum {
  87     WNCNone = 0,
  88         WNCOnName = 1,
  89         WNCOnSender = 2
  90 } WMNotificationCoalescing;
  91
  92
  93 /* The possible states for connections */
  94 typedef enum {
  95     WCNotConnected=0,
  96     WCListening,
  97     WCInProgress,
  98     WCFailed,
  99     WCConnected,
 100     WCDied,
 101     WCClosed
 102 } WMConnectionState;
 103
 104
 105 typedef struct W_Bag WMBag;
 106 typedef struct W_Data WMData;
 107 typedef struct W_HashTable WMHashTable;
 108 typedef struct W_UserDefaults WMUserDefaults;
 109 typedef struct W_Notification WMNotification;
 110 typedef struct W_NotificationQueue WMNotificationQueue;
 111 typedef struct W_Host WMHost;
 112 typedef struct W_Connection WMConnection;
 113
 114
 115
 116 typedef struct {
 117     int position;
 118     int count;
 119 } WMRange;
 120
 121
 122
 123 /* DO NOT ACCESS THE CONTENTS OF THIS STRUCT */
 124 typedef struct {
 125     void *table;
 126     void *nextItem;
 127     int index;
 128 } WMHashEnumerator;
 129
 130
 131 typedef struct {
 132     /* NULL is pointer hash */
 133     unsigned    (*hash)(const void *);
 134     /* NULL is pointer compare */
 135     Bool        (*keyIsEqual)(const void *, const void *);
 136     /* NULL does nothing */
 137     void*       (*retainKey)(const void *);
 138     /* NULL does nothing */
 139     void        (*releaseKey)(const void *);
 140 } WMHashTableCallbacks;
 141
 142
 143 typedef struct W_BagFunctions {
 144     int (*getItemCount)(WMBag *self);
 145     int (*appendBag)(WMBag *self, WMBag *bag);
 146     int (*putInBag)(WMBag *self, void *item);
 147     int (*insertInBag)(WMBag *self, int index, void *item);
 148     int (*removeFromBag)(WMBag *bag, void *item);
 149     int (*deleteFromBag)(WMBag *bag, int index);
 150     void *(*getFromBag)(WMBag *bag, int index);
 151     int (*firstInBag)(WMBag *bag, void *item);
 152     int (*countInBag)(WMBag *bag, void *item);
 153     void *(*replaceInBag)(WMBag *bag, int index, void *item);
 154     void (*sortBag)(WMBag *bag, int (*comparer)(const void*, const void*));
 155     void (*emptyBag)(WMBag *bag);
 156     void (*freeBag)(WMBag *bag);
 157     WMBag *(*mapBag)(WMBag *bag, void * (*function)(void*));
 158     int (*findInBag)(WMBag *bag, int (*match)(void*));
 159     void *(*first)(WMBag *bag, void **ptr);
 160     void *(*last)(WMBag *bag, void **ptr);
 161     void *(*next)(WMBag *bag, void **ptr);
 162     void *(*previous)(WMBag *bag, void **ptr);
 163 } W_BagFunctions;
 164
 165
 166 struct W_Bag {
 167     void *data;
 168
 169     void (*destructor)(void *item);
 170
 171     W_BagFunctions func;
 172 };
 173
 174
 175
 176 #if 0
 177 typedef struct {
 178     char character;                    /* the escape character */
 179     char *value;                       /* value to place */
 180 } WMSEscapes;
 181 #endif
 182
 183
 184 /* The connection callbacks */
 185 typedef struct ConnectionDelegate {
 186     void *data;
 187
 188     void (*didCatchException)(struct ConnectionDelegate *self,
 189                               WMConnection *cPtr);
 190
 191     void (*didDie)(struct ConnectionDelegate *self, WMConnection *cPtr);
 192
 193     void (*didInitialize)(struct ConnectionDelegate *self, WMConnection *cPtr);
 194
 195     void (*didReceiveInput)(struct ConnectionDelegate *self, WMConnection *cPtr);
 196
 197     void (*didTimeout)(struct ConnectionDelegate *self, WMConnection *cPtr);
 198
 199 } ConnectionDelegate;
 200
 201
 202 typedef void WMNotificationObserverAction(void *observerData,
 203                                           WMNotification *notification);
 204
 205
 206
 207 /*......................................................................*/
 208
 209 typedef void (waborthandler)(int);
 210
 211 waborthandler *wsetabort(waborthandler*);
 212
 213
 214 /* don't free the returned string */
 215 char *wstrerror(int errnum);
 216
 217 void wfatal(const char *msg, ...);
 218 void wwarning(const char *msg, ...);
 219 void wsyserror(const char *msg, ...);
 220 void wsyserrorwithcode(int error, const char *msg, ...);
 221
 222 char *wfindfile(char *paths, char *file);
 223
 224 char *wfindfileinlist(char **path_list, char *file);
 225
 226 char *wfindfileinarray(proplist_t array, char *file);
 227
 228 char *wexpandpath(char *path);
 229
 230 /* don't free the returned string */
 231 char *wgethomedir();
 232
 233 void *wmalloc(size_t size);
 234 void *wrealloc(void *ptr, size_t newsize);
 235 void wfree(void *ptr);
 236
 237
 238 void wrelease(void *ptr);
 239 void *wretain(void *ptr);
 240
 241 char *wstrdup(char *str);
 242
 243 char *wstrappend(char *dst, char *src);
 244
 245 char *wusergnusteppath();
 246
 247 char *wdefaultspathfordomain(char *domain);
 248
 249 void wusleep(unsigned int microsec);
 250
 251 #if 0
 252 int wsprintesc(char *buffer, int length, char *format, WMSEscapes **escapes,
 253                int count);
 254 #endif
 255
 256 /*......................................................................*/
 257
 258 /* This function is used _only_ if you create a NON-GUI program.
 259  * For GUI based programs use WMNextEvent()/WMHandleEvent() instead.
 260  * This function will handle all input/timer/idle events, then return.
 261  */
 262
 263 void WHandleEvents();
 264
 265 /*......................................................................*/
 266
 267
 268 WMHashTable *WMCreateHashTable(WMHashTableCallbacks callbacks);
 269
 270 void WMFreeHashTable(WMHashTable *table);
 271
 272 void WMResetHashTable(WMHashTable *table);
 273
 274 void *WMHashGet(WMHashTable *table, const void *key);
 275
 276 /* put data in table, replacing already existing data and returning
 277  * the old value */
 278 void *WMHashInsert(WMHashTable *table, void *key, void *data);
 279
 280 void WMHashRemove(WMHashTable *table, const void *key);
 281
 282 /* warning: do not manipulate the table while using these functions */
 283 WMHashEnumerator WMEnumerateHashTable(WMHashTable *table);
 284
 285 void *WMNextHashEnumeratorItem(WMHashEnumerator *enumerator);
 286
 287 unsigned WMCountHashTable(WMHashTable *table);
 288
 289
 290
 291
 292 /* some predefined callback sets */
 293
 294 extern const WMHashTableCallbacks WMIntHashCallbacks;
 295 /* sizeof(keys) are <= sizeof(void*) */
 296
 297 extern const WMHashTableCallbacks WMStringHashCallbacks;
 298 /* keys are strings. Strings will be copied with wstrdup()
 299  * and freed with free() */
 300
 301 extern const WMHashTableCallbacks WMStringPointerHashCallbacks;
 302 /* keys are strings, bug they are not copied */
 303
 304
 305 /*......................................................................*/
 306
 307
 308 WMBag* WMCreateArrayBag(int size);
 309 WMBag* WMCreateArrayBagWithDestructor(int size, void (*destructor)(void*));
 310
 311
 312 WMBag *WMCreateListBag(void);
 313 WMBag *WMCreateListBagWithDestructor(void (*destructor)(void*));
 314
 315 #define WMCreateBag(size) WMCreateArrayBag(size)
 316
 317 #define WMGetBagItemCount(bag) bag->func.getItemCount(bag)
 318
 319 #define WMAppendBag(bag, other) bag->func.appendBag(bag, other)
 320
 321 #define WMPutInBag(bag, item) bag->func.putInBag(bag, item)
 322
 323 #define WMInsertInBag(bag, index, item) bag->func.insertInBag(bag, index, item)
 324
 325 #define WMRemoveFromBag(bag, item) bag->func.removeFromBag(bag, item)
 326
 327 #define WMDeleteFromBag(bag, index) bag->func.deleteFromBag(bag, index)
 328
 329 #define WMGetFromBag(bag, index) bag->func.getFromBag(bag, index)
 330
 331 #define WMCountInBag(bag, item) bag->func.countInBag(bag, item)
 332
 333 #define WMReplaceInBag(bag, index, item) bag->func.replaceInBag(bag, index, item)
 334
 335 /* comparer must return:
 336  * < 0 if a < b
 337  * > 0 if a > b
 338  * = 0 if a = b
 339  */
 340 #define WMSortBag(bag, comparer) bag->func.sortBag(bag, comparer)
 341
 342 #define WMEmptyBag(bag) bag->func.emptyBag(bag)
 343
 344 #define WMFreeBag(bag) bag->func.freeBag(bag)
 345
 346 #define WMMapBag(bag, function) bag->func.mapBag(bag, function)
 347
 348 #define WMGetFirstInBag(bag, item) bag->func.firstInBag(bag, item)
 349
 350 #define WMCountInBag(bag, item) bag->func.countInBag(bag, item)
 351
 352 #define WMFindInBag(bag, match) bag->func.findInBag(bag, match)
 353
 354 #define WMBagFirst(bag, ptr) bag->func.first(bag, ptr)
 355
 356 #define WMBagLast(bag, ptr) bag->func.last(bag, ptr)
 357
 358 #define WMBagNext(bag, ptr) bag->func.next(bag, ptr)
 359
 360 #define WMBagPrevious(bag, ptr) bag->func.previous(bag, ptr)
 361
 362
 363 /*-------------------------------------------------------------------------*/
 364
 365 /* WMData handling */
 366
 367 /* Creating/destroying data */
 368
 369 WMData* WMCreateDataWithCapacity(unsigned capacity);
 370
 371 WMData* WMCreateDataWithLength(unsigned length);
 372
 373 WMData* WMCreateDataWithBytes(void *bytes, unsigned length);
 374
 375 WMData* WMCreateDataWithBytesNoCopy(void *bytes, unsigned length);
 376
 377 WMData* WMCreateDataWithData(WMData *aData);
 378
 379 WMData* WMRetainData(WMData *aData);
 380
 381 void WMReleaseData(WMData *aData);
 382
 383 /* Adjusting capacity */
 384
 385 void WMSetDataCapacity(WMData *aData, unsigned capacity);
 386
 387 void WMSetDataLength(WMData *aData, unsigned length);
 388
 389 void WMIncreaseDataLengthBy(WMData *aData, unsigned extraLength);
 390
 391 /* Accessing data */
 392
 393 const void* WMDataBytes(WMData *aData);
 394
 395 void WMGetDataBytes(WMData *aData, void *buffer);
 396
 397 void WMGetDataBytesWithLength(WMData *aData, void *buffer, unsigned length);
 398
 399 void WMGetDataBytesWithRange(WMData *aData, void *buffer, WMRange aRange);
 400
 401 WMData* WMGetSubdataWithRange(WMData *aData, WMRange aRange);
 402
 403 /* Testing data */
 404
 405 Bool WMIsDataEqualToData(WMData *aData, WMData *anotherData);
 406
 407 unsigned WMGetDataLength(WMData *aData);
 408
 409 unsigned WMGetDataHash(WMData *aData);
 410
 411 /* Adding data */
 412
 413 void WMAppendDataBytes(WMData *aData, void *bytes, unsigned length);
 414
 415 void WMAppendData(WMData *aData, WMData *anotherData);
 416
 417 /* Modifying data */
 418
 419 void WMReplaceDataBytesInRange(WMData *aData, WMRange aRange, void *bytes);
 420
 421 void WMResetDataBytesInRange(WMData *aData, WMRange aRange);
 422
 423 void WMSetData(WMData *aData, WMData *anotherData);
 424
 425 /* Storing data */
 426
 427
 428 /*--------------------------------------------------------------------------*/
 429
 430
 431 WMNotification *WMCreateNotification(char *name, void *object, void *clientData);
 432
 433 void WMReleaseNotification(WMNotification *notification);
 434
 435 WMNotification *WMRetainNotification(WMNotification *notification);
 436
 437 void *WMGetNotificationClientData(WMNotification *notification);
 438
 439 void *WMGetNotificationObject(WMNotification *notification);
 440
 441 char *WMGetNotificationName(WMNotification *notification);
 442
 443
 444 void WMAddNotificationObserver(WMNotificationObserverAction *observerAction,
 445                                void *observer, char *name, void *object);
 446
 447 void WMPostNotification(WMNotification *notification);
 448
 449 void WMRemoveNotificationObserver(void *observer);
 450
 451 void WMRemoveNotificationObserverWithName(void *observer, char *name,
 452                                           void *object);
 453
 454 void WMPostNotificationName(char *name, void *object, void *clientData);
 455
 456 WMNotificationQueue *WMGetDefaultNotificationQueue(void);
 457
 458 WMNotificationQueue *WMCreateNotificationQueue(void);
 459
 460 void WMDequeueNotificationMatching(WMNotificationQueue *queue,
 461                                    WMNotification *notification,
 462                                    unsigned mask);
 463
 464 void WMEnqueueNotification(WMNotificationQueue *queue,
 465                            WMNotification *notification,
 466                            WMPostingStyle postingStyle);
 467
 468 void WMEnqueueCoalesceNotification(WMNotificationQueue *queue,
 469                                    WMNotification *notification,
 470                                    WMPostingStyle postingStyle,
 471                                    unsigned coalesceMask);
 472
 473
 474 /*......................................................................*/
 475
 476 WMUserDefaults *WMGetStandardUserDefaults(void);
 477
 478 WMUserDefaults *WMGetDefaultsFromPath(char *path);
 479
 480 void WMSynchronizeUserDefaults(WMUserDefaults *database);
 481
 482 void WMSaveUserDefaults(WMUserDefaults *database);
 483
 484 void WMEnableUDPeriodicSynchronization(WMUserDefaults *database, Bool enable);
 485
 486 proplist_t WMGetUDObjectForKey(WMUserDefaults *database, char *defaultName);
 487
 488 void WMSetUDObjectForKey(WMUserDefaults *database, proplist_t object,
 489                          char *defaultName);
 490
 491 void WMRemoveUDObjectForKey(WMUserDefaults *database, char *defaultName);
 492
 493 /* you can free the returned string */
 494 char *WMGetUDStringForKey(WMUserDefaults *database, char *defaultName);
 495
 496 int WMGetUDIntegerForKey(WMUserDefaults *database, char *defaultName);
 497
 498 float WMGetUDFloatForKey(WMUserDefaults *database, char *defaultName);
 499
 500 Bool WMGetUDBoolForKey(WMUserDefaults *database, char *defaultName);
 501
 502 void WMSetUDStringForKey(WMUserDefaults *database, char *value,
 503                          char *defaultName);
 504
 505 void WMSetUDIntegerForKey(WMUserDefaults *database, int value,
 506                           char *defaultName);
 507
 508 void WMSetUDFloatForKey(WMUserDefaults *database, float value,
 509                         char *defaultName);
 510
 511 void WMSetUDBoolForKey(WMUserDefaults *database, Bool value,
 512                        char *defaultName);
 513
 514 proplist_t WMGetUDSearchList(WMUserDefaults *database);
 515
 516 void WMSetUDSearchList(WMUserDefaults *database, proplist_t list);
 517
 518 extern char *WMUserDefaultsDidChangeNotification;
 519
 520
 521 /*-------------------------------------------------------------------------*/
 522
 523 /* WMHost: host handling */
 524
 525 WMHost* WMGetCurrentHost();
 526
 527 WMHost* WMGetHostWithName(char* name);
 528
 529 WMHost* WMGetHostWithAddress(char* address);
 530
 531 WMHost* WMRetainHost(WMHost *hPtr);
 532
 533 void WMReleaseHost(WMHost *hPtr);
 534
 535 /*
 536  * Host cache management
 537  * If enabled, only one object representing each host will be created, and
 538  * a shared instance will be returned by all methods that return a host.
 539  * Enabled by default.
 540  */
 541 void WMSetHostCacheEnabled(Bool flag);
 542
 543 Bool WMIsHostCacheEnabled();
 544
 545 void WMFlushHostCache();
 546
 547 /*
 548  * Compare hosts: Hosts are equal if they share at least one address
 549  */
 550 Bool WMIsHostEqualToHost(WMHost* hPtr, WMHost* anotherHost);
 551
 552 /*
 553  * Host names.
 554  * WMGetHostName() will return first name (official) if a host has several.
 555  * WMGetHostNames() will return a R/O WMBag with all the names of the host.
 556  */
 557 char* WMGetHostName(WMHost* hPtr);
 558
 559 /* The returned bag is R/O. Do not modify it, and do not free it! */
 560 WMBag* WMGetHostNames(WMHost* hPtr);
 561
 562 /*
 563  * Host addresses.
 564  * Addresses are represented as "Dotted Decimal" strings, e.g. "192.42.172.1"
 565  * WMGetHostAddress() will return an arbitrary address if a host has several.
 566  * WMGetHostAddresses() will return a R/O WMBag with all addresses of the host.
 567  */
 568 char* WMGetHostAddress(WMHost* hPtr);
 569
 570 /* The returned bag is R/O. Do not modify it, and do not free it! */
 571 WMBag* WMGetHostAddresses(WMHost* hPtr);
 572
 573
 574 /*-------------------------------------------------------------------------*/
 575
 576 /* WMConnection functions */
 577
 578 WMConnection* WMCreateConnectionAsServerAtAddress(char *host, char *service,
 579                                                   char *protocol);
 580
 581 WMConnection* WMCreateConnectionToAddress(char *host, char *service,
 582                                           char *protocol);
 583
 584 WMConnection* WMCreateConnectionToAddressAndNotify(char *host, char *service,
 585                                                    char *protocol);
 586
 587 void WMCloseConnection(WMConnection *cPtr);
 588
 589 void WMDestroyConnection(WMConnection *cPtr);
 590
 591 WMConnection* WMAcceptConnection(WMConnection *listener);
 592
 593 /* Release the returned data! */
 594 WMData* WMGetConnectionAvailableData(WMConnection *cPtr);
 595
 596 int WMSendConnectionData(WMConnection *cPtr, WMData *data);
 597
 598 Bool WMEnqueueConnectionData(WMConnection *cPtr, WMData *data);
 599
 600 #define WMFlushConnection(cPtr)  WMSendConnectionData((cPtr), NULL)
 601
 602 void WMSetConnectionDelegate(WMConnection *cPtr, ConnectionDelegate *delegate);
 603
 604 /* Connection info */
 605
 606 char* WMGetConnectionAddress(WMConnection *cPtr);
 607
 608 char* WMGetConnectionService(WMConnection *cPtr);
 609
 610 char* WMGetConnectionProtocol(WMConnection *cPtr);
 611
 612 void WMSetConnectionNonBlocking(WMConnection *cPtr, Bool flag);
 613
 614 void* WMGetConnectionClientData(WMConnection *cPtr);
 615
 616 void WMSetConnectionClientData(WMConnection *cPtr, void *data);
 617
 618 unsigned int WMGetConnectionFlags(WMConnection *cPtr);
 619
 620 void WMSetConnectionFlags(WMConnection *cPtr, unsigned int flags);
 621
 622 int WMGetConnectionSocket(WMConnection *cPtr);
 623
 624 WMConnectionState WMGetConnectionState(WMConnection *cPtr);
 625
 626 void WMSetConnectionSendTimeout(WMConnection *cPtr, unsigned int timeout);
 627
 628
 629 /* Global variables */
 630
 631 extern int WCErrorCode;
 632
 633
 634 /*-------------------------------------------------------------------------*/
 635
 636
 637
 638 #ifdef __cplusplus
 639 }
 640 #endif /* __cplusplus */
 641
 642
 643 #endif