00001 /*************************************************************************** 00002 LOW_portUsbDevice.h - description 00003 ------------------- 00004 begin : Sun Oct 12 2003 00005 copyright : (C) 2003 by Harald Roelle 00006 email : roelle@informatik.uni-muenchen.de 00007 ***************************************************************************/ 00008 00009 /*************************************************************************** 00010 * * 00011 * This program is free software; you can redistribute it and/or modify * 00012 * it under the terms of the GNU General Public License as published by * 00013 * the Free Software Foundation; either version 2 of the License, or * 00014 * (at your option) any later version. * 00015 * * 00016 ***************************************************************************/ 00017 00018 #ifndef LOW_PORTUSBDEVICE_H 00019 #define LOW_PORTUSBDEVICE_H 00020 00021 00022 #include "LOW_types.h" 00023 #include "LOW_exception.h" 00024 00025 00026 /** Abstract base class for a device on a USB port. 00027 Each instance represents one USB device. 00028 00029 Specific platforms dereive their implementation classes from this class. 00030 00031 The instances are created by LOW_portUsb_Factory, following the factory 00032 design pattern. 00033 00034 <B>Note:</B> There is no prescribed constructor. A class deriving from this 00035 one should have two constructors. One which requires to specify 00036 some kind of address identifying the device, the other a USB 00037 vendor/product ID pair returning the first device of that kind 00038 found. 00039 00040 This class is far away from beeing generic, it just contains stuff needed for the DS2490. 00041 00042 This class is thread-safe. 00043 00044 @see LOW_portUsb_Factory 00045 @see USB Specification Version 1.1 00046 00047 @author Harald Roelle 00048 @author Parts of the documentation taken from libusb. 00049 */ 00050 class LOW_portUsbDevice { 00051 00052 //======================================================================================= 00053 public: 00054 00055 //===================================================================================== 00056 // 00057 // exceptions 00058 // 00059 00060 /** Exception base class for all exceptions thrown by LOW_portUsbDevice. */ 00061 class_DERIVE_FROM_EXCEPTION( portUsbDevice_error, LOW_exception); 00062 00063 /** Exception class when a device could not be found. */ 00064 class_DERIVE_FROM_EXCEPTION( noSuchDevice_error, portUsbDevice_error); 00065 00066 00067 00068 //===================================================================================== 00069 // 00070 // type definitions 00071 // 00072 00073 typedef uint16_t usbVendorID_t; /**< Type for USB vendor ID. */ 00074 typedef uint16_t usbProductID_t; /**< Type for USB product ID. */ 00075 typedef uint8_t usbConfig_t; /**< Type for USB configuration. */ 00076 typedef uint8_t usbInterface_t; /**< Type for USB interface. */ 00077 typedef uint8_t usbSetting_t; /**< Type for USB setting. */ 00078 typedef uint8_t bmRequestType_t; /**< Corresponds to type defined in USB 1.1 specification. */ 00079 typedef uint8_t bRequest_t; /**< Corresponds to type defined in USB 1.1 specification. */ 00080 typedef uint16_t wValue_t; /**< Corresponds to type defined in USB 1.1 specification. */ 00081 typedef uint16_t wIndex_t; /**< Corresponds to type defined in USB 1.1 specification. */ 00082 typedef uint16_t wLength_t; /**< Corresponds to type defined in USB 1.1 specification. */ 00083 typedef uint8_t *msgData_t; /**< Pointer type for I/O methods. */ 00084 typedef uint16_t usbTimeout_t; /**< Type for timeout on USB operations in ms. */ 00085 typedef uint8_t usbEndpoint_t; /**< Type for USB endpoint. */ 00086 00087 00088 00089 //===================================================================================== 00090 // 00091 // constructors 00092 // 00093 00094 /** Destructor. 00095 */ 00096 virtual ~LOW_portUsbDevice(); 00097 00098 00099 00100 //===================================================================================== 00101 // 00102 // methods 00103 // 00104 00105 /** Get vendor ID of USB device. 00106 */ 00107 virtual usbVendorID_t getVendorID() = 0; 00108 00109 00110 /** Get product ID of USB device. 00111 */ 00112 virtual usbProductID_t getProductID() = 0; 00113 00114 00115 /** Sets the active configuration of a device. 00116 @param inConfig The value as specified in the USB descriptor field bConfigurationValue. 00117 */ 00118 virtual void setConfiguration( const usbConfig_t inConfig) = 0; 00119 00120 00121 /** Claim an interface of a device. 00122 Claims the interface with the Operating System. 00123 00124 <b>Note</b>: The method must be called before you perform any operations related 00125 to this interface (like setIfaceAltSetting(), bulkWrite(), etc). 00126 00127 @param inInterface The value as specified in the USB descriptor field bInterfaceNumber. 00128 */ 00129 virtual void claimInterface( const usbInterface_t inInterface) = 0; 00130 00131 00132 /** Releases a previously claimed interface. 00133 Releases an interface previously claimed with claimInterface(). 00134 00135 @param inInterface The value as specified in the USB descriptor field bInterfaceNumber. 00136 */ 00137 virtual void releaseInterface( const usbInterface_t inInterface) = 0; 00138 00139 00140 /** Sets the active alternate setting of the current interface. 00141 @param inAltInterface The value as specified in the USB descriptor field bAlternateSetting. 00142 */ 00143 virtual void setIfaceAltSetting( const usbSetting_t inAltSetting) = 0; 00144 00145 00146 /** Send a control message to a device. 00147 Performs a control request to the default control pipe on a device. 00148 00149 The parameters mirror the types of the same name in the USB specification. 00150 */ 00151 virtual void controlMsg( const bmRequestType_t inReqType, 00152 const bRequest_t inRequest, 00153 const wValue_t inValue, 00154 const wIndex_t inIndex, 00155 const wLength_t inLength, 00156 msgData_t inOutData, 00157 const usbTimeout_t inTimeout) = 0; 00158 00159 /** Send a control message to a device. 00160 Performs a control request to the default control pipe on a device. 00161 00162 The parameters mirror the types of the same name in the USB specification. 00163 */ 00164 virtual void controlMsg( const bmRequestType_t inReqType, 00165 const bRequest_t inRequest, 00166 const wValue_t inValue, 00167 const wIndex_t inIndex, 00168 byteVec_t &inOutData, 00169 const usbTimeout_t inTimeout) = 0; 00170 00171 00172 /** Clears any halt status on an endpoint. 00173 00174 @param inEOP The value specified in the USB descriptor field bEndpointAddress. 00175 */ 00176 virtual void clearHalt( const usbEndpoint_t inEP) = 0; 00177 00178 00179 00180 /** Write data to a bulk endpoint. 00181 @param inEP The endpoint. 00182 @param inLength Number of bytes to write. 00183 @param inData Pointer to data to write. 00184 @param inTimeout Timeout to wait for completion. 00185 @return Number of bytes actually written. 00186 */ 00187 virtual unsigned int bulkWrite( const usbEndpoint_t inEP, const wLength_t inLength, 00188 const msgData_t inData, const usbTimeout_t inTimeout) = 0; 00189 00190 /** Write data to a bulk endpoint. 00191 @param inEP The endpoint. 00192 @param inData Data to write. 00193 @param inTimeout Timeout to wait for completion. 00194 @return Number of bytes actually written. 00195 */ 00196 virtual unsigned int bulkWrite( const usbEndpoint_t inEP, 00197 const byteVec_t &inData, const usbTimeout_t inTimeout) = 0; 00198 00199 00200 /** Read data from a bulk endpoint. 00201 @param inEP The endpoint. 00202 @param inLength Number of bytes to read. 00203 @param outData Pointer to memory to write data to. Memory must be already allocated! 00204 @param inTimeout Timeout to wait for completion. 00205 @return Number of bytes actually read. 00206 */ 00207 virtual unsigned int bulkRead( const usbEndpoint_t inEP, const wLength_t inLength, 00208 msgData_t outData, const usbTimeout_t inTimeout) = 0; 00209 00210 /** Read data from a bulk endpoint. 00211 @param inEP The endpoint. 00212 @param outData Data that was read. Preset length of the array determines amount of bytes to read. 00213 @param inTimeout Timeout to wait for completion. 00214 @return Number of bytes actually read. 00215 */ 00216 virtual unsigned int bulkRead( const usbEndpoint_t inEP, 00217 byteVec_t &outData, const usbTimeout_t inTimeout) = 0; 00218 00219 }; 00220 00221 #endif
1.3.2