SLAA453A january   2011  – may 2023

 

  1.   1
  2. 1MSP430™ USB HID Windows API Programmer's Guide
  3. 2Introduction
  4. 3Implementation
    1. 3.1 Overview
    2. 3.2 File Organization
    3. 3.3 System Requirements
    4. 3.4 MSP430 USB API Stacks
    5. 3.5 How Windows Maps Physical USB HID Devices to the Host Application
    6. 3.6 Locating a Specific HID Device/Interface on the System and Opening It
    7. 3.7 Sending/Receiving Data
    8. 3.8 Detecting the Dynamic Connection/Disconnection of HID Devices
  5. 4Function Call Reference
    1. 4.1 Device Connection Management and Initialization Calls
      1. 4.1.1 VOID HID_Init(struct strHidDevice* pstrHidDevice)
      2. 4.1.2 DWORD HID_GetSerNums(WORD vid, WORD pid, struct strTrackSerialNumbers *serialNumList)
      3. 4.1.3 DWORD HID_GetNumOfInterfaces(WORD vid, WORD pid, DWORD numSerNums)
      4. 4.1.4 BYTE HID_Open(struct strHidDevice* pstrHidDevice, WORD vid, WORD pid, DWORD deviceIndex, char serialNumber[SERNUM_LEN], DWORD totalDevNum, DWORD totalSerNum)
      5. 4.1.5 BYTE HID_Close(struct strHidDevice* pstrHidDevice)
      6. 4.1.6 BYTE HID_GetVersionNumber(struct strHidDevice* pstrHidDevice, USHORT * VersionNumber)
    2. 4.2 Sending/Receiving Data
      1. 4.2.1 BYTE HID_WriteFile(struct strHidDevice* pstrHidDevice, BYTE* buffer, DWORD bufferSize, DWORD* bytesSent)
      2. 4.2.2 BYTE HID_ReadFile(struct strHidDevice* pStrHidDevice, BYTE* buffer, DWORD bufferSize, DWORD* bytesReturned)
    3. 4.3 Plug and Play Management
      1. 4.3.1 BYTE HID_RegisterForDeviceNotification(HWND hWnd, HDEVNOTIFY* diNotifyHandle)
      2. 4.3.2 BYTE HID_UnregisterForDeviceNotification(HDEVNOTIFY* diNotifyHandle)
      3. 4.3.3 BOOL IsDeviceAffected(struct strHidDevice* pstrHidDevice)
  6. 5Demo Application
  7. 6MSP430 USB Tool Suite
  8.   HID Interface Data Structure: strHidDevice
  9.   Format of Reports on HID-Datapipe Devices
  10.   C References
  11.   C Revision History

4.1.4 BYTE HID_Open(struct strHidDevice* pstrHidDevice, WORD vid, WORD pid, DWORD deviceIndex, char serialNumber[SERNUM_LEN], DWORD totalDevNum, DWORD totalSerNum)

Description

Attempts to locate a device of index deviceIndex within the list of devices on the system that are associated with this VID/PID and serial number. If found, it opens a handle to the device and stores it within the pstrHidDevice structure, and loads the other fields within the structure as well.

To accomplish its goal, HID_Open() needs two additional parameters. One is the totalDevNum, which is the number of HID interfaces on the device described by vid and pid. Usually the developer knows this already. If not, then HID_GetNumOfInterfaces() can be called. Another required parameter is totalSerNum, which is the total number of serial numbers (physical devices) on the system matching this VID/PID.

deviceIndex is a number from 0 to totalDevNum-1. Once vid, pid, and serialNumber are used to filter the Windows HID device list, the list is effectively reduced to HID devices representing HID interfaces contained within a particular physical USB device. All that remains is to select one of those interfaces, and this is what deviceIndex does. The ordering of these HID devices (zero through totalDevNum) is the same as the order in which the HID interfaces were declared in the device's USB descriptors (see Section 3.5).

If the device described by vid and pid has only one HID interface in it, deviceIndex can simply be 0.

The function assumes that this device is in fact an HID device, and not a USB device of another type.

Parameters

Table 4-6 Parameters for HID_Open()
strHidDevice* pstrHidDeviceThe structure to contain the newly-opened device.
WORD vid16-bit vendor ID of the device to be opened.
WORD pid16-bit product ID of the device to be opened.
DWORD deviceIndexThe index within the available devices of this VID/PID and serial number.
char serialNumber[SERNUM_LEN]Char string of size SERNUM_LEN (40) of the serial number of the device to be found.
DWORD totalDevNumThe total number of HID interfaces of a the physical device described by this VID/PID and serial number.
DWORD totalSerNumThe total number of available physical USB devices for this VID/PID
returnsHID_DEVICE_SUCCESS. The device has been found and opened.
HID_DEVICE_ALREADY_OPENED. The device has already been opened.
HID_DEVICE_NOT_FOUND. No device identified by this VID/PID/index could be located.