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