host/windows/usb/api/adb_interface.h

   1 /*\r
   2  * Copyright (C) 2006 The Android Open Source Project\r
   3  *\r
   4  * Licensed under the Apache License, Version 2.0 (the "License");\r
   5  * you may not use this file except in compliance with the License.\r
   6  * You may obtain a copy of the License at\r
   7  *\r
   8  *      http://www.apache.org/licenses/LICENSE-2.0\r
   9  *\r
  10  * Unless required by applicable law or agreed to in writing, software\r
  11  * distributed under the License is distributed on an "AS IS" BASIS,\r
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  13  * See the License for the specific language governing permissions and\r
  14  * limitations under the License.\r
  15  */\r
  16 \r
  17 #ifndef ANDROID_USB_API_ADB_INTERFACE_H__\r
  18 #define ANDROID_USB_API_ADB_INTERFACE_H__\r
  19 /** \file\r
  20   This file consists of declaration of class AdbInterfaceObject that\r
  21   encapsulates a generic interface on our USB device.\r
  22 */\r
  23 \r
  24 #include "adb_object_handle.h"\r
  25 \r
  26 /** \brief Encapsulates an interface on our USB device.\r
  27 \r
  28   This is an abstract class that implements functionality common for both,\r
  29   legacy, and WinUsb based interfaces.\r
  30 */\r
  31 class AdbInterfaceObject : public AdbObjectHandle {\r
  32  public:\r
  33   /** \brief Constructs the object.\r
  34     \r
  35     @param[in] interf_name Name of the interface\r
  36   */\r
  37   explicit AdbInterfaceObject(const wchar_t* interf_name);\r
  38 \r
  39  protected:\r
  40   /** \brief Destructs the object.\r
  41 \r
  42    We hide destructor in order to prevent ourseves from accidentaly allocating\r
  43    instances on the stack. If such attemp occur, compiler will error.\r
  44   */\r
  45   virtual ~AdbInterfaceObject();\r
  46 \r
  47   //\r
  48   // Abstract\r
  49   //\r
  50 \r
  51  public:\r
  52   /** \brief Gets serial number for interface's device.\r
  53 \r
  54     @param[out] buffer Buffer for the serail number string. Can be NULL in\r
  55            which case buffer_char_size will contain number of characters\r
  56            required for the string.\r
  57     @param[in,out] buffer_char_size On the way in supplies size (in characters)\r
  58            of the buffer. On the way out, if method failed and GetLastError\r
  59            reports ERROR_INSUFFICIENT_BUFFER, will contain number of characters\r
  60            required for the name.\r
  61     @param[in] ansi If true the name will be returned as single character\r
  62            string. Otherwise name will be returned as wide character string.\r
  63     @return true on success, false on failure. If false is returned\r
  64             GetLastError() provides extended error information.\r
  65   */\r
  66   virtual bool GetSerialNumber(void* buffer,\r
  67                                unsigned long* buffer_char_size,\r
  68                                bool ansi) = 0;\r
  69 \r
  70 \r
  71   /** \brief Gets information about an endpoint on this interface.\r
  72 \r
  73     @param[in] endpoint_index Zero-based endpoint index. There are two\r
  74            shortcuts for this parameter: ADB_QUERY_BULK_WRITE_ENDPOINT_INDEX\r
  75            and ADB_QUERY_BULK_READ_ENDPOINT_INDEX that provide infor about\r
  76            (default?) bulk write and read endpoints respectively.\r
  77     @param[out] info Upon successful completion will have endpoint information.\r
  78     @return true on success, false on failure. If false is returned\r
  79             GetLastError() provides extended error information.\r
  80   */\r
  81   virtual bool GetEndpointInformation(UCHAR endpoint_index,\r
  82                                       AdbEndpointInformation* info) = 0;\r
  83 \r
  84   /** \brief Opens an endpoint on this interface.\r
  85 \r
  86     @param[in] endpoint_index Zero-based endpoint index. There are two\r
  87            shortcuts for this parameter: ADB_QUERY_BULK_WRITE_ENDPOINT_INDEX\r
  88            and ADB_QUERY_BULK_READ_ENDPOINT_INDEX that provide infor about\r
  89            (default?) bulk write and read endpoints respectively.\r
  90     @param[in] access_type Desired access type. In the current implementation\r
  91            this parameter has no effect on the way endpoint is opened. It's\r
  92            always read / write access.\r
  93     @param[in] sharing_mode Desired share mode. In the current implementation\r
  94            this parameter has no effect on the way endpoint is opened. It's\r
  95            always shared for read / write.\r
  96     @return Handle to the opened endpoint object or NULL on failure.\r
  97             If NULL is returned GetLastError() provides extended information\r
  98             about the error that occurred.\r
  99   */\r
 100   virtual ADBAPIHANDLE OpenEndpoint(UCHAR endpoint_index,\r
 101                                     AdbOpenAccessType access_type,\r
 102                                     AdbOpenSharingMode sharing_mode) = 0;\r
 103 \r
 104   //\r
 105   // Operations\r
 106   //\r
 107 \r
 108  public:\r
 109   /** \brief Gets interface device name.\r
 110 \r
 111     @param[out] buffer Buffer for the name. Can be NULL in which case\r
 112            buffer_char_size will contain number of characters required to fit\r
 113            the name.\r
 114     @param[in,out] buffer_char_size On the way in supplies size (in characters)\r
 115            of the buffer. On the way out if method failed and GetLastError\r
 116            reports ERROR_INSUFFICIENT_BUFFER will contain number of characters\r
 117            required to fit the name.\r
 118     @param[in] ansi If true the name will be returned as single character\r
 119            string. Otherwise name will be returned as wide character string.\r
 120     @return true on success, false on failure. If false is returned\r
 121             GetLastError() provides extended error information.\r
 122   */\r
 123   virtual bool GetInterfaceName(void* buffer,\r
 124                                 unsigned long* buffer_char_size,\r
 125                                 bool ansi);\r
 126 \r
 127   /** \brief Gets device descriptor for the USB device associated with\r
 128     this interface.\r
 129 \r
 130     @param[out] desc Upon successful completion will have usb device\r
 131            descriptor.\r
 132     @return true on success, false on failure. If false is returned\r
 133             GetLastError() provides extended error information.\r
 134   */\r
 135   virtual bool GetUsbDeviceDescriptor(USB_DEVICE_DESCRIPTOR* desc);\r
 136 \r
 137   /** \brief Gets descriptor for the selected USB device configuration.\r
 138 \r
 139     @param[out] desc Upon successful completion will have usb device\r
 140            configuration descriptor.\r
 141     @return true on success, false on failure. If false is returned\r
 142             GetLastError() provides extended error information.\r
 143   */\r
 144   virtual bool GetUsbConfigurationDescriptor(\r
 145                   USB_CONFIGURATION_DESCRIPTOR* desc);\r
 146 \r
 147   /** \brief Gets descriptor for this interface.\r
 148 \r
 149     @param[out] desc Upon successful completion will have interface\r
 150            descriptor.\r
 151     @return true on success, false on failure. If false is returned\r
 152             GetLastError() provides extended error information.\r
 153   */\r
 154   virtual bool GetUsbInterfaceDescriptor(USB_INTERFACE_DESCRIPTOR* desc);\r
 155 \r
 156  public:\r
 157   /// Gets name of the USB interface (device name) for this object\r
 158   const std::wstring& interface_name() const {\r
 159     return interface_name_;\r
 160   }\r
 161 \r
 162   /// This is a helper for extracting object from the AdbObjectHandleMap\r
 163   static AdbObjectType Type() {\r
 164     return AdbObjectTypeInterface;\r
 165   }\r
 166 \r
 167   /// Gets cached usb device descriptor\r
 168   const USB_DEVICE_DESCRIPTOR* usb_device_descriptor() const {\r
 169     return &usb_device_descriptor_;\r
 170   }\r
 171 \r
 172   /// Gets cached usb configuration descriptor\r
 173   const USB_CONFIGURATION_DESCRIPTOR* usb_config_descriptor() const {\r
 174     return &usb_config_descriptor_;\r
 175   }\r
 176 \r
 177   /// Gets cached usb interface descriptor\r
 178   const USB_INTERFACE_DESCRIPTOR* usb_interface_descriptor() const {\r
 179     return &usb_interface_descriptor_;\r
 180   }\r
 181 \r
 182  protected:\r
 183   /// Name of the USB interface (device name) for this object\r
 184   std::wstring                  interface_name_;\r
 185 \r
 186   /// Cached usb device descriptor\r
 187   USB_DEVICE_DESCRIPTOR         usb_device_descriptor_;\r
 188 \r
 189   /// Cached usb configuration descriptor\r
 190   USB_CONFIGURATION_DESCRIPTOR  usb_config_descriptor_;\r
 191 \r
 192   /// Cached usb interface descriptor\r
 193   USB_INTERFACE_DESCRIPTOR      usb_interface_descriptor_;\r
 194 };\r
 195 \r
 196 #endif  // ANDROID_USB_API_ADB_INTERFACE_H__\r