XITRON XT2640 - Page 136

XT2640OperatingManual 13July2016 Page136of187

HidUart_Open
Opensadeviceusingadevicenumberbetween0andHidUart_GetNumDevices()–1andreturnsadeviceobjectpointer
whichwillbeusedforsubsequentaccesses.
HID_UART_STATUS HidUart_Open (HID_UART_DEVICE* device, DWORD deviceNum, WORD vid, WORD
pid)
device
—ReturnsapointertoaXT2640deviceobject.Thispointerwillbeusedbyallsubsequentaccessestothedevice.
deviceNum—Zero‐baseddeviceindex,between0and(HidUart_GetNumDevices()–1).
vid—FilterdeviceresultsbyvendorID.
pid—FilterdeviceresultsbyproductID.
ReturnValue:HID_UART_STATUS=HID_UART_SUCCESS,HID_UART_INVALID_DEVICE_OBJECT,
HID_UART_DEVICE_NOT_FOUND,HID_UART_INVALID_PARAMETER,HID_UART_DEVICE_IO_FAILED,
HID_UART_DEVICE_ACCESS_ERROR,HID_UART_DEVICE_NOT_SUPPORTED
Note‐Becarefulwhenopeningadevice.AnyHIDdevicemaybeopenedbythislibrary.However,ifthedeviceisnot
actuallyaXT2640,useofthislibrarywillcauseundesirableresults.TheXT2640PIDandVIDmustalwaysbeused.
HidUart_Close
ClosesanopeneddeviceusingthedeviceobjectpointerprovidedbyHidUart_Open().
HID_UART_STATUS HidUart_Close (HID_UART_DEVICE device)
device
—DeviceobjectpointerasreturnedbyHidUart_Open().
ReturnValue:HID_UART_STATUS=HID_UART_SUCCESS,HID_UART_INVALID_DEVICE_OBJECT,
HID_UART_INVALID_HANDLE,HID_UART_DEVICE_ACCESS_ERROR
Note‐
deviceisinvalidaftercallingHidUart_Close().ItisrecommendedtosetdevicetoNULLafterthiscall.
HidUart_IsOpened
Returnsthedeviceopenedstatus.
HID_UART_STATUS HidUart_IsOpened (HID_UART_DEVICE device, BOOL* opened)
device
—DeviceobjectpointerasreturnedbyHidUart_Open().
opened—ReturnsTRUEifthedeviceobjectpointerisvalidandthedevicehasbeenopenedusingHidUart_Open().
ReturnValue:HID_UART_STATUS=HID_UART_SUCCESS,HID_UART_INVALID_DEVICE_OBJECT,
HID_UART_INVALID_PARAMETER
HidUart_Read
Readstheavailablenumberofbytesintothesuppliedbufferandreturnsthenumberofbytesreadwhichcanbelessthan
thenumberofbytesrequested.Thisfunctionreturnssynchronouslyafterreadingtherequestednumberofbytesorafter
thetimeoutdurationhaselapsed.Readandwritetimeoutscanbesetusing
HidUart_SetTimeouts().
HID_UART_STATUS HidUart_Read (HID_UART_DEVICE device, BYTE* buffer, DWORD
numBytesToRead, DWORD* numBytesRead)
device
—DeviceobjectpointerasreturnedbyHidUart_Open().
buffer—Addressofabuffertobefilledwithreaddata.
numBytesToRead—Numberofbytestoreadfromthedeviceintothebuffer(1–32768).Thisvaluemustbelessthanor
equaltothesizeof
buffer.
numBytesRead
—Returnsthenumberofbytesactuallyreadintothebufferoncompletion.
ReturnValue:HID_UART_STATUS=HID_UART_SUCCESS,HID_UART_READ_ERROR,HID_UART_INVALID_PARAMETER,
HID_UART_INVALID_DEVICE_OBJECT,HID_UART_READ_TIMED_OUT,HID_UART_INVALID_REQUEST_LENGTH
Note‐
HidUart_Read()returnsHID_UART_READ_TIMED_OUTifthenumberofbytesreadislessthanthenumberofbytes
requested.Thiswillonlyoccurafterthereadtimeouthaselapsed.Ifthenumberofbytesreadmatchesthenumberofbytes
requested,thisfunctionwillreturnHID_UART_SUCCESS.
HidUart_Write
Writethespecifiednumberofbytesfromthesuppliedbuffertothedevice.Thisfunctionreturnssynchronouslyafter
writingtherequestednumberofbytesorafterthetimeoutdurationhaselapsed.Readandwritetimeoutscanbesetusing
HidUart_SetTimeouts().
HID_UART_STATUS HidUart_Write (HID_UART_DEVICE device, BYTE* buffer, DWORD
numBytesToWrite, DWORD* numBytesWritten)
device
—DeviceobjectpointerasreturnedbyHidUart_Open().
buffer—Addressofabuffertobesenttothedevice.
numBytesToWrite—Numberofbytestowritetothedevice(1–4096bytes).Thisvaluemustbelessthanorequaltothesize
ofbuffer.
numBytesWritten
—Returnsthenumberofbytesactuallywrittentothedevice.
ReturnValue:HID_UART_STATUS=HID_UART_SUCCESS,HID_UART_WRITE_ERROR,HID_UART_INVALID_PARAMETER,
HID_UART_INVALID_DEVICE_OBJECT,HID_UART_WRITE_TIMED_OUT,HID_UART_INVALID_REQUEST_LENGTH
Note‐
HidUart_Write()returnsHID_UART_WRITE_TIMED_OUTifthenumberofbyteswrittenislessthanthenumberof
bytesrequested.
HidUart_FlushBuffers