platform_helper.h

Go to the documentation of this file.

//          _         _     __                               _            _                     _       //
//   _ __  | |  __ _ | |_  / _|  ___   _ __  _ __ ___       | |__    ___ | | _ __    ___  _ __ | |__    //
//  | '_ \ | | / _` || __|| |_  / _ \ | '__|| '_ ` _ \      | '_ \  / _ \| || '_ \  / _ \| '__|| '_ \   //
//  | |_) || || (_| || |_ |  _|| (_) || |   | | | | | |     | | | ||  __/| || |_) ||  __/| | _ | | | |  //
//  | .__/ |_| \__,_| \__||_|   \___/ |_|   |_| |_| |_|_____|_| |_| \___||_|| .__/  \___||_|(_)|_| |_|  //
//  |_|                                               |_____|               |_|                         //
//                                                                                                      //
//          This header contains platform-specific definitions that rectify various issues.             //
//          It also contains a lot of the 'core' functionality for strings, startup, etc.               //
//                                                                                                      //

/*****************************************************************************

    X11workbench - X11 programmer's 'work bench' application and toolkit
    Copyright (c) 2010-2019 by Bob Frazier (aka 'Big Bad Bombastic Bob')

  DISCLAIMER:  The X11workbench application and toolkit software are supplied
               'as-is', with no warranties, either implied or explicit.
               Any claims to alleged functionality or features should be
               considered 'preliminary', and might not function as advertised.

  MIT-like license:

  There is no restriction as to what you can do with this software, so long
  as you include the above copyright notice and DISCLAIMER for any distributed
  work that is equal to or derived from this one, along with this paragraph
  that explains the terms of the license if the source is also being made
  available.  A "derived work" describes a work that uses a significant portion
  of the source files or algorithms that are included with this one.
  Specifically excluded from this are files that were generated by the software,
  or anything that is included with the software that is part of another package
  (such as files that were created or added during the 'configure' process).
  Specifically included is the use of part or all of any of the X11 workbench
  toolkit source or header files in your distributed application.  If you do not
  ship the source, the above copyright statement is still required to be placed
  in a reasonably prominent place, such as documentation, splash screens, and/or
  'about the application' dialog boxes.

  Use and distribution are in accordance with GPL, LGPL, and/or the above
  MIT-like license.  See COPYING and README files for more information.


  Additional information at http://sourceforge.net/projects/X11workbench

******************************************************************************/

// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
//
// TODO:  support some kind of COM objects on POSIX systems, with an API that
//        translates directly to OLE 2 on Windows in a platform-indepenent way.
//
// COM equivalents (ORBs) on POSIX include the following technologies:
//
//   libbonobo
//   D-Bus
//   XPCOM (Mozilla)
//   CORBA and DCOP [obsolete]
//
//   'ORB' = 'Object Request Broker'
//
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=


#ifndef _PLATFORM_HELPER_H_INCLUDED_
#define _PLATFORM_HELPER_H_INCLUDED_

#include <stdarg.h> /* stdarg to make sure I have va_list and other important stuff */
#include <stdint.h> /* for standard integer types like uint32_t */

#ifndef WIN32
// X11 header files

#include <X11/Xlib.h>
#include <X11/Xutil.h>
#include <X11/Xmd.h>  // for 'CARD32' and other things
#include <X11/Xatom.h> // for 'XA_CARDINAL' and other things

#else // WIN32

#include <windows.h> // for WIN32 applications

#endif // WIN32



#if defined(__GNUC__) || defined(__DOXYGEN__)

// ======================================================================================
// this section is used for doxygen documentation using the X11 definitions
// Additionally, 'clang' compilers also define '__GNUC__' and will use this section

#include <pthread.h> /* make sure this is included for POSIX */

#ifdef X11WORKBENCH_PROJECT_BUILD

// Globally include the output of the configure script for GNUC compiles for "the project"
#include "X11workbenchToolkit_config.h" // the 'generated' version'

#else // X11WORKBENCH_PROJECT_BUILD

// This is for the installed version, a subset of the things defined by the configure output script.
// NOTE:  this must be installed in the appropriate package directory along with platform_helper.h
#include "X11workbenchToolkit_install_config.h"

#endif // X11WORKBENCH_PROJECT_BUILD

// TESTING THE CONFIGURATION - TODO:  for some, provide alternates?
// NOTE that for '_MSC_VER' defined, certain features won't be checked

// basic checks - test them all up front, then individual errors if any of these
//                are not defined in the appropriate header files
#if !defined( HAVE_ALARM ) || !defined( HAVE_CHOWN ) || \
    !defined( HAVE_CLOCK_GETTIME ) || !defined( HAVE_DUP2 ) || !defined( HAVE_FORK ) || \
    !defined( HAVE_FTRUNCATE ) || !defined( HAVE_GETCWD ) || !defined( HAVE_GETTIMEOFDAY ) || \
    !defined( HAVE_MALLOC ) || !defined( HAVE_MBLEN ) || !defined( HAVE_MEMCHR ) || \
    !defined( HAVE_MEMMOVE ) || !defined( HAVE_MEMSET ) || !defined( HAVE_MKDIR ) || \
    !defined( HAVE_PRINTF ) || !defined( HAVE_REALLOC ) || \
    !defined( HAVE_SELECT ) || !defined( HAVE_SETLOCALE ) || !defined( HAVE_STRCASECMP ) || \
    !defined( HAVE_STRCHR ) || !defined( HAVE_STRNCASECMP ) || !defined( HAVE_STRRCHR ) || \
    !defined( HAVE_STRSTR ) || !defined( HAVE__BOOL ) || \
    ( !defined(_MSC_VER) && ( !defined( LSTAT_FOLLOWS_SLASHED_SYMLINK ) || !defined( HAVE_VFORK ) || \
                              !defined( HAVE_WORKING_FORK ) || !defined( HAVE_WORKING_VFORK ) ))
// *************************************************************
#error
#error configure script feature check 1 fail
#error critical features missing
#error
// this next section spits out errors based on what's not defined.
#ifndef HAVE_ALARM
#error  HAVE_ALARM is not defined
#endif //  HAVE_ALARM
#ifndef HAVE_CHOWN
#error  HAVE_CHOWN is not defined
#endif //  HAVE_CHOWN
#ifndef HAVE_CLOCK_GETTIME
#error  HAVE_CLOCK_GETTIME is not defined
#endif //  HAVE_CLOCK_GETTIME
#ifndef HAVE_DUP2
#error  HAVE_DUP2 is not defined
#endif //  HAVE_DUP2
#ifndef HAVE_FORK
#error  HAVE_FORK is not defined
#endif //  HAVE_FORK
#ifndef HAVE_FTRUNCATE
#error  HAVE_FTRUNCATE is not defined
#endif //  HAVE_FTRUNCATE
#ifndef HAVE_GETCWD
#error  HAVE_GETCWD is not defined
#endif //  HAVE_GETCWD
#ifndef HAVE_GETTIMEOFDAY
#error  HAVE_GETTIMEOFDAY is not defined
#endif //  HAVE_GETTIMEOFDAY
#ifndef HAVE_MALLOC
#error  HAVE_MALLOC is not defined
#endif //  HAVE_MALLOC
#ifndef HAVE_MBLEN
#error  HAVE_MBLEN is not defined
#endif //  HAVE_MBLEN
#ifndef HAVE_MEMCHR
#error  HAVE_MEMCHR is not defined
#endif //  HAVE_MEMCHR
#ifndef HAVE_MEMMOVE
#error  HAVE_MEMMOVE is not defined
#endif //  HAVE_MEMMOVE
#ifndef HAVE_MEMSET
#error  HAVE_MEMSET is not defined
#endif //  HAVE_MEMSET
#ifndef HAVE_MKDIR
#error  HAVE_MKDIR is not defined
#endif //  HAVE_MKDIR
#ifndef HAVE_PRINTF
#error  HAVE_PRINTF is not defined
#endif //  HAVE_PRINTF
#ifndef HAVE_REALLOC
#error  HAVE_REALLOC is not defined
#endif //  HAVE_REALLOC
#ifndef HAVE_SELECT
#error  HAVE_SELECT is not defined
#endif //  HAVE_SELECT
#ifndef HAVE_SETLOCALE
#error  HAVE_SETLOCALE is not defined
#endif //  HAVE_SETLOCALE
#ifndef HAVE_STRCASECMP
#error  HAVE_STRCASECMP is not defined
#endif //  HAVE_STRCASECMP
#ifndef HAVE_STRCHR
#error  HAVE_STRCHR is not defined
#endif //  HAVE_STRCHR
#ifndef HAVE_STRNCASECMP
#error  HAVE_STRNCASECMP is not defined
#endif //  HAVE_STRNCASECMP
#ifndef HAVE_STRRCHR
#error  HAVE_STRRCHR is not defined
#endif //  HAVE_STRRCHR
#ifndef HAVE_STRSTR
#error  HAVE_STRSTR is not defined
#endif //  HAVE_STRSTR
#ifndef HAVE__BOOL
#error  HAVE__BOOL is not defined
#endif //  HAVE__BOOL
#ifndef LSTAT_FOLLOWS_SLASHED_SYMLINK
#error  LSTAT_FOLLOWS_SLASHED_SYMLINK is not defined
#endif //  LSTAT_FOLLOWS_SLASHED_SYMLINK
#ifndef HAVE_VFORK
#error  HAVE_VFORK is not defined
#endif //  HAVE_VFORK
#ifndef HAVE_WORKING_FORK
#error  HAVE_WORKING_FORK is not defined
#endif //  HAVE_WORKING_FORK
#ifndef HAVE_WORKING_VFORK
#error  HAVE_WORKING_VFORK is not defined
#endif //  HAVE_WORKING_VFORK
#error
// the end of that previous error section
// *************************************************************
#else
// -------------------------------------------------------------
#if !( HAVE_ALARM ) || !( HAVE_CHOWN ) || \
    !( HAVE_CLOCK_GETTIME ) || !( HAVE_DUP2 ) || !( HAVE_FORK ) || \
    !( HAVE_FTRUNCATE ) || !( HAVE_GETCWD ) || !( HAVE_GETTIMEOFDAY ) || \
    !( HAVE_MALLOC ) || !( HAVE_MBLEN ) || !( HAVE_MEMCHR ) || \
    !( HAVE_MEMMOVE ) || !( HAVE_MEMSET ) || !( HAVE_MKDIR ) || \
    !( HAVE_PRINTF ) || !( HAVE_REALLOC ) || \
    !( HAVE_SELECT ) || !( HAVE_SETLOCALE ) || !( HAVE_STRCASECMP ) || \
    !( HAVE_STRCHR ) || !( HAVE_STRNCASECMP ) || !( HAVE_STRRCHR ) || \
    !( HAVE_STRSTR ) || !( HAVE__BOOL ) || \
    ( !defined(_MSC_VER) && ( !( LSTAT_FOLLOWS_SLASHED_SYMLINK ) || !( HAVE_VFORK ) || \
                              !( HAVE_WORKING_FORK ) || !( HAVE_WORKING_VFORK ) ))
#error
#error configure script feature check 2 fail
#error critical features missing
#error

// TODO:  individual error messages for those things 'not defined'?  It's a bit
//        easier to see where something is defined as '0' rather than finding
//        something that isn't there.  For now, I won't add that section, but I
//        might do it if it becomes necessary

#endif // all that stuff defined as a zero
// -------------------------------------------------------------
#endif // all that prior stuff

#ifndef HAVE_BZERO
  #define HAVE_BZERO 0
#endif // !HAVE_BZERO

#if !( HAVE_BZERO )
// swap this in for 'bzero' using memset - it was checked for earlier
  #define bzero(X,Y) memset((X),0,(Y))
#endif


// DEBUG vs RELEASE code

#ifdef DEBUG /* explicit DEBUG build */
#ifdef NO_DEBUG
#undef NO_DEBUG // only one may be defined
#endif // NO_DEBUG
#endif // DEBUG

// NOTE:  The debug code will be included when NO_DEBUG is *NOT* defined

#define INVALID_HANDLE_VALUE ((int)-1)

// -----------------
// STRING-IZE MACROS
// -----------------
#define WB_STRINGIZE(X) WB_STRINGIZE_INTERNAL(X)

#define WB_STRINGIZE_INTERNAL(X) #X


//-------------------------------------------------
// branch optimization macros - gcc and clang only
//-------------------------------------------------

#if defined(COMPILER_SUPPORTS_BUILTIN_EXPECT) || defined(__DOXYGEN__)

#define WB_UNLIKELY(x) (__builtin_expect (!!(x), 0))

#define WB_LIKELY(x) (__builtin_expect (!!(x), 1))

#else // !COMPILER_SUPPORTS_BUILTIN_EXPECT

#define WB_UNLIKELY(x) (x)
#define WB_LIKELY(x) (x)

#endif // COMPILER_SUPPORTS_BUILTIN_EXPECT

#if defined(COMPILER_SUPPORTS_UNUSED_ATTRIBUTE) || defined(__DOXYGEN__)

#define WB_UNUSED __attribute__((unused))

#else // !COMPILER_SUPPORTS_UNUSED_ATTRIBUTE

#define WB_UNUSED

#endif // COMPILER_SUPPORTS_UNUSED_ATTRIBUTE


#define WB_INTERNAL_ATOM_MIN_VAL 0x3f000000L         
typedef int WB_INT32;

typedef unsigned int WB_UINT32;


#if defined(HAVE_LONGLONG) || defined(__DOXYGEN__) /* 'configure' tests for 'long long' datatype valid in configure script */

#define HAS_WB_UINT64_BUILTIN


typedef long long WB_INT64;

typedef unsigned long long WB_UINT64;

#else // !defined HAVE_LONGLONG, unlikely (this part won't show up in doxygen either)

typedef struct tagWB_INT64 { WB_UINT32 dw2; WB_INT32 dw1; } WB_INT64;    // note 'dw1' is a signed value
typedef struct tagWB_UINT64 { WB_UINT32 dw2; WB_UINT32 dw1; } WB_UINT64;

#endif // _LONGLONG

#ifdef __DOXYGEN__

typedef unsigned long long WB_UINTPTR;
#else /* regular code uses this next part */

#if !defined(__SIZEOF_POINTER__) // TODO find a better way to deal with pointer size if this isn't defined
#define __SIZEOF_POINTER__ 0
#endif

#if defined(__LP64__) /* TODO see what WIN32 vs WIN64 does */
typedef WB_UINT64 WB_UINTPTR;
#elif __SIZEOF_POINTER__ == 4 /* 4-byte pointer */
typedef WB_UINT32 WB_UINTPTR;
#else // assume long pointer
typedef WB_UINT64 WB_UINTPTR;
#endif // __LP64__
#endif // __DOXYGEN__


#define WB_C99_INITIALIZERS /* allow C99-style initializers */

typedef void * WB_MODULE;

typedef pthread_t WB_THREAD;

typedef void (* WB_PROCADDRESS)(void);

typedef pthread_key_t   WB_THREAD_KEY;

typedef WB_UINT32 WB_COND; // defined as 'WB_UINT32' because of pthread_cond problems under Linux
//typedef pthread_cond_t  WB_COND;

typedef pthread_mutex_t WB_MUTEX;

// TODO:  sizeof(int) sizeof(long) - long is 64-bit for GNUC - MS compilers make it 32-bit

#ifdef __DOXYGEN__

#define __PACKED__ /* platform dependent; actual def must be a blank or doxygen barphs on it */

#else // !__DOXYGEN__

#define __PACKED__ __attribute__((__packed__))

#endif // __DOXYGEN__

// end of section for clang and gcc compilers (and also doxygen definitions)
// ======================================================================================

#elif defined(_MSC_VER) /* Microsoft C/C++ compiler */

// ======================================================================================
// this section is dedicated to Microsoft compilers, which do things a bit different...

// TODO:  add proper support for MS compiler
#if _MSC_VER > 1300

// TODO:  specify correct version in which C99 initializers are supported
//        as of MSC for ".Net" 2010 it's _NOT_ supported (still!)
//#define WB_C99_INITIALIZERS

#endif // _MSC_VER > xxxx

#define WB_UNLIKELY(x) (x)
#define WB_LIKELY(x) (x)

#ifndef __inline__
#define __inline__ inline /* this assumes 'inline' is supported (MSC should support this) */
#endif // __inline__

typedef __int64 WB_INT64;
typedef unsigned __int64 WB_UINT64;
typedef int WB_INT32;
typedef unsigned int WB_UINT32;

// use terms similar to MS Windows Win32 API
typedef HMODULE WB_MODULE ;     /* module handle */
typedef HANDLE WB_THREAD;       /* thread handle - thread IDs are still 'int' types */
typedef FARPROC WB_PROCADDRESS; // generic proc address returned from GetProcAddress()

typedef DWORD WBTHREAD_KEY;     // return from 'TlsAlloc()'
typedef HANDLE WB_COND;         // equivalent to an event handle
typedef HANDLE WB_MUTEX;        // equivalent to a mutex handle


// TODO:  sizeof(int) sizeof(long) - long is 32-bit for MSC

// TODO:  compatibility definition file for winders

#define __PACKED__ /* TODO: a definition for packing in MS-land */

// end of section specific to Microsoft compilers
// ======================================================================================

#else // !defined(_MSVC_VER) && !defined(__GNUC__)

#error unknown and/or unsupported compiler

#endif // __GNUC__


// put standard '#define's and typedefs here, the ones that apply to EVERYBODY

#define WB_SECURE_HASH_TIMEOUT 60000 
typedef char * WB_PSTR;         
typedef const char * WB_PCSTR;  


//                                                                                                                               //
//   ____   _                _                      _                _   ____   _             _       _                          //
//  / ___| | |_  __ _  _ __ | |_  _   _  _ __      / \    _ __    __| | / ___| | |__   _   _ | |_  __| |  ___ __      __ _ __    //
//  \___ \ | __|/ _` || '__|| __|| | | || '_ \    / _ \  | '_ \  / _` | \___ \ | '_ \ | | | || __|/ _` | / _ \\ \ /\ / /| '_ \   //
//   ___) || |_| (_| || |   | |_ | |_| || |_) |  / ___ \ | | | || (_| |  ___) || | | || |_| || |_| (_| || (_) |\ V  V / | | | |  //
//  |____/  \__|\__,_||_|    \__| \__,_|| .__/  /_/   \_\|_| |_| \__,_| |____/ |_| |_| \__,_| \__|\__,_| \___/  \_/\_/  |_| |_|  //
//                                      |_|                                                                                      //
//                                                                                                                               //

extern int bQuitFlag;

// these functions are internal-only, implemented in window_helper.c, but must be defined here
void __internal_startup_display(const char *szVal);
void __internal_startup_minimize(void);
void __internal_startup_maximize(void);
void __internal_startup_geometry(const char *szVal);

// thwaw function ARE internal only, implemented in font_helper.c and window_helper.c
void __internal_disable_antialias(void);
void __internal_disable_imagecache(void);



// *******************************************
// STARTUP AND SHUTDOWN (must-call functions)
// *******************************************

void WBPlatformOnInit(void);

void WBPlatformOnExit(void);

#if defined(DOXYGEN) || !defined(_MSC_VER)
int WBMain(int argc, char *argv[], char *envp[]);
#else // MSVC
int __declspec(selectany) WBMain(int argc, char *argv[], char *envp[]);
#endif // _MSC_VER

#if defined(DOXYGEN) || !defined(_MSC_VER)
void WBUsage(void);
#else // _MSC_VER
void __declspec(selectany) WBUsage(void);
#endif // _MSC_VER

int WBParseStandardArguments(int *pargc, char ***pargv, char ***penvp);

void WBToolkitUsage(void);

const char *GetStartupAppName(void);




//                                                                          //
//      ____               _                     _   _  _    _  _           //
//     / ___|  _   _  ___ | |_  ___  _ __ ___   | | | || |_ (_)| | ___      //
//     \___ \ | | | |/ __|| __|/ _ \| '_ ` _ \  | | | || __|| || |/ __|     //
//      ___) || |_| |\__ \| |_|  __/| | | | | | | |_| || |_ | || |\__ \     //
//     |____/  \__, ||___/ \__|\___||_| |_| |_|  \___/  \__||_||_||___/     //
//             |___/                                                        //
//                                                                          //


#if defined(HAS_WB_UINT64_BUILTIN) || defined(__DOXYGEN__)
WB_UINT64 WBGetTimeIndex(void);
#else // !defined(HAS_WB_UINT64_BUILTIN) && !defined(__DOXYGEN__)
WB_UINT32 WBGetTimeIndex(void);
#endif // defined(HAS_WB_UINT64_BUILTIN) || defined(__DOXYGEN__)


void WBDelay(uint32_t uiDelay);  // approximate delay for specified period (in microseconds).  may be interruptible


int WBCPUCount(void);



//                                                                                                          //
//   __  __                                           _     _  _                     _    _                 //
//  |  \/  |  ___  _ __ ___    ___   _ __  _   _     / \   | || |  ___    ___  __ _ | |_ (_)  ___   _ __    //
//  | |\/| | / _ \| '_ ` _ \  / _ \ | '__|| | | |   / _ \  | || | / _ \  / __|/ _` || __|| | / _ \ | '_ \   //
//  | |  | ||  __/| | | | | || (_) || |   | |_| |  / ___ \ | || || (_) || (__| (_| || |_ | || (_) || | | |  //
//  |_|  |_| \___||_| |_| |_| \___/ |_|    \__, | /_/   \_\|_||_| \___/  \___|\__,_| \__||_| \___/ |_| |_|  //
//                                         |___/                                                            //
//                                                                                                          //


// memory allocation (with debug support)

void *WBAlloc(int nSize);

void WBFree(void *pBuf);

int WBAllocUsableSize(void *pBuf);

void * WBReAlloc(void *pBuf, int nNewSize);

void WBSubAllocTrashMasher(void);


// BASIC STRING UTILITIES

// simple but helpful string utilities

char *WBCopyString(const char *pSrc);

char *WBCopyStringN(const char *pSrc, unsigned int nMaxChars);

void WBCatString(char **ppDest, const char *pSrc);

void WBCatStringN(char **ppDest, const char *pSrc, unsigned int nMaxChars);

void WBDeQuoteString(char *pszStr);      // de-quote a string in place

void WBNormalizeXMLString(char *pString);

int WBStringLineCount(const char *pSrc, unsigned int nMaxChars);

const char *WBStringNextLine(const char *pSrc, unsigned int *pnMaxChars);


#if 0

// THIS IS ALL RESERVED FOR FUTURE USE
// MAY NOT BE NEEDED IF I USE _Xmbtowc _Xwctomb and _Xwctomb
// X11 defines them as mblen(), mbtowc(), and wctomb()
// The alternative is to do something similar on WIN32, once that is implemented in the toolkit
// with '#ifdef blocks all around it

int WBIsMultiByte(const char *pszStr);


XChar2b * WBConvertMultiByteTo16(const char *pszStr);

char *WBConvertMultiByteFrom16(const XChar2b *pwzStr);
#endif // 0


//                                                                          //
//     __  __ ____   __  __   _      _  _                                   //
//     \ \/ /|  _ \ |  \/  | | |    (_)| |__   _ __  __ _  _ __  _   _      //
//      \  / | |_) || |\/| | | |    | || '_ \ | '__|/ _` || '__|| | | |     //
//      /  \ |  __/ | |  | | | |___ | || |_) || |  | (_| || |   | |_| |     //
//     /_/\_\|_|    |_|  |_| |_____||_||_.__/ |_|   \__,_||_|    \__, |     //
//                                                               |___/      //
//                                                                          //


// XPM library (libXpm) and X11/xpm.h

#if defined(X11WORKBENCH_TOOLKIT_HAVE_XPM) && !defined(__DOXYGEN__)

// Doxygen doesn't need THIS part, it needs the other one.

#include <X11/xpm.h>

// no need for doxygen doc comments here, see '!defined(__DOXYGEN__)' above
// these definitions are for when libXpm is being used
#define XPM_ATTRIBUTES XpmAttributes
#define XPM_CREATE_PIXMAP_FROM_DATA(A,B,C,D,E,F) XpmCreatePixmapFromData(A,B,C,D,E,F)
#define XPM_FREE_ATTRIBUTES(pAttr) XpmFreeAttributes(pAttr)

#else // !X11WORKBENCH_TOOLKIT_HAVE_XPM or __DOXYGEN__

typedef struct tagXPM_ATTRIBUTES
{
  // I only need certain information from MyLoadPixmapFromData(), so that's all I'm doing with this structure

  int width;    
  int height;   
  int depth;    

} XPM_ATTRIBUTES;


int MyLoadPixmapFromData(Display *pDisplay, Window wID, char *aData[],
                         Pixmap *pPixmap, Pixmap *pMask, XPM_ATTRIBUTES *pAttr);

#define XPM_CREATE_PIXMAP_FROM_DATA(A,B,C,D,E,F) MyLoadPixmapFromData(A,B,C,D,E,F)

#define XPM_FREE_ATTRIBUTES(pAttr) /* does nothing */


#endif


// some helpful macros that need to be universal without being in a different header

#define NEXT_WORD(pX, pY, pZ) {while(*(pX) && *(pX) <= ' '){(pX)++;} (pY)=(pZ)=(pX); while(*(pX)>' '){(pX)++;} (pZ)=(pX);}





#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

// common macros

#ifndef FALSE
#define FALSE 0
#endif // FALSE
#ifndef TRUE
#define TRUE !0
#endif // TRUE



// HANDLING qsort_r CALLING CONVENTION DIFFERENCES
//
#if defined(QSORT_R_BSD) && !defined(__DOXYGEN__)

// DECLARE_SORT_FUNCTION based on - int (*compar)(void *, const void *, const void *)
//    generates    int fn_name(void *p0, const void *p1, const void *p2)
#define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(void *p0, const void *p1, const void *p2)
// void qsort_r(void *base, size_t nmemb, size_t size, void *thunk, int (*compar)(void *, const void *, const void *))
#define QSORT_R(A,B,C,D,E) qsort_r((A),(B),(C),(D),(E))

#elif defined(QSORT_R_GNUC) && !defined(__DOXYGEN__)

// DECLARE_SORT_FUNCTION based on typedef int (*__compar_d_fn_t) (__const void *, __const void *, void *)
//    generates    int fn_name(const void *p1, const void *p2, void *p0)
#define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(const void *p1, const void *p2, void *p0)
// extern void qsort_r (void *__base, size_t __nmemb, size_t __size, __compar_d_fn_t __compar, void *__arg)
#define QSORT_R(A,B,C,D,E) qsort_r((A),(B),(C),(E),(D))

#else

// here is where I implement 'vectored' quicksort for OTHER PLATFORMS

void my_qsort_r(void *base, int nmemb, int size, void *thunk,
                int (*compar)(void *, const void *, const void *));

// the rest is exactly like the BSD version

#define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(void *p0, const void *p1, const void *p2)


#define QSORT_R(base,nmemb,size,thunk,compar) my_qsort_r((base),(nmemb),(size),(thunk),(compar))

#endif


//                                                                          //
//                ___         _                             _               //
//               |_ _| _ __  | |_  ___  _ __  _ __    __ _ | |              //
//                | | | '_ \ | __|/ _ \| '__|| '_ \  / _` || |              //
//                | | | | | || |_|  __/| |   | | | || (_| || |              //
//               |___||_| |_| \__|\___||_|   |_| |_| \__,_||_|              //
//                                                                          //
//                                                                          //


// *********************************
// INTERNAL memory/security helpers
// *********************************

WB_UINT32 WBCreatePointerHash(void *pPointer);

void WBDestroyPointerHash(WB_UINT32 uiHash);

void WBDestroyPointerHashPtr(void *pPointer);

void * WBGetPointerFromHash(WB_UINT32 uiHash);



//                                                                          //
//                        _    _                                            //
//                       / \  | |_  ___   _ __ ___   ___                    //
//                      / _ \ | __|/ _ \ | '_ ` _ \ / __|                   //
//                     / ___ \| |_| (_) || | | | | |\__ \                   //
//                    /_/   \_\\__|\___/ |_| |_| |_||___/                   //
//                                                                          //
//                                                                          //

//-----------------------------------------
// ATOM HELPERS (internally-defined atoms)
//-----------------------------------------


Atom WBGetAtom(Display *pDisplay, const char *szAtomName);

Atom WBLookupAtom(Display *pDisplay, const char *szAtomName);

char * WBGetAtomName(Display *pDisplay, Atom aAtom);




//                                                                                                               //
//   ____         _    _                              _   _____                         _____  _  _              //
//  |  _ \  __ _ | |_ | |__   ___    __ _  _ __    __| | |_   _|___  _ __ ___   _ __   |  ___|(_)| |  ___  ___   //
//  | |_) |/ _` || __|| '_ \ / __|  / _` || '_ \  / _` |   | | / _ \| '_ ` _ \ | '_ \  | |_   | || | / _ \/ __|  //
//  |  __/| (_| || |_ | | | |\__ \ | (_| || | | || (_| |   | ||  __/| | | | | || |_) | |  _|  | || ||  __/\__ \  //
//  |_|    \__,_| \__||_| |_||___/  \__,_||_| |_| \__,_|   |_| \___||_| |_| |_|| .__/  |_|    |_||_| \___||___/  //
//                                                                             |_|                               //
//                                                                                                               //

// *******************************************
// FILE/APPLICATION SEARCH PATH AND TEMP FILES
// *******************************************

int WBMkDir(const char *szFileName, int flags);


char * WBSearchPath(const char *szFileName);

char * WBTempFile(const char *szExt);


char * WBTempFile0(const char *szExt);



//                                                                                                                       //
//   _____        _                             _      _                   _  _              _    _                      //
//  | ____|__  __| |_  ___  _ __  _ __    __ _ | |    / \    _ __   _ __  | |(_)  ___  __ _ | |_ (_)  ___   _ __   ___   //
//  |  _|  \ \/ /| __|/ _ \| '__|| '_ \  / _` || |   / _ \  | '_ \ | '_ \ | || | / __|/ _` || __|| | / _ \ | '_ \ / __|  //
//  | |___  >  < | |_|  __/| |   | | | || (_| || |  / ___ \ | |_) || |_) || || || (__| (_| || |_ | || (_) || | | |\__ \  //
//  |_____|/_/\_\ \__|\___||_|   |_| |_| \__,_||_| /_/   \_\| .__/ | .__/ |_||_| \___|\__,_| \__||_| \___/ |_| |_||___/  //
//                                                          |_|    |_|                                                   //
//                                                                                                                       //
//                          _                _   ____                                                                    //
//                         / \    _ __    __| | |  _ \  _ __  ___    ___  ___  ___  ___   ___  ___                       //
//                        / _ \  | '_ \  / _` | | |_) || '__|/ _ \  / __|/ _ \/ __|/ __| / _ \/ __|                      //
//                       / ___ \ | | | || (_| | |  __/ | |  | (_) || (__|  __/\__ \\__ \|  __/\__ \                      //
//                      /_/   \_\|_| |_| \__,_| |_|    |_|   \___/  \___|\___||___/|___/ \___||___/                      //
//                                                                                                                       //

// *********************
// SPAWNING APPLICATIONS
// *********************

#ifdef WIN32
#define WB_FILE_HANDLE HANDLE
#define WB_PROCESS_ID HANDLE
#define WB_INVALID_FILE_HANDLE INVALID_HANDLE_VALUE
#else // !WIN32
#define WB_FILE_HANDLE int
#define WB_PROCESS_ID unsigned int
#define WB_INVALID_FILE_HANDLE -1
#endif // WIN32

WB_PROCESS_ID WBRunAsync(const char *szAppName, ...);

int WBGetProcessState(WB_PROCESS_ID idProcess, WB_INT32 *pExitCode);

char * WBRunResult(const char *szAppName, ...);

char * WBRunResultWithInput(const char *szStdInBuf, const char *szAppName, ...);

WB_PROCESS_ID WBRunAsyncPipe(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr,
                             const char *szAppName, ...);

WB_PROCESS_ID WBRunAsyncPipeV(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr,
                              const char *szAppName, va_list va);




//   ____  _   _    _    ____  _____ ____    _     ___ ____ ____     //
//  / ___|| | | |  / \  |  _ \| ____|  _ \  | |   |_ _| __ ) ___|    //
//  \___ \| |_| | / _ \ | |_) |  _| | | | | | |    | ||  _ \___ \    //
//   ___) |  _  |/ ___ \|  _ <| |___| |_| | | |___ | || |_) |__) |   //
//  |____/|_| |_/_/   \_\_| \_\_____|____/  |_____|___|____/____/    //
//                                                                   //

WB_MODULE WBLoadLibrary(const char *szModuleName); // load a library module (shared lib, DLL, whatever)

void WBFreeLibrary(WB_MODULE hModule);

WB_PROCADDRESS WBGetProcAddress(WB_MODULE hModule, const char *szProcName);

void * WBGetDataAddress(WB_MODULE hModule, const char *szDataName);


//   _____ _   _ ____  _____    _    ____  ____     //
//  |_   _| | | |  _ \| ____|  / \  |  _ \/ ___|    //
//    | | | |_| | |_) |  _|   / _ \ | | | \___ \    //
//    | | |  _  |  _ <| |___ / ___ \| |_| |___) |   //
//    |_| |_| |_|_| \_\_____/_/   \_\____/|____/    //
//                                                  //

WB_THREAD_KEY WBThreadAllocLocal(void);

void WBThreadFreeLocal(WB_THREAD_KEY keyVal);

void * WBThreadGetLocal(WB_THREAD_KEY keyVal);

void WBThreadSetLocal(WB_THREAD_KEY keyVal, void *pValue);


// simplified thread support (cross-platform)

WB_THREAD WBThreadGetCurrent(void);

WB_THREAD WBThreadCreate(void *(*function)(void *), void *pParam);

void *WBThreadWait(WB_THREAD hThread);        // closes hThread, returns exit code, waits for thread to terminate (blocks)

int WBThreadRunning(WB_THREAD hThread);

void WBThreadExit(void *pRval);

void WBThreadClose(WB_THREAD hThread);


int WBCondCreate(WB_COND *pCond);

int WBMutexCreate(WB_MUTEX *pMtx);

void WBCondFree(WB_COND *pCond);

void WBMutexFree(WB_MUTEX *pMtx);

int WBMutexLock(WB_MUTEX *pMtx, int nTimeout);

int WBMutexUnlock(WB_MUTEX *pMtx);

int WBCondSignal(WB_COND *pCond);

int WBCondWait(WB_COND *pCond, int nTimeout);

int WBCondWaitMutex(WB_COND *pCond, WB_MUTEX *pMtx, int nTimeout);


WB_UINT32 WBInterlockedDecrement(volatile WB_UINT32 *pValue);


WB_UINT32 WBInterlockedIncrement(volatile WB_UINT32 *pValue);


WB_UINT32 WBInterlockedExchange(volatile WB_UINT32 *pValue, WB_UINT32 nNewVal);


WB_UINT32 WBInterlockedRead(volatile WB_UINT32 *pValue);



//   ____  ____  ___ _   _ _____ ___ _   _  ____    //
//  |  _ \|  _ \|_ _| \ | |_   _|_ _| \ | |/ ___|   //
//  | |_) | |_) || ||  \| | | |  | ||  \| | |  _    //
//  |  __/|  _ < | || |\  | | |  | || |\  | |_| |   //
//  |_|   |_| \_\___|_| \_| |_| |___|_| \_|\____|   //
//                                                  //

// NOTE:  the POSIX world uses postscript, particularly with CUPS.  So does this library.

int WBPrintPostScriptFile(const char *szPrinterName, const char *szFileName);

char *WBGetPrinterList(void);

// TODO:  complete IPP support for cups and network-capable printers

// TODO:  printer capabilities in a binary structure

// TODO:  support for port 515 'printer' TCP/UDP printer services (i.e. cups-lpd or lpd)

// TODO:  dynamically load CUPS API when available. see 'cups-config' application docs



#ifdef __cplusplus
};
#endif // __cplusplus


#endif // _PLATFORM_HELPER_H_INCLDUED_