sssd_dbus.h revision a06e23c0bcf0c8669a29b801876aca8aac422931
e6d40133bc9f858308654afb1262b8b483ec5922Till Mossakowski SSSD - D-BUS interface
98890889ffb2e8f6f722b00e265a211f13b5a861Corneliu-Claudiu Prodescu Copyright (C) Stephen Gallagher 2008
3f69b6948966979163bdfe8331c38833d5d90ecdChristian Maeder This program is free software; you can redistribute it and/or modify
b53688bfed888214b485cf76439d57262d80e0a7Christian Maeder it under the terms of the GNU General Public License as published by
b53688bfed888214b485cf76439d57262d80e0a7Christian Maeder the Free Software Foundation; either version 3 of the License, or
b53688bfed888214b485cf76439d57262d80e0a7Christian Maeder (at your option) any later version.
b53688bfed888214b485cf76439d57262d80e0a7Christian Maeder This program is distributed in the hope that it will be useful,
b53688bfed888214b485cf76439d57262d80e0a7Christian Maeder but WITHOUT ANY WARRANTY; without even the implied warranty of
bdeddba30d29f413af1e1ae6b6bab275c017bd98Christian Maeder MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
b53688bfed888214b485cf76439d57262d80e0a7Christian Maeder GNU General Public License for more details.
46b207daf66b64930a59f3615c8b127aac0b8e43Christian Maeder You should have received a copy of the GNU General Public License
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder along with this program. If not, see <http://www.gnu.org/licenses/>.
b53688bfed888214b485cf76439d57262d80e0a7Christian Maeder/* Older platforms (such as RHEL-6) might not have these error constants
520c5bce318eff52d9315f7c4491c3381a0c4336Christian Maeder/** Interface you invoked a method on isn't known by the object. */
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder "org.freedesktop.DBus.Error.UnknownInterface"
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder#endif /* DBUS_ERROR_UNKNOWN_INTERFACE */
f8cc2399c16fcda7e3bf9d901a0de0cc8a455f86Ewaryst Schulz/** Property you tried to access isn't known by the object. */
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder "org.freedesktop.DBus.Error.UnknownProperty"
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder#endif /* DBUS_ERROR_UNKNOWN_PROPERTY */
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder/** Property you tried to set is read-only. */
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder "org.freedesktop.DBus.Error.PropertyReadOnly"
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder#endif /* DBUS_ERROR_PROPERTY_READ_ONLY */
46b207daf66b64930a59f3615c8b127aac0b8e43Christian Maeder#define DBUS_ERROR_INIT { NULL, NULL, TRUE, 0, 0, 0, 0, NULL }
46b1095ba983ce859e17c2a12f48b50583b7150cChristian Maeder#endif /* DBUS_ERROR_INIT */
c8a9d35be2207e0d4fbd26a2411e1ba17e3e4c96Christian Maeder * Note: internal functions do not rely on the value of this constant to
c2257f94016aeb9e5c3ff3d4d675a81f8f873f0dChristian Maeder * simplify implementation. If this constant change, some functions in
3986813db69106b9bb1b62faa77532af42512a0cChristian Maeder * sssd_dbus_interface.c needs to be amended.
596a8e9039bd2f42c09cc0da4a57c8073f96fbddChristian Maeder * It is not possible to send NULL over D-Bus. We can only test if it
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder * is empty or not.
e982190515f83fe6615436530ebe89bb320770d6Christian Maeder#define SBUS_IS_STRING_EMPTY(str) ((str) == NULL || (str)[0] == '\0')
ab9b86500ed66416e1a7c01be54491ed72c7d633Christian Maeder#define SBUS_SET_STRING(str) (SBUS_IS_STRING_EMPTY(str) ? NULL : (str))
08d506ebb78da1e8656a73a349492e042f4c9f72Christian Maedertypedef int (*sbus_msg_handler_fn)(struct sbus_request *dbus_req,
53a3042e1da2253fd3f103bfef4deb47fc0bf6a6Ewaryst Schulz * sbus_conn_destructor_fn
53a3042e1da2253fd3f103bfef4deb47fc0bf6a6Ewaryst Schulz * Function to be called when a connection is finalized
38824a7dba4f7d82532afec67e0b594a5af5d76bChristian Maedertypedef int (*sbus_conn_destructor_fn)(void *);
ec351e60425e2f99448cb44e933d3828f8025dddChristian Maedertypedef void (*sbus_conn_reconn_callback_fn)(struct sbus_connection *, int, void *);
411588cc915b27cef4e7e66fb23e67514b3a0c92Christian Maeder * sbus_server_conn_init_fn
21dbca247d5964daf2c5abd2de2ac1101e3e1ef4Christian Maeder * Set up function for connection-specific activities
ec351e60425e2f99448cb44e933d3828f8025dddChristian Maeder * This function should define the sbus_conn_destructor_fn
56440c7ae61e7277a3494452d0165ee52e677b29Christian Maeder * for this connection at a minimum
961978c71545e0177683279f8b63358b3e3804b8Christian Maedertypedef int (*sbus_server_conn_init_fn)(struct sbus_connection *, void *);
e4f0eaffd002e9e553ee113be33f9aa6e4181c43Christian Maedertypedef const char ** (* sbus_nodes_fn)(TALLOC_CTX *mem_ctx,
520c5bce318eff52d9315f7c4491c3381a0c4336Christian Maeder * This represents vtable of interface handlers for methods and
c2257f94016aeb9e5c3ff3d4d675a81f8f873f0dChristian Maeder * properties and so on. The actual vtable structs derive from this struct
0850c3e5fb6285405ebaeb5aa433985203ac892dEwaryst Schulz * (ie: have this struct as their first member).
bdf2e01977470bedcb4425e2dadabc9e9f6ba149Ewaryst Schulz * The offsets for matching vtable function pointers are in sbus_method_meta
bdf2e01977470bedcb4425e2dadabc9e9f6ba149Ewaryst Schulz * These are used to dynamically dispatch the method invocations.
4067eba4f5605d9569d78085deb1a27f08ac34e2Christian Maeder /* derived structs place function pointers here. */
bbba6dd86153aacb0f662b182b128df0eb09fd54Christian Maeder/* Special interface and method for D-BUS introspection */
4067eba4f5605d9569d78085deb1a27f08ac34e2Christian Maeder#define DBUS_INTROSPECT_INTERFACE "org.freedesktop.DBus.Introspectable"
d864f0a0e04e61b5f87963496765eafcf646ed7bChristian Maeder/* Special interface and method for D-BUS properties */
72079df98b3cb7cc1fd82a0a24984893dcd05ecaEwaryst Schulz#define DBUS_PROPERTIES_INTERFACE "org.freedesktop.DBus.Properties"
4d54e7814b18ce142359c92a5868e6dcff9219b5Christian Maeder/* Server Functions */
53e165a53dfa59f717588d1f8236c9a763826525Christian Maeder sbus_server_conn_init_fn init_fn, void *init_pvt_data);
aad8b6ac810a08fca14ce0fbbf324fcce5305ad6Christian Maeder/* Connection Functions */
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder/* sbus_new_connection
4067eba4f5605d9569d78085deb1a27f08ac34e2Christian Maeder * Use this function when connecting a new process to
08d506ebb78da1e8656a73a349492e042f4c9f72Christian Maeder * the standard SSSD interface.
08d506ebb78da1e8656a73a349492e042f4c9f72Christian Maeder * This will connect to the address specified and then
d27d203b3f42f0e0ecea00e3f19f55f66045bd96Christian Maeder * call sbus_add_connection to integrate with the main
53a3042e1da2253fd3f103bfef4deb47fc0bf6a6Ewaryst Schulz/* sbus_add_connection
53a3042e1da2253fd3f103bfef4deb47fc0bf6a6Ewaryst Schulz * Integrates a D-BUS connection with the TEvent main
53a3042e1da2253fd3f103bfef4deb47fc0bf6a6Ewaryst Schulz * loop. Use this function when you already have a
53a3042e1da2253fd3f103bfef4deb47fc0bf6a6Ewaryst Schulz * DBusConnection object (for example from dbus_bus_get)
ea8e98e298f33f9362293f392c8fb192722b8904Eugen Kuksa * Connection type can be either:
ab9b86500ed66416e1a7c01be54491ed72c7d633Christian Maeder * SBUS_CONN_TYPE_PRIVATE: Used only from within a D-BUS
e6ac593966607b1da5b619e0f9492d37820eed74Christian Maeder * server such as the Monitor in the
f6b2c6c33c635279973b8f378470da7dbb8ecee8Christian Maeder * new_connection_callback
074f8feaf71e0b71a95145e7439746f8eb8e2a7cChristian Maeder * SBUS_CONN_TYPE_SHARED: Used for all D-BUS client
e6ac593966607b1da5b619e0f9492d37820eed74Christian Maeder * connections, including those retrieved from
f6b2c6c33c635279973b8f378470da7dbb8ecee8Christian Maeder * dbus_bus_get
e6ac593966607b1da5b619e0f9492d37820eed74Christian MaederDBusConnection *sbus_get_connection(struct sbus_connection *conn);
ab9b86500ed66416e1a7c01be54491ed72c7d633Christian Maedervoid sbus_disconnect(struct sbus_connection *conn);
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder * Register a new interface to be available at given object path.
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder * The interface will be exported at @object_path. The method handlers are
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder * represented by @iface_vtable. @pvt contains additional caller specific data
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder * which is made available to handlers.
63719301448519453f66383f4e583d9fd5b89ecbChristian Maederint sbus_conn_register_iface(struct sbus_connection *conn,
38824a7dba4f7d82532afec67e0b594a5af5d76bChristian Maedererrno_t sbus_conn_register_iface_map(struct sbus_connection *conn,
aad8b6ac810a08fca14ce0fbbf324fcce5305ad6Christian Maedersbus_conn_register_nodes(struct sbus_connection *conn,
21dbca247d5964daf2c5abd2de2ac1101e3e1ef4Christian Maedersbus_conn_reregister_paths(struct sbus_connection *conn);
7fe976d9f9c4af1aa7636c568d9919859523de0aChristian Maedersbus_opath_unescape_part(TALLOC_CTX *mem_ctx,
7fe976d9f9c4af1aa7636c568d9919859523de0aChristian Maeder const char *part, ...);
486db0a875bcdd0b80cf0d447d14c9c00a92ae94Simon Ulbricht#define sbus_opath_compose(mem_ctx, base, ...) \
486db0a875bcdd0b80cf0d447d14c9c00a92ae94Simon Ulbricht _sbus_opath_compose(mem_ctx, base, ##__VA_ARGS__, NULL)
38824a7dba4f7d82532afec67e0b594a5af5d76bChristian Maedersbus_opath_decompose_exact(TALLOC_CTX *mem_ctx,
32607d06fe7826eb0711c19d348ee4e395f2577aChristian Maedersbus_opath_strip_prefix(const char *object_path,
411588cc915b27cef4e7e66fb23e67514b3a0c92Christian Maedersbus_opath_get_object_name(TALLOC_CTX *mem_ctx,
32607d06fe7826eb0711c19d348ee4e395f2577aChristian Maederbool sbus_conn_disconnecting(struct sbus_connection *conn);
feeab95fdf7ec92bcce607c104d9dc98e0e6ea90Soeren D. Schulze/* max_retries < 0: retry forever
ec351e60425e2f99448cb44e933d3828f8025dddChristian Maeder * max_retries = 0: never retry (why are you calling this function?)
ec351e60425e2f99448cb44e933d3828f8025dddChristian Maeder * max_retries > 0: obvious
ec351e60425e2f99448cb44e933d3828f8025dddChristian Maedervoid sbus_reconnect_init(struct sbus_connection *conn,
c4076ff1721f8901a30e4b7aa004479ecb2631e0Felix Gabriel Mance * Send a message across the SBUS
c4076ff1721f8901a30e4b7aa004479ecb2631e0Felix Gabriel Mance * If requested, the DBusPendingCall object will
e4f0eaffd002e9e553ee113be33f9aa6e4181c43Christian Maeder * be returned to the caller.
3ec3a22fe2b9c38a3575c98a82b4e3f988af64a6Eugen Kuksa * This function will return EAGAIN in the event
961978c71545e0177683279f8b63358b3e3804b8Christian Maeder * that the connection is not open for
3ec3a22fe2b9c38a3575c98a82b4e3f988af64a6Eugen Kuksa * communication.
4c872eeb600fe8479dbda395405cf13c3d573c24Soeren D. Schulzevoid sbus_conn_send_reply(struct sbus_connection *conn,
4c872eeb600fe8479dbda395405cf13c3d573c24Soeren D. Schulze/* Set up D-BUS access control. If there is a SSSD user, we must allow
4c872eeb600fe8479dbda395405cf13c3d573c24Soeren D. Schulze * him to connect. root is always allowed */
4067eba4f5605d9569d78085deb1a27f08ac34e2Christian Maedervoid sbus_allow_uid(struct sbus_connection *conn, uid_t *uid);
c1d06b3018b34ede2b3fb6c7fe2ad28cd5ce5b68Christian Maeder * This structure is passed to all dbus method and property
b085709d4b69dc84724000b7b917f348edfa932eChristian Maeder * handlers. It is a talloc context which will be valid until
4067eba4f5605d9569d78085deb1a27f08ac34e2Christian Maeder * the request is completed with either the sbus_request_complete()
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder * or sbus_request_fail() functions.
d34c6711bc746459074986c06f7c28b083b4be2fChristian Maeder * Complete a DBus request, and free the @dbus_req context. The @dbus_req
b085709d4b69dc84724000b7b917f348edfa932eChristian Maeder * and associated talloc context are no longer valid after this function
48a98aa04f4c2c1f5f8f79c007e1ff95e699b31aFlorian Mossakowski * If @reply is non-NULL then the reply is sent to the caller. Not sending
8865728716566f42fa73e7e0bc080ba3225df764Christian Maeder * a reply when the caller is expecting one is fairly rude behavior.
1937dccb04b363364f7a7de17fdaae1d70583af9Christian Maeder * The return value is useful for logging, but not much else. In particular
bb9642ff292545658dc11251b83a7b7af3c1fccbChristian Maeder * even if this function return !EOK, @dbus_req is still unusable after this
a7b34c1a61dabe150288424d90389d5988bf9d7aChristian Maeder * function returns.
bb9642ff292545658dc11251b83a7b7af3c1fccbChristian Maederint sbus_request_finish(struct sbus_request *dbus_req,
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder * Return a reply for a DBus method call request. The variable
f6b2c6c33c635279973b8f378470da7dbb8ecee8Christian Maeder * arguments are (unfortunately) formatted exactly the same as those of the
78e7910c3360f74f1db172d63d20bb07c64e56e3Christian Maeder * dbus_message_append_args() function. Documented here:
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder * http://dbus.freedesktop.org/doc/api/html/group__DBusMessage.html
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder * Important: don't pass int or bool or such types as
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder * values to this function. That's not portable. Use actual dbus types.
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder * You must also pass pointers as the values:
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder * dbus_bool_t val1 = TRUE;
4067eba4f5605d9569d78085deb1a27f08ac34e2Christian Maeder * dbus_int32_t val2 = 5;
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder * ret = sbus_request_finish(dbus_req,
96ae1a1d2197d0e0d5b80da2474b64c456feb1b0Christian Maeder * DBUS_TYPE_BOOLEAN, &val1,
eaa88a5cefdc814e61039c5dcc1bffc324a2f93eChristian Maeder * DBUS_TYPE_INT32, &val2,
bb9642ff292545658dc11251b83a7b7af3c1fccbChristian Maeder * DBUS_TYPE_INVALID);
e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder * To pass arrays to this function, use the following syntax. Never
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder * pass actual C arrays with [] syntax to this function. The C standard is
938677803842b384a91fef21f58f86b8e3188b43Ewaryst Schulz * rather vague with C arrays and varargs, and it just plain doesn't work.
35cb254f1f46a6f33b5c24111a37fbab49d79cfeChristian Maeder * const char *array[] = { "one", "two", "three" };
35cb254f1f46a6f33b5c24111a37fbab49d79cfeChristian Maeder * int count = 3; // yes, a plain int
35cb254f1f46a6f33b5c24111a37fbab49d79cfeChristian Maeder * const char **ptr = array;
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder * ret = sbus_request_finish(dbus_req,
35cb254f1f46a6f33b5c24111a37fbab49d79cfeChristian Maeder * DBUS_TYPE_ARRAY, DBUS_TYPE_STRING, &ptr, 3,
35cb254f1f46a6f33b5c24111a37fbab49d79cfeChristian Maeder * DBUS_TYPE_INVALID);
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder * The @dbus_req and associated talloc context are no longer valid after this
3143271856dbf456bd7acc1c07193173f886d986Christian Maeder * function returns, even if this function returns an error code.
1937dccb04b363364f7a7de17fdaae1d70583af9Christian Maederint sbus_request_return_and_finish(struct sbus_request *dbus_req,
56440c7ae61e7277a3494452d0165ee52e677b29Christian Maeder * Return an error for a DBus method call request. The @error is a normal
3ec3a22fe2b9c38a3575c98a82b4e3f988af64a6Eugen Kuksa * DBusError.
53a3042e1da2253fd3f103bfef4deb47fc0bf6a6Ewaryst Schulz * The @dbus_req and associated talloc context are no longer valid after this
3143271856dbf456bd7acc1c07193173f886d986Christian Maeder * function returns, even if this function returns an error code.
c30231257d9116b514dce02703a515fe21cd427dTill Mossakowskiint sbus_request_fail_and_finish(struct sbus_request *dbus_req,
00df6fd583c19393fa141d5a0e21ac74c7bf5b19Christian Maedervoid sbus_request_reply_error(struct sbus_request *sbus_req,
63719301448519453f66383f4e583d9fd5b89ecbChristian Maeder * Construct a new DBusError instance which can be consumed by functions such
1937dccb04b363364f7a7de17fdaae1d70583af9Christian Maeder * as @sbus_request_fail_and_finish().
3143271856dbf456bd7acc1c07193173f886d986Christian Maeder * The @error is a string constant representing a DBus error as documented at
35cb254f1f46a6f33b5c24111a37fbab49d79cfeChristian Maeder * http://dbus.freedesktop.org/doc/api/html/group__DBusProtocol.html.
00df6fd583c19393fa141d5a0e21ac74c7bf5b19Christian Maeder * The parameter @err_msg is a human-readable error representation (or
35cb254f1f46a6f33b5c24111a37fbab49d79cfeChristian Maeder * NULL for none). The returned DBusError is a talloc context and the err_msg
88e08f20c80fea4b7892bbb5e70c5002f7c1da18Christian Maeder * is duplicated using the returned DBusError instance as a talloc parent.
180ab8c3df8cb0c88f0e881bca93354df6b5d560Christian MaederDBusError *sbus_error_new(TALLOC_CTX *mem_ctx,
3143271856dbf456bd7acc1c07193173f886d986Christian Maeder * Parse a DBus method call request.
3143271856dbf456bd7acc1c07193173f886d986Christian Maeder * If parsing the method call message does not succeed, then an error is
ef2affdc0cdf3acd5c051597c04ab9b08a346a7dChristian Maeder * sent to the DBus caller and the request is finished. If this function
3143271856dbf456bd7acc1c07193173f886d986Christian Maeder * returns false then @request is no longer valid.
ce900a84ed9d9882c64fccbd6300f6b0d67efa82Christian Maeder * This also means if this method returns false within a handler, you should
ce900a84ed9d9882c64fccbd6300f6b0d67efa82Christian Maeder * return EOK from the handler. The message has been handled, appropriate
fb37a248ebad4696bbc9d9b94ce1cfc6497a9160Christian Maeder * logs have been written, and everything should just move on.
ce900a84ed9d9882c64fccbd6300f6b0d67efa82Christian Maeder * If the method call does not match the expected arguments, then a
ce900a84ed9d9882c64fccbd6300f6b0d67efa82Christian Maeder * org.freedesktop.DBus.Error.InvalidArgs is returned to the caller as
int first_arg_type,
struct sbus_incoming_signal {
const char *interface;
const char *signal;
const char *path;
void *handler_data);
const char *iface,
const char *signal,
void *handler_data);