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 service.h 33 * 34 * @brief Provides basic types and constants of services. 35 * 36 * This file is mainly used for service development. \n 37 * This file provides basic capabilities such as lifecycle functions of services, inherited macros, 38 * and task configuration. \n 39 * 40 * @since 1.0 41 * @version 1.0 42 */ 43 44 #ifndef LITE_SERVICE_H 45 #define LITE_SERVICE_H 46 47 #include "message.h" 48 49 #ifdef __cplusplus 50 #if __cplusplus 51 extern "C" { 52 #endif 53 #endif 54 55 typedef struct TaskConfig TaskConfig; 56 typedef struct Service Service; 57 58 /** 59 * @brief Enumerates task types. 60 * 61 * These enumerations are used for configuring the task type. \n 62 * 63 * @since 1.0 64 * @version 1.0 65 */ 66 typedef enum TaskType { 67 /** Tasks shared based on their priority by services */ 68 SHARED_TASK = 0, 69 /** Task exclusively occupied by a service */ 70 SINGLE_TASK = 1, 71 /** A specified task shared by multiple services */ 72 SPECIFIED_TASK = 2, 73 /** No task for the service. Generally, this situation does not occur. */ 74 NO_TASK = 0xFF, 75 } TaskType; 76 77 /** 78 * @brief Specifies the tag for the task shared by multiple services. 79 * 80 * These enumerations are used for specifying a multi-service sharing task. \n 81 * 82 * @since 1.0 83 * @version 1.0 84 */ 85 typedef enum SpecifyTag { 86 /** Preset tag */ 87 LEVEL_HIGH = 0, 88 /** Preset tag */ 89 LEVEL_MIDDLE = 1, 90 /** Preset tag */ 91 LEVEL_LOW = 2, 92 /** Customized tag */ 93 LEVEL_CUSTOM_BEGIN, 94 } SpecifyTag; 95 96 /** 97 * @brief Enumerates task priority. 98 * 99 * These enumerations are used for configuring the task priority. \n 100 * The valid range of the priority is (9, 39). \n 101 * 102 * @since 1.0 103 * @version 1.0 104 */ 105 typedef enum TaskPriority { 106 /** Low-priority: (9, 15) */ 107 PRI_LOW = 9, 108 /** Lower than the normal priority: [16, 23) */ 109 PRI_BELOW_NORMAL = 16, 110 /** Normal priority: [24, 31). The log service is available. */ 111 PRI_NORMAL = 24, 112 /** Higher than the normal priority: [32, 39). The communication service is available. */ 113 PRI_ABOVE_NORMAL = 32, 114 /** Upper limit of the priority */ 115 PRI_BUTT = 39, 116 } TaskPriority; 117 118 #pragma pack(1) 119 /** 120 * @brief Defines task configurations for a service. 121 * 122 * This structure defines task configurations for a service, including the task priority, 123 * stack size, queue size, task type, and shared task ID. \n 124 * 125 */ 126 struct TaskConfig { 127 /** 128 * ID of a multi-service sharing task. For details about the level definition, 129 * see {@link SpecifyTag}. 130 */ 131 int16 level; 132 /** Task priority. For details about the definition of priority, see {@link TaskPriority}. */ 133 int16 priority; 134 /** Size of a task stack */ 135 uint16 stackSize; 136 /** Size of a task queue */ 137 uint16 queueSize; 138 /** Task type. For details about the taskFlags definition, see {@link TaskType}. */ 139 uint8 taskFlags; 140 }; 141 #pragma pack() 142 143 /** 144 * @brief Indicates the basic type of a service. 145 * 146 * You need to implement the function pointers of <b>Service</b>. \n 147 * 148 */ 149 struct Service { 150 /** 151 * @brief Obtains the name of a service. 152 * 153 * This function is called by Samgr during service registration and startup. You need to 154 * implement this function. \n 155 * 156 * @param service Indicates the pointer to the service. 157 * @return Returns a constant string no more than 16 bytes if the service name is obtained 158 * successfully; returns <b>NULL</b> if the service name fails to be obtained. 159 * @since 1.0 160 * @version 1.0 */ 161 const char *(*GetName)(Service *service); 162 163 /** 164 * @brief Initializes the service. 165 * 166 * After Samgr assigns tasks to a service, the service calls the function in its own tasks. 167 * You need to implement this function. \n 168 * 169 * @param service Indicates the pointer to the service. 170 * @param identity Indicates the ID allocated by the system to the service. For details, 171 * see {@link Identity}. 172 * @return Returns <b>TRUE</b> if the initialization is successful; returns <b>FALSE</b> 173 * otherwise. 174 * @since 1.0 175 * @version 1.0 176 */ 177 BOOL (*Initialize)(Service *service, Identity identity); 178 179 /** 180 * @brief Processes service messages. 181 * 182 * This function is used to process requests sent by the caller through {@link IUnknown}. 183 * You need to implement this function. \n 184 * 185 * @param service Indicates the pointer to the service. 186 * @param request Indicates the pointer to the request data. 187 * @return Returns <b>TRUE</b> if the message processing is successful; returns <b>FALSE</b> 188 * if the processing fails. 189 * @since 1.0 190 * @version 1.0 191 */ 192 BOOL (*MessageHandle)(Service *service, Request *request); 193 194 /** 195 * @brief Obtains task configurations of a service. 196 * 197 * This function is used to return task configurations. You need to implement this function. \n 198 * 199 * @param service Indicates the pointer to the service. 200 * @return Returns {@link TaskConfig}. 201 * 202 * @since 1.0 203 * @version 1.0 */ 204 TaskConfig (*GetTaskConfig)(Service *service); 205 }; 206 207 /** 208 * @brief Indicates the macro used to inherit the members from the <b>service</b> class. 209 * 210 * This macro provides the capability of inheriting the lifecycle functions of the <b>service</b> 211 * class. You can use this macro to customize the service structure. \n 212 */ 213 #define INHERIT_SERVICE \ 214 const char *(*GetName)(Service * service); \ 215 BOOL (*Initialize)(Service * service, Identity identity); \ 216 BOOL (*MessageHandle)(Service * service, Request * request); \ 217 TaskConfig (*GetTaskConfig)(Service * service) 218 219 #ifdef __cplusplus 220 #if __cplusplus 221 } 222 #endif 223 #endif 224 #endif // LITE_SERVICE_H 225 /** @} */ 226