From: Jose Bollo Date: Mon, 20 Aug 2018 12:44:31 +0000 (+0200) Subject: Provide functions afb_service_call[_sync]_legacy X-Git-Tag: flounder_5.99.4~12 X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?p=src%2Fapp-framework-binder.git;a=commitdiff_plain;h=6492d061bf5753bb3bb67b771fc2f9ce0c910c2b Provide functions afb_service_call[_sync]_legacy These functions was missing and the documentation was erronous. This fixes that issue by providing the missing functions and updating the documentation. Bug-AGL: SPEC-1669 Change-Id: I543b0fbe29370be6f35f15ca3bfa48fef9ab4055 Signed-off-by: Jose Bollo --- diff --git a/docs/afb-migration-to-binding-v3.md b/docs/afb-migration-to-binding-v3.md index f7e09fd9..29ea1790 100644 --- a/docs/afb-migration-to-binding-v3.md +++ b/docs/afb-migration-to-binding-v3.md @@ -180,6 +180,16 @@ of the context and event subscriptions. The new design allows you to specify: See [calls](reference-v3/func-api/#calls-and-job-functions) and [subcalls](reference-v3/func-req/#subcall-functions). +The table below list the changes to apply: + +| Name in Version 2 | New name of Version 3 +|:----------------------:|:----------------------------------------------------: +| afb_req_subcall | afb_req_subcall_legacy +| afb_req_subcall_sync | afb_req_subcall_sync_legacy +| afb_service_call | afb_service_call_legacy +| afb_service_call_sync | afb_service_call_sync_legacy +| afb_req_subcall_req | afb_req_subcall_req (same but obsolete) + Consider use of event handlers ------------------------------ diff --git a/docs/reference-v3/func-api.md b/docs/reference-v3/func-api.md index ef3816d0..aa28932a 100644 --- a/docs/reference-v3/func-api.md +++ b/docs/reference-v3/func-api.md @@ -279,7 +279,7 @@ struct json_object *afb_api_settings( ```C /** - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. + * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'. * The result of the call is delivered to the 'callback' function with the 'callback_closure'. * * For convenience, the function calls 'json_object_put' for 'args'. @@ -323,7 +323,7 @@ void afb_api_call( ```C /** - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. + * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'. * 'result' will receive the response. * * For convenience, the function calls 'json_object_put' for 'args'. @@ -880,8 +880,10 @@ of work. /** * @deprecated try to use @ref afb_api_call instead * - * * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * The result of the call is delivered to the 'callback' function with the 'callback_closure'. + * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' + * in the name of the binding. + * The result of the call is delivered to the 'callback' function + * with the 'callback_closure'. * * For convenience, the function calls 'json_object_put' for 'args'. * Thus, in the case where 'args' should remain available after @@ -924,7 +926,8 @@ void afb_api_call_legacy( /** * @deprecated try to use @ref afb_api_call_sync instead * - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. + * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' + * in the name of the binding. * 'result' will receive the response. * * For convenience, the function calls 'json_object_put' for 'args'. diff --git a/docs/reference-v3/func-service.md b/docs/reference-v3/func-service.md index 2faa7bcd..b82f9c95 100644 --- a/docs/reference-v3/func-service.md +++ b/docs/reference-v3/func-service.md @@ -2,11 +2,15 @@ Functions of class **afb_service** ============================== All the functions of the class **afb_daemon** use the default api. -These are internally aliased to the corresponding legacy function of -class **afb_api**. + +All these function are deprecated, try to use functions of class **afb_api** instead. + +## afb_service_call ```C /** + * @deprecated try to use @ref afb_api_call instead + * * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. * The result of the call is delivered to the 'callback' function with the 'callback_closure'. * @@ -14,27 +18,43 @@ class **afb_api**. * Thus, in the case where 'args' should remain available after * the function returns, the function 'json_object_get' shall be used. * - * The 'callback' receives 3 arguments: - * 1. 'closure' the user defined closure pointer 'callback_closure', - * 2. 'status' a status being 0 on success or negative when an error occured, - * 2. 'result' the resulting data as a JSON object. + * The 'callback' receives 5 arguments: + * 1. 'closure' the user defined closure pointer 'closure', + * 2. 'object' a JSON object returned (can be NULL) + * 3. 'error' a string not NULL in case of error but NULL on success + * 4. 'info' a string handling some info (can be NULL) + * 5. 'api' the api * * @param api The api name of the method to call * @param verb The verb name of the method to call * @param args The arguments to pass to the method * @param callback The to call on completion - * @param callback_closure The closure to pass to the callback + * @param closure The closure to pass to the callback * - * @see also 'afb_req_subcall' + * + * @see afb_req_subcall + * @see afb_req_subcall_sync + * @see afb_api_call_sync */ void afb_service_call( - const char *api, - const char *verb, - struct json_object *args, - void (*callback)(void*closure, int status, struct json_object *result), - void *callback_closure); + const char *api, + const char *verb, + struct json_object *args, + void (*callback)( + void *closure, + struct json_object *object, + const char *error, + const char * info, + afb_api_t api), + void *closure); +``` +## afb_service_call_sync + +```C /** + * @deprecated try to use @ref afb_api_call_sync instead + * * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. * 'result' will receive the response. * @@ -45,15 +65,98 @@ void afb_service_call( * @param api The api name of the method to call * @param verb The verb name of the method to call * @param args The arguments to pass to the method + * @param object Where to store the returned object - should call json_object_put on it - can be NULL + * @param error Where to store the copied returned error - should call free on it - can be NULL + * @param info Where to store the copied returned info - should call free on it - can be NULL + * + * @returns 0 in case of success or a negative value in case of error. + * + * @see afb_req_subcall + * @see afb_req_subcall_sync + * @see afb_api_call + */ +int afb_service_call_sync( + const char *api, + const char *verb, + struct json_object *args, + struct json_object **object, + char **error, + char **info); +``` + +## afb_service_call_legacy + +```C +/** + * @deprecated try to use @ref afb_api_call instead + * + * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' + * in the name of the binding. + * The result of the call is delivered to the 'callback' function with + * the 'callback_closure'. + * + * For convenience, the function calls 'json_object_put' for 'args'. + * Thus, in the case where 'args' should remain available after + * the function returns, the function 'json_object_get' shall be used. + * + * The 'callback' receives 3 arguments: + * 1. 'closure' the user defined closure pointer 'closure', + * 2. 'status' a status being 0 on success or negative when an error occurred, + * 2. 'result' the resulting data as a JSON object. + * + * @param api The api name of the method to call + * @param verb The verb name of the method to call + * @param args The arguments to pass to the method + * @param callback The to call on completion + * @param closure The closure to pass to the callback + * + * @see also 'afb_api_call' + * @see also 'afb_api_call_sync' + * @see also 'afb_api_call_sync_legacy' + * @see also 'afb_req_subcall' + * @see also 'afb_req_subcall_sync' + */ +void afb_service_call_legacy( + const char *api, + const char *verb, + struct json_object *args, + void (*callback)( + void *closure, + int status, + struct json_object *result, + afb_api_t api), + void *closure); +``` + +## afb_service_call_sync_legacy + +```C +/** + * @deprecated try to use @ref afb_api_call_sync instead + * + * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the + * name of the binding. 'result' will receive the response. + * + * For convenience, the function calls 'json_object_put' for 'args'. + * Thus, in the case where 'args' should remain available after + * the function returns, the function 'json_object_get' shall be used. + * + * @param api The api name of the method to call + * @param verb The verb name of the method to call + * @param args The arguments to pass to the method * @param result Where to store the result - should call json_object_put on it - * * @returns 0 in case of success or a negative value in case of error. * + * @see also 'afb_api_call' + * @see also 'afb_api_call_sync' + * @see also 'afb_api_call_legacy' * @see also 'afb_req_subcall' + * @see also 'afb_req_subcall_sync' */ -int afb_service_call_sync( - const char *api, - const char *verb, - struct json_object *args, - struct json_object **result); -``` \ No newline at end of file +int afb_service_call_sync_legacy( + const char *api, + const char *verb, + struct json_object *args, + struct json_object **result); +``` diff --git a/include/afb/afb-binding-predefs.h b/include/afb/afb-binding-predefs.h index 56ac504b..47907a4a 100644 --- a/include/afb/afb-binding-predefs.h +++ b/include/afb/afb-binding-predefs.h @@ -370,6 +370,8 @@ # define afb_service_call afb_service_call_v3 # define afb_service_call_sync afb_service_call_sync_v3 +# define afb_service_call_legacy afb_service_call_legacy_v3 +# define afb_service_call_sync_legacy afb_service_call_sync_legacy_v3 # define AFB_ERROR AFB_ERROR_V3 # define AFB_WARNING AFB_WARNING_V3 diff --git a/include/afb/afb-binding-v3.h b/include/afb/afb-binding-v3.h index 9df2eb99..84af4861 100644 --- a/include/afb/afb-binding-v3.h +++ b/include/afb/afb-binding-v3.h @@ -259,4 +259,6 @@ extern const struct afb_binding_v3 afbBindingV3; #define afb_service_call_v3(...) afb_api_call(afbBindingV3root,__VA_ARGS__) #define afb_service_call_sync_v3(...) afb_api_call_sync(afbBindingV3root,__VA_ARGS__) +#define afb_service_call_legacy_v3(...) afb_api_call_legacy(afbBindingV3root,__VA_ARGS__) +#define afb_service_call_sync_legacy_v3(...) afb_api_call_sync_legacy(afbBindingV3root,__VA_ARGS__)