786d467c78
This backports three commits that are identified in upstream issue #3924 as the fixes for RHBZ #1676946 (failure of sssd to start in current Rawhide).
268 lines
8.8 KiB
Diff
268 lines
8.8 KiB
Diff
From e185b039468ec27bbc905c61c57dffc5496af521 Mon Sep 17 00:00:00 2001
|
|
From: =?UTF-8?q?Pavel=20B=C5=99ezina?= <pbrezina@redhat.com>
|
|
Date: Tue, 5 Feb 2019 10:36:13 +0100
|
|
Subject: [PATCH 2/3] sbus: improve documentation of SBUS_INTERFACE
|
|
|
|
Reviewed-by: Alexey Tikhonov <atikhono@redhat.com>
|
|
---
|
|
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
|
|
|