1 /*
2  * Copyright (c) 2020-2022 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 feature.h
33  *
34  * @brief Defines the base class of a feature.
35  *
36  * This class is used to develop service features. \n
37  * It provides functions for the feature lifecycle of a service. \n
38  *
39  * @since 1.0
40  * @version 1.0
41  */
42 
43 #ifndef LITE_FEATURE_H
44 #define LITE_FEATURE_H
45 
46 #include "message.h"
47 #include "service.h"
48 
49 #ifdef __cplusplus
50 #if __cplusplus
51 extern "C" {
52 #endif
53 #endif
54 
55 typedef struct Feature Feature;
56 
57 /**
58  * @brief Defines the base class of a feature.
59  *
60  * You need to implement the pointer to the feature. \n
61  *
62  * @since 1.0
63  * @version 1.0
64  */
65 struct Feature {
66     /**
67      * @brief Obtains a feature name.
68      *
69      * This function is implemented by developers and called by Samgr during feature registration
70      * and startup. \n
71      *
72      * @param feature Indicates the pointer to the feature.
73      * @return Returns a constant character string less than 16 bytes if the operation is
74      * successful; returns <b>NULL</b> if the operation fails.
75      *
76      * @since 1.0
77      * @version 1.0
78      */
79     const char *(*GetName)(Feature *feature);
80 
81     /**
82      * @brief Initializes a feature.
83      *
84      * This function is implemented by developers. After Samgr dispatches tasks to a service, the
85      * service calls this function in its own tasks. \n
86      *
87      * @param feature Indicates the pointer to the feature.
88      * @param parent Indicates the pointer to the {@link Service} to which the feature belongs.
89      * @param identity Indicates the identity of a feature dispatched by the system.
90      *
91      * @since 1.0
92      * @version 1.0
93      */
94     void (*OnInitialize)(Feature *feature, Service *parent, Identity identity);
95 
96     /**
97      * @brief Stops a feature.
98      *
99      * This function is implemented by developers and is called by Samgr when a feature is
100      * deregistered to stop running services. \n
101      *
102      * @param feature Indicates the pointer to the feature.
103      * @param identity Indicates the {@link Identity} of the feature to be stopped.
104      * @since 1.0
105      * @version 1.0
106      */
107     void (*OnStop)(Feature *feature, Identity identity);
108 
109     /**
110      * @brief Processes a feature message.
111      *
112      * This function is implemented by developers to process requests sent by callers through
113      * IUnknown. \n
114      *
115      * @param feature Indicates the pointer to the feature.
116      * @param request Indicates the request message.
117      * @return Returns <b>TRUE</b> if the processing is successful; returns <b>FALSE</b> if
118      * the processing fails.
119      *
120      * @since 1.0
121      * @version 1.0
122      */
123     BOOL (*OnMessage)(Feature *feature, Request *request);
124 };
125 
126 /**
127  * @brief Inherits from the macro of the feature class.
128  *
129  * This macro provides the capability of inheriting the feature lifecycle. \n
130  *
131  */
132 
133 #define INHERIT_FEATURE                                                         \
134     const char *(*GetName)(Feature *feature);                                   \
135     void (*OnInitialize)(Feature *feature, Service *parent, Identity identity); \
136     void (*OnStop)(Feature *feature, Identity identity);                        \
137     BOOL (*OnMessage)(Feature *feature, Request *request);                      \
138     BOOL (*IsDistributed)(void)
139 #ifdef __cplusplus
140 #if __cplusplus
141 }
142 #endif
143 #endif
144 
145 #endif // LITE_FEATURE_H
146 /** @} */
147