clipboard_helper.c

Go to the documentation of this file.

//                                                                                                     //
//         _  _         _                             _       _            _                           //
//    ___ | |(_) _ __  | |__    ___    __ _  _ __  __| |     | |__    ___ | | _ __    ___  _ __  ___   //
//   / __|| || || '_ \ | '_ \  / _ \  / _` || '__|/ _` |     | '_ \  / _ \| || '_ \  / _ \| '__|/ __|  //
//  | (__ | || || |_) || |_) || (_) || (_| || |  | (_| |     | | | ||  __/| || |_) ||  __/| | _| (__   //
//   \___||_||_|| .__/ |_.__/  \___/  \__,_||_|   \__,_|_____|_| |_| \___||_|| .__/  \___||_|(_)\___|  //
//              |_|                                    |_____|               |_|                       //
//                                                                                                     //
//                                     internal clipboard support                                      //
//                                                                                                     //

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

    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

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


#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
#include <limits.h>
#include <unistd.h>
#include <memory.h>
#include <string.h>
#include <strings.h>
#include <signal.h>
#include <time.h>
#include <fcntl.h>
#include <errno.h>
#include <sys/time.h>

// TODO:  determine if pthread is available
#include <pthread.h> /* currently required */

#define _CLIPBOARD_HELPER_C /* to exclude certain things from window_helper.h like Atoms */

#include "window_helper.h"
#include "pixmap_helper.h"
#include "conf_help.h"
#include "platform_helper.h"
#include "draw_text.h"
#include "text_object.h"

#define MIN_EVENT_LOOP_SLEEP_PERIOD 100    /* 0.1 millisec */
#define MAX_EVENT_LOOP_SLEEP_PERIOD 100000 /* 0.1 seconds max per loop for clipboard */


typedef struct _ClipboardTask_ // only for getting data; setting data done immediately
{
  volatile struct _ClipboardTask_ *pNext; // singly linked list

  int fType;       // get (0) or set (1) [others reserved]
  void *pData;     // 'WBAlloc'd data when 'get' completed
  int cbLength;    // length of buffer
  Atom aSelection; // 'selection' to grab ('None' implies "CLIPBOARD" behavior)
  Atom aType;      // data type
  int nFormat;     // format of data (0, 8, 16, 32)
  int nRefCount;   // reference count (increment before 'owning' while global lock held)

  WB_COND cond;    // condition to trigger when completed (and free when 'freed')

  // state-related things
  int fState;    // flag to indicate status
  Atom aProp;    // the property associated with this task
  WB_UINT64 ullTime; // timestamp for various timeouts (reserved)

} CLIPBOARD_TASK;


typedef struct _ClipboardData_ // for when I own the clipboard
{
  struct _ClipboardData_ *pNext; // double-link list

  Atom aSelection; // 'selection' to grab ('None' implies "CLIPBOARD" behavior)
  Atom aType;      // type of data
  int cbLength;    // length of buffer
  int nFormat;     // format of data

  // cached data
  Window wTo;    // window that I'm currently sending to [for multi-requests]
  int fState;    // flag to indicate status


  char aData[1]; // actual data goes here

} CLIPBOARD_DATA;


static WB_THREAD hClipboardThread = (WB_THREAD)INVALID_HANDLE_VALUE;
static volatile int bClipboardQuitFlag = 0;
static volatile CLIPBOARD_TASK * volatile pCBTHead = NULL;  // WBAlloc'd structures
static CLIPBOARD_DATA *pCBDHead = NULL;  // both are linked lists

static WB_MUTEX xClipboardMutex;

static void * ClipboardThreadProc(void *);



// WBInitClipboardSystem
// return ZERO if clipboard system is initialized properly
int WBInitClipboardSystem(Display *pDisplay, const char *szDisplayName)
{
int iRval;
#ifndef NO_DEBUG
unsigned long long ullTick;
#endif // NO_DEBUG

#ifndef NO_DEBUG
  ullTick = WBGetTimeIndex();
#endif // NO_DEBUG

  iRval = __StartInitClipboardSystem(pDisplay, szDisplayName);

  if(!iRval) // so far so good
  {
    iRval = __FinishInitClipboardSystem(pDisplay, szDisplayName);
  }

#ifndef NO_DEBUG
  ullTick = WBGetTimeIndex() - ullTick;
  WBDebugPrint("TEMPORARY:  %s took %llu ticks)\n", __FUNCTION__, ullTick);
#endif // NO_DEBUG

  return iRval;
}

static char *pGlobalDisplayNameForClipboardInit = NULL;

int __StartInitClipboardSystem(Display *pDisplay, const char *szDisplayName)
{
  // for debugging purposes, keep track of how long it takes

  // TODO:  check 'hClipboardThread' and/or 'bClipboardQuitFlag'

  if(!szDisplayName ||
     (pDisplay && pDisplay != WBGetDefaultDisplay())) // for now, this param is reserved
  {
    szDisplayName = GetStartupDisplayName();
    if(!szDisplayName || !*szDisplayName)
    {
      szDisplayName = ":0.0"; // make sure it's SOMETHING
    }
  }

  pGlobalDisplayNameForClipboardInit = WBCopyString(szDisplayName);

  if(!pGlobalDisplayNameForClipboardInit)
  {
    WB_ERROR_PRINT("ERROR:  in %s - NULL display name\n",__FUNCTION__);

    return 1; // error
  }

  if(1) // TODO:  check for initialization of mutex already
  {
    if(WBMutexCreate(&xClipboardMutex))
    {
      WB_ERROR_PRINT("ERROR:  in %s - Unable to create mutex\n",__FUNCTION__);

      return 2; // error
    }
//    else
//    {
//      WB_ERROR_PRINT("TEMPORARY:  %s - mutex created\n",__FUNCTION__);
//    }
  }

  // TODO:  check if clipboard thread already started?

  bClipboardQuitFlag = 1; // initial value.  when it's zero, I'm started.  If < 0, error

  pCBTHead = NULL;
  pCBDHead = NULL; // make sure in both cases

  hClipboardThread = WBThreadCreate(ClipboardThreadProc, pGlobalDisplayNameForClipboardInit);

  if(hClipboardThread == (WB_THREAD)INVALID_HANDLE_VALUE)
  {
    WBMutexFree(&xClipboardMutex);

    return 3;
  }

  return 0;
}


int __FinishInitClipboardSystem(Display *pDisplay, const char *szDisplayName)
{
int iDelayPeriod = MIN_EVENT_LOOP_SLEEP_PERIOD;

  while(WBThreadRunning(hClipboardThread) &&
        bClipboardQuitFlag > 0)
  {
    WBDelay(iDelayPeriod); // wait for my thread to initialize

    if(iDelayPeriod < MAX_EVENT_LOOP_SLEEP_PERIOD)
    {
      iDelayPeriod += (iDelayPeriod >> 1);
    }
    else
    {
      iDelayPeriod = MAX_EVENT_LOOP_SLEEP_PERIOD;
    }
  }

  if(pGlobalDisplayNameForClipboardInit)
  {
    WBFree(pGlobalDisplayNameForClipboardInit);  // ok to free it now
    pGlobalDisplayNameForClipboardInit = NULL;
  }

  if(bClipboardQuitFlag || !WBThreadRunning(hClipboardThread))
  {
    WBThreadWait(hClipboardThread); // wait for thread to exit (should be already)

    hClipboardThread = (WB_THREAD)NULL; // make sure

    WBMutexFree(&xClipboardMutex);

    return 4; // error
  }

  WB_DEBUG_PRINT(DebugLevel_Light | DebugSubSystem_Init, "INFO:  %s - Clipboard Thread started\n",__FUNCTION__);

  return 0; // everything's ok
}


void WBExitClipboardSystem(Display *pDisplay)
{
  if(pDisplay && pDisplay != WBGetDefaultDisplay())
  {
    WB_ERROR_PRINT("ERROR:  invalid 'pDisplay' in WBExitClipboardSystem\n");
    return;
  }

  if(hClipboardThread != (WB_THREAD)INVALID_HANDLE_VALUE)
  {
    bClipboardQuitFlag = 1;

    WBThreadWait(hClipboardThread); // wait for thread to exit
  }
  else
  {
    WB_ERROR_PRINT("ERROR:  in %s - hClipboardThread == INVALID_HANDLE_VALUE\n",__FUNCTION__);

    // continue anyway to free other resources...
  }

  hClipboardThread = (WB_THREAD)INVALID_HANDLE_VALUE; // make sure

  // while mutex owned, free up the link lists

  while(pCBTHead) // unlikely but possible
  {
    volatile CLIPBOARD_TASK *pT = pCBTHead;
    pCBTHead = pCBTHead->pNext;

    // since I'm not checking the ref count a crash COULD happen here
    // the alternative is a MEMORY LEAK.  Which is worse???
    // The fact is that the calling thread should NOT allow this to be
    // invoked until everything waiting on the clipboard has finished, so...

    WB_ERROR_PRINT("WARNING:  %s - non-null 'clipboard task' being deleted (%p), ref count %d\n",
                   __FUNCTION__, pT, pT->nRefCount);

    if(pT->fType == 0 // only for 'get'
       && pT->pData)
    {
      WBFree(pT->pData);
    }

    WBCondFree((WB_COND *)&(pT->cond)); // assume it works (and signals anything waiting with an error)

    WBFree((void *)pT);
  }

  while(pCBDHead) // this one is more likely to have data in it
  {
    CLIPBOARD_DATA *pD = pCBDHead;
    pCBDHead = pCBDHead->pNext;

    WBFree(pD); // this one is very simple
  }

//  pCBTHead = NULL;
//  pCBDHead = NULL; // make sure in both cases

  if(1) // TODO:  check for initialization of mutex already to avoid possible crashes
  {
    WBMutexFree(&xClipboardMutex);
  }

  WB_DEBUG_PRINT(DebugLevel_Light | DebugSubSystem_Init, "INFO:  %s - Clipboard Thread ended\n",__FUNCTION__);
}


#if 0 /* uncomment this if I need the functionality; otherwise, consider removing it */
// event check 'predicate' proc for selection events
static Bool __ClipboardThreadEventPredicate(Display *pDisplay, XEvent *pEvent, XPointer arg)
{
  if(pEvent &&
     (pEvent->type == SelectionNotify ||
      pEvent->type == SelectionClear ||
      pEvent->type == SelectionRequest))
  {
    return TRUE;
  }
  else
  {
    return FALSE;
  }
}
#endif // 0


// a few utilities placed here to make the code read better

void CleanupDoneList(CLIPBOARD_TASK **ppDoneList)
{
CLIPBOARD_TASK *pT;

  // MUST call this with the clipboard mutex owned

  pT = *ppDoneList; // makes me go through a loop before deleting one of the tasks

  if(pT)
  {
    // remove the first item 'pT' from the done list

    *ppDoneList = (CLIPBOARD_TASK *)pT->pNext;

    pT->pNext = NULL;

    if(!WBInterlockedDecrement((unsigned int *)&(pT->nRefCount))) // flags a delete when ref count is zero
    {
      // if the ref count is higher than zero, someone else must delete this instead

      if(!pT->fType && pT->pData) // it COULD happen...
      {
        WBFree(pT->pData);
        pT->pData = NULL;
      }

      WBCondFree((WB_COND *)&(pT->cond)); // assume it works

      WBFree((void *)pT);  // do this while locked
    }
  }
}

void AddNewItemToRunList(CLIPBOARD_TASK **ppRunList)
{
CLIPBOARD_TASK *pT, *pT2;

  // next, grab an item from the 'new' queue
  pT = (CLIPBOARD_TASK *)pCBTHead;

  if(pT)
  {
    pCBTHead = pT->pNext;

    WBInterlockedIncrement((unsigned int *)&(pT->nRefCount)); // I own it now

    pT->pNext = NULL; // make sure

    // make sure the 'state' flag indicates zero [errors, aka < 0, will cause it to be deleted]
    pT->fState = 0;
    pT->aProp = None; // and also pre-assign this to 'none'

    // now 'walk' the running list and add it

    if(!*ppRunList)
    {
      *ppRunList = (CLIPBOARD_TASK *)pT;
    }
    else
    {
      pT2 = *ppRunList;

      while(pT2->pNext)
      {
        pT2 = (CLIPBOARD_TASK *)pT2->pNext;
      }

      pT2->pNext = pT;
    }
  }
}


// static thread proc for clipboard
// display name is sent as const char *
// TODO:  one thread per display??

void * ClipboardThreadProc(void *pParam)
{
unsigned long long ullTick;
int iLen, iFactor, iDelayPeriod;
const char *pDisplayName = (const char *)pParam;
Display *pDisplay = NULL;
volatile CLIPBOARD_TASK *pT;
CLIPBOARD_TASK *pT2, *pT3;
CLIPBOARD_TASK *pRunList = NULL; // what I'm running at the moment
CLIPBOARD_TASK *pDoneList = NULL; // things that get free'd up later
CLIPBOARD_DATA *pD, *pD2;
Window wWindow = None;
XEvent evt, evt2;
Atom aType;
// NOTE:  Atoms in 'window_helper.h' won't be defined, see headers above.  They apply to the main thread.
//        These local variables will do the job instead, since it becomes local to the thread this way
Atom aINCR, aWBCLIP, aCLIPBOARD, aTEXT, aC_STRING, aCOMPOUND_TEXT, aTARGETS, aMULTIPLE,
     aTIMESTAMP, aPIXEL, aNULL;
#ifdef X_HAVE_UTF8_STRING /* this indicates the extension is present */
Atom aUTF8_STRING;
#endif // X_HAVE_UTF8_STRING
// NOTE:  these atoms won't need to be loaded - they're pre-defined (left for reference)
//Atom aPRIMARY   = XA_PRIMARY;
//Atom aSECONDARY = XA_SECONDARY;
//Atom aSTRING    = XA_STRING;
//Atom aBITMAP    = XA_BITMAP;
//Atom aDRAWABLE  = XA_DRAWABLE;
//Atom aCOLORMAP  = XA_COLORMAP;
//Atom aPIXMAP    = XA_PIXMAP;


  ullTick = WBGetTimeIndex();

  pDisplay = XOpenDisplay(pDisplayName);

  if(!pDisplay)
  {
    WB_ERROR_PRINT("%s - can't open display %s\n", __FUNCTION__, pDisplayName);

    bClipboardQuitFlag = -1;
    goto exit_point;
  }

  // Load all of the atoms for use within this thread
  aINCR             = XInternAtom(pDisplay, "INCR", False);
  aWBCLIP           = XInternAtom(pDisplay, "WB_CLIP", False);
  aCLIPBOARD        = XInternAtom(pDisplay, "CLIPBOARD", False); // should I use XA_CLIPBOARD(pDisplay) instead??
  aTEXT             = XInternAtom(pDisplay, "TEXT", False);
  aC_STRING         = XInternAtom(pDisplay, "C_STRING", False);
  aCOMPOUND_TEXT    = XInternAtom(pDisplay, "COMPOUND_TEXT", False);
  aTARGETS          = XInternAtom(pDisplay, "TARGETS", False);
  aMULTIPLE         = XInternAtom(pDisplay, "MULTIPLE", False);
  aTIMESTAMP        = XInternAtom(pDisplay, "TIMESTAMP", False);
  aPIXEL            = XInternAtom(pDisplay, "PIXEL", False);

#ifdef X_HAVE_UTF8_STRING /* this indicates the extension is present */
  aUTF8_STRING      = XInternAtom(pDisplay, "UTF8_STRING", False);
#endif // X_HAVE_UTF8_STRING

  aNULL             = XInternAtom(pDisplay, "NULL", False);

  // NOTE:  these will actually match the ones allocated from the default display
  //        and later on, I will have to rely on that.  But for now I have my own
  //        copies.  A nice TODO would be to make sure they match.

  if(aINCR             == None ||
     aWBCLIP           == None ||
     aCLIPBOARD        == None ||
     aTEXT             == None ||
     aC_STRING         == None ||
     aCOMPOUND_TEXT    == None ||
     aTARGETS          == None ||
     aMULTIPLE         == None ||
     aTIMESTAMP        == None ||
     aPIXEL            == None ||
#ifdef X_HAVE_UTF8_STRING /* this indicates the extension is present */
     aUTF8_STRING      == None || // TODO:  should this one be optional?
#endif // X_HAVE_UTF8_STRING
     aNULL             == None)
  {
    WB_ERROR_PRINT("%s - error getting Atoms\n"
                   "        aINCR=%d\n"
                   "        aWBCLIP=%d\n"
                   "        aCLIPBOARD=%d\n"
                   "        aTEXT=%d\n"
                   "        aC_STRING=%d\n"
                   "        aCOMPOUND_TEXT=%d\n"
                   "        aTARGETS=%d\n"
                   "        aMULTIPLE=%d\n"
                   "        aTIMESTAMP=%d\n"
                   "        aPIXEL=%d\n"
#ifdef X_HAVE_UTF8_STRING /* this indicates the extension is present */
                   "        aUTF8_STRING=%d\n"
#endif // X_HAVE_UTF8_STRING
                   "        aNULL=%d\n", __FUNCTION__,
                   (int)aINCR, (int)aWBCLIP, (int)aCLIPBOARD, (int)aTEXT, (int)aC_STRING,
                   (int)aCOMPOUND_TEXT, (int)aTARGETS, (int)aMULTIPLE, (int)aTIMESTAMP, (int)aPIXEL,
#ifdef X_HAVE_UTF8_STRING /* this indicates the extension is present */
                   (int)aUTF8_STRING,
#endif // X_HAVE_UTF8_STRING
                   (int)aNULL);

    bClipboardQuitFlag = -1;
    goto exit_point;
  }

  // create thread's 'simple window' and enable property change/selection stuff

  wWindow = XCreateSimpleWindow(pDisplay, DefaultRootWindow(pDisplay), 0, 0, 1, 1, 0, 0, 0);

  if(wWindow == None)
  {
    bClipboardQuitFlag = -1;

    WB_ERROR_PRINT("%s - can't create simple window\n", __FUNCTION__);

    goto exit_point;
  }

  XSelectInput(pDisplay, wWindow, PropertyChangeMask); // important - select property change input

  // wWindow is going to own every clipboard data thing

  XSync(pDisplay, 0); // make sure that the display is "in sync"

  bClipboardQuitFlag = 0;  // to trigger "I am done initializing" and it's ok

  WBDelay(100000); // wait 0.1 seconds for everything to stabilize (TODO: is this needed here?)

  pDisplayName = NULL; // no longer valid (TODO:  cache it for multiple display instances?)

  ullTick = WBGetTimeIndex() - ullTick;

  WB_DEBUG_PRINT(DebugLevel_Light | DebugSubSystem_Init, "INFO:  %s - Clipboard Thread initialization complete\n",__FUNCTION__);
  WB_DEBUG_PRINT(DebugLevel_Medium | DebugSubSystem_Init, "CLIPBOARD THREAD STARTUP took %llu ticks\n", ullTick);

  // -------------------------------------------------------
  // main handler loop - this executes the clipboard thread
  // -------------------------------------------------------

  iDelayPeriod = MIN_EVENT_LOOP_SLEEP_PERIOD;

  while(!bClipboardQuitFlag)
  {
    if(WBMutexLock(&xClipboardMutex, 1000)) // wait up to 1msec to lock
    {
      // well looks like I could NOT own the mutex

      WBDelay(100); // make sure I do this at least once in this loop, waiting for clipboard mutex
    }
    else
    {
      // clipboard task lock achieved, do some housekeeping

      // first clean up the "done" list (removes only the first item in it)
      CleanupDoneList(&pDoneList);

      // next, grab an item from the 'new' queue and add it to the 'run' list
      AddNewItemToRunList(&pRunList);

      // unlock the mutex now
      WBMutexUnlock(&xClipboardMutex); // not locked now
    }

    // now go through my 'run list' and work on whatever is here
    pT2 = NULL;  // this will be my 'prev' pointer for unlinking
    pT = pRunList;

    // NOTE:  because of the use of automatic variables rather than globals,
    //        I pretty much need to do this in one big freaking loop.
              pD = pCBDHead;
    while(pT)
    {
      int bDoneAndSignal = 0; // this flag tells me to place the item in the 'done queue' and signal the owner

      // PROCESS RUN LIST - CHECK 'CANCEL STATE' FIRST

      // check 'fState' - if it's negative, the task has been canceled or was an error I didn't catch before

      if((int)WBInterlockedRead((unsigned int *)&(pT->fState)) < 0) // error state - these will be moved to 'done list'
      {
        bDoneAndSignal = 1; // if marked 'error' the request was canceled and it needs to be deleted
        // this will flow through and signal the caller
      }
      // CONTINUE NORMAL PROCESSING (NOT CANCELED)
      else if(pT->fType == 0) // get clipboard data
      {
        // GET CLIPBOARD DATA - INITIALIZATION, 'state zero'

        if(pT->fState == 0) // state zero - just starting out
        {
          Window wOwn;
          Atom aSelection;

          aSelection = pT->aSelection;
          if(aSelection == None)
          {
            wOwn = XGetSelectionOwner(pDisplay, XA_PRIMARY);

            if(wOwn != None)
            {
              aSelection = XA_PRIMARY;
            }
            else
            {
              wOwn = XGetSelectionOwner(pDisplay, aCLIPBOARD);

              if(wOwn != None)
              {
                aSelection = aCLIPBOARD;
              }
            }

            if(wOwn != None)
            {
              pT->aSelection = aSelection;
            }
          }
          else
          {
            wOwn = XGetSelectionOwner(pDisplay, aSelection);

#ifndef NO_DEBUG
            if(aSelection != XA_PRIMARY && aSelection != aCLIPBOARD)
            {
              char *p1 = WBGetAtomName(pDisplay, aSelection);
              WB_ERROR_PRINT("TEMPORARY:  %s - selection = %d \"%s\"  owner = %u (%08xH)\n",
                             __FUNCTION__, (int)aSelection, p1, (int)wOwn, (int)wOwn);
              if(p1)
              {
                WBFree(p1);
              }
            }
#endif // NO_DEBUG
          }

          if(wOwn == wWindow) // it's me
          {
//            WB_ERROR_PRINT("TEMPORARY: %s - request clipboard and I own it\n", __FUNCTION__);

            // re-acquire the mutex

            if(!WBMutexLock(&xClipboardMutex, 100000L)) // re-lock, up to 0.1 seconds
            {
              // walk the data chain looking for a match
              pD = pCBDHead;

              while(pD && pD->aSelection != aSelection)
              {
                pD = pD->pNext;
              }

              if(!pD) // try 'soft match' instead
              {
                pD = pCBDHead;

                while(pD)
                {
                  if(pD->aSelection == None &&
                     (aSelection == XA_PRIMARY ||
                      aSelection == aCLIPBOARD))
                  {
                    break;
                  }

                  pD = pD->pNext;
                }
              }

              if(pD) // it will match
              {
                if(pD->nFormat == 16) // format determines element size
                {
                  iFactor = 2;
                }
                else if(pD->nFormat == 32)
                {
                  iFactor = 4;
                }
                else
                {
                  iFactor = 1;
                }

                iLen = iFactor * pD->cbLength; // actual length in bytes

                pT->pData = WBAlloc(iLen + iFactor);

                if(pT->pData)
                {
                  memcpy(pT->pData, pD->aData, iLen);

                  pT->cbLength = pD->cbLength;
                  pT->nFormat = pD->nFormat;

                  bDoneAndSignal = 1; // put in 'done' queue, signal caller

//                  WB_ERROR_PRINT("TEMPORARY:  %s - return clipboard data %p len=%d (%d)\n",
//                                 __FUNCTION__, pT->pData, pT->cbLength, iLen);
                }
                else
                {
                  // TODO:  set fState to -1 and set 'bDoneAndSignal?
                  //        this could infinitely re-try if I don't...

                  WB_ERROR_PRINT("TEMPORARY:  %s - clipboard data is NULL\n", __FUNCTION__);

                  goto null_data_me_own; // for now I'll do this
                }
              }
              else
              {
null_data_me_own:
                WB_ERROR_PRINT("TEMPORARY:  %s - return NULL clipboard data, owned by me\n", __FUNCTION__);

                // NULL data
                pT->cbLength = 0;
                pT->nFormat = 8;
                pT->pData = NULL; // make sure

                bDoneAndSignal = 1; // put in 'done' queue, signal caller
              }

              WBMutexUnlock(&xClipboardMutex); // not locked now

              // since I have a ref count it's safe to be unlocked here
              // the data members I 'muck' with are reserved and don't need
              // 'atomic' access between this thread and the caller
            }
            else
            {
              // TODO:  set fState to -1 and set 'bDoneAndSignal?
              //        this could infinitely re-try if I don't...

              WB_ERROR_PRINT("TEMPORARY: %s line %d - unable to lock mutex\n", __FUNCTION__, __LINE__);

              pT->fState = -1;
              bDoneAndSignal = 1;  // well I'll do this for now
            }
          }
          else if(wOwn == None) // nobody owns the clipboard
          {
            // NULL data
            pT->cbLength = 0;
            pT->nFormat = 8;
            pT->pData = NULL; // make sure

            bDoneAndSignal = 1; // put in 'done' queue, signal caller
          }
          else
          {
            // I'm not the owner of the clipboard data.  So I must make a request
            // for the data.  When it arrives, I need to hand it off to the caller
            // and then clean myself up [this will happen asynchronously].

            // convert output to 'WB_CLIP' property on the window of my choice
            pT->aProp = aWBCLIP;  // for now always write to this one - later, custom per request?

            XConvertSelection(pDisplay, aSelection, pT->aType,
                              pT->aProp,
                              wWindow, CurrentTime);

            // NOTE:  the function return does not indicate success/fail

//            WB_ERROR_PRINT("TEMPORARY: %s line %d - XConvertSelection, fState set to 1\n", __FUNCTION__, __LINE__);

            pT->fState = 1; // this tells me I'm waiting for the first reply
            pT->ullTime = WBGetTimeIndex(); // the time I sent the message
          }
        }
        else if(pT->fState == 1)  // XConvertSelection sent, no reply yet
        {
          // TODO:  if I am in state 1 and too much time has passed, do I want to cancel the
          //        request and signal a failure??  or do I want to re-issue the
          //        XConvertSelection request?

          // if((WBGetTimeIndex() - pT->ullTime) > some limit)
          // { do something, re-send request, whatever }

          // NOTE:  if the thing gets canceled by the caller, it will get a state of '-1'
        }

      }
      else if(pT->fType == 1) // assign clipboard
      {
        // SET CLIPBOARD DATA - copy data, assign to data list

        // NOTE:  I don't need to worry about the state here, since all I'm going
        //        to do is set up a copy of the data, own the clipboard, and tell
        //        everyone/thing I completed the task.  So it's almost synchronous


        // COPY TO BUFFER OPERATION
        // TODO:  'cut buffer' XA_STRING selection uses XStoreBuffer (etc.) directly

        // walk the data chain looking for a match, and remove it if it matches.
        // (I'm going to replace it right away and the data and struct are together)

        pD = pCBDHead;
        pD2 = NULL;

        while(pD)
        {
          if(pD->aSelection == pT->aSelection)
          {
            break;  // direct match
          }

          pD2 = pD;
          pD = pD->pNext;
        }

        if(!pD) // try 'soft match' instead
        {
          pD = pCBDHead;
          pD2 = NULL;

          while(pD)
          {
            if(pD->aSelection == None &&
               (pT->aSelection == XA_PRIMARY ||
                pT->aSelection == aCLIPBOARD))
            {
              break;
            }

            if(pT->aSelection == None &&
               (pD->aSelection == XA_PRIMARY ||
                pD->aSelection == aCLIPBOARD))
            {
              break;
            }

            pD2 = pD;
            pD = pD->pNext;
          }
        }

        if(pD) // matching data exists
        {
          if(pD2)
          {
            pD2->pNext = pD->pNext;
          }
          else
          {
            pCBDHead = pD->pNext;
          }

          WBFree(pD); // done with it now
        }

        // NOW, must create 'CLIPBOARD_DATA' struct with this stuff in it.

        if(!pT->pData || !pT->cbLength) // empty the clipboard/selection?
        {
          if(XGetSelectionOwner(pDisplay, pT->aSelection) == wWindow)
          {
            // empty the selection now (because I'm assigning 'NULL')

            if(pT->aSelection == None) // indicates 'clipboard'
            {
              XSetSelectionOwner(pDisplay, XA_PRIMARY, None, CurrentTime);
              XSetSelectionOwner(pDisplay, aCLIPBOARD, None, CurrentTime); // so I do BOTH of them...
            }
            else
            {
              XSetSelectionOwner(pDisplay, pT->aSelection, None, CurrentTime);
            }
          }

//          WB_ERROR_PRINT("TEMPORARY:  %s - empty clipboard assignment\n", __FUNCTION__);
        }
        else
        {
          int iTrueLen;

          if(pT->nFormat == 16)
          {
            iTrueLen = pT->cbLength * 2;
          }
          else if(pT->nFormat == 32)
          {
            iTrueLen = pT->cbLength * 4;
          }
          else
          {
            iTrueLen = pT->cbLength;
          }

          pD = (CLIPBOARD_DATA *)WBAlloc(sizeof(*pD) + 2 + iTrueLen);

          if(!pD)
          {
            // TODO:  indicate 'error' in assigning clipboard data

            XSetSelectionOwner(pDisplay, pT->aSelection, None, CurrentTime);
            // regardless of who owns it, set it to 'None' on error
            WB_ERROR_PRINT("%s - not enough memory for clipboard data - empty clipboard assignment\n", __FUNCTION__);
          }
          else
          {
            memcpy(pD->aData, pT->pData, iTrueLen);

            pD->aSelection = pT->aSelection;
            pD->aType      = pT->aType;
            pD->nFormat    = pT->nFormat;
            pD->cbLength   = pT->cbLength;

//            WB_ERROR_PRINT("TEMPORARY:  %s - owning selection - length=%d (%d)\n", __FUNCTION__, pD->cbLength, iTrueLen);

            if(pD->aSelection != None)
            {
              char *p1 = WBGetAtomName(pDisplay, pD->aSelection);

              XSetSelectionOwner(pDisplay, pD->aSelection, wWindow, CurrentTime);

//              WB_ERROR_PRINT("TEMPORARY:  %s - owned \"%s\"\n", __FUNCTION__, p1);
              WBFree(p1);
            }
            else
            {
              XSetSelectionOwner(pDisplay, XA_PRIMARY, wWindow, CurrentTime);
              XSetSelectionOwner(pDisplay, aCLIPBOARD, wWindow, CurrentTime);

//              WB_ERROR_PRINT("TEMPORARY:  %s - owned XA_PRIMARY and CLIPBOARD\n", __FUNCTION__);
            }

            // add 'pD' to my chain

            pD->pNext = NULL;

            if(!pCBDHead)
            {
              pCBDHead = pD;
            }
            else
            {
              pD2 = pCBDHead;

              while(pD2->pNext)
              {
                pD2 = pD2->pNext;
              }

              pD2->pNext = pD;
            }

#if 0 /* this is a debug-only feature - remove when it's working properly */
            {
              char *p1;
              WB_ERROR_PRINT("TEMPORARY:  %s - walking clipboard data\n", __FUNCTION__);
              pD = pCBDHead;

              while(pD)
              {
                int iLen;
                if(pD->nFormat == 16)
                {
                  iLen = 2 * pD->cbLength;
                }
                else if(pD->nFormat == 32)
                {
                  iLen = 4 * pD->cbLength;
                }
                else
                {
                  iLen = pD->cbLength;
                }

                p1 = WBGetAtomName(pDisplay, pD->aSelection);
                WBDebugPrint("   selection: \"%s\"\n", p1);
                WBFree(p1);

                p1 = WBGetAtomName(pDisplay, pD->aType);
                WBDebugPrint("   type:      \"%s\"\n", p1);
                WBFree(p1);

                WBDebugPrint("   format:    %d\n", pD->nFormat);
                WBDebugPrint("   length:    %d (%d)\n", pD->cbLength, iLen);

                p1 = WBAlloc(iLen + 1);

                if(p1 && iLen)
                {
                  memcpy(p1, pD->aData, iLen);
                }
                if(p1)
                {
                  p1[iLen] = 0;
                }

                WBDebugPrint("----------\n%s\n----------\n", p1);

                WBFree(p1);

                pD = pD->pNext;
              }
            }
#endif // 1
          }

          XFlush(pDisplay);
        }

        bDoneAndSignal = 1;

      }

      // flush and synchronize so that any events that "the above"
      // might have created will be read to be processed right away

      XFlush(pDisplay); // make sure
      XSync(pDisplay, 0); // same here


      if(bDoneAndSignal)
      {
        // signaling the completion of a task

//        WB_ERROR_PRINT("TEMPORARY:  %s line %d - put thingy in done list, signal caller\n", __FUNCTION__, __LINE__);

        // after copying the data, remove it from the 'run' list

        if(pT2) // at THIS point, the 'prev' pointer for unlinking
        {
          pT2->pNext = pT->pNext;
        }
        else
        {
          pRunList = (CLIPBOARD_TASK *)pT->pNext;
        }

        pT->pNext = NULL;

        // now add it to the 'done' list

        if(!pDoneList)
        {
          pDoneList = (CLIPBOARD_TASK *)pT;
        }
        else
        {
          pT3 = pDoneList; // at THIS point, pT2 walks the 'done' list

          while(pT3->pNext)
          {
            pT3 = (CLIPBOARD_TASK *)pT3->pNext;
          }

          pT3->pNext = pT;
        }

        // must now signal the owner.  Since I'm using the 'done list' to decrement
        // the reference count, the object will alays be 'good' here.  So I just
        // need to signal the 'cond' object to get the owner to recognize I'm done
        // with the operation, and everything should be a-OK.

        WBCondSignal((WB_COND *)&(pT->cond)); // tell caller I'm done

        // now - leave pT2 'as-is' here but assign 'pT' to the 'pT2->pNext'
        if(pT2)
        {
          pT = pT2->pNext;             // point to next item in list (after the one I moved)
        }
        else if(pRunList)
        {
          pT = pRunList->pNext;
        }
        else
        {
          pT = NULL;  // end of loop
        }

      }
      else
      {
        // loop to next thingy - this is different than if I signaled
        // the caller, because I'm not pulling it out of the chain

        pT2 = (CLIPBOARD_TASK *)pT; // my new 'prev' pointer for unlinking (must re-assign here)
        pT = pT->pNext;             // point to next item in list
      }
    }

    // check for the 'quit' flag before doing anything else

    if(bClipboardQuitFlag)
    {
      break;
    }

    // HANDLING X SERVER EVENTS

    // NEXT, look for selection events.  If I find one directed at me, I must process
    // it according to whatever's currently going on.

    memset(&evt, 0, sizeof(evt));

    // read every available event, until I find one that I want

    while(XEventsQueued(pDisplay, QueuedAlready) > 0) // we have queued events!
    {
      // read through ALL of the incoming events until I find one
      // that I have to process.  the others are 'eaten'

      XNextEvent(pDisplay, &evt);

      if(evt.type == SelectionClear ||
         evt.type == SelectionRequest ||
         evt.type == SelectionNotify)
      {
        WB_ERROR_PRINT("TEMPORARY: %s line %d - selection event found\n", __FUNCTION__, __LINE__);
        break;
      }
      else
      {
        WBDebugDumpEvent(&evt);
        WB_ERROR_PRINT("TEMPORARY: %s line %d - unrecognized event (ignoring)\n", __FUNCTION__, __LINE__);
      }

      evt.type = 0; // must do this in case I have no events left so next section is skipped
    }


    if(evt.type == SelectionClear ||
       evt.type == SelectionRequest ||
       evt.type == SelectionNotify)
    {
      int iFormat;
      unsigned long nItems, cbLeft;
      unsigned char *pBuf;

      WBDebugDumpEvent(&evt);

      // COPY TO BUFFER OPERATION
      // TODO:  XA_STRING uses XStoreBuffer (etc.) directly, no owner, buffer 0

      // step 1:  own selection using XSetSelectionOwner
      // step 2:  wait for selection events using XNextEvent or similar
      //          if I get 'SelectionClear', set 'clear' flag, continue processing incremental
      // step 3:  on selection request, send the data, incrementally if needed (one message per loop)
      // (when selection is 'cleared' I can stop processing this)

      // COPY FROM CLIPBOARD OPERATION
      // when retrieving a selection, I'll be the one sending the SelectionRequest events
      // (this is typically done using 'XConvertSelection')
      // once retrieved, set appropriate flag in work unit, get next one [if any]
      // if I'm the clipboard owner, just copy the data as-is and mark 'success'

      // get data type in this order:
      // XA_CLIPBOARD(pDisplay) i.e. the atom 'CLIPBOARD' for the given display
      // XA_PRIMARY  (this is the default for 'xclip')
      // XA_SECONDARY
      // XA_STRING

      // 'target' format will typically be
      // XA_UTF8_STRING(pDisplay)  [the atom 'UTF8_STRING']
      // XA_STRING (usually when xselection.property == None in the SelectionEvent)

      // use XGetSelectionOwner to see who owns the selection
      // lock/unlock the X system before (and while) grabbing certain info

      // own the mutex and check for tasks, perform one per loop

      if(evt.type == SelectionClear)
      {
        // SELECTION CLEAR EVENT

        // I'm being asked NOT to own the clipboard, so first check that I'm still the owner

        Window wOwn = XGetSelectionOwner(pDisplay, evt.xselectionclear.selection);

        if(wOwn == wWindow) // do I still own it?
        {
          if(evt.xselectionclear.selection == aCLIPBOARD ||
             evt.xselectionclear.selection == XA_PRIMARY)
          {
            XSetSelectionOwner(pDisplay, XA_PRIMARY,
                               None, CurrentTime); // no owner, now
            XSetSelectionOwner(pDisplay, aCLIPBOARD,
                               None, CurrentTime); // no owner, now
          }
          else
          {
            XSetSelectionOwner(pDisplay, evt.xselectionclear.selection,
                               None, CurrentTime); // no owner, now
          }

          XFlush(pDisplay);
        }

        pD = pCBDHead;
        pD2 = NULL;

        while(pD)
        {
          if(pD->aSelection == evt.xselectionclear.selection ||
             (pD->aSelection == None &&
              (evt.xselectionclear.selection == XA_PRIMARY ||
               evt.xselectionclear.selection == aCLIPBOARD)))
          {
            // remove this item from the chain
            if(!pD2)
            {
              pCBDHead = pD->pNext;
            }
            else
            {
              pD2->pNext = pD->pNext;
            }

            WBFree(pD); // free up the memory [that's all I need to do]

            pD = pD2;  // this continues searching correctly

            if(!pD) // null means empty chain
            {
              break; // I am done
            }
          }

          pD2 = pD;        // the new 'prev' item
          pD = pD->pNext;  // "next" item in chain
        }
      }
      else if(evt.type == SelectionRequest)  // copy FROM me
      {
        // SELECTION REQUEST EVENT

        pD = pCBDHead;

        while(pD && pD->aSelection != evt.xselectionrequest.selection)
        {
          pD = pD->pNext;
        }

        if(!pD) // try 'soft match' instead
        {
          pD = pCBDHead;

          while(pD)
          {
            if(pD->aSelection == None &&
               (evt.xselectionrequest.selection == XA_PRIMARY ||
                evt.xselectionrequest.selection == aCLIPBOARD))
            {
              break;
            }

            pD = pD->pNext;
          }
        }

        // send data to requestor

        if(evt.xselectionrequest.target == aTARGETS) // special target
        {
          Atom aT[2];

          aT[0] = aTARGETS;
          aT[1] = pD ? pD->aType : XA_STRING; // just do this for now

          XChangeProperty(pDisplay, evt.xselectionrequest.requestor,
                          evt.xselectionrequest.property,
                          XA_ATOM, 32, PropModeReplace,
                          (void *)aT, sizeof(aT)/sizeof(aT[0]));

          WB_ERROR_PRINT("TEMPORARY:  %s - sending TARGETS XChangeProperty\n", __FUNCTION__);
        }
        else if(pD &&
                (evt.xselectionrequest.target == pD->aType ||
                 (evt.xselectionrequest.target == XA_STRING && pD->aType == aUTF8_STRING) ||
                 (evt.xselectionrequest.target == aUTF8_STRING && pD->aType == XA_STRING)))
        {
          int nE = pD->cbLength;

          if(pD->nFormat == 16)
          {
            nE /= 2;
          }
          else if(pD->nFormat == 32)
          {
            nE /= 4;
          }

          // TODO:  data conversion to/from UTF8 ??


          // TODO:  handle 'chunking'

          XChangeProperty(pDisplay, evt.xselectionrequest.requestor,
                          evt.xselectionrequest.property,
                          pD->aType, pD->nFormat, PropModeReplace,
                          (unsigned char *)pD->aData, nE);

          // TODO verify that XChangeProperty actually worked by using XSync
          // and testing for response messages.  for now, just assume it works.


          WB_ERROR_PRINT("TEMPORARY:  %s - sent XChangeProperty\n", __FUNCTION__);
        }
        else
        {
          // error - send 'None'

          XChangeProperty(pDisplay, evt.xselectionrequest.requestor,
                          evt.xselectionrequest.property,
                          None, 0, PropModeReplace,
                          NULL, 0);

          WB_ERROR_PRINT("%s - sending 'None' for XChangeProperty\n", __FUNCTION__);
        }

        // EVENT REPLY TO REQUESTOR

        // now I need to reply to the message to say I did it
        // if I do _NOT_ do this in a timely manner, other applications
        // will be affected in a very... bad... way!

        memset(&evt2, 0, sizeof(evt2));

        evt2.xselection.type = SelectionNotify;
        evt2.xselection.display = evt.xselectionrequest.display;
        evt2.xselection.requestor = evt.xselectionrequest.requestor;
        evt2.xselection.property = evt.xselectionrequest.property;
        evt2.xselection.selection = evt.xselectionrequest.selection;
        evt2.xselection.target = evt.xselectionrequest.target;
        evt2.xselection.time = evt.xselectionrequest.time;

        XFlush(evt2.xselection.display);

        /* send the response event */
        XSendEvent(evt2.xselection.display, evt.xselectionrequest.requestor,
                   0, 0, &evt2);
        XFlush(evt2.xselection.display);

        WB_ERROR_PRINT("TEMPORARY:  %s - reply message sent\n", __FUNCTION__);
      }
      else if(evt.type == SelectionNotify)
      {
        // SELECTION NOTIFY EVENT

        int bDoneAndSignal = 0; // this flag tells me to place the item in the 'done queue' and signal the owner

        // now go through my 'run list' and work on whatever is here
        pT2 = NULL;  // this will be my 'prev' pointer for unlinking
        pT = pRunList;

        while(pT)
        {
          WB_ERROR_PRINT("TEMPORARY:  %s line %d - event loop for SelectionNotify\n", __FUNCTION__, __LINE__);

          if(pT->fType == 0                                // getting clipboard/selection data
             && pT->aSelection == evt.xselection.selection // getting property from this selection
             && pT->aType == evt.xselection.target         // and converting to THIS datatype
             && (pT->aProp == evt.xselection.property ||   // matching property name
                 evt.xselection.property == None))         // or an error
          {
            pBuf = NULL; // make sure

            if(evt.xselection.property == None) // this means ERROR
            {
#ifdef X_HAVE_UTF8_STRING /* this indicates the extension is present */
              if(pT->aType == aUTF8_STRING &&
                 pT->fState == 1)
              {
                // fallback, re-issue the request but using XA_STRING instead of aUTF8_STRING
                pT->aType = XA_STRING; // change the type (will return this later)

                // ok here we go again, but an XA_STRINg this time
                XConvertSelection(pDisplay, pT->aSelection, pT->aType,
                                  pT->aProp,
                                  wWindow, CurrentTime);
              }
              else
#endif // X_HAVE_UTF8_STRING
              {
                // assume this is an error condition

                WB_ERROR_PRINT("ERROR:  %s line %d - Unable to do conversion\n", __FUNCTION__, __LINE__);

                pT->fState = -1; // an error

                bDoneAndSignal = 1;
              }
            }
            else if(pT->fState == 1) // state 1 - request sent, waiting for reply
            {
              // first, see what I have assigned to my property

              if(!XGetWindowProperty(pDisplay, wWindow, pT->aProp, 0, 0, False,
                                     AnyPropertyType, &aType, &iFormat, &nItems, &cbLeft, &pBuf))
              {
                if(pBuf)
                {
                  XFree(pBuf);
                  pBuf = NULL;
                }

                // is this the actual data, or a return that says "do it incrementally" ?

                if(aType == aINCR) // incremental
                {
                  // begin incremental process by deleting the property
                  XDeleteProperty(pDisplay, wWindow, pT->aProp);
                  XFlush(pDisplay);

                  // assign state 2, which will pick it up again as incremental
                  pT->fState = 2;
                }
                else
                {
                  int iLen = cbLeft; // the RAW length (in bytes)

                  if(iFormat == 16)
                  {
                    pT->cbLength = cbLeft / 2;
                  }
                  else if(iFormat == 32)
                  {
                    pT->cbLength = cbLeft / 4;
                  }
                  else
                  {
                    pT->cbLength = cbLeft;
                  }

                  if(!XGetWindowProperty(pDisplay, wWindow, pT->aProp, 0, pT->cbLength, False,
                                         AnyPropertyType, &aType, &iFormat, &nItems, &cbLeft, &pBuf) &&
                     pBuf)
                  {
                    pT->nFormat = iFormat;
                    pT->aType = aType;

                    if(nItems != pT->cbLength)
                    {
                      WB_ERROR_PRINT("WARNING:  %s - nItems %ld does not match calculated length %d\n",
                                     __FUNCTION__, nItems, pT->cbLength);
                    }

                    pT->pData = WBAlloc(iLen + 4);

                    if(pT->pData)
                    {
                      memcpy(pT->pData, pBuf, iLen);
                      ((char *)pT->pData)[iLen] = 0; // make sure

                      if(aType == XA_STRING || aType == aUTF8_STRING)
                      {
                        pT->nFormat = 8; // force it
                        pT->cbLength = iLen + 1; // includes the terminating zero byte as part of the length
                      }

                      pT->fState = 3; // mark 'data complete' (for debugging, later, maybe)

                      bDoneAndSignal = 1;
                    }
                    else
                    {
                      WB_ERROR_PRINT("ERROR:  %s line %d - Unable to allocate pointer\n", __FUNCTION__, __LINE__);

                      pT->fState = -1; // an error

                      bDoneAndSignal = 1;
                    }
                  }
                  else
                  {
                    WB_ERROR_PRINT("ERROR:  %s line %d - Unable to get window property\n", __FUNCTION__, __LINE__);

                    pT->fState = -1; // an error

                    bDoneAndSignal = 1;
                  }

                  // regardless, delete the property I use to transfer data

                  XDeleteProperty(pDisplay, wWindow, pT->aProp);
                  XFlush(pDisplay);
                }
              }
              else // error condition
              {
                WB_ERROR_PRINT("ERROR:  %s line %d - Unable to get window property\n", __FUNCTION__, __LINE__);

                pT->fState = -1; // an error

                bDoneAndSignal = 1;
              }
            }
            else if(pT->fState == 2) // incrementally reading the data
            {
              WB_ERROR_PRINT("WARNING:  %s - INCREMENTAL not supported (yet)\n", __FUNCTION__);

              pT->fState = -1; // an error

              bDoneAndSignal = 1;
            }

            if(pBuf)
            {
              XFree(pBuf);
            }
          }

          if(bDoneAndSignal)
          {
            // TASK IS COMPLETE - SIGNAL THE CALLER

            WB_ERROR_PRINT("TEMPORARY:  %s line %d - put thingy in done list, signal caller\n", __FUNCTION__, __LINE__);

            // after copying the data, remove it from the 'run' list

            if(pT2) // at THIS point, the 'prev' pointer for unlinking
            {
              pT2->pNext = pT->pNext;
            }
            else
            {
              pRunList = (CLIPBOARD_TASK *)pT->pNext;
            }

            pT->pNext = NULL;

            // now add it to the 'done' list

            if(!pDoneList)
            {
              pDoneList = (CLIPBOARD_TASK *)pT;
            }
            else
            {
              pT3 = pDoneList; // at THIS point, pT2 walks the 'done' list

              while(pT3->pNext)
              {
                pT3 = (CLIPBOARD_TASK *)pT3->pNext;
              }

              pT3->pNext = pT;
            }

            // must now signal the owner.  Since I'm using the 'done list' to decrement
            // the reference count, the object will alays be 'good' here.  So I just
            // need to signal the 'cond' object to get the owner to recognize I'm done
            // with the operation, and everything should be a-OK.

            WBCondSignal((WB_COND *)&(pT->cond)); // tell caller I'm done

            WB_ERROR_PRINT("TEMPORARY:  %s line %d - signaled caller\n", __FUNCTION__, __LINE__);

            // now - leave pT2 'as-is' here but assign 'pT' to the 'pT2->pNext'
            if(pT2)
            {
              pT = pT2->pNext;             // point to next item in list (after the one I moved)
            }
            else if(pRunList)
            {
              pT = pRunList->pNext;
            }
            else
            {
              pT = NULL;  // end of loop
            }
          }
          else
          {
            // loop to next thingy

            pT2 = (CLIPBOARD_TASK *)pT; // my new 'prev' pointer for unlinking (must re-assign here)
            pT = pT->pNext;             // point to next item in list
          }
        }
      }
    }

    // check for the 'quit' flag before doing anything else

    if(bClipboardQuitFlag)
    {
      break;
    }

    // end of loop

    if(!pCBTHead && // go ahead and test outside of a lock.  if NULL, I need to sleep a bit
       XEventsQueued(pDisplay, QueuedAlready) <= 0) // no events
    {
      static unsigned long long ullLastTime = 0;
      unsigned long long ullTemp;

      // if nothing to do, sleep or something rather than spinning
      // this way if I have events to process, or if I have tasks to manage,
      // I can continue to cycle without delays

//      XFlush(pDisplay);  // force flush just in case

      WBDelay(iDelayPeriod); // 1000); //if I'm not busy, use a sleep state to limit CPU utilization in the thread

      ullTemp = WBGetTimeIndex();
      if((ullTemp - ullLastTime) > 50000) // make sure it's more than 0.05 seconds, so I don't "spin"
      {
        ullLastTime = ullTemp;

        BEGIN_XCALL_DEBUG_WRAPPER
        XSync(pDisplay, False); // force sync just in case
        END_XCALL_DEBUG_WRAPPER
      }

      // each time through, advance the delay period by 50%

      if(iDelayPeriod < MAX_EVENT_LOOP_SLEEP_PERIOD)
      {
        iDelayPeriod += (iDelayPeriod >> 1);
      }
      else
      {
        iDelayPeriod = MAX_EVENT_LOOP_SLEEP_PERIOD;
      }
    }
    else
    {
      iDelayPeriod = MIN_EVENT_LOOP_SLEEP_PERIOD; // reset delay period to 0.1 seconds
    }
  }

  WB_DEBUG_PRINT(DebugLevel_Medium | DebugSubSystem_Init,
                 "INFO:  %s line %d - exit from main thread loop\n", __FUNCTION__, __LINE__);


  // At this point the clipboard thread is done.  time to go away.  clean up.


  // resource cleanup (which should be relatively simple)
  if(WBMutexLock(&xClipboardMutex, -1)) // wait forever to lock it (very important this succeeds)
  {
    WB_ERROR_PRINT("ERROR:  %s - Clipboard Thread can't lock mutex on exit\n",__FUNCTION__);
  }

  while(pDoneList) // already signaled
  {
    pT = pDoneList;
    pDoneList = (CLIPBOARD_TASK *)pT->pNext;

    pT->pNext = NULL;

    if(!WBInterlockedDecrement((unsigned int *)&(pT->nRefCount))) // flags a delete when ref count is zero
    {
      if(!pT->fType && pT->pData) // it COULD happen...
      {
        WBFree(pT->pData);
        pT->pData = NULL;
      }

      WBCondFree((WB_COND *)&(pT->cond)); // assume it works

      WBFree((void *)pT);  // do this while locked
    }
  }

  while(pRunList) // need to be signaled
  {
    pT = pRunList;
    pRunList = (CLIPBOARD_TASK *)pT->pNext;

    pT->pNext = NULL;

    WBCondSignal((WB_COND *)&(pT->cond)); // do this, regardless (won't wake up unless mutex unowned)

    if(!WBInterlockedDecrement((unsigned int *)&(pT->nRefCount))) // flags a delete when ref count is zero
    {
      if(!pT->fType && pT->pData) // it COULD happen...
      {
        WBFree(pT->pData);
        pT->pData = NULL;
      }

      WBCondFree((WB_COND *)&(pT->cond)); // assume it works

      WBFree((void *)pT);  // do this while locked
    }
  }

  while(pCBTHead)
  {
    pT = pCBTHead;
    pCBTHead = pT->pNext;

    pT->pNext = NULL;

    WBCondSignal((WB_COND *)&(pT->cond)); // do this, regardless (won't wake up unless mutex unowned)

    if(!WBInterlockedDecrement((unsigned int *)&(pT->nRefCount))) // flags a delete when ref count is zero
    {
      // NOTE:  unless it was mis-configured, these entries should NOT hve allocated 'pData', evar

      WBCondFree((WB_COND *)&(pT->cond)); // assume it works

      WBFree((void *)pT);  // do this while locked
    }
  }

  XFlush(pDisplay);
  XSync(pDisplay, False);

  // and finally, unlock that mutex!
  WBMutexUnlock(&xClipboardMutex); // not locked now

  // now remove any data items I might be cacheing

  while(pCBDHead) // this one is likely to have data in it
  {
    CLIPBOARD_DATA *pD = pCBDHead;
    pCBDHead = pCBDHead->pNext;

    if(pDisplay && wWindow != None)
    {
      if(pD->aSelection != None &&
         XGetSelectionOwner(pDisplay, pD->aSelection) == wWindow)
      {
        XSetSelectionOwner(pDisplay, pD->aSelection, None, CurrentTime);
      }
      else if(pD->aSelection == None)
      {
        if(XGetSelectionOwner(pDisplay, aCLIPBOARD) == wWindow)
        {
          XSetSelectionOwner(pDisplay, aCLIPBOARD, None, CurrentTime);
        }
        else if(XGetSelectionOwner(pDisplay, XA_PRIMARY) == wWindow)
        {
          XSetSelectionOwner(pDisplay, XA_PRIMARY, None, CurrentTime);
        }
      }
    }

    WBFree(pD); // this one is very simple
  }

  // OK no longer owning the clipboard, so now it's time to

  if(pDisplay)
  {
    BEGIN_XCALL_DEBUG_WRAPPER
    XFlush(pDisplay);
    END_XCALL_DEBUG_WRAPPER
  }

exit_point:

  if(wWindow != None)
  {
    BEGIN_XCALL_DEBUG_WRAPPER
    XDestroyWindow(pDisplay, wWindow);
    END_XCALL_DEBUG_WRAPPER
  }

  if(pDisplay)
  {
    BEGIN_XCALL_DEBUG_WRAPPER
    XSync(pDisplay, FALSE);  // try sync'ing first to avoid certain errors
    XCloseDisplay(pDisplay); // display is to be destroyed now
    END_XCALL_DEBUG_WRAPPER
  }

  WB_DEBUG_PRINT(DebugLevel_Light | DebugSubSystem_Init,
                 "INFO:  %s - Clipboard Thread exit complete\n",__FUNCTION__);

  return NULL;
}



void * WBGetClipboardData(Display *pDisplay, Atom *paType, int *piFormat, unsigned long *pnData)
{
  // TODO:  find better way than using 'None' for the 'aSelection' parameter in order to get "that behavior"

  return WBGetSelectionData(pDisplay, None, paType, piFormat, pnData);
}

int WBSetClipboardData(Display *pDisplay, Atom aType, int iFormat, const void *pData, unsigned long nData)
{
  // TODO:  find better way than using 'None' for the 'aSelection' parameter in order to get "that behavior"

  return WBSetSelectionData(pDisplay, None, aType, iFormat, pData, nData);
}

void * WBGetSelectionData(Display *pDisplay, Atom aSelection, Atom *paType, int *piFormat, unsigned long *pnData)
{
void *pRval = NULL;
volatile CLIPBOARD_TASK *pT, *pTask;
Atom aType = None;
int iFormat = 0;
int iErr;


  if(paType)
  {
    aType = *paType;
    *paType = None;  // this is actually my 'not found' indicator
  }

  if(piFormat)
  {
    iFormat = *piFormat;
    *piFormat = 0;
  }

  if(pnData)
  {
    *pnData = 0; // always
  }

  // for now, if 'pDisplay' isn't NULL or the default display, this will fail
  if(pDisplay && pDisplay != WBGetDefaultDisplay())
  {
    return NULL;
  }

  pTask = (CLIPBOARD_TASK *)WBAlloc(sizeof(*pTask));
  if(!pTask)
  {
    WB_ERROR_PRINT("%s - can't create 'CLIPBOARD_TASK' for clipboard task\n", __FUNCTION__);

    return NULL;
  }

  memset((void *)pTask, 0, sizeof(*pTask));  // always start by doing this

  pTask->fType = 0;
  pTask->pData = NULL; // always for 'get'
  pTask->cbLength = 0;
  pTask->aSelection = aSelection;
  pTask->aType = aType;
  pTask->nFormat = iFormat;
  pTask->nRefCount = 1;
  pTask->pNext = NULL;

  // create the 'cond' object
  if(WBCondCreate((WB_COND *)&(pTask->cond)))
  {
    WB_ERROR_PRINT("%s - can't create 'cond' for clipboard task\n", __FUNCTION__);

    goto exit_point0;
  }

  // own the global mutex and add this to the linked list. then wait on it.

  if(WBMutexLock(&xClipboardMutex, 200000L)) // 0.2 seconds
  {
    WB_ERROR_PRINT("%s - can't lock mutex for clipboard task\n", __FUNCTION__);

    goto exit_point;
  }

  // put it in the chain

  pT = pCBTHead;

  while(pT && pT->pNext)
  {
    pT = pT->pNext;
  }

  if(pT)
  {
    pT->pNext = pTask; // end of chain
  }
  else
  {
    pCBTHead = pTask;  // head of chain
  }

  // wait for it to complete [TODO:  do I need to do this?]

  iErr = WBCondWaitMutex((WB_COND *)&(pTask->cond), &xClipboardMutex, 200000L); // wait up to 0.2 sec for completion

  if(!iErr)
  {
//    WB_ERROR_PRINT("TEMPORARY:  %s - completed wait\n", __FUNCTION__);

    pRval = pTask->pData;  // always for 'get'
    pTask->pData = NULL;   // so I don't accidentally free it, evar [assume WBAlloc from other thread is OK]

    if(paType)
    {
      *paType = pTask->aType;
    }

    if(piFormat)
    {
      *piFormat = pTask->nFormat;
    }

    if(pnData)
    {
      *pnData = pTask->cbLength;
    }

    // TODO:  remove these extra checks later.  also may add stuff to the main
    //        thread loop to make sure that the 'done' list gets freed up at a reasonable rate.

    if(pTask->pNext)
    {
      WB_ERROR_PRINT("ERROR:  %s - clipboard task %p has non-NULL 'pNext' on return (%p), refcount = %d\n",
                     __FUNCTION__, pTask, pTask->pNext, pTask->nRefCount);
    }
    else if(pTask->nRefCount < 1 || pTask->nRefCount > 2) // should be 2, may be 1, anything else unexpected
    {
      WB_ERROR_PRINT("ERROR:  %s - clipboard task %p has wrong refcount %d\n",
                     __FUNCTION__, pTask, pTask->nRefCount);
    }
    else if(!pRval)
    {
      WB_ERROR_PRINT("TEMPORARY:  %s - returning NULL\n", __FUNCTION__);
    }
//    else
//    {
//      WB_ERROR_PRINT("TEMPORARY:  %s - returning %p\n", __FUNCTION__, pRval);
//    }
  }
  else
  {
    // some kind of error - unhook it from the chain.  mutex is owned.

    WB_ERROR_PRINT("%s - %s error waiting on cond,mutex for completion\n", __FUNCTION__,
                   (const char *)(iErr > 0 ? "timeout" : "unknown"));


    // the mutex is owned while I'm doing this, so it's ok

    pT = pCBTHead; // if it hasn't been processed yet, it's in this linked list

    while(pT && pT->pNext)
    {
      if(pT->pNext == pTask)
      {
        pT->pNext = pTask->pNext;

        break;
      }
    }

    // NOTE:  if it wasn't in the 'pCBTHead' list, it's probably in the 'done' list and will be deleted.
    //        but as a matter of course, while the mutex is locked, it's not going away.  SO, I mark the
    //        state with an 'error' flag.

    WBInterlockedExchange((unsigned int *)&(pTask->fState), -1); // changes state to 'error' so it will self-clean-up
    // in case that it wasn't in 'pCBTHead', which is likely
  }

  // at this point 'xClipboardMutex' is assumed to be LOCKED and I can go ahead and mess with the 'pTask' object
  // it should also be OUT of the 'pCBTHead' list, but may be in the 'done' list.

  if(!WBInterlockedDecrement((unsigned int *)&(pTask->nRefCount))) // flags a delete when ref count is zero
  {
//    WB_ERROR_PRINT("TEMPORARY:  %s - ref count zero, deleting 'pTask'\n", __FUNCTION__);

    if(pTask->pData) // it COULD happen...
    {
      WBFree(pTask->pData);
      pTask->pData = NULL;
    }

    WBCondFree((WB_COND *)&(pTask->cond)); // assume it works

    WBFree((void *)pTask);  // do this while locked
  }

  pTask = NULL;   // so I don't try to re-use it

//  WB_ERROR_PRINT("TEMPORARY:  %s - release mutex before exit\n", __FUNCTION__);

  WBMutexUnlock(&xClipboardMutex);

exit_point:

  if(pTask)
  {
    WBCondFree((WB_COND *)&(pTask->cond)); // assume it works
  }

exit_point0:

  if(pTask)
  {
    WBFree((void *)pTask); // TODO:  on error, this might cause a crash... or not
  }

  return pRval; // for now (similar to an error return)
}

int WBSetSelectionData(Display *pDisplay, Atom aSelection, Atom aType, int iFormat, const void *pData, unsigned long nData)
{
int iRval = -1;
volatile CLIPBOARD_TASK *pT, *pTask;


  // for now, if 'pDisplay' isn't NULL or the default display, this will fail
  if(pDisplay && pDisplay != WBGetDefaultDisplay())
  {
    return -1;
  }

  pTask = (CLIPBOARD_TASK *)WBAlloc(sizeof(*pTask));
  if(!pTask)
  {
    WB_ERROR_PRINT("%s - can't create 'CLIPBOARD_TASK' for clipboard task\n", __FUNCTION__);

    return -1;
  }

  memset((void *)pTask, 0, sizeof(*pTask));  // always start by doing this

  pTask->fType = 1;
  pTask->pData = (void *)pData; // will be treated as 'const'
  pTask->cbLength = nData;
  pTask->aSelection = aSelection;
  pTask->aType = aType;
  pTask->nFormat = iFormat;
  pTask->nRefCount = 1;
  pTask->pNext = NULL;

  // create the 'cond' object
  if(WBCondCreate((WB_COND *)&(pTask->cond)))
  {
    WB_ERROR_PRINT("%s - can't create 'cond' for clipboard task\n", __FUNCTION__);

    iRval = -2;
    goto exit_point0;
  }

  // own the global mutex and add this to the linked list. then wait on it.

  if(WBMutexLock(&xClipboardMutex, 200000L)) // up to 0.2 second for locking
  {
    WB_ERROR_PRINT("%s - can't lock mutex for clipboard task\n", __FUNCTION__);

    iRval = -3;
    goto exit_point;
  }

  // put pTask in the chain

  pT = pCBTHead;

  while(pT && pT->pNext)
  {
    pT = pT->pNext;
  }

  if(pT)
  {
    pT->pNext = pTask;
  }
  else
  {
    pCBTHead = pTask;
  }

  // wait for it to complete [TODO:  do I need to do this?]

  if(WBCondWaitMutex((WB_COND *)&(pTask->cond), &xClipboardMutex, 200000L)) // wait up to 0.2 sec for completion
  {
    // some kind of error - unhook it from the chain.  mutex is owned.
    WB_ERROR_PRINT("%s - error waiting on cond,mutex for completionk\n", __FUNCTION__);

    pT = pCBTHead; // if it hasn't been processed yet, it's in this linked list

    while(pT && pT->pNext)
    {
      if(pT->pNext == pTask)
      {
        pT->pNext = pTask->pNext;

        break;
      }
    }

    WBInterlockedExchange((unsigned int *)&(pTask->fState), -1); // changes state to 'error' so it will self-clean-up
    // in case that it wasn't in 'pCBTHead', which is likely

    iRval = -4;
  }

  // at this point 'xClipboardMutex' is assumed to be LOCKED

  if(!WBInterlockedDecrement((unsigned int *)&(pTask->nRefCount))) // flags a delete when ref count is zero
  {
    WBCondFree((WB_COND *)&(pTask->cond)); // assume it works

    WBFree((void *)pTask);  // do this while locked
  }

  pTask = NULL;   // so I don't try to re-use it

  WBMutexUnlock(&xClipboardMutex);

exit_point:

  if(pTask)
  {
    WBCondFree((WB_COND *)&(pTask->cond)); // assume it works
  }

exit_point0:

  if(pTask)
  {
    WBFree((void *)pTask); // TODO:  on error, this might cause a crash... or not
  }

  return iRval;
}