1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
# Usage
## (Optional) Migrate from the git submodule version
### Remove the git submodule version
If you already use the controller component but use the submodule version then
you have to get rid of it to be sure to link and use the library version. To do
so, you have to do the following:
* deinitialize the submodule using `git`
```bash
# This example assumes that the git submodule is named app-controller-submodule
# and is located at your root project repository.
git submodule deinit app-controller-submodule
```
* remove the relative submodule lines from the `.gitmodules` file
```bash
vim .gitmodules
```
* remove the `ctl-utilities` target link from any CMake target you specified.
Those lines look like:
```bash
TARGET_LINK_LIBRARIES(${TARGET_NAME}
ctl-utilities # REMOVE THIS LINE
${link_libraries}
)
```
### Use the native af-binder functions
The controller redefined some binder's functions to add an abstraction between
several binding versions. But now, as the controller is binding v3 only, the
abstraction layer from the controller has been removed and you should switch
your functions from the old controller's definitions to binder's definitions.
You have to replace any `include` statements of `afb-definitions.h` by
`afb/afb-binding.h` if you included it somewhere. If you have only included
`ctl-config.h` file then you are fine.
```diff
- #include <afb-definitions.h>
+ #include <afb/afb-binding.h>
```
To help migrating gracefully the old controller's definitions, you could use the
sed script to automate the migration for you. From your project root directory,
executes the following commands:
```bash
wget -O controller-migration.sed https://iot.bzh/download/public/tools/controller-migration.sed
for f in $(find . -name *.c -o -name *.h)
do
sed -i -rf controller-migration.sed ${f}
done
```
> **NOTE**: `AFB_ServiceCall` and `AFB_ServiceSync` has been migrated to their
> homologue `afb_api_call_legacy` and `afb_api_call_sync_legacy` respectively
> but you have to be aware that they are *legacy* functions and you should use
> the news call functions `afb_api_call` and `afb_api_call_sync` instead.
> Cf [Binder API functions reference](../af-binder/reference-v3/func-api.html#calls-and-job-functions)
> for more details on these functions.
As a reminder, here are the old controller's functions definitions that you
should migrate:
```c
#define AFB_ReqNone NULL
typedef afb_req_t AFB_ReqT;
typedef afb_api_t AFB_ApiT;
typedef afb_event_t AFB_EventT;
#define AFB_EventIsValid(eventid) eventid
#define AFB_EventPush afb_event_push
#define AFB_ReqSubscribe afb_req_subscribe
#define AFB_EventMake(api, name) afb_api_make_event(api, name)
#define AFB_ReqJson(request) afb_req_json(request)
#define AFB_ReqSuccess afb_req_success
#define AFB_ReqSuccessF afb_req_success_f
#define AFB_ReqFail afb_req_fail
#define AFB_ReqFailF afb_req_fail_f
#define AFB_ReqNotice(request, ...) AFB_REQ_NOTICE (request, __VA_ARGS__)
#define AFB_ReqWarning(request, ...) AFB_REQ_WARNING (request, __VA_ARGS__)
#define AFB_ReqDebug(request, ...) AFB_REQ_DEBUG (request, __VA_ARGS__)
#define AFB_ReqError(request, ...) AFB_REQ_ERROR (request, __VA_ARGS__)
#define AFB_ReqInfo(request, ...) AFB_REQ_INFO (request, __VA_ARGS__)
#define AFB_ApiVerbose(api, level, ...) afb_api_verbose(api, level, __VA_ARGS__)
#define AFB_ApiNotice(api, ...) AFB_API_NOTICE (api, __VA_ARGS__)
#define AFB_ApiWarning(api, ...) AFB_API_WARNING (api, __VA_ARGS__)
#define AFB_ApiDebug(api, ...) AFB_API_DEBUG (api, __VA_ARGS__)
#define AFB_ApiError(api, ...) AFB_API_ERROR (api, __VA_ARGS__)
#define AFB_ApiInfo(api, ...) AFB_API_INFO (api, __VA_ARGS__)
#define AFB_GetApiSettings afb_api_settings
#define AFB_ReqIsValid(request) request
#define AFB_EvtIsValid(evtHandle) evtHandle
#define AFB_ServiceCall(api, ...) afb_api_call_legacy(api, __VA_ARGS__)
#define AFB_ServiceSync(api, ...) afb_api_call_sync_legacy(api, __VA_ARGS__)
#define AFB_ApiCall(api, ...) afb_api_call(api, __VA_ARGS__)
#define AFB_ApiSync(api, ...) afb_api_call_sync(api, __VA_ARGS__)
#define AFB_ReqVCBData afb_req_get_vcbdata
#define AFB_ReqGetApi afb_req_get_api
#define AFB_GetEventLoop(api) afb_api_get_event_loop(api)
#define AFB_RootDirGetFD(api) afb_api_rootdir_get_fd(api)
#define AFB_RequireApi(api, ...) afb_api_require_api(api, __VA_ARGS__)
#define AFB_ClientCtxSet(request, replace, createCB, freeCB, handle) afb_req_context(request, replace, createCB, freeCB, handle)
#define AFB_ClientCtxClear(request) afb_req_context_clear(request)
#define AFB_ReqSetLOA(request, level) afb_req_session_set_LOA(request, level)
#define AFB_NewApi afb_api_new_api
#define AFB_ApiAddVerb afb_api_add_verb
#define AFB_ApiSetUserData afb_api_set_userdata
#define AFB_ApiGetUserData afb_api_get_userdata
#define AFB_ApiOnEvent afb_api_on_event
#define AFB_ApiOnInit afb_api_on_init
#define AFB_ApiSeal afb_api_seal
```
## Add libappcontroller as a static library to your binding
In your `config.cmake` file, add a dependency to the controller library, i.e:
```cmake
set(PKG_REQUIRED_LIST
json-c
afb-daemon
appcontroller --> this is the controller library dependency name.
)
```
Or you can also use the [FIND_PACKAGE](https://cmake.org/cmake/help/v3.6/command/find_package.html?highlight=find_package)
CMake command to add it.
## Declare your controller config section in your binding
```C
// CtlSectionT syntax:
// key: "section name in config file"
// loadCB: callback to process section
// handle: a void* pass to callback when processing section
static CtlSectionT ctlSections[]= {
{.key="plugins" , .loadCB= PluginConfig, .handle= &halCallbacks},
{.key="onload" , .loadCB= OnloadConfig},
{.key="halmap" , .loadCB= MapConfigLoad},
{.key=NULL}
};
```
## Do the controller config parsing at binding pre-init
```C
// check if config file exist
const char *dirList= getenv("CTL_CONFIG_PATH");
if (!dirList) dirList=CONTROL_CONFIG_PATH;
const char *configPath = CtlConfigSearch(apiHandle, dirList, "prefix");
if(!confiPath) return -1;
ctlConfig = CtlConfigLoad(dirList, ctlSections);
if (!ctlConfig) return -1;
```
## Execute the controller config during binding init
```C
int err = CtlConfigExec (ctlConfig);
```
|
