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 */
36 class ADBWIN_API_CLASS 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
overlapped()102   LPOVERLAPPED overlapped() {
103     return &overlapped_;
104   }
105 
106   /// Gets parent object
parent_io_object()107   AdbEndpointObject* parent_io_object() const {
108     return parent_io_object_;
109   }
110 
111   /// Gets parent object handle
GetParentObjectHandle()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
Type()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