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 common.h 33 * 34 * @brief Provides common objects and functions for Samgr and external modules. 35 * 36 * 37 * This file provides simplified vector containers and downcast functions. \n 38 * 39 * @since 1.0 40 * @version 1.0 41 */ 42 43 #ifndef LITE_COMMON_H 44 #define LITE_COMMON_H 45 46 #include "ohos_types.h" 47 48 #ifdef __cplusplus 49 #if __cplusplus 50 extern "C" { 51 #endif 52 #endif 53 54 typedef void *MQueueId; 55 typedef void *MutexId; 56 typedef void *ThreadId; 57 58 /** 59 * @brief Calculates the offset of the member in the T type. 60 * 61 * 62 * 63 * @param Indicates the T type. 64 * @param member Indicates the name of the T member variable. 65 * 66 * @since 1.0 67 * @version 1.0 68 */ 69 #define GET_OFFSIZE(T, member) (long)((char *)&(((T *)(0))->member)) 70 71 /** 72 * @brief Downcasts the pointer to the T type. 73 * 74 * 75 * 76 * @param Ptr Indicates the current pointer, which is the address of the T member variable. 77 * @param T Indicates the target type of the downcast. 78 * @param member Indicates the name of the {@code Ptr} as a T member variable. 79 * 80 * @since 1.0 81 * @version 1.0 82 */ 83 #define GET_OBJECT(Ptr, T, member) (T *)(((char *)(Ptr)) - GET_OFFSIZE(T, member)) 84 85 /** 86 * @brief Indicates an invalid vector index. The value is <b>-1</b>. 87 * 88 * This macro indicates that the vector operation fails. \n 89 * <b>INVALID_INDEX</b> is returned if an element cannot be found by {@link VECTOR_Find} or added 90 * to <b>VECTOR_Add</b>. 91 * 92 */ 93 #define INVALID_INDEX (-1) 94 typedef void *(*VECTOR_Key)(const void *); 95 typedef int (*VECTOR_Compare)(const void *, const void *); 96 97 /** 98 * @brief Defines the simplified vector class, which is extended by four elements. 99 * 100 * 101 * This class is applicable to the C language development scenario where the data volume is small 102 * and dynamic expansion is required. \n 103 * 104 */ 105 typedef struct SimpleVector { 106 /** Maximum number of data records that can be stored. The initial value is <b>0</b>. */ 107 int16 max; 108 /** Peak value of the number of stored data records. The initial value is <b>0</b>. */ 109 int16 top; 110 /** Number of data records that have been released. The initial value is <b>0</b>. */ 111 int16 free; 112 /** Data storage pointer */ 113 void **data; 114 /** 115 * Converts a data element into a key for comparison. The key is provided by users, and the 116 * default value is <b>NULL</b>. 117 */ 118 VECTOR_Key key; 119 /** 120 * Compares the sizes of key1 and key2, which are provided by users. The value <b>1</b> 121 * indicates that key1 is greater than key2, the value <b>0</b> indicates that key1 is equal 122 * to key2, and the value <b>-1</b> indicates that key1 is less than key2. The default value 123 * is <b>NULL</b>. 124 */ 125 VECTOR_Compare compare; 126 } Vector; 127 128 /** 129 * @brief Creates or initializes a vector object. 130 * 131 * This function is used to create or initialize a vector object. \n 132 * 133 * @param key Indicates the pointer to the function provided by users for converting data elements 134 * into key values. If this function is not provided, set it to <b>NULL</b>. 135 * @param compare Indicates the pointer to the function for comparing the sizes of two elements. 136 * If this function is not provided, set it to <b>NULL</b>. 137 * @return Returns the vector right value object. 138 * @since 1.0 139 * @version 1.0 140 */ 141 Vector VECTOR_Make(VECTOR_Key key, VECTOR_Compare compare); 142 143 /** 144 * @brief Destruct a vector object. 145 * 146 * This function is used to clear the memory applied by the vector after the temporary vector in 147 * the stack is used. \n 148 * 149 * @param vector Indicates the pointer to the vector to clear. 150 * @since 1.0 151 * @version 1.0 152 */ 153 void VECTOR_Clear(Vector *vector); 154 155 /** 156 * @brief Adds an element to the vector. 157 * 158 * This function is used to add an element to the vector. \n 159 * 160 * @param vector Indicates the <b>this</b> pointer to the vector. 161 * @param element Indicates the element to add. 162 * @return Returns the location of the element to be added if the operation is successful; returns 163 * {@link INVALID_INDEX} if the operation fails. 164 * @since 1.0 165 * @version 1.0 */ 166 int16 VECTOR_Add(Vector *vector, void *element); 167 168 /** 169 * @brief Obtains the number of elements in the vector, including elements that have been set to 170 * <b>NULL</b>. 171 * 172 * This function is used for full traversal. \n 173 * 174 * @param vector Indicates the <b>this</b> pointer to the vector. 175 * @return Returns the top value of the vector, which indicates the number of elements. 176 * @since 1.0 177 * @version 1.0 178 */ 179 int16 VECTOR_Size(Vector *vector); 180 181 /** 182 * @brief Obtains the number of valid elements in the vector, excluding elements that have been set 183 * to <b>NULL</b>. 184 * 185 * This function is used to check whether the number of elements reaches the upper limit. \n 186 * 187 * @param vector Indicates the <b>this</b> pointer to the vector. 188 * @return Returns the top - free value of the vector, which indicates the number of non-null 189 * elements. 190 * @since 1.0 191 * @version 1.0 192 */ 193 int16 VECTOR_Num(Vector *vector); 194 195 /** 196 * @brief Obtains the element at a specified position. 197 * 198 * This function is used to obtain the element at a specified position. 199 * 200 * @param vector Indicates the <b>this</b> pointer to the vector. 201 * @param index Indicates the subscript to be obtained. 202 * @return Returns the element if obtained; returns <b>NULL</b> otherwise. 203 * @since 1.0 204 * @version 1.0 205 */ 206 void *VECTOR_At(Vector *vector, int16 index); 207 208 /** 209 * @brief Swaps the element at a specified position in a vector with another element. 210 * 211 * This function is used to clear, sort, or update elements in the vector. \n 212 * 213 * @param vector Indicates the <b>this</b> pointer to the vector. 214 * @param index Indicates the position of the element to be swapped. 215 * @param element Indicates the pointer to the new element. 216 * @attention Before using this function, ensure that the index is valid. You can use 217 * <b>VECTOR_Size</b> to obtain the upper limit of the index. 218 * @return Returns the original element if the swapping is successful; returns <b>NULL</b> 219 * if the swapping fails. 220 * @see VECTOR_Size 221 * @since 1.0 222 * @version 1.0 223 */ 224 void *VECTOR_Swap(Vector *vector, int16 index, void *element); 225 226 /** 227 * @brief Checks the position of an element. 228 * 229 * This function is used to check whether a vector has a specified element. \n 230 * 231 * @param vector Indicates the <b>this</b> pointer to the vector. 232 * @param element Indicates the element to be checked. 233 * @return Returns the index of the element that is not less than 0 if the check is successful; 234 * returns {@link INVALID_INDEX} if the check fails. 235 * @since 1.0 236 * @version 1.0 237 */ 238 int16 VECTOR_Find(Vector *vector, const void *element); 239 240 /** 241 * @brief Checks the position of the element with a specified key. 242 * 243 * This function is used to check an element based on its key value. \n 244 * 245 * @param vector Indicates the <b>this</b> pointer to the vector. 246 * @param key Indicates the pointer to the key value of the element to check. 247 * @return Returns the index of the key element that is not less than 0 if the check is successful; 248 * returns {@link INVALID_INDEX} if the check fails. 249 * @since 1.0 250 * @version 1.0 251 */ 252 int16 VECTOR_FindByKey(Vector *vector, const void *key); 253 254 #ifdef __cplusplus 255 #if __cplusplus 256 } 257 #endif 258 #endif 259 #endif // LITE_COMMON_H 260 /** @} */ 261