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.2.2 BYTE HID_ReadFile(struct strHidDevice* pStrHidDevice, BYTE* buffer, DWORD bufferSize, DWORD* bytesReturned)

Description

Obtains bufferSize bytes of payload data from the HID device designated by pStrHidDevice, and stores it in buffer. It does this by reading as many HID reports as necessary until bufferSize bytes have been returned.

If the function returns HID_DEVICE_SUCCESS, then bytesReturned will equal bufferSize. bytesReturned will only be less than bufferSize in the event of one of the other return codes.

This function receives the data by using HID reports as "packets". If any attempt to fetch a packet from the USB device times out, according to the value pStrHidDevice.uGetReportTimeout, then the function returns HID_DEVICE_TRANSFER_TIMEOUT.

There is no inherent limit to the number of bytes that can be received, other than the limitation imposed by bufferSize being a DWORD value. Packetization is handled automatically.

Parameters

Table 4-11 Parameters for HID_ReadFile()
strHidDevice* pstrHidDeviceThe structure containing the HID device information.
BYTE* bufferAn array to contain the received data
DWORD bufferSizeSize of buffer, indicating the maximum amount of bytes intended to be received
DWORD* bytesReturnedThe number of bytes actually received (in the event of an error)
returnsHID_DEVICE_NOT_OPENED. The HID device failed to open.
HID_DEVICE_TRANSFER_TIMEOUT. A report request timed out.
HID_DEVICE_TRANSFER_FAILED. The transmission failed for unspecified reasons.
HID_DEVICE_SUCCESS. The correct number of bytes were received.