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_WINUSB_INTERFACE_H__ 18 #define ANDROID_USB_API_ADB_WINUSB_INTERFACE_H__ 19 /** \file 20 This file consists of declaration of class AdbWinUsbInterfaceObject 21 that encapsulates an interface on our USB device that is accessible 22 via WinUsb API. 23 */ 24 25 #include "..\api\adb_interface.h" 26 27 /** \brief Encapsulates an interface on our USB device that is accessible 28 via WinUsb API. 29 */ 30 class AdbWinUsbInterfaceObject : public AdbInterfaceObject { 31 public: 32 /** \brief Constructs the object. 33 34 @param[in] interf_name Name of the interface 35 */ 36 explicit AdbWinUsbInterfaceObject(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 ~AdbWinUsbInterfaceObject(); 45 46 // 47 // Virtual overrides 48 // 49 50 public: 51 /** \brief Releases the object. 52 53 If refcount drops to zero as the result of this release, the object is 54 destroyed in this method. As a general rule, objects must not be touched 55 after this method returns even if returned value is not zero. We override 56 this method in order to make sure that objects of this class are deleted 57 in contect of the DLL they were created in. The problem is that since 58 objects of this class were created in context of AdbWinUsbApi module, they 59 are allocated from the heap assigned to that module. Now, if these objects 60 are deleted outside of AdbWinUsbApi module, this will lead to the heap 61 corruption in the module that deleted these objects. Since all objects of 62 this class are deleted in the Release method only, by overriding it we make 63 sure that we free memory in the context of the module where it was 64 allocated. 65 @return Value of the reference counter after object is released in this 66 method. 67 */ 68 virtual LONG Release(); 69 70 /** \brief Creates handle to this object. 71 72 In this call a handle for this object is generated and object is added 73 to the AdbObjectHandleMap. We override this method in order to initialize 74 WinUsb API for the given interface. 75 @return A handle to this object on success or NULL on an error. 76 If NULL is returned GetLastError() provides extended error 77 information. ERROR_GEN_FAILURE is set if an attempt was 78 made to create already opened object. 79 */ 80 virtual ADBAPIHANDLE CreateHandle(); 81 82 /** \brief This method is called when handle to this object gets closed. 83 84 In this call object is deleted from the AdbObjectHandleMap. We override 85 this method in order close WinUsb handle created in CreateHandle method 86 of this class. 87 @return true on success or false if object is already closed. If 88 false is returned GetLastError() provides extended error 89 information. 90 */ 91 virtual bool CloseHandle(); 92 93 // 94 // Abstract overrides 95 // 96 97 public: 98 /** \brief Gets serial number for interface's device. 99 100 @param[out] buffer Buffer for the serail number string. Can be NULL in 101 which case buffer_char_size will contain number of characters 102 required for the string. 103 @param[in,out] buffer_char_size On the way in supplies size (in characters) 104 of the buffer. On the way out, if method failed and GetLastError 105 reports ERROR_INSUFFICIENT_BUFFER, will contain number of characters 106 required for the name. 107 @param[in] ansi If true the name will be returned as single character 108 string. Otherwise name will be returned as wide character string. 109 @return true on success, false on failure. If false is returned 110 GetLastError() provides extended error information. 111 */ 112 virtual bool GetSerialNumber(void* buffer, 113 unsigned long* buffer_char_size, 114 bool ansi); 115 116 /** \brief Gets information about an endpoint on this interface. 117 118 @param[in] endpoint_index Zero-based endpoint index. There are two 119 shortcuts for this parameter: ADB_QUERY_BULK_WRITE_ENDPOINT_INDEX 120 and ADB_QUERY_BULK_READ_ENDPOINT_INDEX that provide infor about 121 (default?) bulk write and read endpoints respectively. 122 @param[out] info Upon successful completion will have endpoint information. 123 @return true on success, false on failure. If false is returned 124 GetLastError() provides extended error information. 125 */ 126 virtual bool GetEndpointInformation(UCHAR endpoint_index, 127 AdbEndpointInformation* info); 128 129 /** \brief Opens an endpoint on this interface. 130 131 @param[in] endpoint_index Zero-based endpoint index. There are two 132 shortcuts for this parameter: ADB_QUERY_BULK_WRITE_ENDPOINT_INDEX 133 and ADB_QUERY_BULK_READ_ENDPOINT_INDEX that provide infor about 134 (default?) bulk write and read endpoints respectively. 135 @param[in] access_type Desired access type. In the current implementation 136 this parameter has no effect on the way endpoint is opened. It's 137 always read / write access. 138 @param[in] sharing_mode Desired share mode. In the current implementation 139 this parameter has no effect on the way endpoint is opened. It's 140 always shared for read / write. 141 @return Handle to the opened endpoint object or NULL on failure. 142 If NULL is returned GetLastError() provides extended information 143 about the error that occurred. 144 */ 145 virtual ADBAPIHANDLE OpenEndpoint(UCHAR endpoint_index, 146 AdbOpenAccessType access_type, 147 AdbOpenSharingMode sharing_mode); 148 149 // 150 // Operations 151 // 152 153 protected: 154 /** \brief Opens an endpoint on this interface. 155 156 @param[in] endpoint_id Endpoint (pipe) address on the device. 157 @param[in] endpoint_index Zero-based endpoint index. 158 @return Handle to the opened endpoint object or NULL on failure. 159 If NULL is returned GetLastError() provides extended information 160 about the error that occurred. 161 */ 162 ADBAPIHANDLE OpenEndpoint(UCHAR endpoint_id, UCHAR endpoint_index); 163 164 public: 165 /// Gets handle to the USB device usb_device_handle()166 HANDLE usb_device_handle() const { 167 return usb_device_handle_; 168 } 169 170 /// Gets interface handle used by WinUSB API winusb_handle()171 WINUSB_INTERFACE_HANDLE winusb_handle() const { 172 return winusb_handle_; 173 } 174 175 /// Gets current interface number. interface_number()176 UCHAR interface_number() const { 177 return interface_number_; 178 } 179 180 protected: 181 /// Handle to the USB device 182 HANDLE usb_device_handle_; 183 184 /// Interface handle used by WinUSB API 185 WINUSB_INTERFACE_HANDLE winusb_handle_; 186 187 /// Current interface number. This value is obtained via call to 188 /// WinUsb_GetCurrentAlternateSetting and is used in WinUsb_Xxx 189 /// calls that require interface number. 190 UCHAR interface_number_; 191 192 /// Index for the default bulk read endpoint 193 UCHAR def_read_endpoint_; 194 195 /// ID for the default bulk read endpoint 196 UCHAR read_endpoint_id_; 197 198 /// Index for the default bulk write endpoint 199 UCHAR def_write_endpoint_; 200 201 /// ID for the default bulk write endpoint 202 UCHAR write_endpoint_id_; 203 }; 204 205 #endif // ANDROID_USB_API_ADB_WINUSB_INTERFACE_H__ 206