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
 106 typedef struct W_Bag WMBag; /* equivalent to a linked list or array */
 107 typedef struct W_Data WMData;
 108 typedef struct W_HashTable WMHashTable;
 109 typedef struct W_UserDefaults WMUserDefaults;
 110 typedef struct W_Notification WMNotification;
 111 typedef struct W_NotificationQueue WMNotificationQueue;
 112 typedef struct W_Host WMHost;
 113 typedef struct W_Connection WMConnection;
 114
 115
 116
 117 typedef struct {
 118     int position;
 119     int count;
 120 } WMRange;
 121
 122
 123
 124 /* DO NOT ACCESS THE CONTENTS OF THIS STRUCT */
 125 typedef struct {
 126     void *table;
 127     void *nextItem;
 128     int index;
 129 } WMHashEnumerator;
 130
 131
 132 typedef struct {
 133     /* NULL is pointer hash */
 134     unsigned    (*hash)(const void *);
 135     /* NULL is pointer compare */
 136     Bool        (*keyIsEqual)(const void *, const void *);
 137     /* NULL does nothing */
 138     void*       (*retainKey)(const void *);
 139     /* NULL does nothing */
 140     void        (*releaseKey)(const void *);
 141 } WMHashTableCallbacks;
 142
 143
 144
 145 #if 0
 146 typedef struct {
 147     char character;                    /* the escape character */
 148     char *value;                       /* value to place */
 149 } WMSEscapes;
 150 #endif
 151
 152
 153 /* The connection callbacks */
 154 typedef struct ConnectionDelegate {
 155     void *data;
 156
 157     void (*didCatchException)(struct ConnectionDelegate *self,
 158                               WMConnection *cPtr);
 159
 160     void (*didDie)(struct ConnectionDelegate *self, WMConnection *cPtr);
 161
 162     void (*didInitialize)(struct ConnectionDelegate *self, WMConnection *cPtr);
 163
 164     void (*didReceiveInput)(struct ConnectionDelegate *self, WMConnection *cPtr);
 165
 166     void (*didTimeout)(struct ConnectionDelegate *self, WMConnection *cPtr);
 167
 168 } ConnectionDelegate;
 169
 170
 171 typedef void WMNotificationObserverAction(void *observerData,
 172                                           WMNotification *notification);
 173
 174
 175
 176 /*......................................................................*/
 177
 178 typedef void (waborthandler)(int);
 179
 180 waborthandler *wsetabort(waborthandler*);
 181
 182
 183 /* don't free the returned string */
 184 char *wstrerror(int errnum);
 185
 186 void wfatal(const char *msg, ...);
 187 void wwarning(const char *msg, ...);
 188 void wsyserror(const char *msg, ...);
 189 void wsyserrorwithcode(int error, const char *msg, ...);
 190
 191 char *wfindfile(char *paths, char *file);
 192
 193 char *wfindfileinlist(char **path_list, char *file);
 194
 195 char *wfindfileinarray(proplist_t array, char *file);
 196
 197 char *wexpandpath(char *path);
 198
 199 /* don't free the returned string */
 200 char *wgethomedir();
 201
 202 void *wmalloc(size_t size);
 203 void *wrealloc(void *ptr, size_t newsize);
 204 void wfree(void *ptr);
 205
 206
 207 void wrelease(void *ptr);
 208 void *wretain(void *ptr);
 209
 210 char *wstrdup(char *str);
 211
 212 char *wstrappend(char *dst, char *src);
 213
 214 char *wusergnusteppath();
 215
 216 char *wdefaultspathfordomain(char *domain);
 217
 218 void wusleep(unsigned int microsec);
 219
 220 #if 0
 221 int wsprintesc(char *buffer, int length, char *format, WMSEscapes **escapes,
 222                int count);
 223 #endif
 224
 225 /*......................................................................*/
 226
 227 /* This function is used _only_ if you create a NON-GUI program.
 228  * For GUI based programs use WMNextEvent()/WMHandleEvent() instead.
 229  * This function will handle all input/timer/idle events, then return.
 230  */
 231
 232 void WHandleEvents();
 233
 234 /*......................................................................*/
 235
 236
 237 WMHashTable *WMCreateHashTable(WMHashTableCallbacks callbacks);
 238
 239 void WMFreeHashTable(WMHashTable *table);
 240
 241 void WMResetHashTable(WMHashTable *table);
 242
 243 void *WMHashGet(WMHashTable *table, const void *key);
 244
 245 /* put data in table, replacing already existing data and returning
 246  * the old value */
 247 void *WMHashInsert(WMHashTable *table, void *key, void *data);
 248
 249 void WMHashRemove(WMHashTable *table, const void *key);
 250
 251 /* warning: do not manipulate the table while using these functions */
 252 WMHashEnumerator WMEnumerateHashTable(WMHashTable *table);
 253
 254 void *WMNextHashEnumeratorItem(WMHashEnumerator *enumerator);
 255
 256 unsigned WMCountHashTable(WMHashTable *table);
 257
 258
 259
 260
 261 /* some predefined callback sets */
 262
 263 extern const WMHashTableCallbacks WMIntHashCallbacks;
 264 /* sizeof(keys) are <= sizeof(void*) */
 265
 266 extern const WMHashTableCallbacks WMStringHashCallbacks;
 267 /* keys are strings. Strings will be copied with wstrdup()
 268  * and freed with free() */
 269
 270 extern const WMHashTableCallbacks WMStringPointerHashCallbacks;
 271 /* keys are strings, bug they are not copied */
 272
 273
 274 /*......................................................................*/
 275
 276
 277 WMBag *WMCreateBag(int size);
 278
 279 int WMGetBagItemCount(WMBag *bag);
 280
 281 void WMAppendBag(WMBag *bag, WMBag *appendedBag);
 282
 283 void WMPutInBag(WMBag *bag, void *item);
 284
 285 void WMInsertInBag(WMBag *bag, int index, void *item);
 286
 287 int WMGetFirstInBag(WMBag *bag, void *item);
 288
 289 int WMGetLastInBag(WMBag *bag, void *item);
 290
 291 void WMRemoveFromBag(WMBag *bag, void *item);
 292
 293 void WMDeleteFromBag(WMBag *bag, int index);
 294
 295 void *WMGetFromBag(WMBag *bag, int index);
 296
 297 int WMCountInBag(WMBag *bag, void *item);
 298
 299 void *WMReplaceInBag(WMBag *bag, int index, void *item);
 300
 301 /* comparer must return:
 302  * < 0 if a < b
 303  * > 0 if a > b
 304  * = 0 if a = b
 305  */
 306 void WMSortBag(WMBag *bag, int (*comparer)(const void*, const void*));
 307
 308 void WMEmptyBag(WMBag *bag);
 309
 310 void WMFreeBag(WMBag *bag);
 311
 312 WMBag *WMMapBag(WMBag *bag, void* (*function)(void*));
 313
 314 /*-------------------------------------------------------------------------*/
 315
 316 /* WMData handling */
 317
 318 /* Creating/destroying data */
 319
 320 WMData* WMCreateDataWithCapacity(unsigned capacity);
 321
 322 WMData* WMCreateDataWithLength(unsigned length);
 323
 324 WMData* WMCreateDataWithBytes(void *bytes, unsigned length);
 325
 326 WMData* WMCreateDataWithBytesNoCopy(void *bytes, unsigned length);
 327
 328 WMData* WMCreateDataWithData(WMData *aData);
 329
 330 WMData* WMRetainData(WMData *aData);
 331
 332 void WMReleaseData(WMData *aData);
 333
 334 /* Adjusting capacity */
 335
 336 void WMSetDataCapacity(WMData *aData, unsigned capacity);
 337
 338 void WMSetDataLength(WMData *aData, unsigned length);
 339
 340 void WMIncreaseDataLengthBy(WMData *aData, unsigned extraLength);
 341
 342 /* Accessing data */
 343
 344 const void* WMDataBytes(WMData *aData);
 345
 346 void WMGetDataBytes(WMData *aData, void *buffer);
 347
 348 void WMGetDataBytesWithLength(WMData *aData, void *buffer, unsigned length);
 349
 350 void WMGetDataBytesWithRange(WMData *aData, void *buffer, WMRange aRange);
 351
 352 WMData* WMGetSubdataWithRange(WMData *aData, WMRange aRange);
 353
 354 /* Testing data */
 355
 356 Bool WMIsDataEqualToData(WMData *aData, WMData *anotherData);
 357
 358 unsigned WMGetDataLength(WMData *aData);
 359
 360 unsigned WMGetDataHash(WMData *aData);
 361
 362 /* Adding data */
 363
 364 void WMAppendDataBytes(WMData *aData, void *bytes, unsigned length);
 365
 366 void WMAppendData(WMData *aData, WMData *anotherData);
 367
 368 /* Modifying data */
 369
 370 void WMReplaceDataBytesInRange(WMData *aData, WMRange aRange, void *bytes);
 371
 372 void WMResetDataBytesInRange(WMData *aData, WMRange aRange);
 373
 374 void WMSetData(WMData *aData, WMData *anotherData);
 375
 376 /* Storing data */
 377
 378
 379 /*--------------------------------------------------------------------------*/
 380
 381
 382 WMNotification *WMCreateNotification(char *name, void *object, void *clientData);
 383
 384 void WMReleaseNotification(WMNotification *notification);
 385
 386 WMNotification *WMRetainNotification(WMNotification *notification);
 387
 388 void *WMGetNotificationClientData(WMNotification *notification);
 389
 390 void *WMGetNotificationObject(WMNotification *notification);
 391
 392 char *WMGetNotificationName(WMNotification *notification);
 393
 394
 395 void WMAddNotificationObserver(WMNotificationObserverAction *observerAction,
 396                                void *observer, char *name, void *object);
 397
 398 void WMPostNotification(WMNotification *notification);
 399
 400 void WMRemoveNotificationObserver(void *observer);
 401
 402 void WMRemoveNotificationObserverWithName(void *observer, char *name,
 403                                           void *object);
 404
 405 void WMPostNotificationName(char *name, void *object, void *clientData);
 406
 407 WMNotificationQueue *WMGetDefaultNotificationQueue(void);
 408
 409 WMNotificationQueue *WMCreateNotificationQueue(void);
 410
 411 void WMDequeueNotificationMatching(WMNotificationQueue *queue,
 412                                    WMNotification *notification,
 413                                    unsigned mask);
 414
 415 void WMEnqueueNotification(WMNotificationQueue *queue,
 416                            WMNotification *notification,
 417                            WMPostingStyle postingStyle);
 418
 419 void WMEnqueueCoalesceNotification(WMNotificationQueue *queue,
 420                                    WMNotification *notification,
 421                                    WMPostingStyle postingStyle,
 422                                    unsigned coalesceMask);
 423
 424
 425 /*......................................................................*/
 426
 427 WMUserDefaults *WMGetStandardUserDefaults(void);
 428
 429 WMUserDefaults *WMGetDefaultsFromPath(char *path);
 430
 431 void WMSynchronizeUserDefaults(WMUserDefaults *database);
 432
 433 void WMSaveUserDefaults(WMUserDefaults *database);
 434
 435 void WMEnableUDPeriodicSynchronization(WMUserDefaults *database, Bool enable);
 436
 437 proplist_t WMGetUDObjectForKey(WMUserDefaults *database, char *defaultName);
 438
 439 void WMSetUDObjectForKey(WMUserDefaults *database, proplist_t object,
 440                          char *defaultName);
 441
 442 void WMRemoveUDObjectForKey(WMUserDefaults *database, char *defaultName);
 443
 444 /* you can free the returned string */
 445 char *WMGetUDStringForKey(WMUserDefaults *database, char *defaultName);
 446
 447 int WMGetUDIntegerForKey(WMUserDefaults *database, char *defaultName);
 448
 449 float WMGetUDFloatForKey(WMUserDefaults *database, char *defaultName);
 450
 451 Bool WMGetUDBoolForKey(WMUserDefaults *database, char *defaultName);
 452
 453 void WMSetUDStringForKey(WMUserDefaults *database, char *value,
 454                          char *defaultName);
 455
 456 void WMSetUDIntegerForKey(WMUserDefaults *database, int value,
 457                           char *defaultName);
 458
 459 void WMSetUDFloatForKey(WMUserDefaults *database, float value,
 460                         char *defaultName);
 461
 462 void WMSetUDBoolForKey(WMUserDefaults *database, Bool value,
 463                        char *defaultName);
 464
 465 proplist_t WMGetUDSearchList(WMUserDefaults *database);
 466
 467 void WMSetUDSearchList(WMUserDefaults *database, proplist_t list);
 468
 469 extern char *WMUserDefaultsDidChangeNotification;
 470
 471
 472 /*-------------------------------------------------------------------------*/
 473
 474 /* WMHost: host handling */
 475
 476 WMHost* WMGetCurrentHost();
 477
 478 WMHost* WMGetHostWithName(char* name);
 479
 480 WMHost* WMGetHostWithAddress(char* address);
 481
 482 WMHost* WMRetainHost(WMHost *hPtr);
 483
 484 void WMReleaseHost(WMHost *hPtr);
 485
 486 /*
 487  * Host cache management
 488  * If enabled, only one object representing each host will be created, and
 489  * a shared instance will be returned by all methods that return a host.
 490  * Enabled by default.
 491  */
 492 void WMSetHostCacheEnabled(Bool flag);
 493
 494 Bool WMIsHostCacheEnabled();
 495
 496 void WMFlushHostCache();
 497
 498 /*
 499  * Compare hosts: Hosts are equal if they share at least one address
 500  */
 501 Bool WMIsHostEqualToHost(WMHost* hPtr, WMHost* anotherHost);
 502
 503 /*
 504  * Host names.
 505  * WMGetHostName() will return first name (official) if a host has several.
 506  * WMGetHostNames() will return a R/O WMBag with all the names of the host.
 507  */
 508 char* WMGetHostName(WMHost* hPtr);
 509
 510 /* The returned bag is R/O. Do not modify it, and do not free it! */
 511 WMBag* WMGetHostNames(WMHost* hPtr);
 512
 513 /*
 514  * Host addresses.
 515  * Addresses are represented as "Dotted Decimal" strings, e.g. "192.42.172.1"
 516  * WMGetHostAddress() will return an arbitrary address if a host has several.
 517  * WMGetHostAddresses() will return a R/O WMBag with all addresses of the host.
 518  */
 519 char* WMGetHostAddress(WMHost* hPtr);
 520
 521 /* The returned bag is R/O. Do not modify it, and do not free it! */
 522 WMBag* WMGetHostAddresses(WMHost* hPtr);
 523
 524
 525 /*-------------------------------------------------------------------------*/
 526
 527 /* WMConnection functions */
 528
 529 WMConnection* WMCreateConnectionAsServerAtAddress(char *host, char *service,
 530                                                   char *protocol);
 531
 532 WMConnection* WMCreateConnectionToAddress(char *host, char *service,
 533                                           char *protocol);
 534
 535 WMConnection* WMCreateConnectionToAddressAndNotify(char *host, char *service,
 536                                                    char *protocol);
 537
 538 void WMCloseConnection(WMConnection *cPtr);
 539
 540 void WMDestroyConnection(WMConnection *cPtr);
 541
 542 WMConnection* WMAcceptConnection(WMConnection *listener);
 543
 544 /* Release the returned data! */
 545 WMData* WMGetConnectionAvailableData(WMConnection *cPtr);
 546
 547 int WMSendConnectionData(WMConnection *cPtr, WMData *data);
 548
 549 Bool WMEnqueueConnectionData(WMConnection *cPtr, WMData *data);
 550
 551 #define WMFlushConnection(cPtr)  WMSendConnectionData((cPtr), NULL)
 552
 553 void WMSetConnectionDelegate(WMConnection *cPtr, ConnectionDelegate *delegate);
 554
 555 /* Connection info */
 556
 557 char* WMGetConnectionAddress(WMConnection *cPtr);
 558
 559 char* WMGetConnectionService(WMConnection *cPtr);
 560
 561 char* WMGetConnectionProtocol(WMConnection *cPtr);
 562
 563 void WMSetConnectionNonBlocking(WMConnection *cPtr, Bool flag);
 564
 565 void* WMGetConnectionClientData(WMConnection *cPtr);
 566
 567 void WMSetConnectionClientData(WMConnection *cPtr, void *data);
 568
 569 unsigned int WMGetConnectionFlags(WMConnection *cPtr);
 570
 571 void WMSetConnectionFlags(WMConnection *cPtr, unsigned int flags);
 572
 573 int WMGetConnectionSocket(WMConnection *cPtr);
 574
 575 WMConnectionState WMGetConnectionState(WMConnection *cPtr);
 576
 577 void WMSetConnectionSendTimeout(WMConnection *cPtr, unsigned int timeout);
 578
 579
 580 /* Global variables */
 581
 582 extern int WCErrorCode;
 583
 584
 585 /*-------------------------------------------------------------------------*/
 586
 587
 588
 589 #ifdef __cplusplus
 590 }
 591 #endif /* __cplusplus */
 592
 593
 594 #endif