1dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine/* 2dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * Copyright (C) 2006 The Android Open Source Project 3dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * 4dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * Licensed under the Apache License, Version 2.0 (the "License"); 5dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * you may not use this file except in compliance with the License. 6dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * You may obtain a copy of the License at 7dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * 8dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * http://www.apache.org/licenses/LICENSE-2.0 9dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * 10dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * Unless required by applicable law or agreed to in writing, software 11dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * distributed under the License is distributed on an "AS IS" BASIS, 12dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * See the License for the specific language governing permissions and 14dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine * limitations under the License. 15dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine */ 16dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 17dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine#ifndef ANDROID_USB_API_ADB_OBJECT_HANDLE_H__ 18dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine#define ANDROID_USB_API_ADB_OBJECT_HANDLE_H__ 19dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine/** \file 20dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine This file consists of declaration of a class AdbObjectHandle that 21dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine encapsulates an internal API object that is visible to the outside 22dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine of the API through a handle. 23dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine*/ 24dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 25acc6f826433e639b1ba00c021ab5f9161eb56e59vchtchetkine#include "adb_api.h" 26dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine#include "adb_api_private_defines.h" 27dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 28dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine/** \brief Defines types of internal API objects 29dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine*/ 30dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkineenum AdbObjectType { 31dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// Object is AdbInterfaceEnumObject. 32dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectTypeInterfaceEnumerator, 33dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 34dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// Object is AdbInterfaceObject. 35dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectTypeInterface, 36dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 37dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// Object is AdbEndpointObject. 38dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectTypeEndpoint, 39dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 40dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// Object is AdbIOCompletion. 41dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectTypeIoCompletion, 42dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 43dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectTypeMax 44dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine}; 45dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 46dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine/** \brief Encapsulates an internal API basic object that is visible to the 47dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine outside of the API through a handle. 48dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 49dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine In order to prevent crashes when API client tries to access an object through 50dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine an invalid or already closed handle, we keep track of all opened handles in 51dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectHandleMap that maps association between valid ADBAPIHANDLE and 52dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine an object that this handle represents. All objects that are exposed to the 53dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine outside of API via ADBAPIHANDLE are self-destructing referenced objects. 54dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine The reference model for these objects is as such: 55dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 1. When CreateHandle() method is called on an object, a handle (ADBAPIHANDLE 56dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine that is) is assigned to it, a pair <handle, object> is added to the global 57dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectHandleMap instance, object is referenced and then handle is 58dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine returned to the API client. 59dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 2. Every time API is called with a handle, a lookup is performed in 60dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectHandleMap to find an object that is associated with the handle. 61dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine If object is not found then ERROR_INVALID_HANDLE is immediatelly returned 62dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine (via SetLastError() call). If object is found then it is referenced and 63dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine API call is dispatched to appropriate method of the found object. Upon 64dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine return from this method, just before returning from the API call, object 65dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine is dereferenced back to match lookup reference. 66dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 3. When object handle gets closed, assuming object is found in the map, that 67dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine <handle, object> pair is deleted from the map and object's refcount is 68dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine decremented to match refcount increment performed when object has been 69dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine added to the map. 70dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 4. When object's refcount drops to zero, the object commits suicide by 71dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine calling "delete this". 72dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine All API objects that have handles that are sent back to API client must be 73dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine derived from this class. 74dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine*/ 75acc6f826433e639b1ba00c021ab5f9161eb56e59vchtchetkineclass ADBWIN_API_CLASS AdbObjectHandle { 76dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine public: 77dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /** \brief Constructs the object 78dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 79dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine Refernce counter is set to 1 in the constructor. 80dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @param[in] obj_type Object type from AdbObjectType enum 81dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine */ 82dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine explicit AdbObjectHandle(AdbObjectType obj_type); 83dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 84dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine protected: 85dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /** \brief Destructs the object. 86dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 87dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine We hide destructor in order to prevent ourseves from accidentaly allocating 88dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine instances on the stack. If such attempt occurs, compiler will error. 89dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine */ 90dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine virtual ~AdbObjectHandle(); 91dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 92dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine public: 93dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /** \brief References the object. 94dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 95dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @return Value of the reference counter after object is referenced in this 96dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine method. 97dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine */ 98dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine virtual LONG AddRef(); 99dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 100dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /** \brief Releases the object. 101dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 102dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine If refcount drops to zero as the result of this release, the object is 103dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine destroyed in this method. As a general rule, objects must not be touched 104dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine after this method returns even if returned value is not zero. 105dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @return Value of the reference counter after object is released in this 106dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine method. 107dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine */ 108dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine virtual LONG Release(); 109dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 110dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /** \brief Creates handle to this object. 111dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 112dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine In this call a handle for this object is generated and object is added 113dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine to the AdbObjectHandleMap. 114dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @return A handle to this object on success or NULL on an error. 115dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine If NULL is returned GetLastError() provides extended error 116dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine information. ERROR_GEN_FAILURE is set if an attempt was 117dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine made to create already opened object. 118dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine */ 119dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine virtual ADBAPIHANDLE CreateHandle(); 120dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 121dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /** \brief This method is called when handle to this object gets closed. 122dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 123dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine In this call object is deleted from the AdbObjectHandleMap. 124dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @return true on success or false if object is already closed. If 125dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine false is returned GetLastError() provides extended error 126dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine information. 127dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine */ 128dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine virtual bool CloseHandle(); 129dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 130dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /** \brief Checks if this object is of the given type. 131dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 132dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @param[in] obj_type One of the AdbObjectType types to check 133dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @return true is this object type matches obj_type, or false otherwise. 134dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine */ 135dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine virtual bool IsObjectOfType(AdbObjectType obj_type) const; 136dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 137dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /** \brief Looks up AdbObjectHandle instance associated with the given handle 138dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine in the AdbObjectHandleMap. 139dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 140dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine This method increments reference counter for the returned found object. 141dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @param[in] adb_handle ADB handle to the object 142dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @return API object associated with the handle or NULL if object is not 143dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine found. If NULL is returned GetLastError() provides extended error 144dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine information. 145dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine */ 146dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine static AdbObjectHandle* Lookup(ADBAPIHANDLE adb_handle); 147dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 148dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine protected: 149dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /** \brief Called when last reference to this object is released. 150dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 151dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine Derived object should override this method to perform cleanup that is not 152dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine suitable for destructors. 153dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine */ 154dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine virtual void LastReferenceReleased(); 155dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 156dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine public: 157dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// Gets ADB handle associated with this object 158dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine ADBAPIHANDLE adb_handle() const { 159dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine return adb_handle_; 160dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine } 161dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 162dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// Gets type of this object 163dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectType object_type() const { 164dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine return object_type_; 165dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine } 166dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 167dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// Checks if object is still opened. Note that it is not guaranteed that 168dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// object remains opened when this method returns. 169dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine bool IsOpened() const { 170dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine return (NULL != adb_handle()); 171dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine } 172dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 173dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine protected: 174dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// API handle associated with this object 175dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine ADBAPIHANDLE adb_handle_; 176dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 177dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// Type of this object 178dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectType object_type_; 179dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 180dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine /// This object's reference counter 181dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine LONG ref_count_; 182dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine}; 183dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 184dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine/// Maps ADBAPIHANDLE to associated AdbObjectHandle object 185dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkinetypedef std::map< ADBAPIHANDLE, AdbObjectHandle* > AdbObjectHandleMap; 186dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 187dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine/** \brief Template routine that unifies extracting of objects of different 188dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine types from the AdbObjectHandleMap 189dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 190dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @param[in] adb_handle API handle for the object 191dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine @return Object associated with the handle or NULL on error. If NULL is 192dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine returned GetLastError() provides extended error information. 193dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine*/ 194dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkinetemplate<class obj_class> 195dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkineobj_class* LookupObject(ADBAPIHANDLE adb_handle) { 196dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine // Lookup object for the handle in the map 197dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine AdbObjectHandle* adb_object = AdbObjectHandle::Lookup(adb_handle); 198dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine if (NULL != adb_object) { 199dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine // Make sure it's of the correct type 200dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine if (!adb_object->IsObjectOfType(obj_class::Type())) { 201dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine adb_object->Release(); 202dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine adb_object = NULL; 203dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine SetLastError(ERROR_INVALID_HANDLE); 204dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine } 205dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine } else { 206dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine SetLastError(ERROR_INVALID_HANDLE); 207dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine } 208dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine return (adb_object != NULL) ? reinterpret_cast<obj_class*>(adb_object) : 209dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine NULL; 210dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine} 211dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine 212dceaaa52cec11631c72cfea5fb74ee607602ecdevchtchetkine#endif // ANDROID_USB_API_ADB_OBJECT_HANDLE_H__ 213