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