1 /* 2 * Copyright (c) 2020 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Samgr 18 * @{ 19 * 20 * @brief Manages system capabilities. 21 * 22 * This module provides the development framework base of the service-oriented architecture (SOA). 23 * You can develop your own abilities based on the Samgr development framework. \n 24 * This module provides basic models of services, features, and functions, and registration and 25 * discovery capabilities. \n 26 * 27 * @since 1.0 28 * @version 1.0 29 */ 30 31 /** 32 * @file iunknown.h 33 * 34 * @brief Provides the base class and default implementation for external functions of system capabilities. 35 * 36 * @since 1.0 37 * @version 1.0 38 */ 39 40 #ifndef LITE_IUNKOWN_H 41 #define LITE_IUNKOWN_H 42 43 #include "common.h" 44 #include "ohos_errno.h" 45 46 #ifdef __cplusplus 47 #if __cplusplus 48 extern "C" { 49 #endif 50 #endif 51 52 typedef struct IUnknown IUnknown; 53 54 /** 55 * @brief Defines the default IUnknown version. You can customize the version. 56 * 57 * The <b>IUnknown</b> interface of the default version can be called only in the current process. 58 * Inter-process communication is not supported. \n 59 * 60 * @since 1.0 61 * @version 1.0 62 */ 63 #define DEFAULT_VERSION 0x20 64 65 /** 66 * @brief Defines the macro for inheriting the <b>IUnknown</b> interface. 67 * 68 * When developing a subclass of the <b>IUnknown</b> class, you can use this macro to inherit the 69 * structures of the <b>IUnknown</b> interface. \n 70 * 71 */ 72 #define INHERIT_IUNKNOWN \ 73 int (*QueryInterface)(IUnknown *iUnknown, int version, void **target); \ 74 int (*AddRef)(IUnknown *iUnknown); \ 75 int (*Release)(IUnknown *iUnknown) 76 77 /** 78 * @brief Defines the macro for inheriting the classes that implement the <b>IUnknown</b> 79 * interface. 80 * 81 * When developing a subclass of a class that implements the <b>IUnknown</b> interface, you can use 82 * this macro to inherit the structures of the <b>IUnknown</b> implementation class. \n 83 * 84 */ 85 #define INHERIT_IUNKNOWNENTRY(T) \ 86 uint16 ver; \ 87 int16 ref; \ 88 T iUnknown 89 90 /** 91 * @brief Defines the default marco for initializing the <b>IUnknown</b> interface. 92 * 93 * When creating a subclass object of the <b>IUnknown</b> interface, you can use this macro to 94 * initialize members of the <b>IUnknown</b> interface to their default values. \n 95 * 96 */ 97 #define DEFAULT_IUNKNOWN_IMPL \ 98 .QueryInterface = IUNKNOWN_QueryInterface, \ 99 .AddRef = IUNKNOWN_AddRef, \ 100 .Release = IUNKNOWN_Release 101 102 /** 103 * @brief Defines the macro for initializing the classes that implement the <b>IUnknown</b> 104 * interface. 105 * 106 * When creating a subclass object of a class that implements the <b>IUnknown</b> interface, you 107 * can use this macro to initialize members of the <b>IUnknown</b> implementation class to their 108 * default values. \n 109 * You need to add the initialization of the customized member variable. \n 110 * 111 */ 112 #define IUNKNOWN_ENTRY_BEGIN(version) \ 113 .ver = (version), \ 114 .ref = 1, \ 115 .iUnknown = { \ 116 DEFAULT_IUNKNOWN_IMPL 117 118 /** 119 * @brief IUnknown Defines the end macro for initializing the <b>IUnknown</b> implementation 120 * object. 121 * 122 * This macro is used when a subclass object of the <b>IUnknown</b> implementation class is 123 * initialized. \n 124 * 125 */ 126 #define IUNKNOWN_ENTRY_END } 127 128 #define DEFAULT_IUNKNOWN_ENTRY_BEGIN IUNKNOWN_ENTRY_BEGIN(DEFAULT_VERSION) 129 130 #define DEFAULT_IUNKNOWN_ENTRY_END IUNKNOWN_ENTRY_END 131 132 /** 133 * @brief Obtains the pointer of the <b>IUnknown</b> interface object from the subclass object T 134 * (generic macro) of the <b>IUnknown</b> implementation class. 135 * 136 * Use this macro when registering <b>IUnknown</b> interfaces with Samgr so that you can obtain 137 * the interfaces from the subclass objects of different <b>IUnknown</b> implementation classes. \n 138 * 139 * @since 1.0 140 * @version 1.0 141 */ 142 #define GET_IUNKNOWN(T) (IUnknown *)(&((T).iUnknown)) 143 144 /** 145 * @brief Defines the <b>IUnknown</b> class. 146 * 147 * You need to inherit this structure when developing a subclass of the <b>IUnknown</b> interface. \n 148 * 149 */ 150 struct IUnknown { 151 /** 152 * Queries the subclass object of the <b>IUnknown</b> interface of a specified version 153 * (downcasting). 154 */ 155 int (*QueryInterface)(IUnknown *iUnknown, int version, void **target); 156 /** Adds the reference count. */ 157 int (*AddRef)(IUnknown *iUnknown); 158 /** Release the reference to an <b>IUnknown</b> interface. */ 159 int (*Release)(IUnknown *iUnknown); 160 }; 161 162 /** 163 * @brief Defines the <b>IUnknown</b> implementation class. 164 * 165 * You need to inherit this structure when developing a subclass of the <b>IUnknown</b> 166 * implementation class. \n 167 * 168 * Each <b>IUnknown</b> interface must correspond to one or more <b>IUnknown</b> implementation 169 * classes. \n 170 * 171 */ 172 typedef struct IUnknownEntry { 173 /** Version information of <b>IUnknown</b> interface. */ 174 uint16 ver; 175 /** Reference count of <b>IUnknown</b> interface. */ 176 int16 ref; 177 /** 178 * Implementation of <b>IUnknown</b> interface, which is related to the specific definition 179 * implementation. 180 */ 181 IUnknown iUnknown; 182 } IUnknownEntry; 183 184 /** 185 * @brief Increments the reference count in this <b>IUnknown</b> interface. 186 * 187 * This function is called in <b>QueryInterface</b>. Do not call this function in the 188 * <b>IUnknown<b> interface. \n 189 * 190 * When the <b>QueryInterface</b> function is re-implemented, you need to call this function 191 * in the new <b>QueryInterface</b>. 192 * 193 * The system does not provide a lock to protect functions. Therefore, you need to re-implement 194 * functions if multiple developers are using them. \n 195 * 196 * @param iUnknown Indicates the pointer to the <b>IUnknown<b> interface object. 197 * @return Indicates the number of objects that reference the <b>IUnknown<b> interface. 198 * 199 * @since 1.0 200 * @version 1.0 201 */ 202 int IUNKNOWN_AddRef(IUnknown *iUnknown); 203 204 /** 205 * @brief Queries the <b>IUnknown</b> interfaces of a specified version (downcasting). 206 * 207 * After obtaining the <b>IUnknown</b> interface object, the function caller uses 208 * <b>QueryInterface</b> to convert the object to the required subclass type. \n 209 * The system converts {@link DEFAULT_VERSION} into the subclass type required by the caller. 210 * If the type conversion requirements cannot be met, you need to re-implement this function. \n 211 * 212 * @param iUnknown Indicates the pointer to the <b>IUnknown</b> interface. 213 * @param version Indicates the version of the <b>IUnknown</b> interface object to be converted. 214 * @param target Indicates the <b>IUnknown</b> subclass type required by the caller. This is an 215 * output parameter. 216 * @return Returns <b>EC_SUCCESS</b> if the conversion is successful; returns other error codes 217 * if the conversion fails. 218 * 219 * @since 1.0 220 * @version 1.0 221 */ 222 int IUNKNOWN_QueryInterface(IUnknown *iUnknown, int ver, void **target); 223 224 /** 225 * @brief Releases a reference to an <b>IUnknown</b> interface that is no longer used. 226 * 227 * In the default implementation provided by the system, if the reference count is <b>0</b>, 228 * the memory of the <b>IUnknown</b> interface object and implementation object is not released. \n 229 * 230 * If the memory of the <b>IUnknown</b> interface object and implementation object is dynamically 231 * allocated, this function needs to be re-implemented. \n 232 * If the reference count is <b>0</b>, the memory of the <b>IUnknown</b> interface object and 233 * implementation object is released. \n 234 * 235 * @param iUnknown Indicates the pointer to the <b>IUnknown<b> interface object. 236 * @return Indicates the number of <b>IUnknown<b> interface objects that are referenced after the 237 * current reference is released. 238 * 239 * @since 1.0 240 * @version 1.0 241 */ 242 int IUNKNOWN_Release(IUnknown *iUnknown); 243 244 #ifdef __cplusplus 245 #if __cplusplus 246 } 247 #endif 248 #endif 249 #endif // LITE_IUNKOWN_H 250 /** @} */ 251