From 931b39232b82be374256d8532d86903fe1d87bf2 Mon Sep 17 00:00:00 2001 From: Pavel Březina Date: Sat, 1 Mar 2014 12:53:59 +0100 Subject: sss_sifp: introduce API https://fedorahosted.org/sssd/ticket/2254 Reviewed-by: Sumit Bose --- src/lib/sifp/sss_sifp.h | 468 +++++++++++++++++++++++++++++++++++++ src/lib/sifp/sss_sifp_dbus.h | 126 ++++++++++ src/lib/sifp/sss_simpleifp.exports | 43 ++++ 3 files changed, 637 insertions(+) create mode 100644 src/lib/sifp/sss_sifp.h create mode 100644 src/lib/sifp/sss_sifp_dbus.h create mode 100644 src/lib/sifp/sss_simpleifp.exports diff --git a/src/lib/sifp/sss_sifp.h b/src/lib/sifp/sss_sifp.h new file mode 100644 index 000000000..4c6712f5f --- /dev/null +++ b/src/lib/sifp/sss_sifp.h @@ -0,0 +1,468 @@ +/* + Authors: + Pavel Březina + + Copyright (C) 2014 Red Hat + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +#ifndef SSS_SIFP_H_ +#define SSS_SIFP_H_ + +#include +#include +#include + +/** + * @defgroup sss_simpleifp Simple interface to SSSD InfoPipe responder. + * Libsss_simpleifp provides a synchronous interface to simplify basic + * communication with SSSD InfoPipe responder. + * + * This interface is not a full replacement for the complete D-Bus API and it + * provides only access to the most common tasks like fetching attributes + * of SSSD objects. + * + * If there is a need for a more sophisticated communication with the SSSD + * InfoPipe responder a D-Bus API of your choice should be used. + * + * @{ + */ + +/** SSSD InfoPipe bus address */ +#define SSS_SIFP_IFP "org.freedesktop.sssd.infopipe" + +/** SSSD InfoPipe interface */ +#define SSS_SIFP_IFACE_IFP SSS_SIFP_IFP +#define SSS_SIFP_IFACE_COMPONENTS "org.freedesktop.sssd.infopipe.Components" +#define SSS_SIFP_IFACE_SERVICES "org.freedesktop.sssd.infopipe.Services" +#define SSS_SIFP_IFACE_DOMAINS "org.freedesktop.sssd.infopipe.Domains" +#define SSS_SIFP_IFACE_USERS "org.freedesktop.sssd.infopipe.Users" +#define SSS_SIFP_IFACE_GROUPS "org.freedesktop.sssd.infopipe.Groups" + +/** + * Opaque libsss_sifp context. One context shall not be used by multiple + * threads. Each thread needs to create and use its own context. + * + * @see sss_sifp_init + * @see sss_sifp_init_ex + */ +typedef struct sss_sifp_ctx sss_sifp_ctx; + +/** + * Typedef for memory allocation functions + */ +typedef void (sss_sifp_free_func)(void *ptr, void *pvt); +typedef void *(sss_sifp_alloc_func)(size_t size, void *pvt); + +/** + * Error codes used by libsss_sifp + */ +typedef enum sss_sifp_error { + /** Success */ + SSS_SIFP_OK = 0, + + /** Ran out of memory during processing */ + SSS_SIFP_OUT_OF_MEMORY, + + /** Invalid argument */ + SSS_SIFP_INVALID_ARGUMENT, + + /** + * Input/output error + * + * @see sss_sifp_get_last_io_error() to get more information + */ + SSS_SIFP_IO_ERROR, + + /** Internal error */ + SSS_SIFP_INTERNAL_ERROR, + + /** Operation not supported */ + SSS_SIFP_NOT_SUPPORTED, + + /** Attribute does not exist */ + SSS_SIFP_ATTR_MISSING, + + /** Attribute does not have any value set */ + SSS_SIFP_ATTR_NULL, + + /** Incorrect attribute type */ + SSS_SIFP_INCORRECT_TYPE, + + /** Always last */ + SSS_SIFP_ERROR_SENTINEL +} sss_sifp_error; + +/** + * D-Bus object attribute + */ +typedef struct sss_sifp_attr sss_sifp_attr; + +/** + * D-Bus object + */ +typedef struct sss_sifp_object { + char *name; + char *object_path; + char *interface; + sss_sifp_attr **attrs; +} sss_sifp_object; + +/** + * @brief Initialize sss_sifp context using default allocator (malloc) + * + * @param[out] _ctx sss_sifp context + */ +sss_sifp_error +sss_sifp_init(sss_sifp_ctx **_ctx); + +/** + * @brief Initialize sss_sifp context + * + * @param[in] alloc_pvt Private data for allocation routine + * @param[in] alloc_func Function to allocate memory for the context, if + * NULL malloc() is used + * @param[in] free_func Function to free the memory of the context, if + * NULL free() is used + * @param[out] _ctx sss_sifp context + */ +sss_sifp_error +sss_sifp_init_ex(void *alloc_pvt, + sss_sifp_alloc_func *alloc_func, + sss_sifp_free_func *free_func, + sss_sifp_ctx **_ctx); + +/** + * @brief Return last error name from underlying D-Bus communication + * + * @param[in] ctx sss_sifp context + * @return Error message or NULL if no error occurred during last D-Bus call. + */ +const char * +sss_sifp_get_last_io_error_name(sss_sifp_ctx *ctx); + +/** + * @brief Return last error message from underlying D-Bus communication + * + * @param[in] ctx sss_sifp context + * @return Error message or NULL if no error occurred during last D-Bus call. + */ +const char * +sss_sifp_get_last_io_error_message(sss_sifp_ctx *ctx); + +/** + * @brief Fetch selected attributes of given object. + * + * @param[in] ctx sss_sifp context + * @param[in] object_path D-Bus object path + * @param[in] interface D-Bus interface + * @param[in] name Name of desired attribute + * @param[out] _attrs List of acquired attributes + */ +sss_sifp_error +sss_sifp_fetch_attr(sss_sifp_ctx *ctx, + const char *object_path, + const char *interface, + const char *name, + sss_sifp_attr ***_attrs); + +/** + * @brief Fetch all attributes of given object. + * + * @param[in] ctx sss_sifp context + * @param[in] object_path D-Bus object path + * @param[in] interface D-Bus interface + * @param[out] _attrs Acquired attributes + */ +sss_sifp_error +sss_sifp_fetch_all_attrs(sss_sifp_ctx *ctx, + const char *object_path, + const char *interface, + sss_sifp_attr ***_attrs); + +/** + * @brief Fetch D-Bus object. + * + * @param[in] ctx sss_sifp context + * @param[in] object_path D-Bus object path + * @param[in] interface D-Bus interface + * @param[out] _object Object and its attributes + */ +sss_sifp_error +sss_sifp_fetch_object(sss_sifp_ctx *ctx, + const char *object_path, + const char *interface, + sss_sifp_object **_object); + +/** + * @brief Find attribute in list and return its value. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _value Output value + */ +sss_sifp_error +sss_sifp_find_attr_as_bool(sss_sifp_attr **attrs, + const char *name, + bool *_value); + +/** + * @brief Find attribute in list and return its value. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _value Output value + */ +sss_sifp_error +sss_sifp_find_attr_as_int16(sss_sifp_attr **attrs, + const char *name, + int16_t *_value); + +/** + * @brief Find attribute in list and return its value. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _value Output value + */ +sss_sifp_error +sss_sifp_find_attr_as_uint16(sss_sifp_attr **attrs, + const char *name, + uint16_t *_value); + +/** + * @brief Find attribute in list and return its value. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _value Output value + */ +sss_sifp_error +sss_sifp_find_attr_as_int32(sss_sifp_attr **attrs, + const char *name, + int32_t *_value); + +/** + * @brief Find attribute in list and return its value. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _value Output value + */ +sss_sifp_error +sss_sifp_find_attr_as_uint32(sss_sifp_attr **attrs, + const char *name, + uint32_t *_value); + +/** + * @brief Find attribute in list and return its value. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _value Output value + */ +sss_sifp_error +sss_sifp_find_attr_as_int64(sss_sifp_attr **attrs, + const char *name, + int64_t *_value); + +/** + * @brief Find attribute in list and return its value. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _value Output value + */ +sss_sifp_error +sss_sifp_find_attr_as_uint64(sss_sifp_attr **attrs, + const char *name, + uint64_t *_value); + +/** + * @brief Find attribute in list and return its value. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _value Output value + */ +sss_sifp_error +sss_sifp_find_attr_as_string(sss_sifp_attr **attrs, + const char *name, + const char **_value); + +/** + * @brief Find attribute in list and return its values. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _num_values Number of values in the array + * @param[out] _value Output array + */ +sss_sifp_error +sss_sifp_find_attr_as_bool_array(sss_sifp_attr **attrs, + const char *name, + unsigned int *_num_values, + bool **_value); + +/** + * @brief Find attribute in list and return its values. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _num_values Number of values in the array + * @param[out] _value Output array + */ +sss_sifp_error +sss_sifp_find_attr_as_int16_array(sss_sifp_attr **attrs, + const char *name, + unsigned int *_num_values, + int16_t **_value); + +/** + * @brief Find attribute in list and return its values. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _num_values Number of values in the array + * @param[out] _value Output array + */ +sss_sifp_error +sss_sifp_find_attr_as_uint16_array(sss_sifp_attr **attrs, + const char *name, + unsigned int *_num_values, + uint16_t **_value); + +/** + * @brief Find attribute in list and return its values. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _num_values Number of values in the array + * @param[out] _value Output array + */ +sss_sifp_error +sss_sifp_find_attr_as_int32_array(sss_sifp_attr **attrs, + const char *name, + unsigned int *_num_values, + int32_t **_value); + +/** + * @brief Find attribute in list and return its values. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _num_values Number of values in the array + * @param[out] _value Output array + */ +sss_sifp_error +sss_sifp_find_attr_as_uint32_array(sss_sifp_attr **attrs, + const char *name, + unsigned int *_num_values, + uint32_t **_value); + +/** + * @brief Find attribute in list and return its values. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _num_values Number of values in the array + * @param[out] _value Output array + */ +sss_sifp_error +sss_sifp_find_attr_as_int64_array(sss_sifp_attr **attrs, + const char *name, + unsigned int *_num_values, + int64_t **_value); + +/** + * @brief Find attribute in list and return its values. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _num_values Number of values in the array + * @param[out] _value Output array + */ +sss_sifp_error +sss_sifp_find_attr_as_uint64_array(sss_sifp_attr **attrs, + const char *name, + unsigned int *_num_values, + uint64_t **_value); + +/** + * @brief Find attribute in list and return its values. + * + * @param[in] attrs Attributes + * @param[in] name Name of the attribute to find + * @param[out] _num_values Number of values in the array + * @param[out] _value Output array + */ +sss_sifp_error +sss_sifp_find_attr_as_string_array(sss_sifp_attr **attrs, + const char *name, + unsigned int *_num_values, + const char * const **_value); + +/** + * @brief Free sss_sifp context and set it to NULL. + * + * @param[in,out] _ctx sss_sifp context + */ +void +sss_sifp_free(sss_sifp_ctx **_ctx); + +/** + * @brief Free attribute list and set it to NULL. + * + * @param[in] ctx sss_sifp context + * @param[in,out] _attrs Attributes + */ +void +sss_sifp_free_attrs(sss_sifp_ctx *ctx, + sss_sifp_attr ***_attrs); + +/** + * @brief Free sss_sifp object and set it to NULL. + * + * @param[in] ctx sss_sifp context + * @param[in,out] _object Object + */ +void +sss_sifp_free_object(sss_sifp_ctx *ctx, + sss_sifp_object **_object); + +/** + * @brief Free string and set it to NULL. + * + * @param[in] ctx sss_sifp context + * @param[in,out] _str String + */ +void +sss_sifp_free_string(sss_sifp_ctx *ctx, + char **_str); + +/** + * @brief Free array of strings and set it to NULL. + * + * @param[in] ctx sss_sifp context + * @param[in,out] _str_array Array of strings + */ +void +sss_sifp_free_string_array(sss_sifp_ctx *ctx, + char ***_str_array); + +/** + * @} + */ +#endif /* SSS_SIFP_H_ */ diff --git a/src/lib/sifp/sss_sifp_dbus.h b/src/lib/sifp/sss_sifp_dbus.h new file mode 100644 index 000000000..57b136528 --- /dev/null +++ b/src/lib/sifp/sss_sifp_dbus.h @@ -0,0 +1,126 @@ +/* + Authors: + Pavel Březina + + Copyright (C) 2014 Red Hat + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +#ifndef SSS_SIFP_DBUS_H_ +#define SSS_SIFP_DBUS_H_ + +#include +#include + +/** + * @defgroup sss_sifp_dbus Advanced InfoPipe method calls. + * + * Functions in this module provide a way to reuse sss_sifp connection + * to the SSSD's InfoPipe responder. + * + * This allows the caller to send more sophisticated messages to the InfoPipe + * and to use both sss_sifp and D-Bus without the need of maintaining two + * separate D-Bus connections. + * + * However, these functions require the caller to understand the D-Bus + * bindings from libdbus. + * + * @{ + */ + +/** + * @brief Create a new method call message for SSSD InfoPipe bus. + * + * @param[in] object_path D-Bus object path + * @param[in] interface D-Bus interface + * @param[in] method D-Bus method + * + * @return D-Bus message. + */ +DBusMessage * +sss_sifp_create_message(const char *object_path, + const char *interface, + const char *method); + +/** + * @brief Send D-Bus message to SSSD InfoPipe bus with 5 seconds timeout. + * + * @param[in] ctx sss_sifp context + * @param[in] msg D-Bus message + * @param[in] _reply D-Bus reply, may be NULL if the caller is not interested + * + * @return D-Bus message. + */ +sss_sifp_error +sss_sifp_send_message(sss_sifp_ctx *ctx, + DBusMessage *msg, + DBusMessage **_reply); + +/** + * @brief Send D-Bus message to SSSD InfoPipe bus. + * + * @param[in] ctx sss_sifp context + * @param[in] msg D-Bus message + * @param[in] timeout Timeout + * @param[in] _reply D-Bus reply, may be NULL if the caller is not interested + * + * @return D-Bus message. + */ +sss_sifp_error +sss_sifp_send_message_ex(sss_sifp_ctx *ctx, + DBusMessage *msg, + int timeout, + DBusMessage **_reply); + +/** + * @brief List objects that satisfies given conditions. This routine will + * invoke List D-Bus method on SSSD InfoPipe interface. Arguments + * to this method are given as standard variadic D-Bus arguments. + * + * @param[in] ctx sss_sifp context + * @param[in] method D-Bus method to call without the 'List' prefix + * @param[out] _object_paths List of object paths + * @param[in] first_arg_type Type of the first D-Bus argument + * @param[in] ... D-Bus arguments + */ +sss_sifp_error +sss_sifp_invoke_list(sss_sifp_ctx *ctx, + const char *method, + char ***_object_paths, + int first_arg_type, + ...); + +/** + * @brief Find single object that satisfies given conditions. This routine will + * invoke Find D-Bus method on SSSD InfoPipe interface. Arguments + * to this method are given as standard variadic D-Bus arguments. + * + * @param[in] ctx sss_sifp context + * @param[in] method D-Bus method to call without the 'Find' prefix + * @param[out] _object_path Object path + * @param[in] first_arg_type Type of the first D-Bus argument + * @param[in] ... D-Bus arguments + */ +sss_sifp_error +sss_sifp_invoke_find(sss_sifp_ctx *ctx, + const char *method, + char **_object_path, + int first_arg_type, + ...); + +/** + * @} + */ +#endif /* SSS_SIFP_DBUS_H_ */ diff --git a/src/lib/sifp/sss_simpleifp.exports b/src/lib/sifp/sss_simpleifp.exports new file mode 100644 index 000000000..168d08fdd --- /dev/null +++ b/src/lib/sifp/sss_simpleifp.exports @@ -0,0 +1,43 @@ +SSS_SIMPLEIFP_0.0 { + + # public functions + global: + + sss_sifp_init; + sss_sifp_init_ex; + sss_sifp_get_last_io_error_name; + sss_sifp_get_last_io_error_message; + sss_sifp_create_message; + sss_sifp_send_message; + sss_sifp_send_message_ex; + sss_sifp_fetch_attr; + sss_sifp_fetch_all_attrs; + sss_sifp_fetch_object; + sss_sifp_invoke_list; + sss_sifp_invoke_find; + sss_sifp_find_attr_as_bool; + sss_sifp_find_attr_as_int16; + sss_sifp_find_attr_as_uint16; + sss_sifp_find_attr_as_int32; + sss_sifp_find_attr_as_uint32; + sss_sifp_find_attr_as_int64; + sss_sifp_find_attr_as_uint64; + sss_sifp_find_attr_as_string; + sss_sifp_find_attr_as_bool_array; + sss_sifp_find_attr_as_int16_array; + sss_sifp_find_attr_as_uint16_array; + sss_sifp_find_attr_as_int32_array; + sss_sifp_find_attr_as_uint32_array; + sss_sifp_find_attr_as_int64_array; + sss_sifp_find_attr_as_uint64_array; + sss_sifp_find_attr_as_string_array; + sss_sifp_free; + sss_sifp_free_attrs; + sss_sifp_free_object; + sss_sifp_free_string; + sss_sifp_free_string_array; + + # everything else is local + local: + *; +}; -- cgit