bag tree finished.. updated code to new bags
[wmaker-crm.git] / WINGs / WUtil.h
blob19b25c66c49336487db4ba52e3833e85bf6d4ef2
1 #ifndef _WUTIL_H_
2 #define _WUTIL_H_
4 #include <X11/Xlib.h>
5 #include <limits.h>
6 #include <sys/types.h>
8 /* SunOS 4.x Blargh.... */
9 #ifndef NULL
10 #define NULL ((void*)0)
11 #endif
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.
19 #include <proplist.h>
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
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
38 #ifdef NDEBUG
40 #define wassertr(expr) {}
41 #define wassertrv(expr, val) {}
43 #else /* !NDEBUG */
45 #ifdef DEBUG
47 #include <assert.h>
49 #define wassertr(expr) assert(expr)
51 #define wassertrv(expr, val) assert(expr)
53 #else /* !DEBUG */
55 #define wassertr(expr) \
56 if (!(expr)) { \
57 wwarning("%s line %i (%s): assertion %s failed",\
58 __FILE__, __LINE__, __ASSERT_FUNCTION, #expr);\
59 return;\
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);\
68 #endif /* !DEBUG */
70 #endif /* !NDEBUG */
73 #ifdef __cplusplus
74 extern "C" {
75 #endif /* __cplusplus */
78 typedef enum {
79 WMPostWhenIdle = 1,
80 WMPostASAP = 2,
81 WMPostNow = 3
82 } WMPostingStyle;
85 typedef enum {
86 WNCNone = 0,
87 WNCOnName = 1,
88 WNCOnSender = 2
89 } WMNotificationCoalescing;
92 /* The possible states for connections */
93 typedef enum {
94 WCNotConnected=0,
95 WCListening,
96 WCInProgress,
97 WCFailed,
98 WCConnected,
99 WCDied,
100 WCClosed
101 } WMConnectionState;
105 enum {
106 WBNotFound = INT_MIN /* element was not found in bag */
110 typedef struct W_Bag WMBag;
111 typedef struct W_Data WMData;
112 typedef struct W_HashTable WMHashTable;
113 typedef struct W_UserDefaults WMUserDefaults;
114 typedef struct W_Notification WMNotification;
115 typedef struct W_NotificationQueue WMNotificationQueue;
116 typedef struct W_Host WMHost;
117 typedef struct W_Connection WMConnection;
121 typedef struct {
122 int position;
123 int count;
124 } WMRange;
128 /* DO NOT ACCESS THE CONTENTS OF THIS STRUCT */
129 typedef struct {
130 void *table;
131 void *nextItem;
132 int index;
133 } WMHashEnumerator;
136 typedef struct {
137 /* NULL is pointer hash */
138 unsigned (*hash)(const void *);
139 /* NULL is pointer compare */
140 Bool (*keyIsEqual)(const void *, const void *);
141 /* NULL does nothing */
142 void* (*retainKey)(const void *);
143 /* NULL does nothing */
144 void (*releaseKey)(const void *);
145 } WMHashTableCallbacks;
148 typedef void *WMBagIterator;
150 typedef struct W_BagFunctions {
151 int (*getItemCount)(WMBag *self);
152 int (*appendBag)(WMBag *self, WMBag *bag);
153 int (*putInBag)(WMBag *self, void *item);
154 int (*insertInBag)(WMBag *self, int index, void *item);
155 int (*removeFromBag)(WMBag *bag, void *item);
156 int (*eraseFromBag)(WMBag *bag, int index);
157 int (*deleteFromBag)(WMBag *bag, int index);
158 void *(*getFromBag)(WMBag *bag, int index);
159 int (*firstInBag)(WMBag *bag, void *item);
160 int (*countInBag)(WMBag *bag, void *item);
161 void *(*replaceInBag)(WMBag *bag, int index, void *item);
162 int (*sortBag)(WMBag *bag, int (*comparer)(const void*, const void*));
163 void (*emptyBag)(WMBag *bag);
164 void (*freeBag)(WMBag *bag);
165 void (*mapBag)(WMBag *bag, void (*function)(void*, void*), void *data);
166 int (*findInBag)(WMBag *bag, int (*match)(void*));
167 void *(*first)(WMBag *bag, WMBagIterator *ptr);
168 void *(*last)(WMBag *bag, WMBagIterator *ptr);
169 void *(*next)(WMBag *bag, WMBagIterator *ptr);
170 void *(*previous)(WMBag *bag, WMBagIterator *ptr);
171 void *(*iteratorAtIndex)(WMBag *bag, int index, WMBagIterator *ptr);
172 int (*indexForIterator)(WMBag *bag, WMBagIterator ptr);
173 } W_BagFunctions;
176 struct W_Bag {
177 void *data;
179 void (*destructor)(void *item);
181 W_BagFunctions func;
186 #if 0
187 typedef struct {
188 char character; /* the escape character */
189 char *value; /* value to place */
190 } WMSEscapes;
191 #endif
194 /* The connection callbacks */
195 typedef struct ConnectionDelegate {
196 void *data;
198 void (*didCatchException)(struct ConnectionDelegate *self,
199 WMConnection *cPtr);
201 void (*didDie)(struct ConnectionDelegate *self, WMConnection *cPtr);
203 void (*didInitialize)(struct ConnectionDelegate *self, WMConnection *cPtr);
205 void (*didReceiveInput)(struct ConnectionDelegate *self, WMConnection *cPtr);
207 void (*didTimeout)(struct ConnectionDelegate *self, WMConnection *cPtr);
209 } ConnectionDelegate;
212 typedef void WMNotificationObserverAction(void *observerData,
213 WMNotification *notification);
217 /*......................................................................*/
219 typedef void (waborthandler)(int);
221 waborthandler *wsetabort(waborthandler*);
224 /* don't free the returned string */
225 char *wstrerror(int errnum);
227 void wfatal(const char *msg, ...);
228 void wwarning(const char *msg, ...);
229 void wsyserror(const char *msg, ...);
230 void wsyserrorwithcode(int error, const char *msg, ...);
232 char *wfindfile(char *paths, char *file);
234 char *wfindfileinlist(char **path_list, char *file);
236 char *wfindfileinarray(proplist_t array, char *file);
238 char *wexpandpath(char *path);
240 /* don't free the returned string */
241 char *wgethomedir();
243 void *wmalloc(size_t size);
244 void *wrealloc(void *ptr, size_t newsize);
245 void wfree(void *ptr);
248 void wrelease(void *ptr);
249 void *wretain(void *ptr);
251 char *wstrdup(char *str);
253 char *wstrappend(char *dst, char *src);
255 char *wusergnusteppath();
257 char *wdefaultspathfordomain(char *domain);
259 void wusleep(unsigned int microsec);
261 #if 0
262 int wsprintesc(char *buffer, int length, char *format, WMSEscapes **escapes,
263 int count);
264 #endif
266 /*......................................................................*/
268 /* This function is used _only_ if you create a NON-GUI program.
269 * For GUI based programs use WMNextEvent()/WMHandleEvent() instead.
270 * This function will handle all input/timer/idle events, then return.
273 void WHandleEvents();
275 /*......................................................................*/
278 WMHashTable *WMCreateHashTable(WMHashTableCallbacks callbacks);
280 void WMFreeHashTable(WMHashTable *table);
282 void WMResetHashTable(WMHashTable *table);
284 void *WMHashGet(WMHashTable *table, const void *key);
286 /* put data in table, replacing already existing data and returning
287 * the old value */
288 void *WMHashInsert(WMHashTable *table, void *key, void *data);
290 void WMHashRemove(WMHashTable *table, const void *key);
292 /* warning: do not manipulate the table while using these functions */
293 WMHashEnumerator WMEnumerateHashTable(WMHashTable *table);
295 void *WMNextHashEnumeratorItem(WMHashEnumerator *enumerator);
297 unsigned WMCountHashTable(WMHashTable *table);
302 /* some predefined callback sets */
304 extern const WMHashTableCallbacks WMIntHashCallbacks;
305 /* sizeof(keys) are <= sizeof(void*) */
307 extern const WMHashTableCallbacks WMStringHashCallbacks;
308 /* keys are strings. Strings will be copied with wstrdup()
309 * and freed with free() */
311 extern const WMHashTableCallbacks WMStringPointerHashCallbacks;
312 /* keys are strings, bug they are not copied */
315 /*......................................................................*/
319 * Array bags use an array to store the elements.
320 * Item indexes may be any integer number.
322 * Pros:
323 * Fast [O(1)] access to elements
324 * Fast [O(1)] push/pop
326 * Cons:
327 * A little slower [O(n)] for insertion/deletion of elements that
328 * arent in the end
329 * Element indexes with large difference will cause large holes
331 #if 0
332 WMBag* WMCreateArrayBag(int initialSize);
333 WMBag* WMCreateArrayBagWithDestructor(int initialSize,
334 void (*destructor)(void*));
335 #endif
337 * Tree bags use a red-black tree for storage.
338 * Item indexes may be any integer number.
340 * Pros:
341 * O(lg n) insertion/deletion/search
342 * Good for large numbers of elements with sparse indexes
344 * Cons:
345 * O(lg n) insertion/deletion/search
346 * Slow for storing small numbers of elements
348 WMBag *WMCreateTreeBag(void);
349 WMBag *WMCreateTreeBagWithDestructor(void (*destructor)(void*));
352 #define WMCreateArrayBag(a) WMCreateTreeBag()
353 #define WMCreateArrayBagWithDestructor(a,d) WMCreateTreeBagWithDestructor(d)
355 #define WMCreateBag(size) WMCreateTreeBag()
357 #define WMGetBagItemCount(bag) bag->func.getItemCount(bag)
359 #define WMAppendBag(bag, other) bag->func.appendBag(bag, other)
361 #define WMPutInBag(bag, item) bag->func.putInBag(bag, item)
363 /* insert will increment the index of elements after it by 1 */
364 #define WMInsertInBag(bag, index, item) bag->func.insertInBag(bag, index, item)
366 /* this is slow */
367 /* erase will remove the element from the bag,
368 * but will keep the index of the other elements unchanged */
369 #define WMEraseFromBag(bag, index) bag->func.deleteFromBag(bag, index)
371 /* delete and remove will remove the elements and cause the elements
372 * after them to decrement their indexes by 1 */
373 #define WMRemoveFromBag(bag, item) bag->func.removeFromBag(bag, item)
375 #define WMDeleteFromBag(bag, index) bag->func.deleteFromBag(bag, index)
377 #define WMGetFromBag(bag, index) bag->func.getFromBag(bag, index)
379 #define WMCountInBag(bag, item) bag->func.countInBag(bag, item)
381 #define WMReplaceInBag(bag, index, item) bag->func.replaceInBag(bag, index, item)
382 #define WMSetInBag(bag, index, item) bag->func.replaceInBag(bag, index, item)
384 /* comparer must return:
385 * < 0 if a < b
386 * > 0 if a > b
387 * = 0 if a = b
389 #define WMSortBag(bag, comparer) bag->func.sortBag(bag, comparer)
391 #define WMEmptyBag(bag) bag->func.emptyBag(bag)
393 #define WMFreeBag(bag) bag->func.freeBag(bag)
395 #define WMMapBag(bag, function, cdata) bag->func.mapBag(bag, function, cdata)
397 #define WMGetFirstInBag(bag, item) bag->func.firstInBag(bag, item)
399 #define WMCountInBag(bag, item) bag->func.countInBag(bag, item)
401 #define WMFindInBag(bag, match) bag->func.findInBag(bag, match)
403 #define WMBagFirst(bag, ptr) bag->func.first(bag, ptr)
405 #define WMBagLast(bag, ptr) bag->func.last(bag, ptr)
407 #define WMBagNext(bag, ptr) bag->func.next(bag, ptr)
409 #define WMBagPrevious(bag, ptr) bag->func.previous(bag, ptr)
411 #define WMBagIteratorAtIndex(bag, index, ptr) bag->func.iteratorAtIndex(bag, index, ptr)
413 #define WMBagIndexForIterator(bag, ptr) bag->func.indexForIterator(bag, ptr)
417 #define WM_ITERATE_BAG(bag, var, i) \
418 for (var = WMBagFirst(bag, &(i)); (i) != NULL; \
419 var = WMBagNext(bag, &(i)))
421 #define WM_ETARETI_BAG(bag, var, i) \
422 for (var = WMBagLast(bag, &(i)); (i) != NULL; \
423 var = WMBagPrevious(bag, &(i)))
427 /*-------------------------------------------------------------------------*/
429 /* WMData handling */
431 /* Creating/destroying data */
433 WMData* WMCreateDataWithCapacity(unsigned capacity);
435 WMData* WMCreateDataWithLength(unsigned length);
437 WMData* WMCreateDataWithBytes(void *bytes, unsigned length);
439 WMData* WMCreateDataWithBytesNoCopy(void *bytes, unsigned length);
441 WMData* WMCreateDataWithData(WMData *aData);
443 WMData* WMRetainData(WMData *aData);
445 void WMReleaseData(WMData *aData);
447 /* Adjusting capacity */
449 void WMSetDataCapacity(WMData *aData, unsigned capacity);
451 void WMSetDataLength(WMData *aData, unsigned length);
453 void WMIncreaseDataLengthBy(WMData *aData, unsigned extraLength);
455 /* Accessing data */
457 const void* WMDataBytes(WMData *aData);
459 void WMGetDataBytes(WMData *aData, void *buffer);
461 void WMGetDataBytesWithLength(WMData *aData, void *buffer, unsigned length);
463 void WMGetDataBytesWithRange(WMData *aData, void *buffer, WMRange aRange);
465 WMData* WMGetSubdataWithRange(WMData *aData, WMRange aRange);
467 /* Testing data */
469 Bool WMIsDataEqualToData(WMData *aData, WMData *anotherData);
471 unsigned WMGetDataLength(WMData *aData);
473 unsigned WMGetDataHash(WMData *aData);
475 /* Adding data */
477 void WMAppendDataBytes(WMData *aData, void *bytes, unsigned length);
479 void WMAppendData(WMData *aData, WMData *anotherData);
481 /* Modifying data */
483 void WMReplaceDataBytesInRange(WMData *aData, WMRange aRange, void *bytes);
485 void WMResetDataBytesInRange(WMData *aData, WMRange aRange);
487 void WMSetData(WMData *aData, WMData *anotherData);
489 /* Storing data */
492 /*--------------------------------------------------------------------------*/
495 WMNotification *WMCreateNotification(char *name, void *object, void *clientData);
497 void WMReleaseNotification(WMNotification *notification);
499 WMNotification *WMRetainNotification(WMNotification *notification);
501 void *WMGetNotificationClientData(WMNotification *notification);
503 void *WMGetNotificationObject(WMNotification *notification);
505 char *WMGetNotificationName(WMNotification *notification);
508 void WMAddNotificationObserver(WMNotificationObserverAction *observerAction,
509 void *observer, char *name, void *object);
511 void WMPostNotification(WMNotification *notification);
513 void WMRemoveNotificationObserver(void *observer);
515 void WMRemoveNotificationObserverWithName(void *observer, char *name,
516 void *object);
518 void WMPostNotificationName(char *name, void *object, void *clientData);
520 WMNotificationQueue *WMGetDefaultNotificationQueue(void);
522 WMNotificationQueue *WMCreateNotificationQueue(void);
524 void WMDequeueNotificationMatching(WMNotificationQueue *queue,
525 WMNotification *notification,
526 unsigned mask);
528 void WMEnqueueNotification(WMNotificationQueue *queue,
529 WMNotification *notification,
530 WMPostingStyle postingStyle);
532 void WMEnqueueCoalesceNotification(WMNotificationQueue *queue,
533 WMNotification *notification,
534 WMPostingStyle postingStyle,
535 unsigned coalesceMask);
538 /*......................................................................*/
540 WMUserDefaults *WMGetStandardUserDefaults(void);
542 WMUserDefaults *WMGetDefaultsFromPath(char *path);
544 void WMSynchronizeUserDefaults(WMUserDefaults *database);
546 void WMSaveUserDefaults(WMUserDefaults *database);
548 void WMEnableUDPeriodicSynchronization(WMUserDefaults *database, Bool enable);
550 proplist_t WMGetUDObjectForKey(WMUserDefaults *database, char *defaultName);
552 void WMSetUDObjectForKey(WMUserDefaults *database, proplist_t object,
553 char *defaultName);
555 void WMRemoveUDObjectForKey(WMUserDefaults *database, char *defaultName);
557 /* you can free the returned string */
558 char *WMGetUDStringForKey(WMUserDefaults *database, char *defaultName);
560 int WMGetUDIntegerForKey(WMUserDefaults *database, char *defaultName);
562 float WMGetUDFloatForKey(WMUserDefaults *database, char *defaultName);
564 Bool WMGetUDBoolForKey(WMUserDefaults *database, char *defaultName);
566 void WMSetUDStringForKey(WMUserDefaults *database, char *value,
567 char *defaultName);
569 void WMSetUDIntegerForKey(WMUserDefaults *database, int value,
570 char *defaultName);
572 void WMSetUDFloatForKey(WMUserDefaults *database, float value,
573 char *defaultName);
575 void WMSetUDBoolForKey(WMUserDefaults *database, Bool value,
576 char *defaultName);
578 proplist_t WMGetUDSearchList(WMUserDefaults *database);
580 void WMSetUDSearchList(WMUserDefaults *database, proplist_t list);
582 extern char *WMUserDefaultsDidChangeNotification;
585 /*-------------------------------------------------------------------------*/
587 /* WMHost: host handling */
589 WMHost* WMGetCurrentHost();
591 WMHost* WMGetHostWithName(char* name);
593 WMHost* WMGetHostWithAddress(char* address);
595 WMHost* WMRetainHost(WMHost *hPtr);
597 void WMReleaseHost(WMHost *hPtr);
600 * Host cache management
601 * If enabled, only one object representing each host will be created, and
602 * a shared instance will be returned by all methods that return a host.
603 * Enabled by default.
605 void WMSetHostCacheEnabled(Bool flag);
607 Bool WMIsHostCacheEnabled();
609 void WMFlushHostCache();
612 * Compare hosts: Hosts are equal if they share at least one address
614 Bool WMIsHostEqualToHost(WMHost* hPtr, WMHost* anotherHost);
617 * Host names.
618 * WMGetHostName() will return first name (official) if a host has several.
619 * WMGetHostNames() will return a R/O WMBag with all the names of the host.
621 char* WMGetHostName(WMHost* hPtr);
623 /* The returned bag is R/O. Do not modify it, and do not free it! */
624 WMBag* WMGetHostNames(WMHost* hPtr);
627 * Host addresses.
628 * Addresses are represented as "Dotted Decimal" strings, e.g. "192.42.172.1"
629 * WMGetHostAddress() will return an arbitrary address if a host has several.
630 * WMGetHostAddresses() will return a R/O WMBag with all addresses of the host.
632 char* WMGetHostAddress(WMHost* hPtr);
634 /* The returned bag is R/O. Do not modify it, and do not free it! */
635 WMBag* WMGetHostAddresses(WMHost* hPtr);
638 /*-------------------------------------------------------------------------*/
640 /* WMConnection functions */
642 WMConnection* WMCreateConnectionAsServerAtAddress(char *host, char *service,
643 char *protocol);
645 WMConnection* WMCreateConnectionToAddress(char *host, char *service,
646 char *protocol);
648 WMConnection* WMCreateConnectionToAddressAndNotify(char *host, char *service,
649 char *protocol);
651 void WMCloseConnection(WMConnection *cPtr);
653 void WMDestroyConnection(WMConnection *cPtr);
655 WMConnection* WMAcceptConnection(WMConnection *listener);
657 /* Release the returned data! */
658 WMData* WMGetConnectionAvailableData(WMConnection *cPtr);
660 int WMSendConnectionData(WMConnection *cPtr, WMData *data);
662 Bool WMEnqueueConnectionData(WMConnection *cPtr, WMData *data);
664 #define WMFlushConnection(cPtr) WMSendConnectionData((cPtr), NULL)
666 void WMSetConnectionDelegate(WMConnection *cPtr, ConnectionDelegate *delegate);
668 /* Connection info */
670 char* WMGetConnectionAddress(WMConnection *cPtr);
672 char* WMGetConnectionService(WMConnection *cPtr);
674 char* WMGetConnectionProtocol(WMConnection *cPtr);
676 void WMSetConnectionNonBlocking(WMConnection *cPtr, Bool flag);
678 void* WMGetConnectionClientData(WMConnection *cPtr);
680 void WMSetConnectionClientData(WMConnection *cPtr, void *data);
682 unsigned int WMGetConnectionFlags(WMConnection *cPtr);
684 void WMSetConnectionFlags(WMConnection *cPtr, unsigned int flags);
686 int WMGetConnectionSocket(WMConnection *cPtr);
688 WMConnectionState WMGetConnectionState(WMConnection *cPtr);
690 void WMSetConnectionSendTimeout(WMConnection *cPtr, unsigned int timeout);
693 /* Global variables */
695 extern int WCErrorCode;
698 /*-------------------------------------------------------------------------*/
702 #ifdef __cplusplus
704 #endif /* __cplusplus */
707 #endif