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 |
|
| 26 | /** \brief Encapsulates an interface on our USB device.
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 27 |
|
| 28 | This is an abstract class that implements functionality common for both,
|
| 29 | legacy, and WinUsb based interfaces.
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 30 | */
|
Raphael | 3e44f3b | 2009-08-06 20:51:11 -0700 | [diff] [blame^] | 31 | class AdbInterfaceObject : public AdbObjectHandle {
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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 |
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 47 | //
|
| 48 | // Abstract
|
| 49 | //
|
| 50 |
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 51 | public:
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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 | */
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 66 | virtual bool GetSerialNumber(void* buffer,
|
| 67 | unsigned long* buffer_char_size,
|
| 68 | bool ansi) = 0;
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 69 |
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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 | */
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 81 | virtual bool GetEndpointInformation(UCHAR endpoint_index,
|
| 82 | AdbEndpointInformation* info) = 0;
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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 | */
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 100 | virtual ADBAPIHANDLE OpenEndpoint(UCHAR endpoint_index,
|
| 101 | AdbOpenAccessType access_type,
|
| 102 | AdbOpenSharingMode sharing_mode) = 0;
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 103 |
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 104 | //
|
| 105 | // Operations
|
| 106 | //
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 107 |
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 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.
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 122 | */
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 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);
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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 |
|
vchtchetkine | 8267511 | 2009-07-24 11:30:41 -0700 | [diff] [blame] | 182 | protected:
|
Raphael | 3e44f3b | 2009-08-06 20:51:11 -0700 | [diff] [blame^] | 183 | /// Name of the USB interface (device name) for this object
|
| 184 | std::wstring interface_name_;
|
| 185 |
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 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_;
|
vchtchetkine | dceaaa5 | 2009-07-22 13:34:53 -0700 | [diff] [blame] | 194 | };
|
| 195 |
|
| 196 | #endif // ANDROID_USB_API_ADB_INTERFACE_H__
|