// -*- C++;indent-tabs-mode: t; tab-width: 4; c-basic-offset: 4; -*- #ifndef __USBPP_HEADER__ #define __USBPP_HEADER__ #include <string> #include <list> #include <usb.h> /* * The following usb.h function is not wrapped yet: * char *usb_strerror(void); */ /** * \brief Classes to access Universal Serial Bus devices * * The USB Namespace provides a number of classes to work * with Universal Serial Bus (USB) devices attached to the * system. * * \author Brad Hards */ namespace USB { class Device; /** * \brief Class representing a device endpoint * * This class represents a device endpoint. You need this class to * perform bulk reads and writes. * */ class Endpoint { /** * Busses is a friend because it fills in the descriptor type * information on initialisation and rescan. */ friend class Busses; public: Endpoint() {}; #ifdef USE_UNTESTED_LIBUSBPP_METHODS /** * \brief Bulk write * * This method performs a bulk transfer to the endpoint. * * \param message is the message to be sent. * \param timeout is the USB transaction timeout in milliseconds * * \returns the number of bytes sent, or a negative value on * failure */ int bulkWrite(QByteArray message, int timeout = 100); /** * \brief Bulk read * * This method performs a bulk transfer from the endpoint. * * \param length is the maximum data transfer required. * \param message is the message that was received. * \param timeout is the USB transaction timeout in milliseconds * * \returns the number of bytes received, or a negative value on * failure */ int bulkRead(int length, unsigned char *message, int timeout = 100); /** * \brief Reset endpoint * * This method resets the endpoint. */ int reset(void); /** * \brief Clear halt * * This method clears a halt (stall) on the endpoint. */ int clearHalt(void); #endif /* USE_UNTESTED_LIBUSBPP_METHODS */ /** * \brief Endpoint descriptor information output * * This method dumps out the various characteristics * of the endpoint to standard output. * * It is mostly useful for debugging. */ void dumpDescriptor(void); private: void setDescriptor(struct usb_endpoint_descriptor); void setParent(Device *parent); u_int8_t m_Length; u_int8_t m_DescriptorType; u_int8_t m_EndpointAddress; u_int8_t m_Attributes; u_int16_t m_MaxPacketSize; u_int8_t m_Interval; u_int8_t m_Refresh; u_int8_t m_SynchAddress; Device *m_parent; }; class AltSetting : public std::list<Endpoint *> { /** * Busses is a friend because it fills in the descriptor type * information on initialisation and rescan. */ friend class Busses; public: AltSetting() {}; u_int8_t numEndpoints(void); /** * \brief AltSetting descriptor information output * * This method dumps out the various characteristics * of the alternate setting to standard output. * * It is mostly useful for debugging. */ void dumpDescriptor(void); Endpoint *firstEndpoint(void); Endpoint *nextEndpoint(void); Endpoint *lastEndpoint(void); private: std::list<Endpoint *>::const_iterator iter; void setDescriptor(struct usb_interface_descriptor); /* we don't use a normal usb_interface_descriptor */ /* because that would bring in the endpoint list */ u_int8_t m_Length; u_int8_t m_DescriptorType; u_int8_t m_InterfaceNumber; u_int8_t m_AlternateSetting; u_int8_t m_NumEndpoints; u_int8_t m_InterfaceClass; u_int8_t m_InterfaceSubClass; u_int8_t m_InterfaceProtocol; u_int8_t m_Interface; }; /** * \brief Class representing an interface of a Device * * The Interface class represents a USB interface * for a device attached to a Universal Serial Bus. * * Interfaces are the main element of the USB class * structure. * * \author Brad Hards */ class Interface : public std::list<AltSetting *> { /** * Busses is a friend because it fills in the descriptor type * information on initialisation and rescan. */ friend class Busses; public: Interface() {}; #ifdef LIBUSB_HAS_GET_DRIVER_NP /** * \brief get the current driver for an interface * * \param driver a string containing the name of the current * driver for the interface. You can typically pass in an empty * string for this. * * \return length of string, or 0 on error. */ int driverName(std::string &driver); #endif #ifdef USE_UNTESTED_LIBUSBPP_METHODS /** * \brief Claim this interface * * This method claims the interface. You have to claim the * interface before performing any operations on the interface (or * on endpoints that are part of the interface). * * \return 0 on success or negative number on error. */ int claim(void); /** * \brief Release this interface * * This method releases the interface. You should release the * interface after all operations on it (and any lower level * endpoints) are completed. * * \return 0 on success or negative number on error. */ int release(void); /** * \brief Set interface alternate setting * * This method sets the interface to a particular AltSetting. * * \param altSettingNumber the AltSetting that the interface * should be changed to. * * \return 0 on success, or a negative number in case of error. */ int setAltSetting(int altSettingNumber); #endif /* USE_UNTESTED_LIBUSBPP_METHODS */ /** * \brief Number of Alternative Settings that this interface has * * This is a simple accessor method that specifies the number * alternative settings that this device interface has. */ u_int8_t numAltSettings(void); /** * \brief First AltSetting for the Interface * * This method returns a pointer to the first AltSetting * for the Interface. * * See nextAltSetting() for an example of how it might be * used. * * \see nextAltSetting(), lastAltSetting(), numAltSettings() */ AltSetting *firstAltSetting(void); /** * \brief Next AltSetting for the Interface * * This method returns a pointer to the next AltSetting * for the Interface. * * If you want to iterate through each AltSetting on * a device, you can use something like the following: * \code * USB::Configuration *this_Configuration; * this_Configuration = device->firstConfiguration(); * for (i=0; i < device->numConfigurations(); i++) { * this_Configuration->dumpDescriptor(); * USB::Interface *this_Interface; * this_Interface = this_Configuration->firstInterface(); * for (j=0; j < this_Configuration->numInterfaces(); j++) { * USB::AltSetting *this_AltSetting; * this_AltSetting = this_Interface->firstAltSetting(); * for (k=0; k < this_Interface->numAltSettings(); k++) { * // do something with this_AltSetting * this_AltSetting = this_Interface->nextAltSetting(); * } * this_Interface = this_Configuration->nextInterface(); * } * this_Configuration = device->nextConfiguration(); * } * \endcode * * \see firstAltSetting(), lastAltSetting(), numAltSettings() */ AltSetting *nextAltSetting(void); /** * \brief Last AltSetting for the Interface * * This method returns a pointer to the last AltSetting * for the Interface. * * \see firstAltSetting(), nextAltSetting(), numAltSettings() */ AltSetting *lastAltSetting(void); private: std::list<AltSetting *>::const_iterator iter; void setNumAltSettings(u_int8_t); void setParent(Device *parent); u_int8_t m_numAltSettings; Device *m_parent; /* index representing the interface, in this configuration */ int m_interfaceNumber; void setInterfaceNumber(int interfaceNumber); }; /** * \brief Class representing a configuration of a Device * * The Configuration class represents a single configuration * of a device attached to a Universal Serial Bus. * * \author Brad Hards */ class Configuration : public std::list<Interface *> { /** * Busses is a friend because it fills in the descriptor type * information on initialisation and rescan. */ friend class Busses; public: Configuration() {}; /** * \brief Configuration descriptor information output * * This method dumps out the various characteristics * of the configuration to standard output. * * It is mostly useful for debugging. */ void dumpDescriptor(void); /** * \brief Number of Interfaces that this device has * * This is a simple accessor method that specifies the number * Interfaces that this device configuration has. */ u_int8_t numInterfaces(void); /** * \brief First Interface for the Configuration * * This method returns a pointer to the first Interface * for the Configuration. * * See nextInterface() for an example of how it might be * used. * * \see nextInterface(), lastInterface(), numInterfaces() */ Interface *firstInterface(void); /** * \brief Next Interface for the Configuration * * This method returns a pointer to the next Interface * for the Configuration. * * If you want to iterate through each Interface on * a device, you can use something like the following: * \code * USB::Configuration *this_Configuration; * this_Configuration = device->firstConfiguration(); * for (i=0; i < device->numConfigurations(); i++) { * this_Interface = this_Configuration->firstInterface(); * for (j=0; j < this_Configuration->numInterfaces(); j++) { * // do something with this_Interface * this_Interface = this_Configuration->nextInterface(); * } * this_Configuration->nextConfiguration(); * } * \endcode * * \see firstInterface(), lastInterface(), numInterfaces() */ Interface *nextInterface(void); /** * \brief Last Interface for the Configuration * * This method returns a pointer to the last Interface * for the Configuration. * * \see firstInterface(), nextInterface(), numInterfaces() */ Interface *lastInterface(void); private: std::list<Interface *>::const_iterator iter; void setDescriptor(struct usb_config_descriptor); /* we don't use a normal usb_config_descriptor */ /* because that would bring in the interface list */ u_int8_t m_Length; u_int8_t m_DescriptorType; u_int16_t m_TotalLength; u_int8_t m_NumInterfaces; u_int8_t m_ConfigurationValue; u_int8_t m_Configuration; u_int8_t m_Attributes; u_int8_t m_MaxPower; }; /** * \brief Class representing a Device on the Bus * * The Device class represents a single device * attached to a Universal Serial Bus. * * \author Brad Hards */ class Device : public std::list<Configuration *> { /** * Busses is a friend because it fills in the descriptor type * information on initialisation and rescan. */ friend class Busses; /** * Interface is a friend because it needs the handle() function to * perform claim(), release(). */ friend class Interface; /** * Endpoint is a friend because it needs the handle() function to * perform reads, writes, and other transactions. */ friend class Endpoint; public: Device() {}; ~Device(); /** * \brief OS representation of filename for this device * * libusb++ provides a uniform way of accessing USB * devices irrespective of the underlying Operation System * representation. If you want to map the libusb++ representation * to the Operating System representation, you can do this * with filename(). * * On Linux, the filename is usually something like 002, which * represents the second device (usually the first real device, * after the root hub pseudo-device) on the bus. * * \see Bus::directoryName() */ std::string fileName(void); /** * \brief The vendor ID number, as provided by the device. * * This method returns a number containing the vendor * (manufacturer) identification number. These are allocated * by the USB Implementers Forum, and you can construct a * lookup based on the number to get the manufacturer's name, * even if the device does not contain a vendor string. * * \see Vendor() */ u_int16_t idVendor(void); /** * \brief The product ID number, as provided by the device. * * This method returns a number containing the product * identification number. These are allocated * by the manufacturer, and should be different on each device. * * \see Product() */ u_int16_t idProduct(void); /** * \brief The product's revision ID, as provided by the device. * * This method returns a number containing the product's revision. * This revision level is nominally binary coded decimal, but * hexadecimal revision levels are not uncommon. The binary coded * decimal version nominally has a major version in the high byte, * and a minor version in the low byte. */ u_int16_t idRevision(void); /** * \brief The device's USB class, as provided by the device. * * This method returns a number containing the device's class. * These are defined by the USB Implementer's Forum. * * A code of Zero is special (and common) - it means that the * class is found in the Interface descriptor, rather than in the * Device descriptor. * * A code of 0xFF is also special (and far too common) - it means * that the manufacturer didn't conform to one of the defined * class specifications, and chose to implement a vendor specified * protocol. * */ u_int8_t devClass(void); /** * \brief The device's USB subclass, as provided by the device. * * This method returns a number containing the device's subclass. * These subclasses are defined by the USB Implementer's Forum, * and only have meaning in the context of a specified class. */ u_int8_t devSubClass(void); /** * \brief The device's USB protocol, as provided by the device. * * This method returns a number containing the device's protocol. * These protocols are defined by the USB Implementer's Forum, and * only have meaning in the context of a specified class and * subclass. */ u_int8_t devProtocol(void); /** * \brief The vendor name string, as provided by the device. * * This method returns a string containing the name of the * device's vendor (manufacturer), as encoded into the device. * * Note that not all devices contain a vendor name, and also * that under some operating systems you may not be able to * read the vendor name without elevated privledges (typically * root privledges). * * \see idVendor() **/ std::string Vendor(void); /** * \brief The product name string, as provided by the device. * * This method returns a string containing the name of the * device's product name, as encoded into the device. * * Note that not all devices contain a product name, and also * that under some operating systems you may not be able to * read the vendor name without elevated privledges (typically * root privledges). * * \see idProduct() **/ std::string Product(void); /** * \brief The serial number string, as provided by the device. * * This method returns a string containing a serial number for * the device, as encoded into the device. * * Note that few devices contain a serial number string, and also * that under some operating systems you may not be able to * read the serial number without elevated privledges (typically * root privledges). The USB specification requires that serial * numbers are unique if they are provided, but adherence to this * requirement by manufacturers is not universal. **/ std::string SerialNumber(void); /** * \brief Number of Configurations that this device has * * This is a simple accessor method that specifies the number * configurations that this device has. */ u_int8_t numConfigurations(void); /** * \brief fetch an arbitrary string from the device * * \param string the string from the device. You can typically * pass in an empty string for this. * \param index the index of the string required * \param lang the language ID to use. Defaults to using the * first language ID. * * \return length of string, or 0 on error. */ int string(std::string &buf, int index, u_int16_t lang=0); /** * \brief First Configuration for the Device * * This method returns a pointer to the first Configuration * for the Device. * * See nextConfiguration() for an example of how it might be * used. */ Configuration *firstConfiguration(void); /** * \brief Next Configuration for the Device * * This method returns a pointer to the next Configuration * for the Device. * * If you want to iterate through each Configuration on * a device, you can use something like the following: * \code * USB::Configuration *this_Configuration; * this_Configuration = device->firstConfiguration(); * for (i=0; i < device->numConfigurations(); i++) { * // do something with this_Configuration * this_Configuration->nextConfiguration(); * } * \endcode */ Configuration *nextConfiguration(void); /** * \brief Last Configuration for the Device * * This method returns a pointer to the last Configuration * for the Device. * */ Configuration *lastConfiguration(void); /** * \brief USB control transfer * * This method performs a standard control transfer to the default * endpoint. See the USB specification for more details on this. * * \param requestType corresponds to the bmRequestType field * in the transfer * \param request corresponds to the bRequest field in the * transfer * \param value corresponds to the wValue field in the transfer * \param index corresponds to the wIndex field in the transfer * \param length corresponds to the wLength field in the transfer * \param payload corresponds to the data phase of a control * transfer * \param timeout is the timeout period for the control transfer, * in milliseconds * * \return number of bytes sent or received, or a negative number * in case of error. */ int controlTransfer(u_int8_t requestType, u_int8_t request, u_int16_t value, u_int16_t index, u_int16_t length, unsigned char *payload, int timeout = 100); #ifdef USE_UNTESTED_LIBUSBPP_METHODS /** * \brief USB device reset * * This method performs a device reset - see USB Specification * 9.1 for how this changes the device state to the Default state. * * \return 0 on success, or a negative number in case of error. */ int reset(void); /** * \brief Set device configuration * * This method sets the device to a particular Configuration. * * \param configurationNumber the configuration that the device * should be changed to. * * \return 0 on success, or a negative number in case of error. */ int setConfiguration(int configurationNumber); #endif /* USE_UNTESTED_LIBUSBPP_METHODS */ private: std::list<Configuration *>::const_iterator iter; struct usb_dev_handle *handle(); void setFileName(std::string); void setDescriptor(struct usb_device_descriptor); void setVendor(std::string); void setProduct(std::string); void setSerialNumber(std::string); void setDevHandle(struct usb_dev_handle *); std::string m_fileName; std::string m_Vendor; std::string m_Product; std::string m_SerialNumber; struct usb_device *m_dev; struct usb_dev_handle *m_handle; struct usb_device_descriptor m_descriptor; }; /** * \brief Class representing a single bus on the machine * * This class is essentially a list of Device class instances */ class Bus : public std::list<Device *> { /** * Busses is a friend because it fills in the directory name * information on initialisation and rescan. */ friend class Busses; public: Bus() {}; /** * \brief OS representation of directory name for this Bus * * libusb++ provides a uniform way of accessing USB * busses irrespective of the underlying Operation System * representation. If you want to map the libusb++ representation * to the Operating System representation, you can do this * with directory name(). * * On Linux, the directoryname is usually something like 003, which * represents the third bus on the host. * * \see Directory::filename() */ std::string directoryName(void); private: std::list<Device *>::const_iterator iter; void setDirectoryName(std::string); std::string m_directoryName; }; /** * \brief A vendor/product ID pair * * DeviceID provides a list of (vendor, product) identification * pairs. It is intended for use in a list of device numbers to * search for, but there is no reason why it couldn't be used for a * general purpose (vendor,product) tuple if you had some reason for * this. * * The description for Busses::match() provides an example of how * this class might be used. * * \see DeviceIDList, Busses::match() */ class DeviceID { public: DeviceID() {}; /** * \brief Standard constructor * * This constructor takes (vendor, product) tuple, which are * stored away. * * \param vendor the 16 bit vendor number for the device * \param product the 16 bit product number for the device */ DeviceID(u_int16_t vendor, u_int16_t product); /** * \brief vendor number for the device * * This method returns the 16 bit vendor number. */ u_int16_t vendor(void); /** * \brief product number for the device * * This method returns the 16 bit product number. */ u_int16_t product(void); private: u_int16_t m_vendor; u_int16_t m_product; }; /** * \brief A list of vendor/product pairs * * DeviceIDList provides a list of DeviceID classes, which is * essentially a list of (vendor, product) identification pairs. * * \see DeviceID */ typedef std::list<DeviceID> DeviceIDList; /** * \brief Class representing all the busses on the machine * * This class is essentially a list of Bus class instances */ class Busses : public std::list<Bus *> { public: Busses(); /** * \brief Update method * * This method can be called to rescan the various devices * attached to the various busses. You should use it to * update if things change. Unfortunately there is no * way to automatically detect this change in a portable way, * so worst case is that you need to call this using some * kind of timer in the background. */ void rescan(void); /** * \brief find all devices with matching device class designator * * This method searches every device on every bus, and returns a * list of pointers to the devices that have a matching device * class code */ std::list<Device *> match(u_int8_t Class); /** * \brief find all devices with matching device IDs * * This method searches every device on every bus, and returns a * list of pointers to the devices that have a matching device * ID. That is, if the (vendor, product) tuple of a device matches * one of the tuples on the list, then the device will be added to * the list of matches. * * An example of usage is shown below: * \code * USB::Busses buslist; * USB::Device *device; * std::list<USB::Device> miceFound; * USB::DeviceIDList mouseList; * * mouseList.append(USB::DeviceID(VENDOR_LOGITECH, 0xC00E)); // Wheel Mouse Optical * mouseList.append(USB::DeviceID(VENDOR_LOGITECH, 0xC012)); // MouseMan Dual Optical * mouseList.append(USB::DeviceID(VENDOR_LOGITECH, 0xC506)); // MX700 Optical Mouse * * miceFound = buslist.match(mouseList); * * for ( device = miceFound.first(); device; device = miceFound.next() ) { * // do something with each mouse that matched * } * FIXME: This is incorrect now * \endcode */ std::list<Device *> match(DeviceIDList); private: std::list<Bus *>::const_iterator iter; }; class Error { public: private: }; } #endif /* __USBPP_HEADER__ */