• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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