sssd_dbus.h revision 1319e71fd1680ca4864afe0b1aca2b8c8e4a1ee4
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer SSSD - D-BUS interface
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer Copyright (C) Stephen Gallagher 2008
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer This program is free software; you can redistribute it and/or modify
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer it under the terms of the GNU General Public License as published by
7520452bb30b5abbd471f82352fc4c1c937e02c5Till Mossakowski the Free Software Foundation; either version 3 of the License, or
7520452bb30b5abbd471f82352fc4c1c937e02c5Till Mossakowski (at your option) any later version.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer This program is distributed in the hope that it will be useful,
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer but WITHOUT ANY WARRANTY; without even the implied warranty of
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer GNU General Public License for more details.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer You should have received a copy of the GNU General Public License
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer along with this program. If not, see <http://www.gnu.org/licenses/>.
521045d36343cd17dd217a81d4b9422ad6ab6a07Christian Maedertypedef int (*sbus_msg_handler_fn)(struct sbus_request *dbus_req,
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * sbus_conn_destructor_fn
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * Function to be called when a connection is finalized
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyertypedef int (*sbus_conn_destructor_fn)(void *);
7ae38566aaf40710cd83ffa3ba25655c4ad22741Thiemo Wiedemeyertypedef void (*sbus_conn_reconn_callback_fn)(struct sbus_connection *, int, void *);
1c039dc13801bb9c90ad6a1bac0e56af19fd2fbfMihai Codescu * sbus_server_conn_init_fn
38122cbf09ad3dcc31a826cc4093f630515a5cfcChristian Maeder * Set up function for connection-specific activities
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * This function should define the sbus_conn_destructor_fn
f7b9d64160c23654b7288a3b0ee3e2b95af3e752Thiemo Wiedemeyer * for this connection at a minimum
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyertypedef int (*sbus_server_conn_init_fn)(struct sbus_connection *, void *);
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * This represents vtable of interface handlers for methods and
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * properties and so on. The actual vtable structs derive from this struct
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * (ie: have this struct as their first member).
d1066b8fb69179973dcab47154858d77e72760a7Thiemo Wiedemeyer * The offsets for matching vtable function pointers are in sbus_method_meta
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * These are used to dynamically dispatch the method invocations.
f9e0b18852b238ddb649d341194e05d7200d1bbeChristian Maeder /* derived structs place function pointers here. */
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer/* Special interface and method for D-BUS introspection */
4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder#define DBUS_INTROSPECT_INTERFACE "org.freedesktop.DBus.Introspectable"
f7b9d64160c23654b7288a3b0ee3e2b95af3e752Thiemo Wiedemeyer/* Special interface and method for D-BUS properties */
f7b9d64160c23654b7288a3b0ee3e2b95af3e752Thiemo Wiedemeyer#define DBUS_PROPERTIES_INTERFACE "org.freedesktop.DBus.Properties"
16e45483b5ce48f0b92d01c817242a8c9b8bae02Christian Maeder * Creates a new struct sbus_interface instance to be exported by a DBus
28ca54b0d63d1d26a991711c8c7e85c474994715Christian Maeder * Pass the result to sbus_conn_add_interface(). The interface
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * will be exported at @object_path. The method handlers are represented by
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @iface_vtable. @instance_data contains additional caller specific data
02a84229da51532505a93fc2abfca1ccf81b4446Razvan Pascanu * which is made available to handlers.
32d98ca5e560cf6c1062a0463be4c350af32bed5Thiemo Wiedemeyer/* Server Functions */
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer sbus_server_conn_init_fn init_fn, void *init_pvt_data);
d71a37fb09bce02af6c98e7a5ab0aa5639058e4fThiemo Wiedemeyer/* Connection Functions */
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyer/* sbus_new_connection
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyer * Use this function when connecting a new process to
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * the standard SSSD interface.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * This will connect to the address specified and then
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyer * call sbus_add_connection to integrate with the main
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyer/* sbus_add_connection
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * Integrates a D-BUS connection with the TEvent main
0b8b26a22f136a9b2a8e99d655f6fe6b0b96008cThiemo Wiedemeyer * loop. Use this function when you already have a
0b8b26a22f136a9b2a8e99d655f6fe6b0b96008cThiemo Wiedemeyer * DBusConnection object (for example from dbus_bus_get)
ea76e25262c3325f293fbdd6560f180ca18f9be4Thiemo Wiedemeyer * Connection type can be either:
ea76e25262c3325f293fbdd6560f180ca18f9be4Thiemo Wiedemeyer * SBUS_CONN_TYPE_PRIVATE: Used only from within a D-BUS
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * server such as the Monitor in the
788bd3c33ec5aaeb90a1932c341ff837116410cfThiemo Wiedemeyer * new_connection_callback
788bd3c33ec5aaeb90a1932c341ff837116410cfThiemo Wiedemeyer * SBUS_CONN_TYPE_SHARED: Used for all D-BUS client
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * connections, including those retrieved from
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyer * dbus_bus_get
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo WiedemeyerDBusConnection *sbus_get_connection(struct sbus_connection *conn);
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyervoid sbus_disconnect(struct sbus_connection *conn);
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyerint sbus_conn_add_interface(struct sbus_connection *conn,
ea76e25262c3325f293fbdd6560f180ca18f9be4Thiemo Wiedemeyerbool sbus_conn_disconnecting(struct sbus_connection *conn);
ea76e25262c3325f293fbdd6560f180ca18f9be4Thiemo Wiedemeyer/* max_retries < 0: retry forever
ea76e25262c3325f293fbdd6560f180ca18f9be4Thiemo Wiedemeyer * max_retries = 0: never retry (why are you calling this function?)
ea76e25262c3325f293fbdd6560f180ca18f9be4Thiemo Wiedemeyer * max_retries > 0: obvious
ea76e25262c3325f293fbdd6560f180ca18f9be4Thiemo Wiedemeyervoid sbus_reconnect_init(struct sbus_connection *conn,
ea76e25262c3325f293fbdd6560f180ca18f9be4Thiemo Wiedemeyer/* Default message handler
ea76e25262c3325f293fbdd6560f180ca18f9be4Thiemo Wiedemeyer * Should be usable for most cases */
ea76e25262c3325f293fbdd6560f180ca18f9be4Thiemo WiedemeyerDBusHandlerResult sbus_message_handler(DBusConnection *conn,
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyer * Send a message across the SBUS
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyer * If requested, the DBusPendingCall object will
d71a37fb09bce02af6c98e7a5ab0aa5639058e4fThiemo Wiedemeyer * be returned to the caller.
788bd3c33ec5aaeb90a1932c341ff837116410cfThiemo Wiedemeyer * This function will return EAGAIN in the event
d71a37fb09bce02af6c98e7a5ab0aa5639058e4fThiemo Wiedemeyer * that the connection is not open for
788bd3c33ec5aaeb90a1932c341ff837116410cfThiemo Wiedemeyer * communication.
39a2520d13a7d43f0c0fa71b94255c3f7c500005Christian Maederint sbus_conn_send(struct sbus_connection *conn,
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer DBusPendingCallNotifyFunction reply_handler,
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyervoid sbus_conn_send_reply(struct sbus_connection *conn,
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyer * This structure is passed to all dbus method and property
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyer * handlers. It is a talloc context which will be valid until
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * the request is completed with either the sbus_request_complete()
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * or sbus_request_fail() functions.
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder * Complete a DBus request, and free the @dbus_req context. The @dbus_req
92e96be605537638d75e9d3023ab698bd89cf889Thiemo Wiedemeyer * and associated talloc context are no longer valid after this function
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * If @reply is non-NULL then the reply is sent to the caller. Not sending
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * a reply when the caller is expecting one is fairly rude behavior.
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * The return value is useful for logging, but not much else. In particular
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * even if this function return !EOK, @dbus_req is still unusable after this
aa21e7aa42fef563dea0cc77edbde76f66cdbe88Thiemo Wiedemeyer * function returns.
d7aa4e1cbe00f7f3add4da911673b3b176b140c3Thiemo Wiedemeyerint sbus_request_finish(struct sbus_request *dbus_req,
d9f20cf968e246ec283f0c09f60af4b47b174398Thiemo Wiedemeyer * Return a reply for a DBus method call request. The variable
d9f20cf968e246ec283f0c09f60af4b47b174398Thiemo Wiedemeyer * arguments are (unfortunately) formatted exactly the same as those of the
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * dbus_message_append_args() function. Documented here:
d9f20cf968e246ec283f0c09f60af4b47b174398Thiemo Wiedemeyer * http://dbus.freedesktop.org/doc/api/html/group__DBusMessage.html
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * Important: don't pass int or bool or such types as
39a2520d13a7d43f0c0fa71b94255c3f7c500005Christian Maeder * values to this function. That's not portable. Use actual dbus types.
4014fb09362f3e38a91d7bb11b1484a4790e9297Thiemo Wiedemeyer * You must also pass pointers as the values:
39a2520d13a7d43f0c0fa71b94255c3f7c500005Christian Maeder * dbus_bool_t val1 = TRUE;
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * dbus_int32_t val2 = 5;
da1f9fa9339a0115d0559411929835bcff74e5f5Thiemo Wiedemeyer * ret = sbus_request_finish(dbus_req,
da1f9fa9339a0115d0559411929835bcff74e5f5Thiemo Wiedemeyer * DBUS_TYPE_BOOLEAN, &val1,
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * DBUS_TYPE_INT32, &val2,
4014fb09362f3e38a91d7bb11b1484a4790e9297Thiemo Wiedemeyer * DBUS_TYPE_INVALID);
4014fb09362f3e38a91d7bb11b1484a4790e9297Thiemo Wiedemeyer * To pass arrays to this function, use the following syntax. Never
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * pass actual C arrays with [] syntax to this function. The C standard is
3e3efd4ce838940032e875e6d08712a177c9c1d0Thiemo Wiedemeyer * rather vague with C arrays and varargs, and it just plain doesn't work.
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * const char *array[] = { "one", "two", "three" };
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * int count = 3; // yes, a plain int
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * const char **ptr = array;
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * ret = sbus_request_finish(dbus_req,
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * DBUS_TYPE_ARRAY, DBUS_TYPE_STRING, &ptr, 3,
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * DBUS_TYPE_INVALID);
788bd3c33ec5aaeb90a1932c341ff837116410cfThiemo Wiedemeyer * The @dbus_req and associated talloc context are no longer valid after this
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * function returns, even if this function returns an error code.
788bd3c33ec5aaeb90a1932c341ff837116410cfThiemo Wiedemeyerint sbus_request_return_and_finish(struct sbus_request *dbus_req,
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyerint sbus_request_return_as_variant(struct sbus_request *dbus_req,
239991d3955da0cfb760af4d506069446e1676b7Christian Maederint sbus_request_return_array_as_variant(struct sbus_request *dbus_req,
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * Return an error for a DBus method call request. The @error is a normal
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * The @dbus_req and associated talloc context are no longer valid after this
80df5ce65c2bad7a0643106e524fe33cdcfab5b6Thiemo Wiedemeyer * function returns, even if this function returns an error code.
239991d3955da0cfb760af4d506069446e1676b7Christian Maederint sbus_request_fail_and_finish(struct sbus_request *dbus_req,
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * Construct a new DBusError instance which can be consumed by functions such
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * as @sbus_request_fail_and_finish().
788bd3c33ec5aaeb90a1932c341ff837116410cfThiemo Wiedemeyer * The @error is a string constant representing a DBus error as documented at
788bd3c33ec5aaeb90a1932c341ff837116410cfThiemo Wiedemeyer * http://dbus.freedesktop.org/doc/api/html/group__DBusProtocol.html.
788bd3c33ec5aaeb90a1932c341ff837116410cfThiemo Wiedemeyer * The parameter @err_msg is a human-readable error representation (or
32d98ca5e560cf6c1062a0463be4c350af32bed5Thiemo Wiedemeyer * NULL for none). The returned DBusError is a talloc context and the err_msg
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * is duplicated using the returned DBusError instance as a talloc parent.
32d98ca5e560cf6c1062a0463be4c350af32bed5Thiemo WiedemeyerDBusError *sbus_error_new(TALLOC_CTX *mem_ctx,
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * Parse a DBus method call request.
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * If parsing the method call message does not succeed, then an error is
1ac36418f204bbe56f4cd951a979180721758999Christian Maeder * sent to the DBus caller and the request is finished. If this function
370e81d7af7821f0ac6ee0643613e87a727841e7Thiemo Wiedemeyer * returns false then @request is no longer valid.
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * This also means if this method returns false within a handler, you should
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * return EOK from the handler. The message has been handled, appropriate
239991d3955da0cfb760af4d506069446e1676b7Christian Maeder * logs have been written, and everything should just move on.
545d0cd78159cade346b579d06052638b19b0f72Thiemo Wiedemeyer * If the method call does not match the expected arguments, then a
1a389234e68da7c3d087b038307ed8c66fc6dc32Thiemo Wiedemeyer * org.freedesktop.DBus.Error.InvalidArgs is returned to the caller as
44c1fff98bd6c54db237bef5030657d3f47058a5Thiemo Wiedemeyer * The variable arguments are (unfortunately) formatted exactly the same
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * as those of the dbus_message_get_args() function. Documented here:
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * http://dbus.freedesktop.org/doc/api/html/group__DBusMessage.html
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * Exception: You don't need to free string arrays returned by this
44c1fff98bd6c54db237bef5030657d3f47058a5Thiemo Wiedemeyer * function. They are automatically talloc parented to the request memory
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * context and can be used until the request has been finished.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * Important: don't pass int or bool or such types as values to this
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * function. That's not portable. Use actual dbus types. You must also pass
44c1fff98bd6c54db237bef5030657d3f47058a5Thiemo Wiedemeyer * pointers as the values:
1a389234e68da7c3d087b038307ed8c66fc6dc32Thiemo Wiedemeyer * dbus_bool_t val1;
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * dbus_int32_t val2;
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * ret = sbus_request_parse_or_finish(request,
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * DBUS_TYPE_BOOLEAN, &val1,
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * DBUS_TYPE_INT32, &val2,
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * DBUS_TYPE_INVALID);
44c1fff98bd6c54db237bef5030657d3f47058a5Thiemo Wiedemeyer * To pass arrays to this function, use the following syntax. Never
44c1fff98bd6c54db237bef5030657d3f47058a5Thiemo Wiedemeyer * pass actual C arrays with [] syntax to this function. The C standard is
44c1fff98bd6c54db237bef5030657d3f47058a5Thiemo Wiedemeyer * rather vague with C arrays and varargs, and it just plain doesn't work.
a4e6fb26100f53e3b1e9f5b97c2e0a0c129294e5Christian Maeder * int count; // yes, a plain int
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * const char **array;
a4e6fb26100f53e3b1e9f5b97c2e0a0c129294e5Christian Maeder * ret = sbus_request_parse_or_finish(request,
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * DBUS_TYPE_ARRAY, DBUS_TYPE_STRING, &array, &count,
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * DBUS_TYPE_INVALID);
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyerbool sbus_request_parse_or_finish(struct sbus_request *request,
44c1fff98bd6c54db237bef5030657d3f47058a5Thiemo Wiedemeyer#endif /* _SSSD_DBUS_H_*/