From e185b039468ec27bbc905c61c57dffc5496af521 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pavel=20B=C5=99ezina?= Date: Tue, 5 Feb 2019 10:36:13 +0100 Subject: [PATCH 2/3] sbus: improve documentation of SBUS_INTERFACE Reviewed-by: Alexey Tikhonov --- src/sbus/sbus_interface.h | 195 +++++++++++++++++++++++++++----------- 1 file changed, 138 insertions(+), 57 deletions(-) diff --git a/src/sbus/sbus_interface.h b/src/sbus/sbus_interface.h index 45ab4b5ad..2312fde68 100644 --- a/src/sbus/sbus_interface.h +++ b/src/sbus/sbus_interface.h @@ -49,35 +49,47 @@ struct sbus_node; * * @see SBUS_SYNC, SBUS_ASYNC, SBUS_NO_METHODS, SBUS_WITHOUT_METHODS * + * The following examples demonstrate the intended usage of this macro. + * Do not use it in any other way. + * * @example Interface with two methods, one with synchronous handler, * one with asynchronous handler. * - * struct sbus_interface iface = { - * .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD, - * SBUS_METHODS( - * SBUS_SYNC (METHOD, org_freedekstop_sssd, UpdateMembers, - * update_members_sync, pvt_data), - * SBUS_ASYNC(METHOD, org_freedekstop_sssd, UpdateMembersAsync, - * update_members_send, update_members_recv, - * pvt_data) - * ) - * }; + * SBUS_INTERFACE( + * iface_variable, + * org_freedesktop_sssd, + * SBUS_METHODS( + * SBUS_SYNC (METHOD, org_freedekstop_sssd, UpdateMembers, + * update_members_sync, pvt_data), + * SBUS_ASYNC(METHOD, org_freedekstop_sssd, UpdateMembersAsync, + * update_members_send, update_members_recv, + * pvt_data) + * ), + * @signals, + * @properties + * ); * * @example Interface with no methods. * - * struct sbus_interface empty_iface = { - * .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD, - * SBUS_METHODS( - * SBUS_NO_METHODS - * ) - * }; + * SBUS_INTERFACE( + * iface_variable, + * org_freedesktop_sssd, + * SBUS_METHODS( + * SBUS_NO_METHODS + * ), + * @signals, + * @properties + * ); * * or * - * struct sbus_interface empty_iface = { - * .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD, - * SBUS_WITHOUT_METHODS - * }; + * SBUS_INTERFACE( + * iface_variable, + * org_freedesktop_sssd, + * SBUS_WITHOUT_METHODS, + * @signals, + * @properties + * ); */ #define SBUS_METHODS(...) \ { \ @@ -91,30 +103,42 @@ struct sbus_node; * * @see SBUS_EMIT, SBUS_NO_SIGNALS, SBUS_WITHOUT_SIGNALS * + * The following examples demonstrate the intended usage of this macro. + * Do not use it in any other way. + * * @example Interface that can emit a PropertyChanged signal. * - * struct sbus_interface iface = { - * .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD, - * SBUS_SIGNALS( - * SBUS_EMIT(org_freedekstop_sssd, PropertyChanged) - * ) - * }; + * SBUS_INTERFACE( + * iface_variable, + * org_freedesktop_sssd, + * @methods, + * SBUS_SIGNALS( + * SBUS_EMIT(org_freedekstop_sssd, PropertyChanged) + * ), + * @properties + * ); * * @example Interface with no signals. * - * struct sbus_interface empty_iface = { - * .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD, - * SBUS_SIGNALS( - * SBUS_NO_SIGNALS - * ) - * }; + * SBUS_INTERFACE( + * iface_variable, + * org_freedesktop_sssd, + * @methods, + * SBUS_SIGNALS( + * SBUS_NO_SIGNALS + * ), + * @properties + * ); * * or * - * struct sbus_interface empty_iface = { - * .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD, - * SBUS_WITHOUT_SIGNALS - * }; + * SBUS_INTERFACE( + * iface_variable, + * org_freedesktop_sssd, + * @methods, + * SBUS_WITHOUT_SIGNALS, + * @properties + * ); */ #define SBUS_SIGNALS(...) \ { \ @@ -128,35 +152,47 @@ struct sbus_node; * * @see SBUS_SYNC, SBUS_ASYNC, SBUS_NO_PROPERTIES, SBUS_WITHOUT_PROPERTIES * + * The following examples demonstrate the intended usage of this macro. + * Do not use it in any other way. + * * @example Interface with one property with asynchronous getter and * synchronous setter. * - * struct sbus_interface iface = { - * .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD, - * SBUS_PROPERTIES( - * SBUS_SYNC (GETTER, org_freedekstop_sssd, domain_name, - * set_domain_name, pvt_data), - * SBUS_ASYNC(GETTER, org_freedekstop_sssd, domain_name, - * get_domain_name_send, get_domain_name_recv, - * pvt_data) - * ) - * }; + * SBUS_INTERFACE( + * iface_variable, + * org_freedesktop_sssd, + * @methods, + * @signals, + * SBUS_PROPERTIES( + * SBUS_SYNC (GETTER, org_freedekstop_sssd, domain_name, + * set_domain_name, pvt_data), + * SBUS_ASYNC(GETTER, org_freedekstop_sssd, domain_name, + * get_domain_name_send, get_domain_name_recv, + * pvt_data) + * ) + * ); * * @example Interface with no properties. * - * struct sbus_interface empty_iface = { - * .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD, - * SBUS_PROPERTIES( - * SBUS_NO_PROPERTIES - * ) - * }; + * SBUS_INTERFACE( + * iface_variable, + * org_freedesktop_sssd, + * @methods, + * @signals, + * SBUS_PROPERTIES( + * SBUS_NO_PROPERTIES + * ) + * ); * * or * - * struct sbus_interface empty_iface = { - * .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD, - * SBUS_WITHOUT_PROPERTIES - * }; + * SBUS_INTERFACE( + * iface_variable, + * org_freedesktop_sssd, + * @methods, + * @signals, + * SBUS_WITHOUT_PROPERTIES + * ); */ #define SBUS_PROPERTIES(...) \ { \ @@ -239,8 +275,53 @@ struct sbus_node; * @param signals Signals on the interface. * @param properties Properties on the interface. * + * Please note that the following macro introduced to the scope these variables: + * - __varname_m + * - __varname_s + * - __varname_p + * + * These variables are intended for internal purpose only and should not be + * used outside this macro. They are allocated on stack and will be destroyed + * with it. + * + * Additionally, it creates 'struct sbus_interface varname'. This variable + * holds the information about the interfaces you created. The structure and + * all its data are allocated on stack and will be destroyed with it. + * + * The only intended usage of this variable is to assign it to an sbus path + * and then register this path inside the same function where the interface + * is defined. It should not be used in any other way. + * + * The following example demonstrates the intended usage of this macro. + * Do not use it in any other way. + * * @example - * SBUS_INTERFACE(org_freedesktop_sssd, @methods, @signals, @properties) + * SBUS_INTERFACE( + * iface_bus, + * org_freedesktop_DBus, + * SBUS_METHODS( + * SBUS_SYNC(METHOD, org_freedesktop_DBus, Hello, sbus_server_bus_hello, server), + * SBUS_SYNC(METHOD, org_freedesktop_DBus, RequestName, sbus_server_bus_request_name, server), + * ), + * SBUS_SIGNALS( + * SBUS_EMITS(org_freedesktop_DBus, NameOwnerChanged), + * SBUS_EMITS(org_freedesktop_DBus, NameAcquired), + * SBUS_EMITS(org_freedesktop_DBus, NameLost) + * ), + * SBUS_WITHOUT_PROPERTIES + * ); + * + * struct sbus_path paths[] = { + * {"/org/freedesktop/dbus", &iface_bus}, + * {NULL, NULL} + * }; + * + * ret = sbus_router_add_path_map(server->router, paths); + * if (ret != EOK) { + * DEBUG(SSSDBG_CRIT_FAILURE, "Unable to add paths [%d]: %s\n", + * ret, sss_strerror(ret)); + * return ret; + * } * * @see SBUS_METHODS, SBUS_SIGNALS, SBUS_PROPERTIES to create those arguments. */ -- 2.20.1