vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 21 | encapsulates a generic interface on our USB device.
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 22 | */
|
| 23 |
|
| 24 | #include "adb_object_handle.h"
|
| 25 |
|
vchtchetkine | f855c4e | 2009-08-05 16:57:18 -0700 | [diff] [blame^] | 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)
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 31 | /** \brief Encapsulates an interface on our USB device.
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 32 |
|
| 33 | This is an abstract class that implements functionality common for both,
|
| 34 | legacy, and WinUsb based interfaces.
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 35 | */
|
vchtchetkine | f855c4e | 2009-08-05 16:57:18 -0700 | [diff] [blame^] | 36 | class ADBWIN_API_CLASS AdbInterfaceObject : public AdbObjectHandle {
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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 |
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 52 | //
|
| 53 | // Abstract
|
| 54 | //
|
| 55 |
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 56 | public:
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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 | */
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 71 | virtual bool GetSerialNumber(void* buffer,
|
| 72 | unsigned long* buffer_char_size,
|
| 73 | bool ansi) = 0;
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 74 |
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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 | */
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 86 | virtual bool GetEndpointInformation(UCHAR endpoint_index,
|
| 87 | AdbEndpointInformation* info) = 0;
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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 | */
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 105 | virtual ADBAPIHANDLE OpenEndpoint(UCHAR endpoint_index,
|
| 106 | AdbOpenAccessType access_type,
|
| 107 | AdbOpenSharingMode sharing_mode) = 0;
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 108 |
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 109 | //
|
| 110 | // Operations
|
| 111 | //
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 112 |
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 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.
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 127 | */
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 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);
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 160 |
|
| 161 | public:
|
| 162 | /// Gets name of the USB interface (device name) for this object
|
| 163 | const std::wstring& interface_name() const {
|
| 164 | return interface_name_;
|
| 165 | }
|
| 166 |
|
| 167 | /// This is a helper for extracting object from the AdbObjectHandleMap
|
| 168 | static AdbObjectType Type() {
|
| 169 | return AdbObjectTypeInterface;
|
| 170 | }
|
| 171 |
|
| 172 | /// Gets cached 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
|
| 178 | const USB_CONFIGURATION_DESCRIPTOR* usb_config_descriptor() const {
|
| 179 | return &usb_config_descriptor_;
|
| 180 | }
|
| 181 |
|
| 182 | /// Gets cached usb interface descriptor
|
| 183 | const USB_INTERFACE_DESCRIPTOR* usb_interface_descriptor() const {
|
| 184 | return &usb_interface_descriptor_;
|
| 185 | }
|
| 186 |
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 187 | protected:
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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_;
|
vchtchetkine | f855c4e | 2009-08-05 16:57:18 -0700 | [diff] [blame^] | 196 |
|
| 197 | private:
|
| 198 | /// Name of the USB interface (device name) for this object
|
| 199 | std::wstring interface_name_;
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 200 | };
|
vchtchetkine | f855c4e | 2009-08-05 16:57:18 -0700 | [diff] [blame^] | 201 | #pragma warning(default: 4251)
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 202 |
|
| 203 | #endif // ANDROID_USB_API_ADB_INTERFACE_H__
|