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