X11 Work Bench Toolkit  1.0
platform_helper.h
Go to the documentation of this file.
1 
2 // _ _ __ _ _ _ //
3 // _ __ | | __ _ | |_ / _| ___ _ __ _ __ ___ | |__ ___ | | _ __ ___ _ __ | |__ //
4 // | '_ \ | | / _` || __|| |_ / _ \ | '__|| '_ ` _ \ | '_ \ / _ \| || '_ \ / _ \| '__|| '_ \ //
5 // | |_) || || (_| || |_ | _|| (_) || | | | | | | | | | | || __/| || |_) || __/| | _ | | | | //
6 // | .__/ |_| \__,_| \__||_| \___/ |_| |_| |_| |_|_____|_| |_| \___||_|| .__/ \___||_|(_)|_| |_| //
7 // |_| |_____| |_| //
8 // //
9 // platform-specific definitions to rectify various issues //
10 // //
12 
13 /*****************************************************************************
14 
15  X11workbench - X11 programmer's 'work bench' application and toolkit
16  Copyright (c) 2010-2016 by Bob Frazier (aka 'Big Bad Bombastic Bob')
17  all rights reserved
18 
19  DISCLAIMER: The X11workbench application and toolkit software are supplied
20  'as-is', with no warranties, either implied or explicit.
21  Any claims to alleged functionality or features should be
22  considered 'preliminary', and might not function as advertised.
23 
24  BSD-like license:
25 
26  There is no restriction as to what you can do with this software, so long
27  as you include the above copyright notice and DISCLAIMER for any distributed
28  work that is equal to or derived from this one, along with this paragraph
29  that explains the terms of the license if the source is also being made
30  available. A "derived work" describes a work that uses a significant portion
31  of the source files or algorithms that are included with this one.
32  Specifically excluded from this are files that were generated by the software,
33  or anything that is included with the software that is part of another package
34  (such as files that were created or added during the 'configure' process).
35  Specifically included is the use of part or all of any of the X11 workbench
36  toolkit source or header files in your distributed application. If you do not
37  ship the source, the above copyright statement is still required to be placed
38  in a reasonably prominent place, such as documentation, splash screens, and/or
39  'about the application' dialog boxes.
40 
41  Use and distribution are in accordance with GPL, LGPL, and/or the above
42  BSD-like license. See COPYING and README files for more information.
43 
44 
45  Additional information at http://sourceforge.net/projects/X11workbench
46 
47 ******************************************************************************/
48 
59 #ifndef _PLATFORM_HELPER_H_INCLUDED_
60 #define _PLATFORM_HELPER_H_INCLUDED_
61 
62 #include <stdarg.h> /* stdarg to make sure I have va_list and other important stuff */
63 
64 // X11 header files (TODO: use 'ifdef' blocks around this as needed for non-X platforms)
65 
66 #include <X11/Xlib.h>
67 #include <X11/Xutil.h>
68 #include <X11/Xmd.h> // for 'CARD32' and other things
69 #include <X11/Xatom.h> // for 'XA_CARDINAL' and other things
70 
71 
72 #if defined(__GNUC__) || defined(__DOXYGEN__)
73 
74 // this section included for doxygen documentation using the X11 definitions
75 
76 #include <pthread.h> /* make sure this is included for POSIX */
77 
78 #ifdef X11WORKBENCH_PROJECT_BUILD
79 
80 // Globally include the output of the configure script for GNUC compiles for "the project"
81 #include "X11workbenchToolkit_config.h" // the 'generated' version'
82 
83 #else // X11WORKBENCH_PROJECT_BUILD
84 
85 // This is for the installed version, a subset of the things defined by the configure output script.
86 // NOTE: this must be installed in the appropriate package directory along with platform_helper.h
87 #include "X11workbenchToolkit_install_config.h"
88 
89 #endif // X11WORKBENCH_PROJECT_BUILD
90 
91 
92 // DEBUG vs RELEASE code
93 
94 #ifdef DEBUG /* explicit DEBUG build */
95 #ifdef NO_DEBUG
96 #undef NO_DEBUG
97 #endif // NO_DEBUG
98 #endif // DEBUG
99 
100 // NOTE: The debug code will be included when NO_DEBUG is *NOT* defined
101 
102 
109 #define INVALID_HANDLE_VALUE ((int)-1)
110 
111 
116 //--------------------------------------
117 // branch optimization macros - gcc only
118 //--------------------------------------
119 
120 #define WB_UNLIKELY(x) (__builtin_expect (!!(x), 0))
121 #define WB_LIKELY(x) (__builtin_expect (!!(x), 1))
141 #define WB_INTERNAL_ATOM_MIN_VAL 0x3f000000L
152 typedef int WB_INT32;
153 
159 typedef unsigned int WB_UINT32;
160 
161 
162 #if defined(HAVE_LONGLONG) || defined(__DOXYGEN__) /* 'configure' tests for 'long long' datatype valid in configure script */
163 
167 #define HAS_WB_UINT64_BUILTIN
168 
169 
175 typedef long long WB_INT64;
176 
182 typedef unsigned long long WB_UINT64;
183 
184 #else // !defined HAVE_LONGLONG, unlikely (this part won't show up in doxygen either)
185 
186 typedef struct __WB_INT64__ { WB_UINT32 dw2; WB_INT32 dw1; } WB_INT64; // note 'dw1' is a signed value
187 typedef struct __WB_UINT64__ { WB_UINT32 dw2; WB_UINT32 dw1; } WB_UINT64;
188 
189 #endif // _LONGLONG
190 
191 
192 #define WB_C99_INITIALIZERS /* allow C99-style initializers */
193 
199 typedef void * WB_MODULE;
200 
206 typedef pthread_t WB_THREAD;
207 
213 typedef void (* WB_PROCADDRESS)(void);
214 
220 typedef pthread_key_t WB_THREAD_KEY;
221 
227 typedef WB_UINT32 WB_COND; // defined as 'WB_UINT32' because of pthread_cond problems under Linux
228 //typedef pthread_cond_t WB_COND;
229 
235 typedef pthread_mutex_t WB_MUTEX;
236 
237 
238 // TODO: sizeof(int) sizeof(long) - long is 64-bit for GNUC - MS compilers make it 32-bit
239 
240 
241 
242 #ifdef __DOXYGEN__
243 
249 #define __PACKED__ /* platform dependent; actual def must be a blank or doxygen barphs on it */
250 
251 #else // !__DOXYGEN__
252 
253 #define __PACKED__ __attribute__((__packed__))
254 
255 #endif // __DOXYGEN__
256 
257 #elif defined(_MSC_VER) /* Microsoft C/C++ compiler */
258 
259 // TODO: add proper support for MS compiler
260 #if _MSC_VER > 1300
261 
262 // TODO: specify correct version in which C99 initializers are supported
263 // as of MSC for ".Net" 2010 it's _NOT_ supported (still!)
264 //#define WB_C99_INITIALIZERS
265 
266 #endif // _MSC_VER > xxxx
267 
268 #define WB_UNLIKELY(x) (x)
269 #define WB_LIKELY(x) (x)
270 
271 #ifndef __inline__
272 #define __inline__ inline /* this assumes 'inline' is supported (MSC should support this) */
273 #endif // __inline__
274 
275 typedef __int64 WB_INT64;
276 typedef unsigned __int64 WB_UINT64;
277 typedef int WB_INT32;
278 typedef unsigned int WB_UINT32;
279 
280 // assume MS Windows Win32 API
281 typedef HMODULE WB_MODULE ; /* module handle */
282 typedef HANDLE WB_THREAD; /* thread handle - thread IDs are still 'int' types */
283 typedef FARPROC WB_PROCADDRESS; // generic proc address returned from GetProcAddress()
284 
285 typedef DWORD WBTHREAD_KEY; // return from 'TlsAlloc()'
286 typedef HANDLE WB_COND; // equivalent to an event handle
287 typedef HANDLE WB_MUTEX; // equivalent to a mutex handle
288 
289 
290 // TODO: sizeof(int) sizeof(long) - long is 32-bit for MSC
291 
292 // TODO: compatibility definition file for winders
293 
294 #define __PACKED__ /* TODO: a definition for packing in MS-land */
295 
296 #else // !defined(_MSVC_VER) && !defined(__GNUC__)
297 
298 #error unknown and/or unsupported compiler
299 
300 #define __PACKED__
301 
302 #endif // __GNUC__
303 
304 
305 // put standard '#define's and typedefs here, the ones that apply to EVERYBODY
306 
310 #define WB_SECURE_HASH_TIMEOUT 60000
312 typedef char * WB_PSTR;
313 typedef const char * WB_PCSTR;
314 
319 // memory allocation (with debug support)
320 
329 void *WBAlloc(int nSize);
330 
339 void WBFree(void *pBuf);
340 
358 int WBAllocUsableSize(void *pBuf);
359 
369 void * WBReAlloc(void *pBuf, int nNewSize);
370 
380 void WBSubAllocTrashMasher(void);
381 
382 
383 // BASIC STRING UTILITIES
384 
385 // simple but helpful string utilities
386 
399 char *WBCopyString(const char *pSrc);
400 
415 char *WBCopyStringN(const char *pSrc, unsigned int nMaxChars);
416 
432 void WBCatString(char **ppDest, const char *pSrc);
433 
451 void WBCatStringN(char **ppDest, const char *pSrc, unsigned int nMaxChars);
452 
464 void WBDeQuoteString(char *pszStr); // de-quote a string in place
465 
479 int WBStringLineCount(const char *pSrc, unsigned int nMaxChars);
480 
494 const char *WBStringNextLine(const char *pSrc, unsigned int *pnMaxChars);
495 
496 
497 #if 0
498 
499 // THIS IS ALL RESERVED FOR FUTURE USE
500 // MAY NOT BE NEEDED IF I USE _Xmbtowc _Xwctomb and _Xwctomb
501 // X11 defines them as mblen(), mbtowc(), and wctomb()
502 // The alternative is to do something similar on WIN32, once that is implemented in the toolkit
503 // with '#ifdef blocks all around it
504 
522 int WBIsMultiByte(const char *pszStr);
523 
524 
536 XChar2b * WBConvertMultiByteTo16(const char *pszStr);
537 
548 char *WBConvertMultiByteFrom16(const XChar2b *pwzStr);
549 #endif // 0
550 
551 
552 
553 
554 // XPM library (libXpm) and X11/xpm.h
555 
556 #if defined(X11WORKBENCH_TOOLKIT_HAVE_XPM) && !defined(__DOXYGEN__)
557 
558 // Doxygen doesn't need THIS part, it needs the other one.
559 
560 #include <X11/xpm.h>
561 
562 // no need for doxygen doc comments here, see '!defined(__DOXYGEN__)' above
563 // these definitions are for when libXpm is being used
564 #define XPM_ATTRIBUTES XpmAttributes
565 #define XPM_CREATE_PIXMAP_FROM_DATA(A,B,C,D,E,F) XpmCreatePixmapFromData(A,B,C,D,E,F)
566 #define XPM_FREE_ATTRIBUTES(pAttr) XpmFreeAttributes(pAttr)
567 
568 #else // !X11WORKBENCH_TOOLKIT_HAVE_XPM or __DOXYGEN__
569 
616 typedef struct _XPM_ATTRIBUTES_
617 {
618  // I only need certain information from MyLoadPixmapFromData(), so that's all I'm doing with this structure
619 
620  int width;
621  int height;
622  int depth;
623 
625 
626 
655 int MyLoadPixmapFromData(Display *pDisplay, Window wID, char *aData[],
656  Pixmap *pPixmap, Pixmap *pMask, XPM_ATTRIBUTES *pAttr);
657 
672 #define XPM_CREATE_PIXMAP_FROM_DATA(A,B,C,D,E,F) MyLoadPixmapFromData(A,B,C,D,E,F)
673 
685 #define XPM_FREE_ATTRIBUTES(pAttr) /* does nothing */
686 
687 
688 #endif
689 
690 
691 // some helpful macros that need to be universal without being in a different header
692 
702 #define NEXT_WORD(pX, pY, pZ) {while(*(pX) && *(pX) <= ' '){(pX)++;} (pY)=(pZ)=(pX); while(*(pX)>' '){(pX)++;} (pZ)=(pX);}
703 
704 
705 
706 
707 
708 #ifdef __cplusplus
709 extern "C" {
710 #endif // __cplusplus
711 
712 // common macros
713 
714 #ifndef FALSE
715 #define FALSE 0
716 #endif // FALSE
717 #ifndef TRUE
718 #define TRUE !0
719 #endif // TRUE
720 
721 
722 
723 // HANDLING qsort_r CALLING CONVENTION DIFFERENCES
724 //
725 #if defined(QSORT_R_BSD) && !defined(__DOXYGEN__)
726 
727 // DECLARE_SORT_FUNCTION based on - int (*compar)(void *, const void *, const void *)
728 // generates int fn_name(void *p0, const void *p1, const void *p2)
729 #define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(void *p0, const void *p1, const void *p2)
730 // void qsort_r(void *base, size_t nmemb, size_t size, void *thunk, int (*compar)(void *, const void *, const void *))
731 #define QSORT_R(A,B,C,D,E) qsort_r((A),(B),(C),(D),(E))
732 
733 #elif defined(QSORT_R_GNUC) && !defined(__DOXYGEN__)
734 
735 // DECLARE_SORT_FUNCTION based on typedef int (*__compar_d_fn_t) (__const void *, __const void *, void *)
736 // generates int fn_name(const void *p1, const void *p2, void *p0)
737 #define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(const void *p1, const void *p2, void *p0)
738 // extern void qsort_r (void *__base, size_t __nmemb, size_t __size, __compar_d_fn_t __compar, void *__arg)
739 #define QSORT_R(A,B,C,D,E) qsort_r((A),(B),(C),(E),(D))
740 
741 #else
742 
743 // here is where I implement 'vectored' quicksort for OTHER PLATFORMS
744 
758 void my_qsort_r(void *base, int nmemb, int size, void *thunk,
759  int (*compar)(void *, const void *, const void *));
760 
761 // the rest is exactly like the BSD version
762 
795 #define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(void *p0, const void *p1, const void *p2)
796 
797 
811 #define QSORT_R(base,nmemb,size,thunk,compar) my_qsort_r((base),(nmemb),(size),(thunk),(compar))
812 
813 #endif
814 
815 // *******************************************
816 // STARTUP AND SHUTDOWN (must-call functions)
817 // *******************************************
818 
827 void WBPlatformOnInit(void);
828 
839 void WBPlatformOnExit(void);
840 
841 
842 
843 // *********************************
844 // INTERNAL memory/security helpers
845 // *********************************
846 
872 WB_UINT32 WBCreatePointerHash(void *pPointer);
873 
888 void WBDestroyPointerHash(WB_UINT32 uiHash);
889 
906 void * WBGetPointerFromHash(WB_UINT32 uiHash);
907 
908 
909 
910 //-----------------------------------------
911 // ATOM HELPERS (internally-defined atoms)
912 //-----------------------------------------
913 
914 
938 Atom WBGetAtom(Display *pDisplay, const char *szAtomName);
939 
967 Atom WBLookupAtom(Display *pDisplay, const char *szAtomName);
968 
989 char * WBGetAtomName(Display *pDisplay, Atom aAtom);
990 
991 
992 
993 
994 // *******************************************
995 // FILE/APPLICATION SEARCH PATH AND TEMP FILES
996 // *******************************************
997 
998 
1013 char * WBSearchPath(const char *szFileName);
1014 
1033 char * WBTempFile(const char *szExt);
1034 
1035 
1050 char * WBTempFile0(const char *szExt);
1051 
1052 
1053 
1055 // ____ ____ ___ ____ _____ ____ ____ ____ ___ _ _ _____ ____ ___ _ //
1056 // | _ \| _ \ / _ \ / ___| ____/ ___/ ___| / ___/ _ \| \ | |_ _| _ \ / _ \| | //
1057 // | |_) | |_) | | | | | | _| \___ \___ \ | | | | | | \| | | | | |_) | | | | | //
1058 // | __/| _ <| |_| | |___| |___ ___) |__) | | |__| |_| | |\ | | | | _ <| |_| | |___ //
1059 // |_| |_| \_\\___/ \____|_____|____/____/ \____\___/|_| \_| |_| |_| \_\\___/|_____| //
1060 // //
1062 
1063 // *********************
1064 // SPAWNING APPLICATIONS
1065 // *********************
1066 
1067 #ifdef WIN32
1068 #define WB_FILE_HANDLE HANDLE
1069 #define WB_PROCESS_ID HANDLE
1070 #define WB_INVALID_FILE_HANDLE INVALID_HANDLE_VALUE
1071 #else // !WIN32
1072 #define WB_FILE_HANDLE int
1073 #define WB_PROCESS_ID unsigned int
1074 #define WB_INVALID_FILE_HANDLE -1
1075 #endif // WIN32
1076 
1090 WB_PROCESS_ID WBRunAsync(const char *szAppName, ...);
1091 
1109 char * WBRunResult(const char *szAppName, ...);
1110 
1133 char * WBRunResultPipe(const char *szStdInBuf, const char *szAppName, ...);
1134 
1135 
1161 WB_PROCESS_ID WBRunAsyncPipe(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr,
1162  const char *szAppName, ...);
1163 
1164 
1195 WB_PROCESS_ID WBRunAsyncPipeV(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr,
1196  const char *szAppName, va_list va);
1197 
1198 
1199 
1200 
1202 // ____ _ _ _ ____ _____ ____ _ ___ ____ ____ //
1203 // / ___|| | | | / \ | _ \| ____| _ \ | | |_ _| __ ) ___| //
1204 // \___ \| |_| | / _ \ | |_) | _| | | | | | | | || _ \___ \ //
1205 // ___) | _ |/ ___ \| _ <| |___| |_| | | |___ | || |_) |__) | //
1206 // |____/|_| |_/_/ \_\_| \_\_____|____/ |_____|___|____/____/ //
1207 // //
1209 
1220 WB_MODULE WBLoadLibrary(const char *szModuleName); // load a library module (shared lib, DLL, whatever)
1221 
1231 void WBFreeLibrary(WB_MODULE hModule);
1232 
1244 WB_PROCADDRESS WBGetProcAddress(WB_MODULE hModule, const char *szProcName);
1245 
1246 
1247 
1249 // _____ _ _ ____ _____ _ ____ ____ //
1250 // |_ _| | | | _ \| ____| / \ | _ \/ ___| //
1251 // | | | |_| | |_) | _| / _ \ | | | \___ \ //
1252 // | | | _ | _ <| |___ / ___ \| |_| |___) | //
1253 // |_| |_| |_|_| \_\_____/_/ \_\____/|____/ //
1254 // //
1256 
1267 
1277 void WBThreadFreeLocal(WB_THREAD_KEY keyVal);
1278 
1289 void * WBThreadGetLocal(WB_THREAD_KEY keyVal);
1290 
1301 void WBThreadSetLocal(WB_THREAD_KEY keyVal, void *pValue);
1302 
1303 
1304 // simplified thread support (cross-platform)
1305 
1317 
1329 WB_THREAD WBThreadCreate(void *(*function)(void *), void *pParam);
1330 
1342 void *WBThreadWait(WB_THREAD hThread); // closes hThread, returns exit code, waits for thread to terminate (blocks)
1343 
1357 int WBThreadRunning(WB_THREAD hThread);
1358 
1370 void WBThreadExit(void *pRval);
1371 
1385 void WBThreadClose(WB_THREAD hThread);
1386 
1387 
1399 int WBCondCreate(WB_COND *pCond);
1400 
1411 int WBMutexCreate(WB_MUTEX *pMtx);
1412 
1422 void WBCondFree(WB_COND *pCond);
1423 
1433 void WBMutexFree(WB_MUTEX *pMtx);
1434 
1448 int WBMutexLock(WB_MUTEX *pMtx, int nTimeout);
1449 
1460 int WBMutexUnlock(WB_MUTEX *pMtx);
1461 
1473 int WBCondSignal(WB_COND *pCond);
1474 
1487 int WBCondWait(WB_COND *pCond, int nTimeout);
1488 
1507 int WBCondWaitMutex(WB_COND *pCond, WB_MUTEX *pMtx, int nTimeout);
1508 
1509 
1522 WB_UINT32 WBInterlockedDecrement(volatile WB_UINT32 *pValue);
1523 
1524 
1537 WB_UINT32 WBInterlockedIncrement(volatile WB_UINT32 *pValue);
1538 
1539 
1554 WB_UINT32 WBInterlockedExchange(volatile WB_UINT32 *pValue, WB_UINT32 nNewVal);
1555 
1556 
1570 WB_UINT32 WBInterlockedRead(volatile WB_UINT32 *pValue);
1571 
1572 
1573 
1575 // ____ ____ ___ _ _ _____ ___ _ _ ____ //
1576 // | _ \| _ \|_ _| \ | |_ _|_ _| \ | |/ ___| //
1577 // | |_) | |_) || || \| | | | | || \| | | _ //
1578 // | __/| _ < | || |\ | | | | || |\ | |_| | //
1579 // |_| |_| \_\___|_| \_| |_| |___|_| \_|\____| //
1580 // //
1582 
1583 // NOTE: the POSIX world uses postscript, particularly with CUPS. So does this library.
1584 
1612 int WBPrintPostScriptFile(const char *szPrinterName, const char *szFileName);
1613 
1632 char *WBGetPrinterList(void);
1633 
1634 // TODO: complete IPP support for cups and network-capable printers
1635 
1636 // TODO: printer capabilities in a binary structure
1637 
1638 // TODO: support for port 515 'printer' TCP/UDP printer services (i.e. cups-lpd or lpd)
1639 
1640 // TODO: dynamically load CUPS API when available. see 'cups-config' application docs
1641 
1642 
1643 
1644 #ifdef __cplusplus
1645 };
1646 #endif // __cplusplus
1647 
1648 
1649 #endif // _PLATFORM_HELPER_H_INCLDUED_
1650