windows-server-2003/multimedia/directx/dinput/dx8/dll/diem.h

/*****************************************************************************
 *
 *  DIEm.h
 *
 *  Copyright (c) 1996-1997 Microsoft Corporation.  All Rights Reserved.
 *
 *  Abstract:
 *
 *      DirectInput internal header file for emulation.
 *
 *****************************************************************************/

/*****************************************************************************
 *
 *  @doc    INTERNAL
 *
 *  @struct CEd |
 *
 *          Emulation descriptor.  One of these is created for each
 *          device.  It is never destroyed, so the variable must
 *          be a global variable or memory allocated inside a
 *          container that will eventually be destroyed.
 *
 *          ISSUE-2001/03/29-timgill  Need a better destructor function
 *
 *  @field  LPVOID const | pState |
 *
 *          State buffer that everybody parties into.
 *
 *          It too is never destroyed, so once again it should be
 *          a global variable or live inside something else that
 *          will be destroyed.
 *
 *  @field  LPDWORD const | pDevType |
 *
 *          Array of device type descriptors, indexed by data format
 *          offset.  Used to determine whether a particular piece of
 *          data belongs to an axis, button, or POV.
 *
 *  @field  EMULATIONPROC | Acquire |
 *
 *          Callback function for acquisition and loss thereof.
 *          It is called once when the first client acquires,
 *          and again when the last app unacquires.  It is not
 *          informed of nested acquisition.
 *
 *  @field  LONG | cAcquire |
 *
 *          Number of times the device emulation has been acquired (minus one). 
 *
 *  @field  DWORD | cbData |
 *
 *          Size of the device data type.  In other words, size of
 *          <p pState> in bytes.
 *
 *****************************************************************************/

typedef STDMETHOD(EMULATIONPROC)(struct CEm *, BOOL fAcquire);

typedef struct CEd {

    LPVOID const    pState;
    LPDWORD const   pDevType;
    EMULATIONPROC   Acquire;
    LONG            cAcquire;
    DWORD           cbData;
    ULONG           cRef;
} CEd, ED, *PED;

/*****************************************************************************
 *
 *  @doc    INTERNAL
 *
 *  @struct CEm |
 *
 *          Emulation state information.
 *
 *  @field  VXDINSTANCE | vi |
 *
 *          Information shared with parent device.
 *
 *  @field  PEM | pemNext |
 *
 *          Next item in linked list of all active device instances.
 *
 *  @field  LPDWORD | rgdwDf |
 *
 *          Array of items (one for each byte in the device
 *          data format).  This maps each device data format byte
 *          into an application device data offset, or -1 if the
 *          application doesn't care about the corresponding object.
 *
 *  @field  ULONG_PTR  | dwExtra |
 *
 *          Extra information passed in the <t VXDDEVICEFORMAT>
 *          when the device was created.  This is used by each
 *          particular device to encode additional instance infomation.
 *
 *  @field  PED | ped |
 *
 *          The device that owns this instance.  Multiple instances
 *          of the same device share the same <e CEm.ped>.
 *
 *  @field  LONG | cRef |
 *
 *          Reference count.
 *
 *
 *  @field  LONG | cAcquire |
 *
 *          Number of times the device instance has been acquired (minus one). 
 *
 *
 *  @field  BOOL | fWorkerThread |
 *
 *          This is used by low-level hooks and HID devices, which
 *          require a worker thread to collect the data.
 *          This is not cheap, so
 *          instead, we spin up the thread on the first acquire, and
 *          on the unacquire, we keep the thread around so that the next
 *          acquire is fast.  When the last object is released, we finally
 *          kill the thread.
 *
 *****************************************************************************/

typedef struct CEm {

    VXDINSTANCE vi;             /* This must be first */
    struct CEm *pemNext;
    LPDWORD rgdwDf;
    ULONG_PTR   dwExtra;
    PED     ped;
    LONG    cAcquire;
    LONG    cRef;
#ifdef WORKER_THREAD
    BOOL    fWorkerThread;
#endif
#ifdef DEBUG
    DWORD   dwSignature;
#endif
    BOOL    fHidden;
} CEm, EM, *PEM;

#define CEM_SIGNATURE       0x4D4D4545      /* "EEMM" */

/*****************************************************************************
 *
 *  @doc    INTERNAL
 *
 *  @func   PEM | pemFromPvi |
 *
 *          Given an interior pointer to a <t VXDINSTANCE>, retrieve
 *          a pointer to the parent <t CEm>.
 *
 *  @parm   PVXDINSTANCE | pvi |
 *
 *          The pointer to convert.
 *
 *****************************************************************************/

PEM INLINE
pemFromPvi(PVXDINSTANCE pvi)
{
    return pvSubPvCb(pvi, FIELD_OFFSET(CEm, vi));
}

/*****************************************************************************
 *
 *          NT low-level hook support
 *
 *          Low-level hooks live on a separate thread which we spin
 *          up when first requested and take down when the last
 *          DirectInput device that used a thread has been destroyed.
 *
 *          If we wanted, we could destroy the thread when the
 *          device is unacquired (rather than when the device is
 *          destroyed), but we cache the thread instead, because
 *          a device that once has been acquired will probably be
 *          acquired again.
 *
 *          To prevent race conditions from crashing us, we addref
 *          our DLL when the thread exists and have the thread
 *          perform a FreeLibrary as its final act.
 *
 *          Note that this helper thread is also used by the HID data
 *          collector.
 *
 *****************************************************************************/

#ifdef USE_SLOW_LL_HOOKS

/*****************************************************************************
 *
 *  @doc    INTERNAL
 *
 *  @struct LLHOOKSTATE |
 *
 *          Low-level hook information about a single hook.
 *
 *  @field  int | cHook |
 *
 *          Number of times the hook has been requested.  If zero,
 *          then there should be no hook.  All modifications to
 *          this field must be interlocked to avoid race conditions
 *          when two threads try to hook or unhook simultaneously.
 *
 *  @field  int | cExcl |
 *
 *          Number of times the hook has been requested in an exclusive 
 *          mode.  This value should always be less than or equal to the 
 *          cHook value.  All modifications to this field must be 
 *          interlocked to avoid race conditions when two threads try to 
 *          hook or unhook simultaneously.
 *
 *  @field  HHOOK | hhk |
 *
 *          The actual hook, if it is installed.  Only the hook thread
 *          touches this field, so it does not need to be protected.
 *
 *  @field  BOOLEAN | fExcluded |
 *
 *          Flag to indicate whether or not exclusivity has been applied.  
 *          Only the hook thread touches this field, so it does not need to 
 *          be protected.
 *
 *****************************************************************************/

typedef struct LLHOOKSTATE {

    int     cHook;
    int     cExcl;
    HHOOK   hhk;
    BOOLEAN fExcluded;
} LLHOOKSTATE, *PLLHOOKSTATE;

LRESULT CALLBACK CEm_LL_KbdHook(int nCode, WPARAM wp, LPARAM lp);
LRESULT CALLBACK CEm_LL_MseHook(int nCode, WPARAM wp, LPARAM lp);

#endif  /* USE_SLOW_LL_HOOKS */

#ifdef WORKER_THREAD

/*****************************************************************************
 *
 *  @doc    INTERNAL
 *
 *  @struct LLTHREADSTATE |
 *
 *          Low-level hook state for a thread.  Note that this is
 *          a dynamically
 *          allocated structure instead of a static.  This avoids various
 *          race conditions where, for example, somebody terminates the
 *          worker thread and somebody else starts it up before the
 *          worker thread is completely gone.
 *
 *          A pointer to the hThread is passed as the pointer to an array 
 *          of two handles in calls to WaitForMultipleObject so hEvent must 
 *          follow it directly.
 *
 *  @field  DWORD | idThread |
 *
 *          The ID of the worker thread.
 *
 *  @field  LONG | cRef |
 *
 *          Thread reference count.  The thread kills itself when this
 *          drops to zero.
 *
 *  @field  LLHOOKSTATE | rglhs[2] |
 *
 *          Hook states, indexed by LLTS_* values.
 *
 *          These are used only if low-level hooks are enabled.
 *
 *  @field  HANDLE | hThread |
 *
 *          The handle (from the create) of the worker thread.
 *
 *          This is used only if HID support is enabled.
 *
 *  @field  HANDLE | hEvent |
 *
 *          The handle to the event used to synchronize with the worker thread.
 *
 *          This is used only if HID support is enabled.
 *
 *  @field  GPA | gpaHid |
 *
 *          Pointer array of HID devices which are acquired.
 *
 *          This is used only if HID support is enabled.
 *
 *  @field  PEM | pemCheck |
 *
 *          Pointer to Emulation state information.
 *
 *          This is used only if HID support is enabled.
 *
 *****************************************************************************/

#define LLTS_KBD    0
#define LLTS_MSE    1
#define LLTS_MAX    2

typedef struct LLTHREADSTATE {
    DWORD       idThread;
    LONG        cRef;
#ifdef USE_SLOW_LL_HOOKS
    LLHOOKSTATE rglhs[LLTS_MAX];
#endif
    HANDLE      hThread;    /* MUST be followed by hEvent, see above */
    HANDLE      hEvent;     /* MUST follow hThread, see above */
    GPA         gpaHid;
    PEM         pemCheck;
} LLTHREADSTATE, *PLLTHREADSTATE;

/*****************************************************************************
 *
 *  @doc    INTERNAL
 *
 *  @topic  Communicating with the worker thread |
 *
 *          Communication with the worker thread is performed via
 *          <c WM_NULL> messages.  Extra care must be taken to make
 *          sure that someone isn't randomly sending messages to us.
 *
 *          We use the <c WM_NULL> message because there are race
 *          windows where we might post a message to a thread after
 *          it is gone.  During this window, the thread ID might get
 *          recycled, and we end up posting the message to some random
 *          thread that isn't ours.  By using the <c WM_NULL> message,
 *          we are safe in knowing that the target thread won't barf
 *          on the unexpected message.
 *
 *          The <t WPARAM> of the <c WM_NULL> is the magic value
 *          <c WT_WPARAM>.
 *
 *          The <t LPARAM> of the <c WM_NULL> is either a pointer
 *          to the <t CEm> that needs to be refreshed or is
 *          zero if we merely want to check our bearings.
 *
 *****************************************************************************/

#define WT_WPARAM       0

#define PostWorkerMessage(thid, lp)                                     \
        PostThreadMessage(thid, WM_NULL, WT_WPARAM, (LPARAM)(lp))       \

#define NudgeWorkerThread(thid)                                         \
        PostThreadMessage(thid, WM_NULL, WT_WPARAM, (LPARAM)NULL)

HRESULT EXTERNAL NudgeWorkerThreadPem( PLLTHREADSTATE plts, PEM pem );

HRESULT EXTERNAL NotifyWorkerThreadPem(DWORD idThread, PEM pem);

STDMETHODIMP CEm_GetWorkerThread(PEM pem, PLLTHREADSTATE *pplts);

/*****************************************************************************
 *
 *  @doc    INTERNAL
 *
 *  @global PLLTHREADSTATE | g_plts |
 *
 *          The thread state of the currently-active thread.
 *
 *          This variable needs to be externally accessible
 *          because you can't pass instance data to a windows
 *          hook function.  (Whose idea was that?)
 *
 *****************************************************************************/

extern PLLTHREADSTATE g_plts;

void EXTERNAL CEm_Mouse_OnMouseChange(void);

#endif  /* WORKER_THREAD */

/*
 *  Private helper functions in diem.c
 */

#define FDUFL_NORMAL       0x0000           /* Nothing unusual */
#define FDUFL_UNPLUGGED    VIFL_UNPLUGGED   /* Device disconnected */

void  EXTERNAL CEm_ForceDeviceUnacquire(PED ped, UINT fdufl);
void  EXTERNAL CEm_AddState(PED ped, LPVOID pvData, DWORD tm);
DWORD EXTERNAL CEm_AddEvent(PED ped, DWORD dwData, DWORD dwOfs, DWORD tm);
BOOL  EXTERNAL CEm_ContinueEvent(PED ped, DWORD dwData, DWORD dwOfs, DWORD tm, DWORD dwSeq);

STDMETHODIMP CEm_LL_Acquire(PEM this, BOOL fAcquire, ULONG fl, UINT ilts);

HRESULT EXTERNAL
CEm_CreateInstance(PVXDDEVICEFORMAT pdevf, PVXDINSTANCE *ppviOut, PED ped);

void EXTERNAL CEm_FreeInstance(PEM this);

/*****************************************************************************
 *
 *  @doc    INTERNAL
 *
 *  @func   void | CEm_AddRef |
 *
 *          Bump the reference count because we're doing something with it.
 *
 *  @parm   PEM | this |
 *
 *          The victim.
 *
 *****************************************************************************/

void INLINE
CEm_AddRef(PEM this)
{
    AssertF(this->dwSignature == CEM_SIGNATURE);
    InterlockedIncrement(&this->cRef);
}

/*****************************************************************************
 *
 *  @doc    INTERNAL
 *
 *  @func   void | CEm_Release |
 *
 *          Drop the reference count and blow it away if it's gone.
 *
 *  @parm   PEM | this |
 *
 *          The victim.
 *
 *****************************************************************************/

void INLINE
CEm_Release(PEM this)
{
    AssertF(this->dwSignature == CEM_SIGNATURE);
    if (InterlockedDecrement(&this->cRef) == 0) {
        CEm_FreeInstance(this);
    }
}