adb_interface.h revision 3e44f3b231c027f01290367049f2244514f22d16 
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