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_API_INSTANCE_H__ 18 #define ANDROID_USB_API_ADB_API_INSTANCE_H__ 19 /** \file 20 This file consists of declaration of class AdbApiInstance that is a main 21 API object representing a device interface that is in the interest of 22 the API client. All device (interface) related operations go through this 23 class first. 24 */ 25 26 #include "adb_api.h" 27 #include "adb_api_private_defines.h" 28 29 /** Class AdbApiInstance is the main API interbal object representing a device 30 interface that is in the interest of the API client. All device (interface) 31 related operations go through this class first. So, before doing anything 32 meaningfull with the API a client must first create instance of the API 33 via CreateAdbApiInstance, select a device interface for that instance and 34 then do everything else. 35 Objects of this class are globally stored in the map that matches 36 ADBAPIINSTANCEHANDLE to the corresponded object. 37 This class is self-referenced with the following reference model: 38 1. When object of this class is created and added to the map, its recount 39 is set to 1. 40 2. Every time the client makes an API call that uses ADBAPIINSTANCEHANDLE 41 a corresponded AdbApiInstance object is looked up in the table and its 42 refcount is incremented. Upon return from the API call that incremented 43 the refcount refcount gets decremented. 44 3. When the client closes ADBAPIINSTANCEHANDLE via DeleteAdbApiInstance call 45 corresponded object gets deleted from the map and its refcount is 46 decremented. 47 So, at the end, this object destroys itself when refcount drops to zero. 48 */ 49 class AdbApiInstance { 50 public: 51 /** \brief Constructs the object 52 53 @param handle[in] Instance handle associated with this object 54 */ 55 AdbApiInstance(); 56 57 private: 58 /// Destructs the object 59 ~AdbApiInstance(); 60 61 /** \brief 62 This method is called when last reference to this object has been released 63 64 In this method object is uninitialized and deleted (that is "delete this" 65 is called). 66 */ 67 void LastReferenceReleased(); 68 69 public: 70 /// Gets name of the USB interface (device name) for this instance interface_name()71 const std::wstring& interface_name() const { 72 return interface_name_; 73 } 74 75 /// References the object and returns number of references AddRef()76 LONG AddRef() { 77 return InterlockedIncrement(&ref_count_); 78 } 79 80 /** \brief Dereferences the object and returns number of references 81 82 Object may be deleted in this method, so you cannot touch it after 83 this method returns, even if returned value is not zero, because object 84 can be deleted in another thread. 85 */ Release()86 LONG Release() { 87 LONG ret = InterlockedDecrement(&ref_count_); 88 if (0 == ret) 89 LastReferenceReleased(); 90 91 return ret; 92 } 93 94 /// Checks if instance has been initialized IsInitialized()95 bool IsInitialized() const { 96 return !interface_name_.empty(); 97 } 98 99 private: 100 /// Name of the USB interface (device name) for this instance 101 std::wstring interface_name_; 102 103 /// Instance handle for this object 104 ADBAPIINSTANCEHANDLE instance_handle_; 105 106 /// Reference counter for this instance 107 LONG ref_count_; 108 }; 109 110 /// Defines map that matches ADBAPIINSTANCEHANDLE with AdbApiInstance object 111 typedef std::map< ADBAPIINSTANCEHANDLE, AdbApiInstance* > AdbApiInstanceMap; 112 113 #endif // ANDROID_USB_API_ADB_API_INSTANCE_H__ 114