xref: /macosx-10.9.5/SmartcardCCID-55005/libusb/libusb/usbpp.h

// -*- 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__ */