#ifndef TDx_InputDeviceH
#define TDx_InputDeviceH

// ==========================================================================
// File:         TDx_InputDevice.H
// Authors:      BCB_Code_Generator v1.70,
//               Darren Dwyer (source code, documentation, demos, website),
//               Hugh Edwards (documentation, icons, website),
//               Brian Austin (some source code, documentation)
// Description:  This file defines the TDx_InputDevice Component 
//
// "TDx_Input_Library v1.70"
// (c) 2003 BCB-Tools.com Pty. Ltd., Sydney, Australia.
// All Rights Reserved.
//
// Refer to the 'Licence.Txt' file for licencing & copyright information.
// ==========================================================================

// --------------------------------------------------------------------------
// #includes
// --------------------------------------------------------------------------
#include <vcl\SysUtils.hpp>
#include <vcl\Controls.hpp>
#include <vcl\Classes.hpp>
#include <vcl\Forms.hpp>
// --------------------------------------------------------------------------
#include "TDx_Library_Defns.H"
#include "TDx_Library_Functions.H"
// --------------------------------------------------------------------------
#include "TDx_Input_Library_Defns.H"
#include "TDx_Input_Library_Functions.H"
// --------------------------------------------------------------------------
// external classes used by the TDx_InputDevice component.
class TDx_Input;
// --------------------------------------------------------------------------
// external classes used by TDx_InputDevice methods.
class TDIEffect;
class TDx_InputEffect;
class TDIEffEscape;
class TDIDevCaps;
class TDIDeviceObjectData;
class TDIDeviceInstance;
class TDIMouseState2;
class TDIEffectInfo;
class TDIDeviceObjectInstance;
class TDIPropHeader;
class TDIFileEffect;

// --------------------------------------------------------------------------
// --------------------------------------------------------------------------
// Definition for the OnEnumCreatedEffectObjects callback event.
typedef	__fastcall void	(__closure*        TDx_EnumCreatedEffectObjects) 
                        ( TObject*         Sender, 
                          TDx_InputEffect* Effect, 
                          void*            Context, 
                          bool&            Finished ); 

// Definition for the OnEnumEffects callback event.
typedef	__fastcall void	(__closure*      TDx_EnumEffects) 
                        ( TObject*       Sender, 
                          TDIEffectInfo* EffectInfo, 
                          void*          Context, 
                          bool&          Finished ); 

// Definition for the OnEnumEffectsInFile callback event.
typedef	__fastcall void	(__closure*      TDx_EnumEffectsInFile) 
                        ( TObject*       Sender, 
                          TDIFileEffect* FileEffect, 
                          void*          Context, 
                          bool&          Finished ); 

// Definition for the OnEnumObjects callback event.
typedef	__fastcall void	(__closure*                TDx_EnumObjects) 
                        ( TObject*                 Sender, 
                          TDIDeviceObjectInstance* ObjectInstance, 
                          void*                    Context, 
                          bool&                    Finished ); 

// ==========================================================================
// Class:       TDx_InputDevice
// Description: The TDx_InputDevice component wraps the DirectX 
//              IDirectInputDevice7 interface used for acquiring and 
//              releasing input device access, managing the behaviour, 
//              properties and information related to the device, creating, 
//              saving, loading and playing force feedback effects and 
//              invoking a device's control panel. 
//              
//              TDx_InputDevice also supports additional force feedback 
//              effects and polled device support. 
//              
//              To create a IDirectInputDevice7 interface, use the 
//              TDx_InputDevice::Create() method and to destroy the 
//              interface, use the TDx_InputDevice::Destroy() method. You 
//              could also use TDx_Input::CreateDevice() for creating the 
//              device, but it will not trigger the 
//              TDx_InputDevice::OnCreate() event. 
//              
//              Use the TDx_InputDevice::OnCreate() event and 
//              TDx_InputDevice::OnDestroy() events to simplify the creation 
//              and destruction of dependent objects. 
//              
//              Once created, call any of the TDx_InputDevice methods and 
//              handle any error results using the TDx_InputDevice::OnError() 
//              event and the TDx_InputDevice::ErrorValue property. 
// ==========================================================================
#if (__BORLANDC__ >= 0x0530) // BCB Version 3 +
class PACKAGE TDx_InputDevice : public TComponent
{
// --------------------------------------------------------------------------
#else // BCB Version 1
class TDx_InputDevice : public TComponent
{
#endif
// ==========================================================================
__published:
// ==========================================================================

    // ----------------------------------------------------------------------
    // Event:       OnCreate()
    // Description: The OnCreate() event is triggered by the 
    //              TDx_InputDevice::Create() method after it has 
    //              successfully created the internal LPDIRECTINPUTDEVICE7 
    //              used within the TDx_InputDevice component. 
    //              
    //              Note that since this event is only called upon successful 
    //              creation, this event is an ideal place for code that is 
    //              to be activated only once, immediately upon the 
    //              successful creation of the LPDIRECTINPUTDEVICE7 
    //              interface. 
    //              
    //              For example, you could retrieve the TDx_InputDevice 
    //              component's capabilities, Create() dependant components, 
    //              allocate memory, etc. 
    //              
    //              When used in conjunction with the 
    //              TDx_InputDevice::OnDestroy() event, you can fully 
    //              automate and insulate your code on a per-component basis. 
    // ----------------------------------------------------------------------
    __property TDx_Event OnCreate = {read=FOnCreate, write=FOnCreate, 
    nodefault}; 

    // ----------------------------------------------------------------------
    // Event:       OnDestroy()
    // Description: The OnDestroy() event is triggered by the 
    //              TDx_InputDevice::Destroy() method, just before the 
    //              TDx_InputDevice internal LPDIRECTINPUTDEVICE7 interface 
    //              is destroyed. 
    //              
    //              Note: This event is an ideal place to place code that 
    //              reverses the results of the TDx_InputDevice::OnCreate() 
    //              event. For example, assume you have already setup the 
    //              TDx_InputDevice::OnCreate() event to retrieve the 
    //              component's capabilities, Create() a dependant component 
    //              and allocate some memory; 
    //              You can then fully automate and insulate your code on a 
    //              per-component basis by placing code in the 
    //              TDx_InputDevice::OnDestroy() event to deallocate memory, 
    //              Destroy() the dependant components and, when required, 
    //              destroy the capabilities component. 
    // ----------------------------------------------------------------------
    __property TDx_Event OnDestroy = {read=FOnDestroy, write=FOnDestroy, 
    nodefault}; 

    // ----------------------------------------------------------------------
    // Event:       OnDeviceStateChange()
    // Description: The OnDeviceStateChange Event is triggered by a change in 
    //              the current devices state (eg button click, axis change) 
    //              when the TDx_InputDevice::SetEventNotification() method 
    //              is called with true as its parameter.  This is non-polled 
    //              access of the device. 
    // ----------------------------------------------------------------------
    __property TDx_Event OnDeviceStateChange = {read=FOnDeviceStateChange, 
    write=FOnDeviceStateChange, nodefault}; 

    // ----------------------------------------------------------------------
    // Event:       OnError()
    // Description: The OnError event is called when an error occurs in the 
    //              TDx_InputDevice component. 
    // ----------------------------------------------------------------------
    __property TDx_Error OnError = {read=FOnError, write=FOnError, 
    nodefault}; 

    // ----------------------------------------------------------------------
    // Callback:    OnEnumCreatedEffectObjects()
    // Description: The OnEnumCreatedEffectObjects is called for every 
    //              DirectInputDevice Effect enumerated by the 
    //              EnumCreatedEffectObjects method. 
    // ----------------------------------------------------------------------
    __property TDx_EnumCreatedEffectObjects OnEnumCreatedEffectObjects = 
    {read=FOnEnumCreatedEffectObjects, write=FOnEnumCreatedEffectObjects, 
    nodefault}; 

    // ----------------------------------------------------------------------
    // Callback:    OnEnumEffects()
    // Description: The OnEnumEffects Callback is called for every effect 
    //              enumerated by the EnumEffects method. 
    // ----------------------------------------------------------------------
    __property TDx_EnumEffects OnEnumEffects = {read=FOnEnumEffects, 
    write=FOnEnumEffects, nodefault}; 

    // ----------------------------------------------------------------------
    // Callback:    OnEnumEffectsInFile()
    // Description: The OnEnumEffectsInFile() event is used to process 
    //              information generated by the 
    //              TDx_InputDevice::EnumEffectsInFile() method. 
    // ----------------------------------------------------------------------
    __property TDx_EnumEffectsInFile OnEnumEffectsInFile = 
    {read=FOnEnumEffectsInFile, write=FOnEnumEffectsInFile, nodefault}; 

    // ----------------------------------------------------------------------
    // Callback:    OnEnumObjects()
    // Description: The OnEnumObjects is called for every DirectInputDevice 
    //              object enumerated by the EnumObjects  method 
    // ----------------------------------------------------------------------
    __property TDx_EnumObjects OnEnumObjects = {read=FOnEnumObjects, 
    write=FOnEnumObjects, nodefault}; 

// ==========================================================================
public:
// ==========================================================================

    // ----------------------------------------------------------------------
    // Property:    Created
    // Description: The Created property is true if the internal 
    //              LPDIRECTINPUTDEVICE7 used in this component has been 
    //              successfully created, otherwise Created is false. 
    //              
    //              To create the internal LPDIRECTINPUTDEVICE7, call the 
    //              TDx_InputDevice::Create() method. 
    // ----------------------------------------------------------------------
    __property bool Created = { read=FGetCreated, write=FSetCreated, 
    default=false }; 

    // ----------------------------------------------------------------------
    // Property:    ErrorValue
    // Description: The ErrorValue property contains the last error value 
    //              returned from a call to a TDx_InputDevice method or 
    //              fget/fset. eg. DI_OK or DDERR_SURFACELOST or TDX_ERROR 
    // ----------------------------------------------------------------------
    __property HRESULT ErrorValue = { read=FGetErrorValue, 
    write=FSetErrorValue, default=DI_OK }; 

    // ----------------------------------------------------------------------
    // Property:    EventHandle
    // Description: The EventHandle property is used internally to store the 
    //              event assigned to the device. 
    // ----------------------------------------------------------------------
    __property HANDLE EventHandle = { read=FGetEventHandle, default=NULL }; 

    // ----------------------------------------------------------------------
    // Property:    LastDataFormat
    // Description: The LastDataFormat property is used internally to store 
    //              the data format last used within the 
    //              TDx_InputDevice::SetDataFormat() method. 
    // ----------------------------------------------------------------------
    __property TDIData* LastDataFormat = { read=FGetLastDataFormat, 
    default=NULL }; 

    // ----------------------------------------------------------------------
    // Method:      Acquire()
    // Description: The Acquire() method will obtain access to the input 
    //              device. 
    //              
    //              A data format must be set using 
    //              TDx_InputDevice::SetDataFormat() before the device can be 
    //              aquired. 
    //              Devices must be acquired before 
    //              TDx_InputDevice::GetDeviceState() or 
    //              TDx_InputDevice::GetDeviceData() can be used. 
    //              
    //              A device is either acquired or unaquired, thus calling 
    //              Acquire() multiple times and then calling 
    //              TDx_InputDevice::UnAquire() once still results in the 
    //              device being completely unacquired. 
    //              
    //              You will need to call 
    //              TDx_InputDevice::SetCooperativeLevel() before calling 
    //              this method. 
    //              
    //              Error values that can be generated are: 
    //              
    //              DIERR_INVALIDPARAM   
    //              DIERR_NOTINITIALIZED   
    //              DIERR_OTHERAPPHASPRIO 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Acquire(); 

    // ----------------------------------------------------------------------
    // Method:      Create()
    // Description: The Create() method is used to automatically create the 
    //              internal LPDIRECTINPUTDEVICE7 interface used in the 
    //              TDx_InputDevice component and must be called before any 
    //              methods of the TDx_InputDevice component will function. 
    // Params:      pGuid - 
    //                The pGuid parameter is used to define what type of device 
    //                to create. System GUIDs for the mouse and keyboard are: 
    //                GUID_SysKeyboard 
    //                GUID_SysMouse 
    //                GUIDs for other devices are obtained by calling 
    //                TDx_Input::EnumDevices() 
    //              pInput - 
    //                The pInput parameter references a TDx_Input Object that 
    //                has been previously created.  The TDx_Input::CreateDevice 
    //                method is called to create the InputDevice, these two 
    //                methods are identical in function. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Create( GUID pGuid, TDx_Input* pInput ); 

    // ----------------------------------------------------------------------
    // Method:      CreateEffect()
    // Description: The CreateEffect() method will create and initialize an 
    //              effect instance. 
    //              
    //              A return value of S_OK will be generated if the device is 
    //              not acquired in exclusive mode. This indicates that the 
    //              effect has been created and its parameters updated, but 
    //              it may not have been downloaded to the device. 
    //              
    //              Error values that can be generated are: 
    //              
    //              DIERR_DEVICENOTREG   
    //              DIERR_DEVICEFULL   
    //              DIERR_INVALIDPARAM   
    //              DIERR_NOTINITIALIZED 
    // Params:      pRefGuid - 
    //                The RefGuid parameter identifies the effect being 
    //                created. 
    //                
    //                One of the predefined effects below or a GUID obtained 
    //                from TDx_InputDevice::EnumEffects() can be used. 
    //                
    //                GUID_ConstantForce 
    //                GUID_RampForce 
    //                
    //                Periodic: 
    //                GUID_Square 
    //                GUID_Sine 
    //                GUID_Triangle 
    //                GUID_SawtoothUp 
    //                GUID_SawtoothDown 
    //                
    //                Conditions: 
    //                GUID_Spring 
    //                GUID_Damper 
    //                GUID_Inertia 
    //                GUID_Friction 
    //                
    //                User Defined: 
    //                GUID_CustomForce 
    //              pEffectData - 
    //                The EffectData parameter references a TDIEffect component 
    //                holding the properties of the effect being created. 
    //                
    //                Set this property to NULL to create a blank effect object 
    //                to be set later up using 
    //                TDx_InputEffect::SetParameters(). 
    //              pNewEffect - 
    //                The NewEffect parameter will reference the new 
    //                TDx_InputEffect interface if the method returns 
    //                successfully. 
    // ----------------------------------------------------------------------
    virtual HRESULT __fastcall CreateEffect( REFGUID pRefGuid, TDIEffect* 
    pEffectData, TDx_InputEffect* pNewEffect ); 

    // ----------------------------------------------------------------------
    // Method:      Destroy()
    // Description: The Destroy() method is used to automatically destroy the 
    //              internal LPDIRECTINPUTDEVICE7 interface used in the 
    //              TDx_InputDevice component and should be called when the 
    //              internal interface is no longer required. 
    //              
    //              Note: This method is called by the component's 
    //              destructor. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Destroy(); 

    // ----------------------------------------------------------------------
    // Method:      EnumCreatedEffectObjects()
    // Description: The EnumCreatedEffectObjects() method will enumerate 
    //              effects currently created for this device by 
    //              TDx_InputDevice::CreateEffect(). 
    //              
    //              Creating or destroying effects while the enumeration is 
    //              in progress may result in unpredictable results, but the 
    //              callback function can safely release effects passed to 
    //              it. 
    //              
    //              Error values that can be generated are: 
    //              
    //              DIERR_INVALIDPARAM   
    //              DIERR_NOTINITIALIZED 
    // Params:      pReferenceData - 
    //                The ReferenceData parameter defines context or reference 
    //                data to be passed to the callback function each time it 
    //                is called. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall EnumCreatedEffectObjects( void* pReferenceData ); 

    // ----------------------------------------------------------------------
    // Method:      EnumEffects()
    // Description: The EnumEffects() method will enumerate the effects 
    //              supported by the device's force feedback system. 
    //              
    //              The returned GUID's may represent predefined or device 
    //              specific effects. 
    //              
    //              General effect information can be found in the EffectType 
    //              parameter, but to exploit a device specific effect to the 
    //              fullest, consult the documentation provided by the 
    //              manufacturer. 
    //              
    //              Error values that can be generated are: 
    //              
    //              DIERR_INVALIDPARAM   
    //              DIERR_NOTINITIALIZED 
    // Params:      pReferenceData - 
    //                The ReferenceData parameter references an application 
    //                defined 32 bit value to be passed to the callback 
    //                function for each enumeration. 
    //              pEffectType - 
    //                The EffectType parameter defines flags indicating which 
    //                effect types should be enumerated. 
    //                The described effect applies when the flag is set. 
    //                Flags:
    //                  DIEFT_ALL -
    //                    All effects are to be enumerated, regardless of 
    //                    type. 
    //                  DIEFT_CONDITION -
    //                    Only conditions should be enumerated. 
    //                  DIEFT_CONSTANTFORCE -
    //                    Only constant force effects should be enumerated. 
    //                  DIEFT_CUSTOMFORCE -
    //                    Only custom forces should be enumerated. 
    //                  DIEFT_HARDWARE -
    //                    Only hardware specific effects should be 
    //                    enumerated. 
    //                  DIEFT_PERIODIC -
    //                    Only periodic effects should be enumerated. 
    //                  DIEFT_RAMPFORCE -
    //                    Only ramp force effects should be enumerated. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall EnumEffects( void* pReferenceData, dword 
    pEffectType ); 

    // ----------------------------------------------------------------------
    // Method:      EnumEffectsInFile()
    // Description: The EnumEffectsInFile() method will enumerate effects 
    //              stored in a file by the Force Editor utility or another 
    //              application that utilizes the same file format. (RIFF) 
    //              
    //              The Force Editor is included with the DirectX sdk and can 
    //              usually be found at (SDK root)\Bin\Dxutils\Fedit.exe or 
    //              under DirectX 7->DX Tools on your start bar. 
    //              
    //              When enumeration is halted by the callback function, the 
    //              return result is still DI_OK. 
    //              
    //              Error values that can be generated are: 
    //              
    //              DIERR_INVALIDPARAM   
    //              DIERR_NOTINITIALIZED 
    // Params:      pFileName - 
    //                The FileName parameter defines the name of the RIFF file. 
    //              pReferenceData - 
    //                The ReferenceData parameter references an application 
    //                defined 32 bit value to be passed to the callback 
    //                function for each enumeration. 
    //              pFlags - 
    //                The Flags parameter defines flags indicating which 
    //                effects to include or modify while enumerating. 
    //                The described effect applies when the flag is set. 
    //                Flags:
    //                  DIFEF_DEFAULT -
    //                    This flag is equivilent to setting the parameter to 
    //                    0. 
    //                  DIFEF_INCLUDENONSTANDARD -
    //                    Effect types that are undefined by DirectInput 
    //                    should also be enumerated. 
    //                  DIFEF_MODIFYIFNEEDED -
    //                    Modify the effects being enumerated so that they 
    //                    can be played on this device. 
    //                    
    //                    Setting this flag causes the properties of the 
    //                    TDIEffect component referenced by the 
    //                    TDIFileEffect::Effect in the callback function to 
    //                    be modified. 
    //                    
    //                    For example : An attempt to play an effect authored 
    //                    for a two axis device on a single axis device will 
    //                    fail unless this flag was set when retrieving the 
    //                    effect from the file. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall EnumEffectsInFile( AnsiString pFileName, void* 
    pReferenceData, dword pFlags ); 

    // ----------------------------------------------------------------------
    // Method:      EnumObjects()
    // Description: The EnumObjects() method will enumerate the individual 
    //              input and force feedback objects of a device. 
    //              
    //              Error values that can be generated are: 
    //              
    //              DIERR_INVALIDPARAM   
    //              DIERR_NOTINITIALIZED 
    // Params:      pReferenceData - 
    //                The ReferenceData parameter defines context or reference 
    //                data to be passed to the callback function each time it 
    //                is called. 
    //              pFlags - 
    //                The Flags parameter defines flags indicating which object 
    //                types are to be enumerated. 
    //                The described effect applies when the flag is set. 
    //                
    //                Objects matching any of the flags set will be enumerated 
    //                unless DIDFT_FFACTUATOR or DIDFT_FFEFFECTTRIGGER is 
    //                present, in which case enumeration is limited to objects 
    //                matching all the set flags values. 
    //                Flags:
    //                  DIDFT_ABSAXIS -
    //                    Enumerate any object with an absolute axis. 
    //                  DIDFT_ALL -
    //                    Enumerate all objects. 
    //                  DIDFT_AXIS -
    //                    Enumerate any object with an absolute or relative 
    //                    axis. 
    //                  DIDFT_BUTTON -
    //                    Enumerate any object with push or toggle buttons. 
    //                  DIDFT_COLLECTION -
    //                    Enumerate HID link collections. 
    //                  DIDFT_ENUMCOLLECTION(n) -
    //                    Enumerate objects that belong to HID link 
    //                    collection number n. 
    //                  DIDFT_FFACTUATOR -
    //                    Enumerate objects to which force-feedback may be 
    //                    applied. 
    //                  DIDFT_FFEFFECTTRIGGER -
    //                    Enumerate objects that can trigger force-feedback 
    //                    effects. 
    //                  DIDFT_NOCOLLECTION -
    //                    Enumerate objects that do not belong to any HID 
    //                    link collection. 
    //                    Objects falling into this category are those that 
    //                    have TDIDeviceObjectInstance::CollectionNumber = 0. 
    //                  DIDFT_NODATA -
    //                    Enumerate objects that do not generate data. 
    //                  DIDFT_OUTPUT -
    //                    Enumerate objects to which data can be sent using 
    //                    TDx_InputDevice::SendDeviceData(). 
    //                  DIDFT_POV -
    //                    Enumerate point-of-view controllers. 
    //                  DIDFT_PSHBUTTON -
    //                    Enumerate push buttons. 
    //                    Push buttons is reported as down when pressed, and 
    //                    up when released. 
    //                  DIDFT_RELAXIS -
    //                    Enumerate objects with a relative axis. 
    //                  DIDFT_TGLBUTTON -
    //                    Enumerate objects that are toggle buttons. 
    //                    Toggle buttons are reported down when pressed, and 
    //                    remain down until re-pressed. 
    //                  DIDFT_VENDORDEFINED -
    //                    Enumerate objects of a type defined by the device 
    //                    manufacturer. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall EnumObjects( void* pReferenceData, dword pFlags 
    ); 

    // ----------------------------------------------------------------------
    // Method:      Escape()
    // Description: The Escape() method will send a hardware-specific command 
    //              directly to the device driver. 
    //              
    //              TDIDeviceInstance::FFDriver should be checked against the 
    //              expected driver identifier to ensure the escape is sent 
    //              to the right driver. 
    //              
    //              The driver documentation should list and describe the 
    //              comands that are valid for the driver. 
    //              
    //              Error Values that can be generated are: 
    //              
    //              DIERR_NOTINITIALIZED   
    //              DIERR_DEVICEFULL 
    // Params:      pEscape - 
    //                The EffectEscape parameter references a TDIEffEscape 
    //                component describing the command to be sent to the 
    //                driver. 
    //                
    //                On returning, the TDIEffEscape::OutBufferSize property 
    //                will define amount of data, in bytes, written to 
    //                TDIEffEscape::OutBuffer. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Escape( TDIEffEscape* pEscape ); 

    // ----------------------------------------------------------------------
    // Method:      GetCapabilities()
    // Description: The GetCapabilities() method will retrieve the 
    //              cababilities of this device. 
    //              
    //              Error Values that can be generated are: 
    //              
    //              DIERR_INVALIDPARAM   
    //              DIERR_NOTINITIALIZED 
    // Params:      pDevCaps - 
    //                The DevCaps parameter references a TIDevCaps component 
    //                for holding the device capabilities if this method 
    //                returns successfully. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetCapabilities( TDIDevCaps* pDevCaps ); 

    // ----------------------------------------------------------------------
    // Method:      GetDeviceData()
    // Description: The GetDeviceData() method will retrieve buffered data 
    //              that the device is holding. 
    //              
    //              The data format must be set with 
    //              TDx_InputDevice::SetDataFormat(), the buffer size must be 
    //              set with TDx_InputDevice::SetProperty() and the device 
    //              acquired with TDx_InputDevice::Acquire() before device 
    //              data can be obtained. 
    //              
    //              To flush the buffer, set the DOD parameter to NULL and 
    //              the InOut parameter to INFINITE. 
    //              The number of items flushed will be returned in the InOut 
    //              parameter. 
    //              Setting the Flags parameter to DIGDD_PEEK will return the 
    //              number of items without flushing the buffer. 
    //              
    //              Error Values that can be generated are: 
    //              
    //              DIERR_INPUTLOST   
    //              DIERR_INVALIDPARAM   
    //              DIERR_NOTACQUIRED   
    //              DIERR_NOTBUFFERED   
    //              DIERR_NOTINITIALIZED 
    // Params:      pObjectData - 
    //                The ObjectData parameter defines the size, in bytes, of 
    //                each of the TDIDeviceObjectData components referenced by 
    //                the DOD parameter. 
    //              pDeviceObjectData - 
    //                The DeviceObjectData parameter references an array of 
    //                TDIDeviceDeviceObjectData components for holding the data 
    //                retrieved. 
    //                
    //                Setting this parameter to NULL will discard the buffered 
    //                data while still allowing the other effects of the method 
    //                call to occur. 
    //              pInOut - 
    //                The InOut parameter initially defines the number of 
    //                elements in the DOD array and on return it holds the 
    //                actual number of elements retrieved. 
    //              pFlags - 
    //                The Flags parameter defines a flag indicating whether to 
    //                retain the data after if has been retrieved. 
    //                The described effect applies when the flag is set. 
    //                Flags:
    //                  DIGDD_PEEK -