rpms/sssd
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
80cc892c48
sssd/0002-sbus-improve-documentation-of-SBUS_INTERFACE.patch
Adam Williamson 786d467c78 Backport fix for RHBZ #1676946 (see upstream #3924) 
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).
2019-02-13 17:55:26 -08:00

268 lines
8.8 KiB
Diff
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink