1 /* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_USB_API_ADB_INTERFACE_H__ 18 #define ANDROID_USB_API_ADB_INTERFACE_H__ 19 /** \file 20 This file consists of declaration of class AdbInterfaceObject that 21 encapsulates a generic interface on our USB device. 22 */ 23 24 #include "adb_object_handle.h" 25 26 // 'AdbInterfaceObject::interface_name_' : class 'std::basic_string<_E,_Tr,_A>' 27 // needs to have dll-interface to be used by clients of class 28 // 'AdbInterfaceObject' We're ok with that, since interface_name_ will not 29 // be referenced by name from outside of this class. 30 #pragma warning(disable: 4251) 31 /** \brief Encapsulates an interface on our USB device. 32 33 This is an abstract class that implements functionality common for both, 34 legacy, and WinUsb based interfaces. 35 */ 36 class ADBWIN_API_CLASS AdbInterfaceObject : public AdbObjectHandle { 37 public: 38 /** \brief Constructs the object. 39 40 @param[in] interf_name Name of the interface 41 */ 42 explicit AdbInterfaceObject(const wchar_t* interf_name); 43 44 protected: 45 /** \brief Destructs the object. 46 47 We hide destructor in order to prevent ourseves from accidentaly allocating 48 instances on the stack. If such attemp occur, compiler will error. 49 */ 50 virtual ~AdbInterfaceObject(); 51 52 // 53 // Abstract 54 // 55 56 public: 57 /** \brief Gets serial number for interface's device. 58 59 @param[out] buffer Buffer for the serail number string. Can be NULL in 60 which case buffer_char_size will contain number of characters 61 required for the string. 62 @param[in,out] buffer_char_size On the way in supplies size (in characters) 63 of the buffer. On the way out, if method failed and GetLastError 64 reports ERROR_INSUFFICIENT_BUFFER, will contain number of characters 65 required for the name. 66 @param[in] ansi If true the name will be returned as single character 67 string. Otherwise name will be returned as wide character string. 68 @return true on success, false on failure. If false is returned 69 GetLastError() provides extended error information. 70 */ 71 virtual bool GetSerialNumber(void* buffer, 72 unsigned long* buffer_char_size, 73 bool ansi) = 0; 74 75 76 /** \brief Gets information about an endpoint on this interface. 77 78 @param[in] endpoint_index Zero-based endpoint index. There are two 79 shortcuts for this parameter: ADB_QUERY_BULK_WRITE_ENDPOINT_INDEX 80 and ADB_QUERY_BULK_READ_ENDPOINT_INDEX that provide infor about 81 (default?) bulk write and read endpoints respectively. 82 @param[out] info Upon successful completion will have endpoint information. 83 @return true on success, false on failure. If false is returned 84 GetLastError() provides extended error information. 85 */ 86 virtual bool GetEndpointInformation(UCHAR endpoint_index, 87 AdbEndpointInformation* info) = 0; 88 89 /** \brief Opens an endpoint on this interface. 90 91 @param[in] endpoint_index Zero-based endpoint index. There are two 92 shortcuts for this parameter: ADB_QUERY_BULK_WRITE_ENDPOINT_INDEX 93 and ADB_QUERY_BULK_READ_ENDPOINT_INDEX that provide infor about 94 (default?) bulk write and read endpoints respectively. 95 @param[in] access_type Desired access type. In the current implementation 96 this parameter has no effect on the way endpoint is opened. It's 97 always read / write access. 98 @param[in] sharing_mode Desired share mode. In the current implementation 99 this parameter has no effect on the way endpoint is opened. It's 100 always shared for read / write. 101 @return Handle to the opened endpoint object or NULL on failure. 102 If NULL is returned GetLastError() provides extended information 103 about the error that occurred. 104 */ 105 virtual ADBAPIHANDLE OpenEndpoint(UCHAR endpoint_index, 106 AdbOpenAccessType access_type, 107 AdbOpenSharingMode sharing_mode) = 0; 108 109 // 110 // Operations 111 // 112 113 public: 114 /** \brief Gets interface device name. 115 116 @param[out] buffer Buffer for the name. Can be NULL in which case 117 buffer_char_size will contain number of characters required to fit 118 the name. 119 @param[in,out] buffer_char_size On the way in supplies size (in characters) 120 of the buffer. On the way out if method failed and GetLastError 121 reports ERROR_INSUFFICIENT_BUFFER will contain number of characters 122 required to fit the name. 123 @param[in] ansi If true the name will be returned as single character 124 string. Otherwise name will be returned as wide character string. 125 @return true on success, false on failure. If false is returned 126 GetLastError() provides extended error information. 127 */ 128 virtual bool GetInterfaceName(void* buffer, 129 unsigned long* buffer_char_size, 130 bool ansi); 131 132 /** \brief Gets device descriptor for the USB device associated with 133 this interface. 134 135 @param[out] desc Upon successful completion will have usb device 136 descriptor. 137 @return true on success, false on failure. If false is returned 138 GetLastError() provides extended error information. 139 */ 140 virtual bool GetUsbDeviceDescriptor(USB_DEVICE_DESCRIPTOR* desc); 141 142 /** \brief Gets descriptor for the selected USB device configuration. 143 144 @param[out] desc Upon successful completion will have usb device 145 configuration descriptor. 146 @return true on success, false on failure. If false is returned 147 GetLastError() provides extended error information. 148 */ 149 virtual bool GetUsbConfigurationDescriptor( 150 USB_CONFIGURATION_DESCRIPTOR* desc); 151 152 /** \brief Gets descriptor for this interface. 153 154 @param[out] desc Upon successful completion will have interface 155 descriptor. 156 @return true on success, false on failure. If false is returned 157 GetLastError() provides extended error information. 158 */ 159 virtual bool GetUsbInterfaceDescriptor(USB_INTERFACE_DESCRIPTOR* desc); 160 161 public: 162 /// Gets name of the USB interface (device name) for this object interface_name()163 const std::wstring& interface_name() const { 164 return interface_name_; 165 } 166 167 /// This is a helper for extracting object from the AdbObjectHandleMap Type()168 static AdbObjectType Type() { 169 return AdbObjectTypeInterface; 170 } 171 172 /// Gets cached usb device descriptor usb_device_descriptor()173 const USB_DEVICE_DESCRIPTOR* usb_device_descriptor() const { 174 return &usb_device_descriptor_; 175 } 176 177 /// Gets cached usb configuration descriptor usb_config_descriptor()178 const USB_CONFIGURATION_DESCRIPTOR* usb_config_descriptor() const { 179 return &usb_config_descriptor_; 180 } 181 182 /// Gets cached usb interface descriptor usb_interface_descriptor()183 const USB_INTERFACE_DESCRIPTOR* usb_interface_descriptor() const { 184 return &usb_interface_descriptor_; 185 } 186 187 protected: 188 /// Cached usb device descriptor 189 USB_DEVICE_DESCRIPTOR usb_device_descriptor_; 190 191 /// Cached usb configuration descriptor 192 USB_CONFIGURATION_DESCRIPTOR usb_config_descriptor_; 193 194 /// Cached usb interface descriptor 195 USB_INTERFACE_DESCRIPTOR usb_interface_descriptor_; 196 197 private: 198 /// Name of the USB interface (device name) for this object 199 std::wstring interface_name_; 200 }; 201 #pragma warning(default: 4251) 202 203 #endif // ANDROID_USB_API_ADB_INTERFACE_H__ 204