adb_io_completion.h revision 8267511c96e3226e45a0be773ee442b66261824d 
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_IO_COMPLETION_H__
18#define ANDROID_USB_API_ADB_IO_COMPLETION_H__
19/** \file
20  This file consists of declaration of class AdbIOCompletion that encapsulates
21  a generic wrapper around OVERLAPPED Win32 structure returned from
22  asynchronous I/O requests.
23*/
24
25#include "adb_endpoint_object.h"
26
27/** \brief Encapsulates encapsulates a generic wrapper around OVERLAPPED Win32
28  structure returned from asynchronous I/O requests.
29
30  This is an abstract class that implements functionality common for I/O
31  performed via WinUsb as well as legacy driver APIs. A handle to this object
32  is returned to the caller of each successful asynchronous I/O request. Just
33  like all other handles this handle must be closed after it's no longer
34  needed.
35*/
36class AdbIOCompletion : public AdbObjectHandle {
37 public:
38  /** \brief Constructs the object
39
40    @param[in] parent_io_obj Parent I/O object that created this instance.
41           Parent object will be referenced in this object's constructor and
42           released in the destructor.
43    @param[in] expected_trans_size Number of bytes expected to be transferred
44          with the I/O.
45    @param[in] event_hndl Event handle that should be signaled when I/O
46           completes. Can be NULL. If it's not NULL this handle will be
47           used to initialize OVERLAPPED structure for this object.
48  */
49  AdbIOCompletion(AdbEndpointObject* parent_io_obj,
50                  ULONG expected_trans_size,
51                  HANDLE event_hndl);
52
53 protected:
54  /** \brief Destructs the object.
55
56    We hide destructor in order to prevent ourseves from accidentaly allocating
57    instances on the stack. If such attemp occur, compiler will error.
58  */
59  virtual ~AdbIOCompletion();
60
61  //
62  // Abstract
63  //
64
65 public:
66  /** \brief Gets overlapped I/O result
67
68    @param[out] ovl_data Buffer for the copy of this object's OVERLAPPED
69           structure. Can be NULL.
70    @param[out] bytes_transferred Pointer to a variable that receives the
71           number of bytes that were actually transferred by a read or write
72           operation. See SDK doc on GetOvelappedResult for more information.
73           Unlike regular GetOvelappedResult call this parameter can be NULL.
74    @param[in] wait If this parameter is true, the method does not return
75           until the operation has been completed. If this parameter is false
76           and the operation is still pending, the method returns false and
77           the GetLastError function returns ERROR_IO_INCOMPLETE.
78    @return true if I/O has been completed or false on failure or if request
79           is not yet completed. If false is returned GetLastError() provides
80           extended error information. If GetLastError returns
81           ERROR_IO_INCOMPLETE it means that I/O is not yet completed.
82  */
83  virtual bool GetOvelappedIoResult(LPOVERLAPPED ovl_data,
84                                    ULONG* bytes_transferred,
85                                    bool wait) = 0;
86
87  //
88  // Operations
89  //
90
91 public:
92  /** \brief Checks if I/O that this object represents has completed.
93
94    @return true if I/O has been completed or false if it's still
95            incomplete. Regardless of the returned value, caller should
96            check GetLastError to validate that handle was OK.
97  */
98  virtual bool IsCompleted();
99
100 public:
101  /// Gets overlapped structure for this I/O
102  LPOVERLAPPED overlapped() {
103    return &overlapped_;
104  }
105
106  /// Gets parent object
107  AdbEndpointObject* parent_io_object() const {
108    return parent_io_object_;
109  }
110
111  /// Gets parent object handle
112  ADBAPIHANDLE GetParentObjectHandle() const {
113    return (NULL != parent_io_object()) ? parent_io_object()->adb_handle() :
114                                          NULL;
115  }
116
117  // This is a helper for extracting object from the AdbObjectHandleMap
118  static AdbObjectType Type() {
119    return AdbObjectTypeIoCompletion;
120  }
121
122 protected:
123  /// Overlapped structure for this I/O
124  OVERLAPPED          overlapped_;
125
126  /// Parent I/O object
127  AdbEndpointObject*  parent_io_object_;
128
129  /// Expected number of bytes transferred in thi I/O
130  ULONG               expected_transfer_size_;
131};
132
133#endif  // ANDROID_USB_API_ADB_IO_COMPLETION_H__
134