hid.pas

human interface devices.zip 一套组件

//
// The link collection tree consists of an array of LINK_COLLECTION_NODES
// where the index into this array is the same as the collection number.
//
// Given a collection A which contains a subcollection B, A is defined to be
// the parent B, and B is defined to be the child.
//
// Given collections A, B, and C where B and C are children of A, and B was
// encountered before C in the report descriptor, B is defined as a sibling of
// C.  (This implies, of course, that if B is a sibling of C, then C is NOT a
// sibling of B).
//
// B is defined as the NextSibling of C if and only if there exists NO
// child collection of A, call it D, such that B is a sibling of D and D
// is a sibling of C.
//
// E is defined to be the FirstChild of A if and only if for all children of A,
// F, that are not equivalent to E, F is a sibling of E.
// (This implies, of course, that the does not exist a child of A, call it G,
// where E is a sibling of G).  In other words the first sibling is the last
// link collection found in the list.
//
// In other words, if a collection B is defined within the definition of another
// collection A, B becomes a child of A.  All collections with the same parent
// are considered siblings.  The FirstChild of the parent collection, A, will be
// last collection defined that has A as a parent.  The order of sibling pointers
// is similarly determined.  When a collection B is defined, it becomes the
// FirstChild of it's parent collection.  The previously defined FirstChild of the
// parent collection becomes the NextSibling of the new collection.  As new
// collections with the same parent are discovered, the chain of sibling is built.
//
// With that in mind, the following describes conclusively a data structure
// that provides direct traversal up, down, and accross the link collection
// tree.

  PHIDPLinkCollectionNode = ^THIDPLinkCollectionNode;
  HIDP_LINK_COLLECTION_NODE = record
    LinkUsage:        TUsage;
    LinkUsagePage:    TUsage;
    Parent:           Word;
    NumberOfChildren: Word;
    NextSibling:      Word;
    FirstChild:       Word;
    CollectionType:   BYTE;    // As defined in 6.2.2.6 of HID spec
    IsAlias:          BYTE;    // This link node is an alias of the next link node.
    Reserved:         Word;    // (rom) bitfields
    UserContext:      Pointer; // The user can hang his coat here.
  end;
  THIDPLinkCollectionNode = HIDP_LINK_COLLECTION_NODE;

//
// When a link collection is described by a delimiter, alias link collection
// nodes are created.  (One for each usage within the delimiter).
// The parser assigns each capability description listed above only one
// link collection.
//
// If a control is defined within a collection defined by
// delimited usages, then that control is said to be within multiple link
// collections, one for each usage within the open and close delimiter tokens.
// Such multiple link collecions are said to be aliases.  The first N-1 such
// collections, listed in the link collection node array, have their IsAlias
// bit set.  The last such link collection is the link collection index used
// in the capabilities described above.
// Clients wishing to set a control in an aliased collection, should walk the
// collection array once for each time they see the IsAlias flag set, and use
// the last link collection as the index for the below accessor functions.
//
// NB: if IsAlias is set, then NextSibling should be one more than the current
// link collection node index.

  PHIDPReportDescriptor = PChar;

  PHIDPCaps = ^THIDPCaps;
  HIDP_CAPS = record
    Usage:                     TUsage;
    UsagePage:                 TUsage;
    InputReportByteLength:     Word;
    OutputReportByteLength:    Word;
    FeatureReportByteLength:   Word;
    Reserved:                  array [0..16] of Word;

    NumberLinkCollectionNodes: Word;

    NumberInputButtonCaps:     Word;
    NumberInputValueCaps:      Word;
    NumberInputDataIndices:    Word;

    NumberOutputButtonCaps:    Word;
    NumberOutputValueCaps:     Word;
    NumberOutputDataIndices:   Word;

    NumberFeatureButtonCaps:   Word;
    NumberFeatureValueCaps:    Word;
    NumberFeatureDataIndices:  Word;
  end;
  THIDPCaps = HIDP_CAPS;

  PHIDPData = ^THIDPData;
  HIDP_DATA = record
    DataIndex: Word;
    Reserved:  Word;
  case Integer of
    0: (RawValue: ULONG);      // for values
    1: (On_:      ByteBool);   // for buttons MUST BE TRUE for buttons.
                               // (rom) name change On is reserved in Pascal
  end;
  THIDPData = HIDP_DATA;

// The HIDP_DATA structure is used with HidP_GetData and HidP_SetData
// functions.
//
// The parser contiguously assigns every control (button or value) in a hid
// device a unique data index from zero to NumberXXXDataIndices -1 , inclusive.
// This value is found in the HIDP_BUTTON_CAPS and HIDP_VALUE_CAPS structures.
//
// Most clients will find the Get/Set Buttons / Value accessor functions
// sufficient to their needs, as they will allow the clients to access the
// data known to them while ignoring the other controls.
//
// More complex clients, which actually read the Button / Value Caps, and which
// do a value add service to these routines (EG Direct Input), will need to
// access all the data in the device without interest in the individual usage
// or link collection location.  These are the clients that will find
// HidP_Data useful.

  PHIDPUnknownToken = ^THIDPUnknownToken;
  HIDP_UNKNOWN_TOKEN = record
    Token:    BYTE;
    Reserved: array [0..2] of BYTE;
    BitField: DWORD;
  end;
  THIDPUnknownToken = HIDP_UNKNOWN_TOKEN;

  PHIDPExtendedAttributes = ^THIDPExtendedAttributes;
  HIDP_EXTENDED_ATTRIBUTES = record
    NumGlobalUnknowns: BYTE;
    Reserved:          array [0..2] of BYTE;
    GlobalUnknowns:    PHIDPUnknownToken;
    // ... Additional attributes
    Data:              array [0..0] of ULONG; // variableLength  DO NOT ACCESS THIS FIELD
  end;
  THIDPExtendedAttributes = HIDP_EXTENDED_ATTRIBUTES;

  // (rom) callback function type for HidP_TranslateUsagesToI8042ScanCodes param
  // (rom) maybe calling convention is incorrect
  THIDPInsertScanCodes = function(
    Context:      Pointer; // Some caller supplied context
    NewScanCodes: PChar;   // A list of i8042 scan codes
    Length:       ULONG    // the length of the scan code list
   ): Boolean; stdcall;

{$IFNDEF HID_LINKONREQUEST}

// (rom) undocumented easter egg function
// (rom) fills buffer with "Hello\nI hate Jello\n"
// (rom) returns number of bytes filled in == strlen(Buffer)+1 == 20
// (rom) bugs: handing in nil as buffer gives access violation.
// (rom)       always returns 20 even if buffer length is less than 20
// (rom)       but does not produce buffer overflow

function HidD_Hello(Buffer: PChar; BufferLength: ULONG): ULONG; stdcall;

procedure HidD_GetHidGuid(var HidGuid: TGUID) stdcall;

function HidD_GetPreparsedData(HidDeviceObject: THandle;
  var PreparsedData: PHIDPPreparsedData): LongBool; stdcall;

function HidD_FreePreparsedData(PreparsedData: PHIDPPreparsedData): LongBool; stdcall;

// Routine Description:
//     Get the configuration information for this Hid device
//
// Arguments:
//    HidDeviceObject      A handle to a Hid Device Object.
//
//    Configuration        A configuration structure.  HidD_GetConfiguration MUST
//                         be called before the configuration can be modified and
//                         set using HidD_SetConfiguration
//
//    ConfigurationLength  That is ``sizeof (HIDD_CONFIGURATION)''. Using this
//                         parameter, we can later increase the length of the
//                         configuration array and not break older apps.
//
// Return Value:
//    TRUE if successful
//    FALSE otherwise  -- Use GetLastError() to get extended error information

function HidD_GetConfiguration(HidDeviceObject: THandle;
  var HidConfig: THIDDConfiguration; Size: Integer): LongBool; stdcall;

// Routine Description:
//    Set the configuration information for this Hid device...
//
//    NOTE: HidD_GetConfiguration must be called to retrieve the current
//          configuration information before this information can be modified
//          and set.
//
// Arguments:
//     HidDeviceObject      A handle to a Hid Device Object.
//
//     Configuration        A configuration structure.  HidD_GetConfiguration MUST
//                          be called before the configuration can be modified and
//                          set using HidD_SetConfiguration
//
//     ConfigurationLength  That is ``sizeof (HIDD_CONFIGURATION)''. Using this
//                          parameter, we can later increase the length of the
//                          configuration array and not break older apps.
//
// Return Value:
//     TRUE if successful
//     FALSE otherwise  -- Use GetLastError() to get extended error information

function HidD_SetConfiguration(HidDeviceObject: THandle;
  const HidConfig: THIDDConfiguration; Size: Integer): LongBool; stdcall;

// Routine Description:
//     Flush the input queue for the given HID device.
//
// Arguments:
//    HidDeviceObject A handle to a Hid Device that the client obtains using
//                    a call to CreateFile on a valid Hid device string name.
//                    The string name can be obtained using standard PnP calls.
//
// Return Value:
//    TRUE if successful
//    FALSE otherwise  -- Use GetLastError() to get extended error information

function HidD_FlushQueue(HidDeviceObject: THandle): LongBool; stdcall;

// Routine Description:
//     Retrieve a feature report from a HID device.
//
// Arguments:
//     HidDeviceObject      A handle to a Hid Device Object.
//
//     ReportBuffer         The buffer that the feature report should be placed
//                          into.  The first byte of the buffer should be set to
//                          the report ID of the desired report
//
//     ReportBufferLength   The size (in bytes) of ReportBuffer.  This value
//                          should be greater than or equal to the
//                          FeatureReportByteLength field as specified in the
//                          HIDP_CAPS structure for the device
// Return Value:
//     TRUE if successful
//     FALSE otherwise  -- Use GetLastError() to get extended error information

function HidD_GetFeature(HidDeviceObject: THandle;
  var Report; Size: Integer): LongBool; stdcall;

// Routine Description:
//     Send a feature report to a HID device.
//
// Arguments:
//     HidDeviceObject      A handle to a Hid Device Object.
//
//     ReportBuffer         The buffer of the feature report to send to the device
//
//     ReportBufferLength   The size (in bytes) of ReportBuffer.  This value
//                          should be greater than or equal to the
//                          FeatureReportByteLength field as specified in the
//                          HIDP_CAPS structure for the device
// Return Value:
//     TRUE if successful
//     FALSE otherwise  -- Use GetLastError() to get extended error information

function HidD_SetFeature(HidDeviceObject: THandle;
  var Report; Size: Integer): LongBool; stdcall;

// Routine Description:
//     This function returns the number of input buffers used by the specified
//     file handle to the Hid device.  Each file object has a number of buffers
//     associated with it to queue reports read from the device but which have
//     not yet been read by the user-mode app with a handle to that device.
//
// Arguments:
//     HidDeviceObject      A handle to a Hid Device Object.
//
//     NumberBuffers        Number of buffers currently being used for this file
//                          handle to the Hid device