EasyUSB::Device Class Reference

Represents a USB Device. More...

Inheritance diagram for EasyUSB::Device:

Public Member Functions
void	Close ()
	Closes the device.
void	CyclePort ()
	Power cycles the USB port the device is attached to.
	Device ()
	Default constructor.
char	GetConfiguration ()
	Gets the current configuration ID.
Descriptors::Configuration	GetConfigurationDescriptor ()
	Gets the configuration descriptor of the current configuration.
Descriptors::Configuration	GetConfigurationDescriptor (unsigned char ConfigID)
	Gets a configuration descriptor.
Descriptors::Device	GetDeviceDescriptor ()
	Gets the USB device descriptor.
std::wstring	GetDevicePath ()
	Gets the unique device path.
Endpoint *	GetEndpoint (unsigned char InterfaceID, unsigned char Index)
	Gets a configured endpoint.
Endpoint *	GetEndpoint (unsigned char Address)
	Gets a configured endpoint.
Descriptors::Endpoint	GetEndpointDescriptor (unsigned char InterfaceID, unsigned char EndpointID)
	Gets an endpoint descriptor.
Descriptors::Endpoint	GetEndpointDescriptor (unsigned char InterfaceID, unsigned char SettingID, unsigned char EndpointID)
	Gets an endpoint descriptor.
Descriptors::Interface	GetInterfaceDescriptor (unsigned char InterfaceID)
	Gets an interface descriptor.
Descriptors::Interface	GetInterfaceDescriptor (unsigned char InterfaceID, unsigned char SettingID)
	Gets an interface descriptor.
std::vector< unsigned short >	GetLangIDs ()
	Gets a list of all available languages.
char	GetSetting (unsigned char InterfaceID)
	Gets the current setting of an interface.
std::wstring	GetString (unsigned char StringID, unsigned short LangID=0x0409)
	Gets a unicode string from the device.
unsigned char	NumConfigurations () throw (Errors::DeviceNotAvailable)
	Gets the number of avaiable USB configurations.
unsigned char	NumEndpointsActive ()
	Retrieves the number of active (that means selected) endpoints.
unsigned char	NumSettings (unsigned char InterfaceID)
	Gets the number of settings available for an interface.
bool	Open (unsigned short Index)
	Tries to open a USB device connected to the system.
bool	Restore ()
	Tries to restore the USB device to full functionality.
void	SetConfiguration (unsigned char ConfigID) throw (Errors::InvalidParameter, Errors::IOError, Errors::ResourceError)
	Sets the current configuration.
void	SetSetting (unsigned char InterfaceID, unsigned char SettingID)
	Sets a new active setting on an interface.
bool	Validate ()
	Checks every endpoint and validates the device.
	~Device ()
	Default destructor.
Protected Attributes
Descriptors::Device	m_DeviceDescriptor
	The USB device descriptor.

---

Detailed Description

Represents a USB Device.

---

Constructor & Destructor Documentation

EasyUSB::Device::Device

(

)

Default constructor.

EasyUSB::Device::~Device

(

)

Default destructor.

---

Member Function Documentation

void EasyUSB::Device::Close

(

)

Closes the device.

Note:

This function does the following:

• Cancel all outstanding AsyncIO transfers (Callbacks are used).
• Destroy all endpoints.
• Disconnect from the driver.

void EasyUSB::Device::CyclePort

(

)

Power cycles the USB port the device is attached to.

Exceptions:

FileNotFound

The device could not be found 1 second after cycling the port.

Note:

All endpoints are deleted and with them all AsyncIO objects. After power cycling the device is reset to configuration 1.

char EasyUSB::Device::GetConfiguration

(

)

Gets the current configuration ID.

Returns:

Configuration ID.

Descriptors::Configuration EasyUSB::Device::GetConfigurationDescriptor

(

)

Gets the configuration descriptor of the current configuration.

Returns:

A Configuration structure containing the descriptor.

Exceptions:

	-	All exceptions thrown by SendIOCTL.
	NotEnoughMemory	Not enough memory to complete this operation.

Descriptors::Configuration EasyUSB::Device::GetConfigurationDescriptor

(

unsigned char

ConfigID

)

Gets a configuration descriptor.

Parameters:

ConfigID

The configuration index usually starting with 1.

Returns:

A Configuration structure containing the descriptor.

Exceptions:

	-	All exceptions thrown by SendIOCTL.
	NotEnoughMemory	Not enough memory to complete this operation.

Descriptors::Device EasyUSB::Device::GetDeviceDescriptor

(

)

Gets the USB device descriptor.

Returns:

A Device structure containing the descriptor.

std::wstring EasyUSB::Device::GetDevicePath

(

)

Gets the unique device path.

Returns:

The device path.

Note:

This path is used to identify the USB device in the windows device tree.

Endpoint* EasyUSB::Device::GetEndpoint	(	unsigned char	InterfaceID,
		unsigned char	Index
	)

Gets a configured endpoint.

Parameters:

	InterfaceID	The parent interface of the endpoint.
	Index	The index of the endpoint in the list of all endpoints of the specific interface.

Returns:

A pointer to an Endpoint.

Endpoint* EasyUSB::Device::GetEndpoint

(

unsigned char

Address

)

Gets a configured endpoint.

Parameters:

Address

The endpoint address.

Returns:

A pointer to an Endpoint.

Descriptors::Endpoint EasyUSB::Device::GetEndpointDescriptor	(	unsigned char	InterfaceID,
		unsigned char	EndpointID
	)

Gets an endpoint descriptor.

Parameters:

	InterfaceID	The requested interface.
	EndpointID	The requested endpoint index.

Returns:

A Endpoint structure containing the descriptor.

Exceptions:

-

All exceptions thrown by SendIOCTL.

Note:

This function uses the current setting.

Descriptors::Endpoint EasyUSB::Device::GetEndpointDescriptor	(	unsigned char	InterfaceID,
		unsigned char	SettingID,
		unsigned char	EndpointID
	)

Gets an endpoint descriptor.

Parameters:

	InterfaceID	The requested interface.
	SettingID	The requested alternate setting.
	EndpointID	The requested endpoint index.

Returns:

A Endpoint structure containing the descriptor.

Exceptions:

-

All exceptions thrown by SendIOCTL.

Note:

If SettingID != CurrentSetting you cannot execute any IO operations on the returned endpoint. Control operations can be used.

Descriptors::Interface EasyUSB::Device::GetInterfaceDescriptor

(

unsigned char

InterfaceID

)

Gets an interface descriptor.

Parameters:

InterfaceID

The requested interface starting with 0.

Returns:

A Interface structure containing the descriptor.

Exceptions:

-

All exceptions thrown by SendIOCTL.

Note:

The alternate setting ID is set to 0.

Descriptors::Interface EasyUSB::Device::GetInterfaceDescriptor	(	unsigned char	InterfaceID,
		unsigned char	SettingID
	)

Gets an interface descriptor.

Parameters:

	InterfaceID	The requested interface starting with 0.
	SettingID	The requested alternate setting ID starting with 0.

Returns:

A Interface structure containing the descriptor.

Exceptions:

-

All exceptions thrown by SendIOCTL.

std::vector<unsigned short> EasyUSB::Device::GetLangIDs

(

)

Gets a list of all available languages.

Returns:

A vector containing the usb language ids.

char EasyUSB::Device::GetSetting

(

unsigned char

InterfaceID

)

Gets the current setting of an interface.

Parameters:

InterfaceID

The interface to retrieve the setting from.

Returns:

The current setting,

Exceptions:

InvalidParameter

The interface ID was invalid.

std::wstring EasyUSB::Device::GetString	(	unsigned char	StringID,
		unsigned short	LangID = 0x0409
	)

Gets a unicode string from the device.

Parameters:

	StringID	The string ID to be retrieved. These IDs can be found in various USB descriptors.
	LangID	The language of the returned string. Default is 0x0409 English (USA).

Returns:

A unicode string.

Exceptions:

	-	All exceptions thrown by SendIOCTL.
	NotEnoughMemory	Not enough memory to complete this operation.

unsigned char EasyUSB::Device::NumConfigurations

(

)

throw (Errors::DeviceNotAvailable)

Gets the number of avaiable USB configurations.

Returns:

The number of configurations.

Exceptions:

DeviceNotAvailable

The device is not conencted.

unsigned char EasyUSB::Device::NumEndpointsActive

(

)

Retrieves the number of active (that means selected) endpoints.

Returns:

The number of active endpoints.

unsigned char EasyUSB::Device::NumSettings

(

unsigned char

InterfaceID

)

Gets the number of settings available for an interface.

Parameters:

InterfaceID

The interface to get the information from.

Returns:

The number of settings.

Exceptions:

	-	All exceptions thrown by SendIOCTL.
	InvalidParameter	An invalid parameter was specified.

bool EasyUSB::Device::Open

(

unsigned short

Index

)

Tries to open a USB device connected to the system.

Parameters:

Index

The device index if multiple EasyUSB devices are connected to the system.

Returns:

true if the device was successfully opened, false if the device could not be found.

Exceptions:

	-	Every exception thrown by SendIOCTL.
	ResourceError	The control endpoint could not be found.
	NotEnoughMemory	Not enough memory for internal functions.

bool EasyUSB::Device::Restore

(

)

Tries to restore the USB device to full functionality.

Returns:

true if the device was fully restored.

Note:

If this function fails the device state is undefined and you should close it.

void EasyUSB::Device::SetConfiguration

(

unsigned char

ConfigID

)

throw (Errors::InvalidParameter, Errors::IOError, Errors::ResourceError)

Sets the current configuration.

Parameters:

ConfigID

The new configuration to load.

Exceptions:

	-	All exceptions thrown by SendIOCTL.
	InvalidParameter	An invalid parameter was specified.
	NotEnoughMemory	Not enough memory to complete this operation.

Note:

All endpoints and their data will become invalid. If this function fails, the device handle will be valid, but no endpoints are available. You should then try to restore the device with Restore().

void EasyUSB::Device::SetSetting	(	unsigned char	InterfaceID,
		unsigned char	SettingID
	)

Sets a new active setting on an interface.

Parameters:

	InterfaceID	The interface to manipulate.
	SettingID	The new setting.

Exceptions:

	-	All exceptions thrown by SendIOCTL.
	InvalidParameter	An invalid parameter was specified.
	NotEnoughMemory	Not enough memory to complete this operation.

Note:

If this function fails with an exception other then InvalidParameter the device is in an undefined state and you should use Restore().

bool EasyUSB::Device::Validate

(

)

Checks every endpoint and validates the device.

Returns:

true if all endpoint are valid. false if the device is no longer connected.

Note:

If this function fails the device state is undefined and you should close it.

---

Field Documentation

Descriptors::Device EasyUSB::Device::m_DeviceDescriptor [protected]

The USB device descriptor.