sssd_dbus.h revision 46ee931314e6a5517f5c6b6b14f759364be119cc
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina SSSD - D-BUS interface
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina Copyright (C) Stephen Gallagher 2008
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina This program is free software; you can redistribute it and/or modify
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina it under the terms of the GNU General Public License as published by
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina the Free Software Foundation; either version 3 of the License, or
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina (at your option) any later version.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina This program is distributed in the hope that it will be useful,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina but WITHOUT ANY WARRANTY; without even the implied warranty of
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina GNU General Public License for more details.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina You should have received a copy of the GNU General Public License
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina along with this program. If not, see <http://www.gnu.org/licenses/>.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/* Older platforms (such as RHEL-6) might not have these error constants
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/** Interface you invoked a method on isn't known by the object. */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina "org.freedesktop.DBus.Error.UnknownInterface"
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina#endif /* DBUS_ERROR_UNKNOWN_INTERFACE */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/** Property you tried to access isn't known by the object. */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina "org.freedesktop.DBus.Error.UnknownProperty"
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina#endif /* DBUS_ERROR_UNKNOWN_PROPERTY */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/** Property you tried to set is read-only. */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina "org.freedesktop.DBus.Error.PropertyReadOnly"
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina#endif /* DBUS_ERROR_PROPERTY_READ_ONLY */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina#define DBUS_ERROR_INIT { NULL, NULL, TRUE, 0, 0, 0, 0, NULL }
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina#endif /* DBUS_ERROR_INIT */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinatypedef int (*sbus_msg_handler_fn)(struct sbus_request *dbus_req,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * sbus_conn_destructor_fn
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Function to be called when a connection is finalized
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinatypedef int (*sbus_conn_destructor_fn)(void *);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinatypedef void (*sbus_conn_reconn_callback_fn)(struct sbus_connection *, int, void *);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * sbus_server_conn_init_fn
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Set up function for connection-specific activities
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * This function should define the sbus_conn_destructor_fn
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * for this connection at a minimum
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinatypedef int (*sbus_server_conn_init_fn)(struct sbus_connection *, void *);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * This represents vtable of interface handlers for methods and
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * properties and so on. The actual vtable structs derive from this struct
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * (ie: have this struct as their first member).
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * The offsets for matching vtable function pointers are in sbus_method_meta
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * These are used to dynamically dispatch the method invocations.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina /* derived structs place function pointers here. */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/* Special interface and method for D-BUS introspection */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina#define DBUS_INTROSPECT_INTERFACE "org.freedesktop.DBus.Introspectable"
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/* Special interface and method for D-BUS properties */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina#define DBUS_PROPERTIES_INTERFACE "org.freedesktop.DBus.Properties"
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/* Server Functions */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina sbus_server_conn_init_fn init_fn, void *init_pvt_data);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/* Connection Functions */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/* sbus_new_connection
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Use this function when connecting a new process to
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * the standard SSSD interface.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * This will connect to the address specified and then
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * call sbus_add_connection to integrate with the main
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/* sbus_add_connection
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Integrates a D-BUS connection with the TEvent main
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * loop. Use this function when you already have a
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBusConnection object (for example from dbus_bus_get)
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Connection type can be either:
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * SBUS_CONN_TYPE_PRIVATE: Used only from within a D-BUS
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * server such as the Monitor in the
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * new_connection_callback
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * SBUS_CONN_TYPE_SHARED: Used for all D-BUS client
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * connections, including those retrieved from
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * dbus_bus_get
a641a13889d617aca6bd998025e9087e822ff7f0Pavel BřezinaDBusConnection *sbus_get_connection(struct sbus_connection *conn);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinavoid sbus_disconnect(struct sbus_connection *conn);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Register a new interface to be available at given object path.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * The interface will be exported at @object_path. The method handlers are
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * represented by @iface_vtable. @pvt contains additional caller specific data
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * which is made available to handlers.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinaint sbus_conn_register_iface(struct sbus_connection *conn,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinasbus_conn_reregister_paths(struct sbus_connection *conn);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinabool sbus_conn_disconnecting(struct sbus_connection *conn);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/* max_retries < 0: retry forever
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * max_retries = 0: never retry (why are you calling this function?)
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * max_retries > 0: obvious
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinavoid sbus_reconnect_init(struct sbus_connection *conn,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Send a message across the SBUS
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * If requested, the DBusPendingCall object will
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * be returned to the caller.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * This function will return EAGAIN in the event
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * that the connection is not open for
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * communication.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinaint sbus_conn_send(struct sbus_connection *conn,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinavoid sbus_conn_send_reply(struct sbus_connection *conn,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina/* Set up D-BUS access control. If there is a SSSD user, we must allow
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * him to connect. root is always allowed */
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinavoid sbus_allow_uid(struct sbus_connection *conn, uid_t *uid);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * This structure is passed to all dbus method and property
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * handlers. It is a talloc context which will be valid until
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * the request is completed with either the sbus_request_complete()
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * or sbus_request_fail() functions.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Complete a DBus request, and free the @dbus_req context. The @dbus_req
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * and associated talloc context are no longer valid after this function
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * If @reply is non-NULL then the reply is sent to the caller. Not sending
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * a reply when the caller is expecting one is fairly rude behavior.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * The return value is useful for logging, but not much else. In particular
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * even if this function return !EOK, @dbus_req is still unusable after this
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * function returns.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinaint sbus_request_finish(struct sbus_request *dbus_req,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Return a reply for a DBus method call request. The variable
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * arguments are (unfortunately) formatted exactly the same as those of the
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * dbus_message_append_args() function. Documented here:
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * http://dbus.freedesktop.org/doc/api/html/group__DBusMessage.html
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Important: don't pass int or bool or such types as
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * values to this function. That's not portable. Use actual dbus types.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * You must also pass pointers as the values:
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * dbus_bool_t val1 = TRUE;
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * dbus_int32_t val2 = 5;
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * ret = sbus_request_finish(dbus_req,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBUS_TYPE_BOOLEAN, &val1,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBUS_TYPE_INT32, &val2,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBUS_TYPE_INVALID);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * To pass arrays to this function, use the following syntax. Never
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * pass actual C arrays with [] syntax to this function. The C standard is
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * rather vague with C arrays and varargs, and it just plain doesn't work.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * const char *array[] = { "one", "two", "three" };
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * int count = 3; // yes, a plain int
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * const char **ptr = array;
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * ret = sbus_request_finish(dbus_req,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBUS_TYPE_ARRAY, DBUS_TYPE_STRING, &ptr, 3,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBUS_TYPE_INVALID);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * The @dbus_req and associated talloc context are no longer valid after this
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * function returns, even if this function returns an error code.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinaint sbus_request_return_and_finish(struct sbus_request *dbus_req,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinaint sbus_add_variant_to_dict(DBusMessageIter *iter_dict,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina const char *key,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina const void *value);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinaint sbus_add_array_as_variant_to_dict(DBusMessageIter *iter_dict,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina const char *key,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina const unsigned int item_size);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinaint sbus_request_return_as_variant(struct sbus_request *dbus_req,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina const void *value);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinaint sbus_request_return_array_as_variant(struct sbus_request *dbus_req,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Return an error for a DBus method call request. The @error is a normal
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * The @dbus_req and associated talloc context are no longer valid after this
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * function returns, even if this function returns an error code.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinaint sbus_request_fail_and_finish(struct sbus_request *dbus_req,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Construct a new DBusError instance which can be consumed by functions such
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * as @sbus_request_fail_and_finish().
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * The @error is a string constant representing a DBus error as documented at
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * http://dbus.freedesktop.org/doc/api/html/group__DBusProtocol.html.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * The parameter @err_msg is a human-readable error representation (or
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * NULL for none). The returned DBusError is a talloc context and the err_msg
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * is duplicated using the returned DBusError instance as a talloc parent.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina const char *fmt,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Parse a DBus method call request.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * If parsing the method call message does not succeed, then an error is
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * sent to the DBus caller and the request is finished. If this function
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * returns false then @request is no longer valid.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * This also means if this method returns false within a handler, you should
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * return EOK from the handler. The message has been handled, appropriate
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * logs have been written, and everything should just move on.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * If the method call does not match the expected arguments, then a
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * org.freedesktop.DBus.Error.InvalidArgs is returned to the caller as
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * The variable arguments are (unfortunately) formatted exactly the same
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * as those of the dbus_message_get_args() function. Documented here:
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * http://dbus.freedesktop.org/doc/api/html/group__DBusMessage.html
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Exception: You don't need to free string arrays returned by this
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * function. They are automatically talloc parented to the request memory
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * context and can be used until the request has been finished.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * Important: don't pass int or bool or such types as values to this
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * function. That's not portable. Use actual dbus types. You must also pass
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * pointers as the values:
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * dbus_bool_t val1;
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * dbus_int32_t val2;
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * ret = sbus_request_parse_or_finish(request,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBUS_TYPE_BOOLEAN, &val1,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBUS_TYPE_INT32, &val2,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBUS_TYPE_INVALID);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * To pass arrays to this function, use the following syntax. Never
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * pass actual C arrays with [] syntax to this function. The C standard is
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * rather vague with C arrays and varargs, and it just plain doesn't work.
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * int count; // yes, a plain int
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * const char **array;
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * ret = sbus_request_parse_or_finish(request,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBUS_TYPE_ARRAY, DBUS_TYPE_STRING, &array, &count,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina * DBUS_TYPE_INVALID);
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březinabool sbus_request_parse_or_finish(struct sbus_request *request,
a641a13889d617aca6bd998025e9087e822ff7f0Pavel Březina#endif /* _SSSD_DBUS_H_*/