sssd_dbus.h revision 10a28f461c25d788ff4dcffefa881e7aa724a25d
/*
SSSD
SSSD - D-BUS interface
Copyright (C) Stephen Gallagher 2008
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 <http://www.gnu.org/licenses/>.
*/
#ifndef _SSSD_DBUS_H_
#define _SSSD_DBUS_H_
struct sbus_connection;
struct sbus_interface;
struct sbus_request;
/* Older platforms (such as RHEL-6) might not have these error constants
* defined */
#ifndef DBUS_ERROR_UNKNOWN_INTERFACE
/** Interface you invoked a method on isn't known by the object. */
#define DBUS_ERROR_UNKNOWN_INTERFACE \
"org.freedesktop.DBus.Error.UnknownInterface"
#endif /* DBUS_ERROR_UNKNOWN_INTERFACE */
#ifndef DBUS_ERROR_UNKNOWN_PROPERTY
/** Property you tried to access isn't known by the object. */
#define DBUS_ERROR_UNKNOWN_PROPERTY \
"org.freedesktop.DBus.Error.UnknownProperty"
#endif /* DBUS_ERROR_UNKNOWN_PROPERTY */
#ifndef DBUS_ERROR_PROPERTY_READ_ONLY
/** Property you tried to set is read-only. */
#define DBUS_ERROR_PROPERTY_READ_ONLY \
"org.freedesktop.DBus.Error.PropertyReadOnly"
#endif /* DBUS_ERROR_PROPERTY_READ_ONLY */
#ifndef DBUS_ERROR_INIT
#endif /* DBUS_ERROR_INIT */
/**
* Note: internal functions do not rely on the value of this constant to
* simplify implementation. If this connstant change, some functions in
* sssd_dbus_interface.c needs to be amended.
*/
#define SBUS_SUBTREE_SUFFIX "/*"
void *handler_data);
/*
* sbus_conn_destructor_fn
* Function to be called when a connection is finalized
*/
typedef int (*sbus_conn_destructor_fn)(void *);
typedef void (*sbus_conn_reconn_callback_fn)(struct sbus_connection *, int, void *);
/*
* sbus_server_conn_init_fn
* Set up function for connection-specific activities
* This function should define the sbus_conn_destructor_fn
* for this connection at a minimum
*/
typedef int (*sbus_server_conn_init_fn)(struct sbus_connection *, void *);
enum {
};
enum {
};
/*
* This represents vtable of interface handlers for methods and
* properties and so on. The actual vtable structs derive from this struct
* (ie: have this struct as their first member).
*
* The offsets for matching vtable function pointers are in sbus_method_meta
* These are used to dynamically dispatch the method invocations.
*/
struct sbus_vtable {
const struct sbus_interface_meta *meta;
int flags; /* unused for now */
/* derived structs place function pointers here. */
};
/* Special interface and method for D-BUS introspection */
#define DBUS_INTROSPECT_INTERFACE "org.freedesktop.DBus.Introspectable"
#define DBUS_INTROSPECT_METHOD "Introspect"
/* Special interface and method for D-BUS properties */
#define DBUS_PROPERTIES_INTERFACE "org.freedesktop.DBus.Properties"
struct sbus_interface {
const char *path;
struct sbus_vtable *vtable;
void *handler_data;
};
/* Server Functions */
struct tevent_context *ev,
const char *address,
bool use_symlink,
struct sbus_connection **server,
/* Connection Functions */
/* sbus_new_connection
* Use this function when connecting a new process to
* the standard SSSD interface.
* This will connect to the address specified and then
* call sbus_add_connection to integrate with the main
* loop.
*/
struct tevent_context *ev,
const char *address,
struct sbus_connection **conn);
/* sbus_add_connection
* Integrates a D-BUS connection with the TEvent main
* loop. Use this function when you already have a
* DBusConnection object (for example from dbus_bus_get)
* Connection type can be either:
* SBUS_CONN_TYPE_PRIVATE: Used only from within a D-BUS
* server such as the Monitor in the
* new_connection_callback
* SBUS_CONN_TYPE_SHARED: Used for all D-BUS client
* connections, including those retrieved from
* dbus_bus_get
*/
struct tevent_context *ev,
int connection_type,
struct sbus_connection **_conn);
/*
* Register a new interface to be available at given object path.
*
* The interface will be exported at @object_path. The method handlers are
* represented by @iface_vtable. @pvt contains additional caller specific data
* which is made available to handlers.
*/
struct sbus_vtable *iface_vtable,
const char *object_path,
void *handler_data);
char *
const char *object_path_part);
char *
const char *object_path_part);
char *
const char *base,
const char *part, ...);
const char *object_path,
const char *prefix,
char ***_components,
const char *object_path,
const char *prefix,
char ***_components);
const char *
sbus_opath_strip_prefix(const char *object_path,
const char *prefix);
char *
const char *object_path,
const char *base_path);
/* max_retries < 0: retry forever
* max_retries = 0: never retry (why are you calling this function?)
* max_retries > 0: obvious
*/
int max_retries,
void *pvt);
/*
* Send a message across the SBUS
* If requested, the DBusPendingCall object will
* be returned to the caller.
*
* This function will return EAGAIN in the event
* that the connection is not open for
* communication.
*/
int timeout_ms,
void *pvt,
DBusMessage *reply);
/* Set up D-BUS access control. If there is a SSSD user, we must allow
* him to connect. root is always allowed */
/*
* This structure is passed to all dbus method and property
* handlers. It is a talloc context which will be valid until
* the request is completed with either the sbus_request_complete()
* or sbus_request_fail() functions.
*/
struct sbus_request {
struct sbus_connection *conn;
struct sbus_interface *intf;
const struct sbus_method_meta *method;
const char *path;
};
/*
* Complete a DBus request, and free the @dbus_req context. The @dbus_req
* and associated talloc context are no longer valid after this function
* returns.
*
* If @reply is non-NULL then the reply is sent to the caller. Not sending
* a reply when the caller is expecting one is fairly rude behavior.
*
* The return value is useful for logging, but not much else. In particular
* even if this function return !EOK, @dbus_req is still unusable after this
* function returns.
*/
DBusMessage *reply);
/*
* Return a reply for a DBus method call request. The variable
* arguments are (unfortunately) formatted exactly the same as those of the
* dbus_message_append_args() function. Documented here:
*
*
* Important: don't pass int or bool or such types as
* values to this function. That's not portable. Use actual dbus types.
* You must also pass pointers as the values:
*
* dbus_bool_t val1 = TRUE;
* dbus_int32_t val2 = 5;
* ret = sbus_request_finish(dbus_req,
* DBUS_TYPE_BOOLEAN, &val1,
* DBUS_TYPE_INT32, &val2,
* DBUS_TYPE_INVALID);
*
* To pass arrays to this function, use the following syntax. Never
* pass actual C arrays with [] syntax to this function. The C standard is
* rather vague with C arrays and varargs, and it just plain doesn't work.
*
* const char *array[] = { "one", "two", "three" };
* int count = 3; // yes, a plain int
* const char **ptr = array;
* ret = sbus_request_finish(dbus_req,
* DBUS_TYPE_ARRAY, DBUS_TYPE_STRING, &ptr, 3,
* DBUS_TYPE_INVALID);
*
* The @dbus_req and associated talloc context are no longer valid after this
* function returns, even if this function returns an error code.
*/
int first_arg_type,
...);
/*
* Return an error for a DBus method call request. The @error is a normal
* DBusError.
*
* The @dbus_req and associated talloc context are no longer valid after this
* function returns, even if this function returns an error code.
*/
/*
* Construct a new DBusError instance which can be consumed by functions such
* as @sbus_request_fail_and_finish().
*
* The @error is a string constant representing a DBus error as documented at
* The parameter @err_msg is a human-readable error representation (or
* NULL for none). The returned DBusError is a talloc context and the err_msg
* is duplicated using the returned DBusError instance as a talloc parent.
*/
const char *dbus_err_name,
const char *fmt,
/*
* Parse a DBus method call request.
*
* If parsing the method call message does not succeed, then an error is
* sent to the DBus caller and the request is finished. If this function
* returns false then @request is no longer valid.
*
* This also means if this method returns false within a handler, you should
* return EOK from the handler. The message has been handled, appropriate
* logs have been written, and everything should just move on.
*
* If the method call does not match the expected arguments, then a
* org.freedesktop.DBus.Error.InvalidArgs is returned to the caller as
* expected.
*
* The variable arguments are (unfortunately) formatted exactly the same
* as those of the dbus_message_get_args() function. Documented here:
*
*
* Exception: You don't need to free string arrays returned by this
* function. They are automatically talloc parented to the request memory
* context and can be used until the request has been finished.
*
* Important: don't pass int or bool or such types as values to this
* function. That's not portable. Use actual dbus types. You must also pass
* pointers as the values:
*
* dbus_bool_t val1;
* dbus_int32_t val2;
* ret = sbus_request_parse_or_finish(request,
* DBUS_TYPE_BOOLEAN, &val1,
* DBUS_TYPE_INT32, &val2,
* DBUS_TYPE_INVALID);
*
* To pass arrays to this function, use the following syntax. Never
* pass actual C arrays with [] syntax to this function. The C standard is
* rather vague with C arrays and varargs, and it just plain doesn't work.
*
* int count; // yes, a plain int
* const char **array;
* ret = sbus_request_parse_or_finish(request,
* DBUS_TYPE_ARRAY, DBUS_TYPE_STRING, &array, &count,
* DBUS_TYPE_INVALID);
*/
int first_arg_type,
...);
#endif /* _SSSD_DBUS_H_*/