Skip to content

Commit

Permalink
sbus: improve documentation of SBUS_INTERFACE
Browse files Browse the repository at this point in the history 
Reviewed-by: Alexey Tikhonov <atikhono@redhat.com>
  • Loading branch information
@pbrezina @jhrozek
pbrezina authored and jhrozek committed Feb 5, 2019
1 parent 1944388 commit e185b03
Showing 1 changed file with 138 additions and 57 deletions.
195 changes: 138 additions & 57 deletions src/sbus/sbus_interface.h
View file
Expand Up @@ -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(...) \
{ \
Expand All @@ -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(...) \
{ \
Expand All @@ -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(...) \
{ \
Expand Down Expand Up @@ -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.
*/
Expand Down

0 comments on commit e185b03

Please sign in to comment.