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