Home | History | Annotate | Download | only in api 
      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
    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