docs/3_Developer_Guides/5_Controller_Guides/3.6.3_Usage.md

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