AIOUSB::USBDeviceManager Class Reference

#include <USBDeviceManager.hpp>

Collaboration diagram for AIOUSB::USBDeviceManager:

Collaboration graph
[legend]

List of all members.

Public Member Functions

 USBDeviceManager ()
virtual ~USBDeviceManager ()
virtual std::ostream & print (std::ostream &out)
USBDeviceManagerprintDevices ()
std::string getAIOUSBVersion () const
std::string getAIOUSBVersionDate () const
void listDevices () const
bool isOpen () const
USBDeviceManageropen ()
USBDeviceManagerclose ()
USBDeviceManagerscanForDevices ()
USBDeviceArray getDeviceByProductID (int productID) const
USBDeviceArray getDeviceByProductID (int minProductID, int maxProductID) const
USBDeviceArray getDeviceByProductID (const IntArray &productIDs) const
USBDeviceArray getDeviceBySerialNumber (__uint64_t serialNumber) const

Static Public Member Functions

static std::string productIDToName (int productID)
static StringArray productIDToName (const IntArray &productID)
static int productNameToID (const std::string &productName)
static IntArray productNameToID (const StringArray &productName)
static std::string getResultCodeAsString (int result)

Static Public Attributes

static const std::string VERSION_NUMBER = "1.8"
static const std::string VERSION_DATE = "18 January 2010"
static const int MIN_PRODUCT_ID = 0
static const int MAX_PRODUCT_ID = 0xffff

Protected Member Functions

void emptyDeviceList ()

Protected Attributes

USBDeviceArray deviceList
unsigned long openStatus

Static Protected Attributes

static const unsigned long OPEN_PATTERN = 0x786938f5
static const std::string MESSAGE_NOT_OPEN = "Not open, must call open() first"


Detailed Description

Class USBDeviceManager manages all the USB devices on the bus. It scans the bus and builds a list of all the devices found. It also initializes and terminates use of the underlying AIOUSB module.

Constructor & Destructor Documentation

AIOUSB::USBDeviceManager::USBDeviceManager (  ) 

AIOUSB::USBDeviceManager::~USBDeviceManager (  )  [virtual]


Member Function Documentation

USBDeviceManager & AIOUSB::USBDeviceManager::close (  ) 

"Closes" the USB device manager for use. When finished using the USB device manager, and assuming open() was properly called, close() must be called. Close() terminates use of the underlying AIOUSB module and discards the list of devices found. You must terminate use of all USB devices before calling close()! You can call open() again to reinitialize things and reestablish connections to USB devices.

Returns:
This device manager, useful for chaining together multiple operations.
Exceptions:
OperationFailedException 

void AIOUSB::USBDeviceManager::emptyDeviceList (  )  [protected]

std::string AIOUSB::USBDeviceManager::getAIOUSBVersion (  )  const [inline]

Gets the version number of the underlying AIOUSB module.

Returns:
The AIOUSB module version number as a string with the form, "1.78".

std::string AIOUSB::USBDeviceManager::getAIOUSBVersionDate (  )  const [inline]

Gets the version date of the underlying AIOUSB module.

Returns:
The AIOUSB module version date as a string with the form, "15 November 2009".

USBDeviceArray AIOUSB::USBDeviceManager::getDeviceByProductID ( const IntArray productIDs  )  const

Gets a list of all the devices found on the bus matching the specified set of product IDs. Any device with a product ID equal to one of the products listed in productIDs[] will be returned.

Parameters:
productIDs an array containing one or more product IDs to search for.
Returns:
An array of all the devices found. If no devices were found matching the specified set of product IDs, the array will be empty (i.e. contain zero items).
Exceptions:
IllegalArgumentException 

USBDeviceArray AIOUSB::USBDeviceManager::getDeviceByProductID ( int  minProductID,
int  maxProductID 
) const

Gets a list of all the devices found on the bus matching the specified product ID range. Any device with a product ID greater than or equal to minProductID and less than or equal to maxProductID will be returned. You can obtain the entire list of devices detected by passing a value of 0 for minProductID and a value of 0xffff for maxProductID. Then you can search the list obtained using your own search criteria.

Parameters:
minProductID the minimum product ID to search for.
maxProductID the maximum product ID to search for.
Returns:
An array of all the devices found. If no devices were found matching the specified product ID range, the array will be empty (i.e. contain zero items).
Exceptions:
IllegalArgumentException 

USBDeviceArray AIOUSB::USBDeviceManager::getDeviceByProductID ( int  productID  )  const

Gets a list of all the devices found on the bus matching the specified product ID. Only devices exactly matching the specified product ID will be returned. You can search for devices by product name using productNameToID( const std::string &productName ), like so:

USBDeviceArray devices = deviceManager.getDeviceByProductID( deviceManager.productNameToID( "USB-CTR-15" ) );
Parameters:
productID the product ID to search for.
Returns:
An array of all the devices found. If no devices were found matching the specified product ID, the array will be empty (i.e. contain zero items).

USBDeviceArray AIOUSB::USBDeviceManager::getDeviceBySerialNumber ( __uint64_t  serialNumber  )  const

Gets a list of all the devices found on the bus matching the specified serial number. Only devices exactly matching the specified serial number will be returned. In theory, there ought to be only one device matching a given serial number, but this method returns a vector in order to be consistent with the other search methods, and in unlikely event that multiple devices do share the same serial number.

Parameters:
serialNumber the serial number to search for.
Returns:
An array of all the devices found. If no devices were found matching the specified serial number, the array will be empty (i.e. contain zero items).

static std::string AIOUSB::USBDeviceManager::getResultCodeAsString ( int  result  )  [inline, static]

Gets the string representation of an AIOUSB result code, useful mainly for debugging purposes. This method is also used to convert an AIOUSB result code to a string when an OperationFailedException is thrown in response to an AIOUSB failure.

Although this method is static, an instance of USBDeviceManager must be created and be "open" for use before this method can be used. This stipulation is imposed because the underlying library must be initialized in order for result code lookups to succeed, and that initialization occurs only when an instance of USBDeviceManager is created and its open() method is called.

Parameters:
result an AIOUSB result code.
Returns:
The string representation of result.

bool AIOUSB::USBDeviceManager::isOpen (  )  const [inline]

Tells if the USB device manager has been "opened" for use (see open()).

Returns:
True indicates that the device manager is open and ready to be used; false indicates that it is not open.

void AIOUSB::USBDeviceManager::listDevices (  )  const [inline]

Prints the properties of all the devices found on the bus to the standard output device. This function is similar to printDevices() but is implemented by the underlying AIOUSB module and produces different output than printDevices(). Mainly useful for diagnostic purposes.

USBDeviceManager & AIOUSB::USBDeviceManager::open (  ) 

"Opens" the USB device manager for use. Before the USB device manager may be used, open() must be called. Open() initializes the underlying AIOUSB module and scans the bus for devices, building a list of the devices found. When finished using the USB device manager, close() must be called. It is possible to call close() and then call open() again, which effectively reinitializes everything.

Returns:
This device manager, useful for chaining together multiple operations.
Exceptions:
OperationFailedException 

ostream & AIOUSB::USBDeviceManager::print ( std::ostream &  out  )  [virtual]

Prints the properties of this device manager and all of the devices found on the bus to the specified print stream. Mainly useful for diagnostic purposes.

Parameters:
out the print stream where properties will be printed.
Returns:
The print stream.

USBDeviceManager & AIOUSB::USBDeviceManager::printDevices (  ) 

Prints the properties of this device manager and all of the devices found on the bus to the standard output device. Mainly useful for diagnostic purposes.

Returns:
This device manager, useful for chaining together multiple operations.
Exceptions:
OperationFailedException 

StringArray AIOUSB::USBDeviceManager::productIDToName ( const IntArray productID  )  [static]

Gets the product names for an array of product IDs. Functionally identical to productIDToName( int productID ) except that it operates on an array of product IDs rather than an individual product ID.

Although this method is static, an instance of USBDeviceManager must be created and be "open" for use before this method can be used. This stipulation is imposed because the underlying library must be initialized in order for product name/ID lookups to succeed, and that initialization occurs only when an instance of USBDeviceManager is created and its open() method is called.

Parameters:
productID an array of product IDs to translate to product names.
Returns:
An array of strings containing the product names, or "UNKNOWN" for any product ID that was not found. The product names are returned in the same order as the product IDs passed in productID[].
Exceptions:
IllegalArgumentException 

std::string AIOUSB::USBDeviceManager::productIDToName ( int  productID  )  [static]

Gets the product name for a product ID. This name is only "approximate," as an actual device reports its own name. Generally the names reported by the device are the same as those obtained from this method, but that is not guaranteed. This method provides a name that constitutes a user-friendly alternative to a product ID number. The complement of this method is productNameToID( const std::string &productName ).

Although this method is static, an instance of USBDeviceManager must be created and be "open" for use before this method can be used. This stipulation is imposed because the underlying library must be initialized in order for product name/ID lookups to succeed, and that initialization occurs only when an instance of USBDeviceManager is created and its open() method is called.

Parameters:
productID the product ID to translate to a product name.
Returns:
A string containing the product name, or "UNKNOWN" if the product ID was not found.
Exceptions:
IllegalArgumentException 

IntArray AIOUSB::USBDeviceManager::productNameToID ( const StringArray productName  )  [static]

Gets the product IDs for an array of product names. Functionally identical to productNameToID( const std::string &productName ) except that it operates on an array of product names rather than an individual product name.

Although this method is static, an instance of USBDeviceManager must be created and be "open" for use before this method can be used. This stipulation is imposed because the underlying library must be initialized in order for product name/ID lookups to succeed, and that initialization occurs only when an instance of USBDeviceManager is created and its open() method is called.

Parameters:
productName an array of product names to translate to product IDs.
Returns:
An array of integers containing the product IDs, or 0 (zero) for any product name that was not found. The product IDs are returned in the same order as the product names passed in productName[].
Exceptions:
IllegalArgumentException 

int AIOUSB::USBDeviceManager::productNameToID ( const std::string &  productName  )  [static]

Gets the product ID for a product name. This method is the complement of productIDToName( int productID ) and one should read the notes for that method. It is not guaranteed that productNameToID() will successfully ascertain the product ID for a name obtained from a device, although it usually will. ProductNameToID() will always successfully ascertain the product ID for a name obtained from productIDToName(). If one has access to a device and its name, then they should obtain the product ID from the device itself rather than from this method. This method is mainly for easily converting between product names and IDs, primarily to serve the needs of user interfaces.

Although this method is static, an instance of USBDeviceManager must be created and be "open" for use before this method can be used. This stipulation is imposed because the underlying library must be initialized in order for product name/ID lookups to succeed, and that initialization occurs only when an instance of USBDeviceManager is created and its open() method is called.

Parameters:
productName the product name to translate to a product ID.
Returns:
The product ID for the specified product name, or 0 (zero) if the name was not found.
Exceptions:
IllegalArgumentException 

USBDeviceManager & AIOUSB::USBDeviceManager::scanForDevices (  ) 

Re-scans the bus for devices. ScanForDevices() is called automatically by open(). You must terminate use of all USB devices before calling scanForDevices()! After calling scanForDevices() you can reestablish connections to USB devices.

Returns:
This device manager, useful for chaining together multiple operations.
Exceptions:
OperationFailedException 


Member Data Documentation

const int AIOUSB::USBDeviceManager::MAX_PRODUCT_ID = 0xffff [static]

const std::string AIOUSB::USBDeviceManager::MESSAGE_NOT_OPEN = "Not open, must call open() first" [static, protected]

const unsigned long AIOUSB::USBDeviceManager::OPEN_PATTERN = 0x786938f5 [static, protected]

unsigned long AIOUSB::USBDeviceManager::openStatus [protected]

const std::string AIOUSB::USBDeviceManager::VERSION_DATE = "18 January 2010" [static]

The version date of this Java class library.

const std::string AIOUSB::USBDeviceManager::VERSION_NUMBER = "1.8" [static]

The version number of this Java class library.


doxygen