1 /* 2 * Copyright (C) 2009 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_LEGACY_INTERFACE_H__ 18 #define ANDROID_USB_API_ADB_LEGACY_INTERFACE_H__ 19 /** \file 20 This file consists of declaration of class AdbLegacyInterfaceObject 21 that encapsulates an interface on our USB device that is accessible 22 via custom USB driver. 23 */ 24 25 #include "adb_interface.h" 26 27 /** \brief Encapsulates an interface on our USB device that is accessible 28 via custom USB driver. 29 */ 30 class AdbLegacyInterfaceObject : public AdbInterfaceObject { 31 public: 32 /** \brief Constructs the object. 33 34 @param[in] interf_name Name of the interface 35 */ 36 explicit AdbLegacyInterfaceObject(const wchar_t* interf_name); 37 38 protected: 39 /** \brief Destructs the object. 40 41 We hide destructor in order to prevent ourseves from accidentaly allocating 42 instances on the stack. If such attemp occur, compiler will error. 43 */ 44 virtual ~AdbLegacyInterfaceObject(); 45 46 // 47 // Virtual overrides 48 // 49 50 public: 51 /** \brief Creates handle to this object. 52 53 In this call a handle for this object is generated and object is added 54 to the AdbObjectHandleMap. We override this method in order to initialize 55 access to the custom driver. 56 @return A handle to this object on success or NULL on an error. 57 If NULL is returned GetLastError() provides extended error 58 information. ERROR_GEN_FAILURE is set if an attempt was 59 made to create already opened object. 60 */ 61 virtual ADBAPIHANDLE CreateHandle(); 62 63 // 64 // Abstract overrides 65 // 66 67 public: 68 /** \brief Gets serial number for interface's device. 69 70 @param[out] buffer Buffer for the serail number string. Can be NULL in 71 which case buffer_char_size will contain number of characters 72 required for the string. 73 @param[in,out] buffer_char_size On the way in supplies size (in characters) 74 of the buffer. On the way out, if method failed and GetLastError 75 reports ERROR_INSUFFICIENT_BUFFER, will contain number of characters 76 required for the name. 77 @param[in] ansi If true the name will be returned as single character 78 string. Otherwise name will be returned as wide character string. 79 @return true on success, false on failure. If false is returned 80 GetLastError() provides extended error information. 81 */ 82 virtual bool GetSerialNumber(void* buffer, 83 unsigned long* buffer_char_size, 84 bool ansi); 85 86 /** \brief Gets information about an endpoint on this interface. 87 88 @param[in] endpoint_index Zero-based endpoint index. There are two 89 shortcuts for this parameter: ADB_QUERY_BULK_WRITE_ENDPOINT_INDEX 90 and ADB_QUERY_BULK_READ_ENDPOINT_INDEX that provide infor about 91 (default?) bulk write and read endpoints respectively. 92 @param[out] info Upon successful completion will have endpoint information. 93 @return true on success, false on failure. If false is returned 94 GetLastError() provides extended error information. 95 */ 96 virtual bool GetEndpointInformation(UCHAR endpoint_index, 97 AdbEndpointInformation* info); 98 99 /** \brief Opens an endpoint on this interface. 100 101 @param[in] endpoint_index Zero-based endpoint index. There are two 102 shortcuts for this parameter: ADB_QUERY_BULK_WRITE_ENDPOINT_INDEX 103 and ADB_QUERY_BULK_READ_ENDPOINT_INDEX that provide infor about 104 (default?) bulk write and read endpoints respectively. 105 @param[in] access_type Desired access type. In the current implementation 106 this parameter has no effect on the way endpoint is opened. It's 107 always read / write access. 108 @param[in] sharing_mode Desired share mode. In the current implementation 109 this parameter has no effect on the way endpoint is opened. It's 110 always shared for read / write. 111 @return Handle to the opened endpoint object or NULL on failure. 112 If NULL is returned GetLastError() provides extended information 113 about the error that occurred. 114 */ 115 virtual ADBAPIHANDLE OpenEndpoint(UCHAR endpoint_index, 116 AdbOpenAccessType access_type, 117 AdbOpenSharingMode sharing_mode); 118 119 // 120 // Internal operations 121 // 122 123 protected: 124 /** \brief Opens an endpoint on this interface. 125 126 @param[in] endpoint_name Endpoint file name. 127 @param[in] endpoint_id Endpoint (pipe) address on the device. 128 @param[in] endpoint_index Zero-based endpoint index. 129 @param[in] access_type Desired access type. In the current implementation 130 this parameter has no effect on the way endpoint is opened. It's 131 always read / write access. 132 @param[in] sharing_mode Desired share mode. In the current implementation 133 this parameter has no effect on the way endpoint is opened. It's 134 always shared for read / write. 135 @return Handle to the opened endpoint object or NULL on failure. 136 If NULL is returned GetLastError() provides extended information 137 about the error that occurred. 138 */ 139 ADBAPIHANDLE OpenEndpoint(const wchar_t* endpoint_name, 140 UCHAR endpoint_id, 141 UCHAR endpoint_index, 142 AdbOpenAccessType access_type, 143 AdbOpenSharingMode sharing_mode); 144 145 /** \brief Caches device descriptor for the USB device associated with 146 this interface. 147 148 This method is called from CreateHandle method to cache some interface 149 information. 150 @param[in] usb_device_handle Handle to USB device. 151 @return 'true' on success, 'false' on failure. If 'false' is returned 152 GetLastError() provides extended error information. 153 */ 154 bool CacheUsbDeviceDescriptor(HANDLE usb_device_handle); 155 156 /** \brief Caches descriptor for the selected USB device configuration. 157 158 This method is called from CreateHandle method to cache some interface 159 information. 160 @param[in] usb_device_handle Handle to USB device. 161 @return 'true' on success, 'false' on failure. If 'false' is returned 162 GetLastError() provides extended error information. 163 */ 164 bool CacheUsbConfigurationDescriptor(HANDLE usb_device_handle); 165 166 /** \brief Caches descriptor for this interface. 167 168 This method is called from CreateHandle method to cache some interface 169 information. 170 @param[in] usb_device_handle Handle to USB device. 171 @return 'true' on success, 'false' on failure. If 'false' is returned 172 GetLastError() provides extended error information. 173 */ 174 bool CacheUsbInterfaceDescriptor(HANDLE usb_device_handle); 175 176 protected: 177 /// Index for the default bulk read endpoint 178 UCHAR def_read_endpoint_; 179 180 /// ID for the default bulk read endpoint 181 UCHAR read_endpoint_id_; 182 183 /// Index for the default bulk write endpoint 184 UCHAR def_write_endpoint_; 185 186 /// ID for the default bulk write endpoint 187 UCHAR write_endpoint_id_; 188 }; 189 190 #endif // ANDROID_USB_API_ADB_LEGACY_INTERFACE_H__ 191