adb_interface.h revision 8267511c96e3226e45a0be773ee442b66261824d
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/** \brief Encapsulates an interface on our USB device. 27 28 This is an abstract class that implements functionality common for both, 29 legacy, and WinUsb based interfaces. 30*/ 31class AdbInterfaceObject : public AdbObjectHandle { 32 public: 33 /** \brief Constructs the object. 34 35 @param[in] interf_name Name of the interface 36 */ 37 explicit AdbInterfaceObject(const wchar_t* interf_name); 38 39 protected: 40 /** \brief Destructs the object. 41 42 We hide destructor in order to prevent ourseves from accidentaly allocating 43 instances on the stack. If such attemp occur, compiler will error. 44 */ 45 virtual ~AdbInterfaceObject(); 46 47 // 48 // Abstract 49 // 50 51 public: 52 /** \brief Gets serial number for interface's device. 53 54 @param[out] buffer Buffer for the serail number string. Can be NULL in 55 which case buffer_char_size will contain number of characters 56 required for the string. 57 @param[in,out] buffer_char_size On the way in supplies size (in characters) 58 of the buffer. On the way out, if method failed and GetLastError 59 reports ERROR_INSUFFICIENT_BUFFER, will contain number of characters 60 required for the name. 61 @param[in] ansi If true the name will be returned as single character 62 string. Otherwise name will be returned as wide character string. 63 @return true on success, false on failure. If false is returned 64 GetLastError() provides extended error information. 65 */ 66 virtual bool GetSerialNumber(void* buffer, 67 unsigned long* buffer_char_size, 68 bool ansi) = 0; 69 70 71 /** \brief Gets information about an endpoint on this interface. 72 73 @param[in] endpoint_index Zero-based endpoint index. There are two 74 shortcuts for this parameter: ADB_QUERY_BULK_WRITE_ENDPOINT_INDEX 75 and ADB_QUERY_BULK_READ_ENDPOINT_INDEX that provide infor about 76 (default?) bulk write and read endpoints respectively. 77 @param[out] info Upon successful completion will have endpoint information. 78 @return true on success, false on failure. If false is returned 79 GetLastError() provides extended error information. 80 */ 81 virtual bool GetEndpointInformation(UCHAR endpoint_index, 82 AdbEndpointInformation* info) = 0; 83 84 /** \brief Opens an endpoint on this interface. 85 86 @param[in] endpoint_index Zero-based endpoint index. There are two 87 shortcuts for this parameter: ADB_QUERY_BULK_WRITE_ENDPOINT_INDEX 88 and ADB_QUERY_BULK_READ_ENDPOINT_INDEX that provide infor about 89 (default?) bulk write and read endpoints respectively. 90 @param[in] access_type Desired access type. In the current implementation 91 this parameter has no effect on the way endpoint is opened. It's 92 always read / write access. 93 @param[in] sharing_mode Desired share mode. In the current implementation 94 this parameter has no effect on the way endpoint is opened. It's 95 always shared for read / write. 96 @return Handle to the opened endpoint object or NULL on failure. 97 If NULL is returned GetLastError() provides extended information 98 about the error that occurred. 99 */ 100 virtual ADBAPIHANDLE OpenEndpoint(UCHAR endpoint_index, 101 AdbOpenAccessType access_type, 102 AdbOpenSharingMode sharing_mode) = 0; 103 104 // 105 // Operations 106 // 107 108 public: 109 /** \brief Gets interface device name. 110 111 @param[out] buffer Buffer for the name. Can be NULL in which case 112 buffer_char_size will contain number of characters required to fit 113 the name. 114 @param[in,out] buffer_char_size On the way in supplies size (in characters) 115 of the buffer. On the way out if method failed and GetLastError 116 reports ERROR_INSUFFICIENT_BUFFER will contain number of characters 117 required to fit the name. 118 @param[in] ansi If true the name will be returned as single character 119 string. Otherwise name will be returned as wide character string. 120 @return true on success, false on failure. If false is returned 121 GetLastError() provides extended error information. 122 */ 123 virtual bool GetInterfaceName(void* buffer, 124 unsigned long* buffer_char_size, 125 bool ansi); 126 127 /** \brief Gets device descriptor for the USB device associated with 128 this interface. 129 130 @param[out] desc Upon successful completion will have usb device 131 descriptor. 132 @return true on success, false on failure. If false is returned 133 GetLastError() provides extended error information. 134 */ 135 virtual bool GetUsbDeviceDescriptor(USB_DEVICE_DESCRIPTOR* desc); 136 137 /** \brief Gets descriptor for the selected USB device configuration. 138 139 @param[out] desc Upon successful completion will have usb device 140 configuration descriptor. 141 @return true on success, false on failure. If false is returned 142 GetLastError() provides extended error information. 143 */ 144 virtual bool GetUsbConfigurationDescriptor( 145 USB_CONFIGURATION_DESCRIPTOR* desc); 146 147 /** \brief Gets descriptor for this interface. 148 149 @param[out] desc Upon successful completion will have interface 150 descriptor. 151 @return true on success, false on failure. If false is returned 152 GetLastError() provides extended error information. 153 */ 154 virtual bool GetUsbInterfaceDescriptor(USB_INTERFACE_DESCRIPTOR* desc); 155 156 public: 157 /// Gets name of the USB interface (device name) for this object 158 const std::wstring& interface_name() const { 159 return interface_name_; 160 } 161 162 /// This is a helper for extracting object from the AdbObjectHandleMap 163 static AdbObjectType Type() { 164 return AdbObjectTypeInterface; 165 } 166 167 /// Gets cached usb device descriptor 168 const USB_DEVICE_DESCRIPTOR* usb_device_descriptor() const { 169 return &usb_device_descriptor_; 170 } 171 172 /// Gets cached usb configuration descriptor 173 const USB_CONFIGURATION_DESCRIPTOR* usb_config_descriptor() const { 174 return &usb_config_descriptor_; 175 } 176 177 /// Gets cached usb interface descriptor 178 const USB_INTERFACE_DESCRIPTOR* usb_interface_descriptor() const { 179 return &usb_interface_descriptor_; 180 } 181 182 protected: 183 /// Name of the USB interface (device name) for this object 184 std::wstring interface_name_; 185 186 /// Cached usb device descriptor 187 USB_DEVICE_DESCRIPTOR usb_device_descriptor_; 188 189 /// Cached usb configuration descriptor 190 USB_CONFIGURATION_DESCRIPTOR usb_config_descriptor_; 191 192 /// Cached usb interface descriptor 193 USB_INTERFACE_DESCRIPTOR usb_interface_descriptor_; 194}; 195 196#endif // ANDROID_USB_API_ADB_INTERFACE_H__ 197