adb_endpoint_object.h revision dceaaa52cec11631c72cfea5fb74ee607602ecde 
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_ENDPOINT_OBJECT_H__
18#define ANDROID_USB_API_ADB_ENDPOINT_OBJECT_H__
19/** \file
20  This file consists of declaration of class AdbIOObject that encapsulates a
21  handle opened to an endpoint on our device.
22*/
23
24#include "adb_interface.h"
25
26/** Class AdbEndpointObject encapsulates a handle opened to an endpoint on
27  our device.
28*/
29class AdbEndpointObject : public AdbObjectHandle {
30 public:
31  /** \brief Constructs the object
32
33    @param[in] interface Parent interface for this object. Interface will be
34           referenced in this object's constructur and released in the
35           destructor.
36    @param[in] endpoint_id Endpoint ID (endpoint address) on the device.
37    @param[in] endpoint_index Zero-based endpoint index in the interface's
38          array of endpoints.
39  */
40  AdbEndpointObject(AdbInterfaceObject* parent_interf,
41                    UCHAR endpoint_id,
42                    UCHAR endpoint_index);
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 ~AdbEndpointObject();
51
52 public:
53  /** \brief Gets information about this endpoint.
54
55    @param[out] info Upon successful completion will have endpoint information.
56    @return true on success, false on failure. If false is returned
57            GetLastError() provides extended error information.
58  */
59  bool GetEndpointInformation(AdbEndpointInformation* info);
60
61  /** \brief Reads from opened I/O object asynchronously
62
63    @param[out] buffer Pointer to the buffer that receives the data.
64    @param[in] bytes_to_read Number of bytes to be read.
65    @param[out] bytes_read Number of bytes read. Can be NULL.
66    @param[in] event_handle Event handle that should be signaled when async I/O
67           completes. Can be NULL. If it's not NULL this handle will be used to
68           initialize OVERLAPPED structure for this I/O.
69    @param[in] time_out A timeout (in milliseconds) required for this I/O to
70           complete. Zero value in this parameter means that there is no
71           timeout set for this I/O.
72    @return A handle to IO completion object or NULL on failure. If NULL is
73            returned GetLastError() provides extended error information.
74  */
75  virtual ADBAPIHANDLE AsyncRead(void* buffer,
76                                 ULONG bytes_to_read,
77                                 ULONG* bytes_read,
78                                 HANDLE event_handle,
79                                 ULONG time_out);
80
81  /** \brief Writes to opened I/O object asynchronously
82
83    @param[in] buffer Pointer to the buffer containing the data to be written.
84    @param[in] bytes_to_write Number of bytes to be written.
85    @param[out] bytes_written Number of bytes written. Can be NULL.
86    @param[in] event_handle Event handle that should be signaled when async I/O
87           completes. Can be NULL. If it's not NULL this handle will be used to
88           initialize OVERLAPPED structure for this I/O.
89    @param[in] time_out A timeout (in milliseconds) required for this I/O to
90           complete. Zero value in this parameter means that there is no
91           timeout set for this I/O.
92    @return A handle to IO completion object or NULL on failure. If NULL is
93            returned GetLastError() provides extended error information.
94  */
95  virtual ADBAPIHANDLE AsyncWrite(void* buffer,
96                                  ULONG bytes_to_write,
97                                  ULONG* bytes_written,
98                                  HANDLE event_handle,
99                                  ULONG time_out);
100
101  /** \brief Reads from opened I/O object synchronously
102
103    @param[out] buffer Pointer to the buffer that receives the data.
104    @param[in] bytes_to_read Number of bytes to be read.
105    @param[out] bytes_read Number of bytes read. Can be NULL.
106    @param[in] time_out A timeout (in milliseconds) required for this I/O to
107           complete. Zero value in this parameter means that there is no
108           timeout set for this I/O.
109    @return true on success and false on failure. If false is
110            returned GetLastError() provides extended error information.
111  */
112  virtual bool SyncRead(void* buffer,
113                        ULONG bytes_to_read,
114                        ULONG* bytes_read,
115                        ULONG time_out);
116
117  /** \brief Writes to opened I/O object synchronously
118
119    @param[in] buffer Pointer to the buffer containing the data to be written.
120    @param[in] bytes_to_write Number of bytes to be written.
121    @param[out] bytes_written Number of bytes written. Can be NULL.
122    @param[in] time_out A timeout (in milliseconds) required for this I/O to
123           complete. Zero value in this parameter means that there is no
124           timeout set for this I/O.
125    @return true on success and false on failure. If false is
126            returned GetLastError() provides extended error information.
127  */
128  virtual bool SyncWrite(void* buffer,
129                         ULONG bytes_to_write,
130                         ULONG* bytes_written,
131                         ULONG time_out);
132
133 protected:
134  /** \brief Common code for async read / write
135
136    @param[in] is_read Read or write selector.
137    @param[in,out] buffer Pointer to the buffer for read / write.
138    @param[in] bytes_to_transfer Number of bytes to be read / written.
139    @param[out] bytes_transferred Number of bytes read / written. Can be NULL.
140    @param[in] event_handle Event handle that should be signaled when async I/O
141           completes. Can be NULL. If it's not NULL this handle will be used to
142           initialize OVERLAPPED structure for this I/O.
143    @param[in] time_out A timeout (in milliseconds) required for this I/O to
144           complete. Zero value in this parameter means that there is no
145           timeout set for this I/O.
146    @return A handle to IO completion object or NULL on failure. If NULL is
147            returned GetLastError() provides extended error information.
148  */
149  virtual ADBAPIHANDLE CommonAsyncReadWrite(bool is_read,
150                                            void* buffer,
151                                            ULONG bytes_to_transfer,
152                                            ULONG* bytes_transferred,
153                                            HANDLE event_handle,
154                                            ULONG time_out);
155
156  /** \brief Common code for sync read / write
157
158    @param[in] is_read Read or write selector.
159    @param[in,out] buffer Pointer to the buffer for read / write.
160    @param[in] bytes_to_transfer Number of bytes to be read / written.
161    @param[out] bytes_transferred Number of bytes read / written. Can be NULL.
162    @param[in] time_out A timeout (in milliseconds) required for this I/O to
163           complete. Zero value in this parameter means that there is no
164           timeout set for this I/O.
165    @return true on success, false on failure. If false is returned
166            GetLastError() provides extended error information.
167  */
168  virtual bool CommonSyncReadWrite(bool is_read,
169                                   void* buffer,
170                                   ULONG bytes_to_transfer,
171                                   ULONG* bytes_transferred,
172                                   ULONG time_out);
173  /** \brief Sets read / write operation timeout.
174
175    @param[in] timeout Timeout value in milliseconds to use for current read
176          or write operation. Zero value passed in this parameters indicate
177          not timeout at all. Note that timeout that is set with this method is
178          global per endpoint (pipe). I.e. once set, it will be used against
179          all read / write operations performed on this endpoint, untill
180          another call to this method modifies it. This is a WinUsb design
181          flaw. Microsoft is aware of this and (hopefuly) future versions of
182          WinUsb framework will accept a timeout parameter in WinUsb_Read/Write
183          routines. For the purposes of ADB this flaw doesn't apperar to be an
184          issue, since we use single-threaded synchronous read / writes, so
185          there is no conflict in setting per-endpoint timeouts.
186    @return true on success, false on failure. If false is returned
187            GetLastError() provides extended error information.
188  */
189  virtual bool SetTimeout(ULONG timeout);
190
191 public:
192  /// This is a helper for extracting object from the AdbObjectHandleMap
193  static AdbObjectType Type() {
194    return AdbObjectTypeEndpoint;
195  }
196
197  /// Gets parent interface
198  AdbInterfaceObject* parent_interface() const {
199    return parent_interface_;
200  }
201  /// Gets this endpoint ID
202  UCHAR endpoint_id() const {
203    return endpoint_id_;
204  }
205
206  /// Gets this endpoint index on the interface
207  UCHAR endpoint_index() const {
208    return endpoint_index_;
209  }
210
211  /// Gets parent interface handle
212  ADBAPIHANDLE GetParentInterfaceHandle() const {
213    return (NULL != parent_interface()) ? parent_interface()->adb_handle() :
214                                          NULL;
215  }
216
217  /// Gets parent interface WinUsb handle
218  WINUSB_INTERFACE_HANDLE winusb_handle() const {
219    return parent_interface()->winusb_handle();
220  }
221
222 protected:
223  /// Parent interface
224  AdbInterfaceObject* parent_interface_;
225
226  /// This endpoint id
227  UCHAR               endpoint_id_;
228
229  /// This endpoint index on the interface
230  UCHAR               endpoint_index_;
231};
232
233#endif  // ANDROID_USB_API_ADB_ENDPOINT_OBJECT_H__
234