jvhidcontrollerclass.pas

human interface devices.zip 一套组件

{-----------------------------------------------------------------------------
The contents of this file are subject to the Mozilla Public License
Version 1.1 (the "License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.mozilla.org/MPL/MPL-1.1.html

Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either expressed or implied. See the License for
the specific language governing rights and limitations under the License.

The Original Code is: JvHidControllerClass.PAS, released on 2001-02-28.

The Initial Developer of the Original Code is Robert Marquardt [robert_marquardt att gmx dott de]
Portions created by Robert Marquardt are Copyright (C) 1999-2003 Robert Marquardt.
All Rights Reserved.

Contributor(s): Michael Beck [mbeck att bigfoot dott com].

You may retrieve the latest version of this file at the Project JEDI's JVCL home page,
located at http://jvcl.sourceforge.net

Known Issues:
-----------------------------------------------------------------------------}
// $Id: JvHidControllerClass.pas,v 1.31 2005/09/20 10:38:13 marquardt Exp $

unit JvHidControllerClass;

{$DEFINE DEFAULT_JVCL_INC}

{$I jvcl.inc}
{$I windowsonly.inc}

interface

uses
  {$IFDEF USEJVCL}
  {$IFDEF UNITVERSIONING}
  JclUnitVersioning,
  {$ENDIF UNITVERSIONING}
  {$ENDIF USEJVCL}
  Windows, Messages, Classes, SysUtils,
  {$IFNDEF COMPILER6_UP}
  Forms,
  {$ENDIF COMPILER6_UP}
  {$IFDEF USEJVCL}
  JvComponentBase,
  {$ENDIF USEJVCL}
  DBT, SetupApi, HID, ModuleLoader, Dialogs;

const
  // a version string for the component
  cHidControllerClassVersion = '1.0.32';

  // strings from the registry for CheckOutByClass
  cHidNoClass = 'HIDClass';

type
  // forward declarations
  TJvHidDeviceController = class;
  TJvHidDevice = class;

  // the Event function declarations
  TJvHidEnumerateEvent = function(HidDev: TJvHidDevice;
    const Idx: Integer): Boolean of object;
  TJvHidPlugEvent = procedure(HidDev: TJvHidDevice) of object;
  TJvHidUnplugEvent = TJvHidPlugEvent;
  TJvHidDataEvent = procedure(HidDev: TJvHidDevice; ReportID: Byte;
    const Data: Pointer; Size: Word) of object;
  TJvHidDataErrorEvent = procedure(HidDev: TJvHidDevice; Error: DWORD) of object;

  // check out test function
  TJvHidCheckCallback = function(HidDev: TJvHidDevice): Boolean; stdcall;

  // open overlapped read or write file handle
  TJvHidOpenExMode = (omhRead, omhWrite);

  // the physical descriptor
  TJvPhysicalDescriptor = array of WORD;

  // all USB relevant driver entries in the registry
  TJvHidPnPInfo = class(TObject)
  private
    FDeviceID: DWORD;
    FDevicePath: string;
    FCapabilities: DWORD;
    FClassDescr: string;
    FClassGUID: string;
    FCompatibleIDs: TStringList;
    FConfigFlags: DWORD;
    FDeviceDescr: string;
    FDriver: string;
    FFriendlyName: string;
    FHardwareID: TStringList;
    FLowerFilters: TStringList;
    FMfg: string;
    FUpperFilters: TStringList;
    FAddress: string;
    FBusNumber: DWORD;
    FBusType: string;
    FCharacteristics: string;
    FDevType: DWORD;
    FEnumeratorName: string;
    FExclusive: DWORD;
    FLegacyBusType: DWORD;
    FLocationInfo: string;
    FPhysDevObjName: string;
    FSecuritySDS: string;
    FService: string;
    FUINumber: DWORD;
    FUINumberFormat: string;
    function GetRegistryPropertyString(PnPHandle: HDEVINFO;
      const DevData: TSPDevInfoData; Prop: DWORD): string;
    function GetRegistryPropertyStringList(PnPHandle: HDEVINFO;
      const DevData: TSPDevInfoData; Prop: DWORD): TStringList;
    function GetRegistryPropertyDWord(PnPHandle: HDEVINFO;
      const DevData: TSPDevInfoData; Prop: DWORD): DWORD;
    function GetCompatibleIDs: TStrings;
    function GetHardwareID: TStrings;
    function GetLowerFilters: TStrings;
    function GetUpperFilters: TStrings;
  public
    property DeviceID: DWORD read FDeviceID;
    property DevicePath: string read FDevicePath;
    // registry values
    property Capabilities: DWORD read FCapabilities;
    property ClassDescr: string read FClassDescr;
    property ClassGUID: string read FClassGUID;
    property CompatibleIDs: TStrings read GetCompatibleIDs;
    property ConfigFlags: DWORD read FConfigFlags;
    property DeviceDescr: string read FDeviceDescr;
    property Driver: string read FDriver;
    property FriendlyName: string read FFriendlyName;
    property HardwareID: TStrings read GetHardwareID;
    property LowerFilters: TStrings read GetLowerFilters;
    property Mfg: string read FMfg;
    property UpperFilters: TStrings read GetUpperFilters;
    property Address: string read FAddress;
    property BusNumber: DWORD read FBusNumber;
    property BusType: string read FBusType;
    property Characteristics: string read FCharacteristics;
    property DevType: DWORD read FDevType;
    property EnumeratorName: string read FEnumeratorName;
    property Exclusive: DWORD read FExclusive;
    property LegacyBusType: DWORD read FLegacyBusType;
    property LocationInfo: string read FLocationInfo;
    property PhysDevObjName: string read FPhysDevObjName;
    property SecuritySDS: string read FSecuritySDS;
    property Service: string read FService;
    property UINumber: DWORD read FUINumber;
    property UINumberFormat: string read FUINumberFormat;
    constructor Create(APnPHandle: HDEVINFO; ADevData: TSPDevInfoData; ADevicePath: PChar);
    destructor Destroy; override;
  end;

  // a thread helper class to implement TJvHidDevice.OnData

  TJvHidDeviceReadThread = class(TThread)
  private
    FErr: DWORD;
    procedure DoData;
    procedure DoDataError;
    constructor CtlCreate(const Dev: TJvHidDevice);
  public
    Device: TJvHidDevice;
    NumBytesRead: Cardinal;
    Report: array of Byte;
    procedure Execute; override;
    constructor Create(CreateSuspended: Boolean);
  end;

  // the representation of a HID device

  TJvHidDevice = class(TObject)
  private
    // internal control variables
    FMyController: TJvHidDeviceController;
    FIsPluggedIn: Boolean;
    FIsCheckedOut: Boolean;
    FIsEnumerated: Boolean;
    FHidFileHandle: THandle;
    FHidOverlappedRead: THandle;
    FHidOverlappedWrite: THandle;
    FOvlRead: TOverlapped;
    FOvlWrite: TOverlapped;
    // internal properties part
    FAttributes: THIDDAttributes;
    FPnPInfo: TJvHidPnPInfo;
    FVendorName: WideString;
    FProductName: WideString;
    FPhysicalDescriptor: TJvPhysicalDescriptor;
    FPreparsedData: PHIDPPreparsedData;
    FSerialNumber: WideString;
    FLanguageStrings: TStringList;
    FNumInputBuffers: Integer;
    FNumOverlappedBuffers: Integer;
    FThreadSleepTime: Integer;
    FLinkCollection: array of THIDPLinkCollectionNode;
    FMaxDataListLength: ULONG;
    FMaxUsageListLength: ULONG;
    FMaxButtonListLength: ULONG;
    FReportTypeParam: THIDPReportType;
    FUsagePageParam: TUsage;
    FLinkCollectionParam: WORD;
    FUsageParam: TUsage;
    FData: TJvHidDataEvent;
    FDataError: TJvHidDataErrorEvent;
    FUnplug: TJvHidUnplugEvent;
    FHasReadWriteAccess: Boolean;
    FDataThread: TJvHidDeviceReadThread;
    FTag: Integer;
    // tells if access to device is allowed
    function IsAccessible: Boolean;
    procedure GetMax;
    // internal property implementors
    function GetDeviceStringAnsi(Idx: Byte): string;
    function GetDeviceStringUnicode(Idx: Byte): WideString;
    function GetLinkCollectionNode(Idx: WORD): THIDPLinkCollectionNode;
    function GetConfiguration: THIDDConfiguration;
    function GetPreparsedData: PHIDPPreparsedData;
    function GetCaps: THIDPCaps;
    function GetVendorName: WideString;
    function GetProductName: WideString;
    function GetSerialNumber: WideString;
    function GetPhysicalDescriptor: TJvPhysicalDescriptor;
    function GetLanguageStrings: TStrings;
    function GetOverlappedReadResult: DWORD;
    function GetOverlappedWriteResult: DWORD;
    procedure SetConfiguration(const Config: THIDDConfiguration);
    procedure SetDataEvent(const DataEvent: TJvHidDataEvent);
    procedure SetNumInputBuffers(const Num: Integer);
    procedure SetNumOverlappedBuffers(const Num: Integer);
    procedure SetReportTypeParam(const ReportType: THIDPReportType);
    procedure SetThreadSleepTime(const SleepTime: Integer);
    procedure SetUsagePageParam(const UsagePage: TUsage);
    procedure StartThread;
    procedure StopThread;
    // Constructor is hidden! Only a TJvHidDeviceController can create a TJvHidDevice object.
    constructor CtlCreate(const APnPInfo: TJvHidPnPInfo;
      const Controller: TJvHidDeviceController);
  protected
    // internal event implementor
    procedure DoUnplug;
  public
    // dummy constructor
    constructor Create;
    destructor Destroy; override;
    // methods
    function CancelIO(const Mode: TJvHidOpenExMode): Boolean;
    procedure CloseFile;
    procedure CloseFileEx(const Mode: TJvHidOpenExMode);
    function DeviceIoControl(IoControlCode: DWORD; InBuffer: Pointer; InSize: DWORD;
      OutBuffer: Pointer; OutSize: DWORD;
      var BytesReturned: DWORD): Boolean;
    function FlushQueue: Boolean;
    function GetButtonCaps(ButtonCaps: PHIDPButtonCaps; var Count: WORD): NTSTATUS;
    function GetButtons(UsageList: PUsage; var UsageLength: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function GetButtonsEx(UsageList: PUsageAndPage; var UsageLength: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function GetData(DataList: PHIDPData; var DataLength: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function GetFeature(var Report; const Size: Integer): Boolean;
    function GetScaledUsageValue(var UsageValue: Integer;
      var Report; ReportLength: ULONG): NTSTATUS;
    function GetSpecificButtonCaps(ButtonCaps: PHIDPButtonCaps; var Count: WORD): NTSTATUS;
    function GetSpecificValueCaps(ValueCaps: PHIDPValueCaps; var Count: WORD): NTSTATUS;
    function GetUsages(UsageList: PUsage; var UsageLength: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function GetUsagesEx(UsageList: PUsageAndPage; var UsageLength: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function GetUsageValue(var UsageValue: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function GetUsageValueArray(UsageValue: PChar; UsageValueByteLength: WORD;
      var Report; ReportLength: ULONG): NTSTATUS;
    function GetValueCaps(ValueCaps: PHIDPValueCaps; var Count: WORD): NTSTATUS;
    function OpenFile: Boolean;
    function OpenFileEx(Mode: TJvHidOpenExMode): Boolean;
    function SetButtons(UsageList: PUsage; var UsageLength: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function SetData(DataList: PHIDPData; var DataLength: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function SetFeature(var Report; const Size: Integer): Boolean;
    function SetScaledUsageValue(UsageValue: Integer;
      var Report; ReportLength: ULONG): NTSTATUS;
    function SetUsages(UsageList: PUsage; var UsageLength: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function SetUsageValue(UsageValue: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function SetUsageValueArray(UsageValue: PChar; UsageValueByteLength: WORD;
      var Report; ReportLength: ULONG): NTSTATUS;
    function UnsetButtons(UsageList: PUsage; var UsageLength: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function UnsetUsages(UsageList: PUsage; var UsageLength: ULONG;
      var Report; ReportLength: ULONG): NTSTATUS;
    function ReadFile(var Report; ToRead: DWORD; var BytesRead: DWORD): Boolean;
    function ReadFileEx(var Report; ToRead: DWORD;
      CallBack: TPROverlappedCompletionRoutine): Boolean;
    function WriteFile(var Report; ToWrite: DWORD; var BytesWritten: DWORD): Boolean;
    function WriteFileEx(var Report; ToWrite: DWORD;
      CallBack: TPROverlappedCompletionRoutine): Boolean;
    function CheckOut: Boolean;
    // read only properties
    property Attributes: THIDDAttributes read FAttributes;
    property Caps: THIDPCaps read GetCaps;
    property HasReadWriteAccess: Boolean read FHasReadWriteAccess;
    property HidFileHandle: THandle read FHidFileHandle;
    property HidOverlappedRead: THandle read FHidOverlappedRead;
    property HidOverlappedWrite: THandle read FHidOverlappedWrite;
    property HidOverlappedReadResult: DWORD read GetOverlappedReadResult;
    property HidOverlappedWriteResult: DWORD read GetOverlappedWriteResult;
    property IsCheckedOut: Boolean read FIsCheckedOut;
    property IsPluggedIn: Boolean read FIsPluggedIn;
    property LanguageStrings: TStrings read GetLanguageStrings;
    property MaxButtonListLength: ULONG read FMaxButtonListLength;
    property MaxDataListLength: ULONG read FMaxDataListLength;
    property MaxUsageListLength: ULONG read FMaxUsageListLength;
    property PhysicalDescriptor: TJvPhysicalDescriptor read GetPhysicalDescriptor;
    property PnPInfo: TJvHidPnPInfo read FPnPInfo;
    property PreparsedData: PHIDPPreparsedData read GetPreparsedData;
    property ProductName: WideString read GetProductName;
    property SerialNumber: WideString read GetSerialNumber;
    property VendorName: WideString read GetVendorName;
    // read write properties
    property Configuration: THIDDConfiguration read GetConfiguration write SetConfiguration;
    property LinkCollectionParam: WORD read FLinkCollectionParam write FLinkCollectionParam;
    property NumInputBuffers: Integer read FNumInputBuffers write SetNumInputBuffers;
    property NumOverlappedBuffers: Integer read FNumOverlappedBuffers write SetNumOverlappedBuffers;
    property ReportTypeParam: THIDPReportType read FReportTypeParam write SetReportTypeParam;
    property Tag: Integer read FTag write FTag;
    property ThreadSleepTime: Integer read FThreadSleepTime write SetThreadSleepTime;
    property UsagePageParam: TUsage read FUsagePageParam write SetUsagePageParam;
    property UsageParam: TUsage read FUsageParam write FUsageParam;
    // indexed properties
    property DeviceStrings[Idx: Byte]: string read GetDeviceStringAnsi;
    property DeviceStringsUnicode[Idx: Byte]: WideString read GetDeviceStringUnicode;
    property LinkCollectionNodes[Idx: WORD]: THIDPLinkCollectionNode read GetLinkCollectionNode;
    // event properties
    property OnData: TJvHidDataEvent read FData write SetDataEvent;
    property OnDataError: TJvHidDataErrorEvent read FDataError write FDataError;
    property OnUnplug: TJvHidUnplugEvent read FUnplug write FUnplug;
  end;

  // controller class to manage all HID devices

  {$IFDEF USEJVCL}
  TJvHidDeviceController = class(TJvComponent)
  {$ELSE}
  TJvHidDeviceController = class(TComponent)
  {$ENDIF USEJVCL}
  private
    // internal properties part
    FHidGuid: TGUID;
    FArrivalEvent: TJvHidPlugEvent;
    FDeviceChangeEvent: TNotifyEvent;
    FEnumerateEvent: TJvHidEnumerateEvent;
    FDevDataEvent: TJvHidDataEvent;
    FDevDataErrorEvent: TJvHidDataErrorEvent;
    FDevUnplugEvent: TJvHidUnplugEvent;
    FRemovalEvent: TJvHidUnplugEvent;
    FDevThreadSleepTime: Integer;
    FVersion: string;
    FDummy: string;
    // internal list of all HID device objects
    FList: TList;
    // counters for the list
    FNumCheckedInDevices: Integer;
    FNumCheckedOutDevices: Integer;
    FNumUnpluggedDevices: Integer;
    // reentrancy
    FInDeviceChange: Boolean;
    FLParam: LPARAM;
    // window to catch WM_DEVICECHANGE