UsbInterface Class Reference

Detailed Description

An IoInterface for dealing specifically with Xsens USB devices.

Definition at line 35 of file usbinterface.h.

#include <xSens_MT4/xcommunication/include/xsens/usbinterface.h>

Inheritance diagram for UsbInterface:

Public Member Functions
	UsbInterface ()
	Default constructor, initializes all members to their default values. More...
	~UsbInterface ()
	Destructor, de-initializes, frees memory allocated for buffers, etc. More...
XsResultValue	open (const XsPortInfo &portInfo, uint32_t readBufSize=0, uint32_t writeBufSize=0)
	Open a communication channel to the given USB port name. More...
XsResultValue	close (void)
	Close the USB communication port. More...
XsResultValue	closeUsb (void)
	Close the USB communication port. More...
XsResultValue	flushData (void)
	Flush all data in the buffers to and from the device. More...
bool	isOpen (void) const
	Return whether the USB communication port is open or not. More...
uint8_t	usbBus () const
	The USB bus number this device is on (libusb/linux only) More...
uint8_t	usbAddress () const
	The address of the device (libusb/linux only) More...
XsResultValue	getLastResult (void) const
	Return the error code of the last operation. More...
XsResultValue	setTimeout (uint32_t ms)
	Set the default timeout value to use in blocking operations. More...
uint32_t	getTimeout (void) const
	Return the current timeout value. More...
void	setRawIo (bool enable)
	Sets the RAWIO mode of the USB interface. More...
bool	getRawIo (void)
	Retrieves the state of the RAWIO mode of the USB interface. More...
virtual XsResultValue	writeData (const XsByteArray &data, XsSize *written=nullptr)
	Write the data to the USB port. More...
virtual XsResultValue	readData (XsSize maxLength, XsByteArray &data)
	Read data from the USB port and put it into the data buffer. More...
XsResultValue	writeData (XsSize length, const void *data, XsSize *written=nullptr)
	Write the data to the USB port. More...
XsResultValue	readData (XsSize maxLength, void *data, XsSize *length=nullptr)
	Read data from the serial port and put it into the data buffer. More...
XsResultValue	waitForData (XsSize maxLength, void *data, XsSize *length=nullptr)
	Wait for data to arrive or a timeout to occur. More...
void	getPortName (XsString &portname) const
	Retrieve the port name that was last successfully opened. More...
virtual XsResultValue	waitForData (XsSize maxLength, XsByteArray &data)
	Wait for data to arrive or a timeout to occur. More...
virtual XsResultValue	open (const XsString &filename, bool createNew, bool readOnly)
	Open a file. More...
virtual XsResultValue	waitForData (XsSize maxLength, XsByteArray &data)
	Wait for data to arrive or a timeout to occur. More...
virtual void	cancelIo (void) const
	Cancel any pending io requests. More...
virtual XsResultValue	appendData (const XsByteArray &bdata)
	Write data to the end of the file. More...
virtual XsResultValue	closeAndDelete (void)
	Close the file and delete it. More...
virtual XsResultValue	create (const XsString &filename)
	Create an empty file. More...
virtual XsResultValue	deleteData (XsFilePos start, XsSize length)
	Delete the given data from the file. More...
virtual XsResultValue	find (const XsByteArray &needleV, XsFilePos &pos)
	Find a string of bytes in the file. More...
virtual XsFilePos	getFileSize (void) const
	Return the size of the file. More...
virtual XsResultValue	getName (XsString &filename) const
	Retrieve the filename that was last successfully opened. More...
virtual XsFilePos	getReadPosition (void) const
	Return the current read position. More...
virtual XsFilePos	getWritePosition (void) const
	Return the current write position. More...
virtual XsResultValue	insertData (XsFilePos start, const XsByteArray &data)
	Insert the given data into the file. More...
virtual bool	isReadOnly (void) const
	Return whether the file is readonly or not. More...
virtual XsResultValue	setReadPosition (XsFilePos pos)
	Set the new absolute read position. More...
virtual XsResultValue	setWritePosition (XsFilePos pos=-1)
	Set the new absolute write position. More...

Private Attributes
UsbInterfacePrivate *	d

Constructor & Destructor Documentation

UsbInterface()

UsbInterface::UsbInterface

(

)

Default constructor, initializes all members to their default values.

Definition at line 406 of file usbinterface.cpp.

References d, FALSE, UsbInterfacePrivate::m_dataInEndPoint, UsbInterfacePrivate::m_dataOutEndPoint, UsbInterfacePrivate::m_deviceHandle, UsbInterfacePrivate::m_endTime, UsbInterfacePrivate::m_lastResult, UsbInterfacePrivate::m_portname, UsbInterfacePrivate::m_timeout, TRUE, and XRV_OK.

~UsbInterface()

UsbInterface::~UsbInterface

(

)

Destructor, de-initializes, frees memory allocated for buffers, etc.

Definition at line 437 of file usbinterface.cpp.

References closeUsb(), and d.

Member Function Documentation

appendData()

XsResultValue IoInterface::appendData ( const XsByteArray &  bdata )

virtualinherited

Write data to the end of the file.

The function writes the given data to the file at the end. The current write position is also moved to the end of the file.

Parameters

bdata

The byte data to append to the file

Returns

XRV_OK if the write was successful

Reimplemented in IoInterfaceFile.

Definition at line 77 of file iointerface.cpp.

References void(), and XRV_INVALIDOPERATION.

cancelIo()

void IoInterface::cancelIo ( void  ) const

virtualinherited

Cancel any pending io requests.

Reimplemented in SerialInterface.

Definition at line 74 of file iointerface.cpp.

close()

XsResultValue UsbInterface::close ( void  )

virtual

Close the USB communication port.

Implements IoInterface.

Definition at line 457 of file usbinterface.cpp.

References closeUsb().

closeAndDelete()

XsResultValue IoInterface::closeAndDelete ( void  )

virtualinherited

Close the file and delete it.

Returns

XRV_OK if the file was closed and deleted successfully

Reimplemented in IoInterfaceFile.

Definition at line 83 of file iointerface.cpp.

References XRV_INVALIDOPERATION.

closeUsb()

XsResultValue UsbInterface::closeUsb

(

void

)

Close the USB communication port.

Returns

XRV_OK if the port was closed successfully

Note

Linux:
If a kernel driver was detached when communication with the device started, attach it again. No guarantee is given that udev will pick up on it though.

Definition at line 464 of file usbinterface.cpp.

References XsLibUsb::attach_kernel_driver, XsLibUsb::close, d, mrpt::system::os::fclose(), flushData(), XsLibUsb::get_device, UsbInterfacePrivate::getContextManager(), isOpen(), UsbInterfacePrivate::m_dataInEndPoint, UsbInterfacePrivate::m_dataOutEndPoint, UsbInterfacePrivate::m_deviceHandle, UsbInterfacePrivate::m_endTime, UsbInterfacePrivate::m_interface, UsbInterfacePrivate::m_interfaceCount, UsbInterfacePrivate::m_lastResult, UsbInterfacePrivate::UsbContext::m_libUsb, xsens::msleep(), XsLibUsb::release_interface, XsLibUsb::unref_device, XRV_NOPORTOPEN, and XRV_OK.

Referenced by close(), and ~UsbInterface().

create()

XsResultValue IoInterface::create ( const XsString &  filename )

virtualinherited

Create an empty file.

Parameters

filename

The desired (path+)name of the file

Returns

XRV_OK if the file was created successfully

Reimplemented in IoInterfaceFile.

Definition at line 85 of file iointerface.cpp.

References void(), and XRV_INVALIDOPERATION.

deleteData()

XsResultValue IoInterface::deleteData ( XsFilePos  start, XsSize  length  )

virtualinherited

Delete the given data from the file.

The function erases the given data from the file at the given write position. This operation may take a while to complete, but is faster than insertData.

The write position is not changed and the read position is checked for validity upon function exit.

Parameters

start	The offset of the first byte to delete
length	The total number of bytes to delete

Returns

XRV_OK if the data was deleted successfully

Reimplemented in IoInterfaceFile.

Definition at line 91 of file iointerface.cpp.

References void(), and XRV_INVALIDOPERATION.

find()

XsResultValue IoInterface::find ( const XsByteArray &  needleV, XsFilePos &  pos  )

virtualinherited

Find a string of bytes in the file.

The function searches from the current read position until the given needle is found. If the needle is not found, XsResultValue::NOT_FOUND is returned. The function will update the seek position to the first character of the found needle.

Parameters

needleV	The byte string to find.
pos	The position where needleV was found. This will point to the first character of the found needleV.

Returns

XRV_OK if the data was found, XRV_ENDOFFILE if it wasn't found

Reimplemented in IoInterfaceFile.

Definition at line 98 of file iointerface.cpp.

References void(), and XRV_INVALIDOPERATION.

flushData()

XsResultValue UsbInterface::flushData ( void  )

virtual

Flush all data in the buffers to and from the device.

Returns

XRV_OK if the data was flushed successfully

Implements IoInterface.

Definition at line 538 of file usbinterface.cpp.

References d, UsbInterfacePrivate::getContextManager(), UsbInterfacePrivate::m_dataInEndPoint, UsbInterfacePrivate::m_deviceHandle, UsbInterfacePrivate::m_endTime, UsbInterfacePrivate::m_lastResult, and XRV_OK.

Referenced by closeUsb(), and open().

getFileSize()

XsFilePos IoInterface::getFileSize ( void  ) const

virtualinherited

Return the size of the file.

Returns

The size of the file.

Reimplemented in IoInterfaceFile.

Definition at line 105 of file iointerface.cpp.

getLastResult()

XsResultValue UsbInterface::getLastResult ( void  ) const

virtual

Return the error code of the last operation.

Implements IoInterface.

Definition at line 574 of file usbinterface.cpp.

References d, and UsbInterfacePrivate::m_lastResult.

getName()

XsResultValue IoInterface::getName ( XsString &  filename ) const

virtualinherited

Retrieve the filename that was last successfully opened.

\param filename     The XsString which will contain the filename.
\returns XRV_OK

Reimplemented in IoInterfaceFile.

Definition at line 107 of file iointerface.cpp.

References void(), and XRV_INVALIDOPERATION.

getPortName()

void UsbInterface::getPortName

(

XsString &

portname

)

const

Retrieve the port name that was last successfully opened.

Definition at line 1188 of file usbinterface.cpp.

References d, and UsbInterfacePrivate::m_portname.

getRawIo()

bool UsbInterface::getRawIo

(

void

)

Retrieves the state of the RAWIO mode of the USB interface.

Returns

true if raw IO mode is enabled

Note

Only applies to WinUSB implementations

Definition at line 1012 of file usbinterface.cpp.

References d.

getReadPosition()

XsFilePos IoInterface::getReadPosition ( void  ) const

virtualinherited

Return the current read position.

Returns

The current read position.

Reimplemented in IoInterfaceFile.

Definition at line 113 of file iointerface.cpp.

getTimeout()

uint32_t UsbInterface::getTimeout ( void  ) const

virtual

Return the current timeout value.

Implements StreamInterface.

Definition at line 580 of file usbinterface.cpp.

References d, and UsbInterfacePrivate::m_timeout.

getWritePosition()

XsFilePos IoInterface::getWritePosition ( void  ) const

virtualinherited

Return the current write position.

Returns

The current write position.

Reimplemented in IoInterfaceFile.

Definition at line 115 of file iointerface.cpp.

insertData()

XsResultValue IoInterface::insertData ( XsFilePos  start, const XsByteArray &  data  )

virtualinherited

Insert the given data into the file.

The function writes the given data to the file at the current write position. This operation may take a while to complete.

The write position is placed at the end of the inserted data.

Parameters

start	The offset in the file to write the first byte
data	The data to insert in the file

Returns

XRV_OK if the data was inserted successfully

Reimplemented in IoInterfaceFile.

Definition at line 117 of file iointerface.cpp.

References void(), and XRV_INVALIDOPERATION.

isOpen()

bool UsbInterface::isOpen ( void  ) const

virtual

Return whether the USB communication port is open or not.

Implements IoInterface.

Definition at line 582 of file usbinterface.cpp.

References d, and UsbInterfacePrivate::m_deviceHandle.

Referenced by closeUsb(), open(), readData(), and writeData().

isReadOnly()

bool IoInterface::isReadOnly ( void  ) const

virtualinherited

Return whether the file is readonly or not.

Returns

true if the file is readonly

Reimplemented in IoInterfaceFile.

Definition at line 124 of file iointerface.cpp.

open() [1/2]

XsResultValue UsbInterface::open ( const XsPortInfo &  portInfo, uint32_t  readBufSize = 0, uint32_t  writeBufSize = 0  )

virtual

Open a communication channel to the given USB port name.

Reimplemented from IoInterface.

Definition at line 584 of file usbinterface.cpp.

References XsLibUsb::attach_kernel_driver, XsLibUsb::claim_interface, XsLibUsb::close, d, XsLibUsb::detach_kernel_driver, FALSE, flushData(), XsLibUsb::free_config_descriptor, XsLibUsb::free_device_list, XsLibUsb::get_active_config_descriptor, XsLibUsb::get_device_address, XsLibUsb::get_device_descriptor, XsLibUsb::get_device_list, UsbInterfacePrivate::getContextManager(), isOpen(), JLALERT, JLDEBUG, XsLibUsb::kernel_driver_active, UsbInterfacePrivate::libusbErrorToXrv(), UsbInterfacePrivate::m_dataInEndPoint, UsbInterfacePrivate::m_dataOutEndPoint, UsbInterfacePrivate::m_deviceHandle, UsbInterfacePrivate::m_endTime, UsbInterfacePrivate::m_interface, UsbInterfacePrivate::m_interfaceCount, UsbInterfacePrivate::m_lastResult, UsbInterfacePrivate::UsbContext::m_libUsb, UsbInterfacePrivate::m_portname, XsLibUsb::open, XsLibUsb::ref_device, XsLibUsb::release_interface, setTimeout(), mrpt::system::os::sprintf(), XsLibUsb::unref_device, XRV_ALREADYOPEN, XRV_ERROR, XRV_INPUTCANNOTBEOPENED, XRV_OK, XRV_PORTNOTFOUND, XSENS_INVALID_THREAD, XsPortInfo_usbAddress(), XsPortInfo_usbBus(), and xsStartThread.

open() [2/2]

XsResultValue IoInterface::open ( const XsString &  filename, bool  createNew, bool  readOnly  )

virtualinherited

Open a file.

Parameters

filename	The name of the file to open
createNew	When true, the file will be created if it doesn't exist yet
readOnly	When true, the file will be marked as read only for IoInterfaceFile, preventing accidental writes to the file.

Returns

XRV_OK if the file was opened successfully

See also

createFile

Reimplemented in IoInterfaceFile.

Definition at line 126 of file iointerface.cpp.

References void(), and XRV_INVALIDOPERATION.

readData() [1/2]

XsResultValue UsbInterface::readData	(	XsSize	maxLength,
		void *	data,
		XsSize *	length = nullptr
	)

Read data from the serial port and put it into the data buffer.

This function reads up to maxLength bytes from the USB port (non-blocking) and puts it into the data buffer.

Parameters

maxLength	The maximum number of bytes to read.
data	Pointer to a buffer that will store the received data.
length	The number of bytes placed into data.

Returns

XRV_OK if no error occurred. It can be that no data is available and XRV_OK will be returned. Check *length for the number of bytes that were read.

Definition at line 891 of file usbinterface.cpp.

References XsLibUsb::bulk_transfer, d, mrpt::system::os::fopen(), UsbInterfacePrivate::getContextManager(), isOpen(), JLTRACE, UsbInterfacePrivate::libusbErrorToString(), UsbInterfacePrivate::libusbErrorToXrv(), UsbInterfacePrivate::m_dataInEndPoint, UsbInterfacePrivate::m_deviceHandle, UsbInterfacePrivate::m_lastResult, UsbInterfacePrivate::UsbContext::m_libUsb, UsbInterfacePrivate::m_timeout, mrpt::system::os::memcpy(), mrpt::system::os::sprintf(), usbAddress(), usbBus(), XRV_NOPORTOPEN, XRV_OK, and XS_MAX_FILENAME_LENGTH.

readData() [2/2]

XsResultValue UsbInterface::readData ( XsSize  maxLength, XsByteArray &  data  )

virtual

Read data from the USB port and put it into the data buffer.

This function reads up to maxLength bytes from the port (non-blocking) and puts it into the data buffer.

Parameters

maxLength	The maximum amount of data read.
data	The buffer that will store the received data.

Returns

XRV_OK if no error occurred. It can be that no data is available and XRV_OK will be returned. Check data.size() for the number of bytes that were read.

Implements IoInterface.

Definition at line 871 of file usbinterface.cpp.

Referenced by waitForData().

setRawIo()

void UsbInterface::setRawIo

(

bool

enable

)

Sets the RAWIO mode of the USB interface.

Note

Only applies to WinUSB implementations

Parameters

enable

: If true will enable RAW IO mode

Definition at line 992 of file usbinterface.cpp.

References d, JLDEBUG, UsbInterfacePrivate::m_lastResult, void(), and XRV_OK.

setReadPosition()

XsResultValue IoInterface::setReadPosition ( XsFilePos  pos )

virtualinherited

Set the new absolute read position.

The read position is checked against the filesize first.

Parameters

pos	The new read position

Returns

XRV_OK if the read position was updated successfully

Reimplemented in IoInterfaceFile.

Definition at line 135 of file iointerface.cpp.

References void(), and XRV_INVALIDOPERATION.

setTimeout()

XsResultValue UsbInterface::setTimeout ( uint32_t  ms )

virtual

Set the default timeout value to use in blocking operations.

This function sets the value of m_timeout. There is no infinity value. The value 0 means that the default value is used.

Parameters

ms	The desired timeout in milliseconds

Returns

XRV_OK if the timeout value was successfully updated

Implements StreamInterface.

Definition at line 961 of file usbinterface.cpp.

References d, FALSE, JLDEBUG, UsbInterfacePrivate::m_lastResult, UsbInterfacePrivate::m_timeout, and XRV_OK.

Referenced by open().

setWritePosition()

XsResultValue IoInterface::setWritePosition ( XsFilePos  pos = -1 )

virtualinherited

Set the new absolute write position.

The write position is checked against the filesize first.

Parameters

pos	The new write position

Returns

XRV_OK if the write position was updated successfully

Reimplemented in IoInterfaceFile.

Definition at line 141 of file iointerface.cpp.

References void(), and XRV_INVALIDOPERATION.

usbAddress()

uint8_t UsbInterface::usbAddress

(

)

const

The address of the device (libusb/linux only)

Definition at line 1172 of file usbinterface.cpp.

References d, XsLibUsb::get_device, XsLibUsb::get_device_address, UsbInterfacePrivate::getContextManager(), UsbInterfacePrivate::m_deviceHandle, and UsbInterfacePrivate::UsbContext::m_libUsb.

Referenced by readData(), and writeData().

usbBus()

uint8_t UsbInterface::usbBus

(

)

const

The USB bus number this device is on (libusb/linux only)

Definition at line 1156 of file usbinterface.cpp.

References d, XsLibUsb::get_bus_number, XsLibUsb::get_device, UsbInterfacePrivate::getContextManager(), UsbInterfacePrivate::m_deviceHandle, and UsbInterfacePrivate::UsbContext::m_libUsb.

Referenced by readData(), and writeData().

waitForData() [1/3]

XsResultValue UsbInterface::waitForData	(	XsSize	maxLength,
		void *	data,
		XsSize *	length = nullptr
	)

Wait for data to arrive or a timeout to occur.

The function waits until maxLength data is available or until a timeout occurs. The function returns success if data is available or XsResultValue::TIMEOUT if a timeout occurred. A timeout value of 0 indicates that the default timeout stored in the class should be used.

Parameters

maxLength	The maximum number of bytes to wait for
data	A buffer that will be filled with the read data. It must be able to contain at least maxLength bytes.
length	An optional pointer to storage for the actual number of bytes read.

Returns

XRV_OK if the requested data was read

Definition at line 1042 of file usbinterface.cpp.

References d, xsens::getTimeOfDay(), JLTRACE, UsbInterfacePrivate::m_lastResult, UsbInterfacePrivate::m_timeout, readData(), XRV_OK, and XRV_TIMEOUT.

waitForData() [2/3]

XsResultValue IoInterface::waitForData

Wait for data to arrive or a timeout to occur.

The function waits until maxLength data is available or until a timeout occurs. The function returns success if data is available or XsResultValue::TIMEOUT if a timeout occurred. A timeout value of 0 indicates that the default timeout stored in the class should be used.

Parameters

maxLength	The maximum number of bytes to read before returning
data	The buffer to put the read data in.

Returns

XRV_OK if maxLength bytes were read, XRV_TIMEOUT if less was read, XRV_TIMEOUTNODATA if nothing was read

Definition at line 67 of file iointerface.cpp.

waitForData() [3/3]

XsResultValue IoInterface::waitForData ( XsSize  maxLength, XsByteArray &  data  )

virtualinherited

Wait for data to arrive or a timeout to occur.

The function waits until maxLength data is available or until a timeout occurs. The function returns success if data is available or XsResultValue::TIMEOUT if a timeout occurred. A timeout value of 0 indicates that the default timeout stored in the class should be used.

Parameters

maxLength	The maximum number of bytes to read before returning
data	The buffer to put the read data in.

Returns

XRV_OK if maxLength bytes were read, XRV_TIMEOUT if less was read, XRV_TIMEOUTNODATA if nothing was read

Reimplemented in SerialInterface.

Definition at line 67 of file iointerface.cpp.

References void(), and XRV_INVALIDOPERATION.

writeData() [1/2]

XsResultValue UsbInterface::writeData ( const XsByteArray &  data, XsSize *  written = nullptr  )

virtual

Write the data to the USB port.

The function writes the given data to the connected USB port. The default timeout is respected in this operation.

Parameters

data	The data to be written
written	An optional pointer to storage for the actual number of bytes that were written

Returns

XRV_OK if the data was successfully written

See also

writeData(const XsSize, const void *, XsSize*)

Implements IoInterface.

Definition at line 1081 of file usbinterface.cpp.

writeData() [2/2]

XsResultValue UsbInterface::writeData	(	XsSize	length,
		const void *	data,
		XsSize *	written = nullptr
	)

Write the data to the USB port.

The function writes the given data to the connected USB port. The default timeout is respected in this operation.

Parameters

length	The number of bytes to write.
data	A pointer to a memory buffer that contains the bytes to send
written	An optional pointer to storage for the actual number of bytes that were written

Returns

XRV_OK if the data was successfully written

See also

writeData(const XsByteArray&, XsSize*)

Definition at line 1096 of file usbinterface.cpp.

References XsLibUsb::bulk_transfer, d, mrpt::system::os::fopen(), UsbInterfacePrivate::getContextManager(), isOpen(), JLALERT, UsbInterfacePrivate::libusbErrorToString(), UsbInterfacePrivate::libusbErrorToXrv(), UsbInterfacePrivate::m_dataOutEndPoint, UsbInterfacePrivate::m_deviceHandle, UsbInterfacePrivate::m_lastResult, UsbInterfacePrivate::UsbContext::m_libUsb, mrpt::system::os::sprintf(), usbAddress(), usbBus(), XRV_NOPORTOPEN, XRV_OK, and XS_MAX_FILENAME_LENGTH.

Member Data Documentation

d

UsbInterfacePrivate* UsbInterface::d

private

Definition at line 78 of file usbinterface.h.

Referenced by closeUsb(), flushData(), getLastResult(), getPortName(), getRawIo(), getTimeout(), isOpen(), open(), readData(), setRawIo(), setTimeout(), usbAddress(), usbBus(), UsbInterface(), waitForData(), writeData(), and ~UsbInterface().