sssd_dbus.h revision d9577dbd92555b0755881e37724019ef9c578404
/*
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_request;
/*
* 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"
struct sbus_interface {
const char *path;
struct sbus_vtable *vtable;
};
/* Server Functions */
struct tevent_context *ev,
const char *address,
struct sbus_interface *intf,
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_interface *intf,
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,
struct sbus_interface *intf,
int connection_type,
struct sbus_connection **_conn);
int sbus_default_connection_destructor(void *ctx);
struct sbus_interface *intf);
/* 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);
/* Default message handler
* Should be usable for most cases */
void *user_data);
/*
* 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);
/*
* 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;
};
/*
* 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.
*/
#endif /* _SSSD_DBUS_H_*/