![]() |
![]() |
Contains APIs related to HID (Human Interface Device) device class.
Functions | |
BYTE | USBHID_sendReport (const BYTE *reportData, BYTE intfNum) |
BYTE | USBHID_receiveReport (BYTE *reportData, BYTE intfNum) |
BYTE | USBHID_sendData (const BYTE *data, WORD size, BYTE intfNum) |
BYTE | USBHID_abortSend (WORD *size, BYTE intfNum) |
BYTE | USBHID_receiveData (BYTE *data, WORD size, BYTE intfNum) |
BYTE | USBHID_abortReceive (WORD *size, BYTE intfNum) |
BYTE | USBHID_rejectData (BYTE intfNum) |
BYTE | USBHID_intfStatus (BYTE intfNum, WORD *bytesSent, WORD *bytesReceived) |
BYTE | USBHID_bytesInUSBBuffer (BYTE intfNum) |
BYTE USBHID_sendReport | ( | const BYTE * | reportData, |
BYTE | intfNum | ||
) |
Sends a Data Report to the Host.
reportData | is an array containing the report. |
intfNum | is which HID interface the data should be transmitted over. |
Sends a pre-built report reportData to the host, on interface intfNum. The report must be organized to reflect the format defined by the report descriptor in descriptors.c.
When the function returns kUSBHID_sendComplete, the data has been written to the USB transmit buffers, and will be transferred to the host in the next polling frame. If the function returns kUSBHID_busNotAvailable, then the bus has either been disconnected or the device is suspended, allowing no reports to be sent. If the function returns kUSBHID_intfBusyError, it means the USB buffer for the interface has data in it, suggesting that the host has not yet fetched the previously-loaded report.
BYTE USBHID_receiveReport | ( | BYTE * | reportData, |
BYTE | intfNum | ||
) |
Receives a Report from the Host into reportData.
reportData | is an array containing the report. |
intfNum | is the HID interface over which the data is to be received. |
Receives a report from the host into reportData, on interface intfNum. It is expected that the host will organize the report in the format defined by the report descriptor in descriptors.c.
When the function returns kUSBHID_receiveCompleted, the data has been successfully copied from the USB receive buffers into reportData. If the function returns kUSBHID_busNotAvailable, then the bus has either been disconnected or the device is suspended, allowing no reports to be sent. If the function returns kUSBHID_generalError, it means the call failed for unspecified reasons.
The call is intended to be called only when it is known that a report is in the USB buffer. This means it is best called in response to the API calling USBHID_handleDataReceived(), which indicates that a report has been received for interface intfNum.
BYTE USBHID_sendData | ( | const BYTE * | data, |
WORD | size, | ||
BYTE | intfNum | ||
) |
Initiates Sending of a User Buffer Over HID Interface.
data | is an array of data to be sent. |
size | is the number of bytes to be sent, starting from address data. |
intfNum | is which data interface the data should be transmitted over. |
Initiates sending of a user buffer over HID interface intfNum, of size size and starting at address data. If size is larger than the packet size, the function handles all packetization and buffer management. size has no inherent upper limit (beyond being a 16-bit value).
In most cases where a send operation is successfully started, the function will return kUSBHID_sendStarted. A send operation is said to be underway. At some point, either before or after the function returns, the send operation will complete, barring any events that would preclude it. (Even if the operation completes before the function returns, the return code will still be kUSBHID_sendStarted.)
If the bus is not connected when the function is called, the function returns kUSBHID_busNotAvailable, and no operation is begun. If size is 0, the function returns kUSBHID_generalError. If a previous send operation is already underway for this data interface, the function returns with kUSBHID_intfBusyError.
USB includes low-level mechanisms that ensure valid transmission of data.
See Sec. 7.2 of "Programmer's Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" for a detailed discussion of send operations.
Referenced by hidSendDataInBackground(), and hidSendDataWaitTilDone().
BYTE USBHID_abortSend | ( | WORD * | size, |
BYTE | intfNum | ||
) |
Aborts an Active Send Operation on Data Interface.
size | is the number of bytes that were sent prior to the aboert action. |
intfNum | is the data interface for which the send should be aborted. |
Aborts an active send operation on data interface intfNum. Returns the number of bytes that were sent prior to the abort, in size.
An application may choose to call this function if sending failed, due to factors such as:
BYTE USBHID_receiveData | ( | BYTE * | data, |
WORD | size, | ||
BYTE | intfNum | ||
) |
Receives size Bytes Over HID Interface.
data | is an array to contain the data received. |
size | is the number of bytes to be received. |
intfNum | is which data interface to receive from. |
Receives size bytes over HID interface intfNum into memory starting at address data. size has no inherent upper limit (beyond being a 16-bit value).
The function may return with kUSBHID_receiveStarted, indicating that a receive operation is underway. The operation completes when size bytes are received. The application should ensure that the data memory buffer be available during the whole of the receive operation.
The function may also return with kUSBHID_receiveCompleted. This means that the receive operation was complete by the time the function returned.
If the bus is not connected when the function is called, the function returns kUSBHID_busNotAvailable, and no operation is begun. If size is 0, the function returns kUSBHID_generalError. If a previous receive operation is already underway for this data interface, the function returns kUSBHID_intfBusyError.
USB includes low-level mechanisms that ensure valid transmission of data.
See Sec. 7.2 of "Programmer's Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" for a detailed discussion of receive operations.
Referenced by hidReceiveDataInBuffer().
BYTE USBHID_abortReceive | ( | WORD * | size, |
BYTE | intfNum | ||
) |
Aborts an Active Recieve Operation on HID Interface.
size | is the number of bytes that were received and are waiting at the assigned address. |
intfNum | is the data interface for which the receive should be aborted. |
Aborts an active receive operation on HID interface intfNum. Returns the number of bytes that were received and transferred to the data location established for this receive operation. The data moved to the buffer up to that time remains valid.
An application may choose to call this function if it decides it no longer wants to receive data from the USB host. It should be noted that if a continuous stream of data is being received from the host, aborting the operation is akin to pressing a "pause" button; the host will be NAK'ed until another receive operation is opened.
See Sec. 7.2 of "Programmer's Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" for a detailed discussion of receive operations.
BYTE USBHID_rejectData | ( | BYTE | intfNum | ) |
Rejects Data Received from the Host.
This function rejects data that has been received from the host, for interface intfNum, that does not have an active receive operation underway. It resides in the USB endpoint buffer and blocks further data until a receive operation is opened, or until rejected. When this function is called, the buffer for this interface is purged, and the data lost. This frees the USB path to resume communication.
See Sec. 7.2 of "Programmer's Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" for a detailed discussion of receive operations.
BYTE USBHID_intfStatus | ( | BYTE | intfNum, |
WORD * | bytesSent, | ||
WORD * | bytesReceived | ||
) |
Indicates the Status of the HID Interface.
intfNum | is the interface number for which the status is being retrieved. |
bytesSent | If a send operation is underway, the number of bytes that have been transferred to the host is returned in this location. If no send operation is underway, this returns zero. |
bytesReceived | If a receive operation is underway, the number of bytes that have been transferred to the assigned memory location is returned in this location. If no receive operation is underway, this returns zero. |
Indicates the status of the HID interface intfNum. If a send operation is active for this interface, the function also returns the number of bytes that have been transmitted to the host. If a receive operation is active for this interface, the function also returns the number of bytes that have been received from the host and are waiting at the assigned address.
Because multiple flags can be returned, the possible values can be masked together - for example, kUSBHID_waitingForSend + kUSBHID_dataWaiting.
Referenced by hidSendDataInBackground(), and hidSendDataWaitTilDone().
BYTE USBHID_bytesInUSBBuffer | ( | BYTE | intfNum | ) |
Returns the Number of Bytes Waiting in the USB Endpoint Buffer.
intfNum | is the data interface whose buffer is to be checked. |
Returns the number of bytes waiting in the USB endpoint buffer for intfNum. A non-zero value generally means that no receive operation is open by which these bytes can be copied to a user buffer. If the value is non-zero, the application should either open a receive operation so that the data can be moved out of the endpoint buffer, or the data should be rejected (USBHID_rejectData()).
Referenced by hidReceiveDataInBuffer().