}
/**
- * Returns the method string of an address entry.
+ * Returns the method string of an address entry. For example, given
+ * the address entry "tcp:host=example.com" it would return the string
+ * "tcp"
*
* @param entry the entry.
* @returns a string describing the method. This string
}
/**
- * Returns a value from a key of an entry.
+ * Returns a value from a key of an entry. For example,
+ * given the address "tcp:host=example.com,port=8073" if you asked
+ * for the key "host" you would get the value "example.com"
*
+ * The returned value is already unescaped.
+ *
* @param entry the entry.
* @param key the key.
* @returns the key value. This string must not be freed.
* method:key=value,key=value;method:key=value
*
* See the D-Bus specification for complete docs on the format.
+ *
+ * When connecting to an address, the first address entries
+ * in the semicolon-separated list should be tried first.
*
* @param address the address.
* @param entry return location to an array of entries.
/**
* Unescapes the given string as a value in a key=value pair
- * for a D-Bus address.
+ * for a D-Bus address. Note that dbus_address_entry_get_value()
+ * returns an already-unescaped value.
*
* @param value the escaped value
* @param error error to set if the unescaping fails
}
/**
- * Sets the mainloop wakeup function for the connection. This function is
- * responsible for waking up the main loop (if its sleeping) when some some
- * change has happened to the connection that the mainloop needs to reconsider
- * (e.g. a message has been queued for writing).
- * When using Qt, this typically results in a call to QEventLoop::wakeUp().
- * When using GLib, it would call g_main_context_wakeup().
- *
+ * Sets the mainloop wakeup function for the connection. This function
+ * is responsible for waking up the main loop (if its sleeping in
+ * another thread) when some some change has happened to the
+ * connection that the mainloop needs to reconsider (e.g. a message
+ * has been queued for writing). When using Qt, this typically
+ * results in a call to QEventLoop::wakeUp(). When using GLib, it
+ * would call g_main_context_wakeup().
*
* @param connection the connection.
* @param wakeup_main_function function to wake up the mainloop
* that messages should be dispatched later, when the main loop
* is re-entered.
*
+ * If you don't set a dispatch status function, you have to be sure to
+ * dispatch on every iteration of your main loop, especially if
+ * dbus_watch_handle() or dbus_timeout_handle() were called.
+ *
* @param connection the connection
* @param function function to call on dispatch status changes
* @param data data for function
* @{
*/
+/* documented in dbus-watch.c */
typedef struct DBusWatch DBusWatch;
+/* documented in dbus-timeout.c */
typedef struct DBusTimeout DBusTimeout;
+/** Opaque type representing preallocated resources so a message can be sent without further memory allocation. */
typedef struct DBusPreallocatedSend DBusPreallocatedSend;
+/** Opaque type representing a method call that has not yet received a reply. */
typedef struct DBusPendingCall DBusPendingCall;
+/** Opaque type representing a connection to a remote application and associated incoming/outgoing message queues. */
typedef struct DBusConnection DBusConnection;
+/** Set of functions that must be implemented to handle messages sent to a particular object path. */
typedef struct DBusObjectPathVTable DBusObjectPathVTable;
+/**
+ * Indicates the status of a #DBusWatch.
+ */
typedef enum
{
DBUS_WATCH_READABLE = 1 << 0, /**< As in POLLIN */
* the flag can be passed to dbus_watch_handle()).
*/
DBUS_WATCH_HANGUP = 1 << 3 /**< As in POLLHUP (can't watch for it, but
- * can be present in current state). */
+ * can be present in current state).
+ */
} DBusWatchFlags;
+/**
+ * Indicates the status of incoming data on a #DBusConnection. This determines whether
+ * dbus_connection_dispatch() needs to be called.
+ */
typedef enum
{
DBUS_DISPATCH_DATA_REMAINS, /**< There is more data to potentially convert to messages. */
DBUS_DISPATCH_NEED_MEMORY /**< More memory is needed to continue. */
} DBusDispatchStatus;
+/** Called when libdbus needs a new watch to be monitored by the main
+ * loop. Returns #FALSE if it lacks enough memory to add the
+ * watch. Set by dbus_connection_set_watch_functions() or
+ * dbus_server_set_watch_functions().
+ */
typedef dbus_bool_t (* DBusAddWatchFunction) (DBusWatch *watch,
void *data);
+/** Called when dbus_watch_get_enabled() may return a different value
+ * than it did before. Set by dbus_connection_set_watch_functions()
+ * or dbus_server_set_watch_functions().
+ */
typedef void (* DBusWatchToggledFunction) (DBusWatch *watch,
void *data);
+/** Called when libdbus no longer needs a watch to be monitored by the
+ * main loop. Set by dbus_connection_set_watch_functions() or
+ * dbus_server_set_watch_functions().
+ */
typedef void (* DBusRemoveWatchFunction) (DBusWatch *watch,
void *data);
+/** Called when libdbus needs a new timeout to be monitored by the main
+ * loop. Returns #FALSE if it lacks enough memory to add the
+ * watch. Set by dbus_connection_set_timeout_functions() or
+ * dbus_server_set_timeout_functions().
+ */
typedef dbus_bool_t (* DBusAddTimeoutFunction) (DBusTimeout *timeout,
void *data);
+/** Called when dbus_timeout_get_enabled() may return a different
+ * value than it did before.
+ * Set by dbus_connection_set_timeout_functions() or
+ * dbus_server_set_timeout_functions().
+ */
typedef void (* DBusTimeoutToggledFunction) (DBusTimeout *timeout,
void *data);
+/** Called when libdbus no longer needs a timeout to be monitored by the
+ * main loop. Set by dbus_connection_set_timeout_functions() or
+ * dbus_server_set_timeout_functions().
+ */
typedef void (* DBusRemoveTimeoutFunction) (DBusTimeout *timeout,
void *data);
+/** Called when the return value of dbus_connection_get_dispatch_status()
+ * may have changed. Set with dbus_connection_set_dispatch_status_function().
+ */
typedef void (* DBusDispatchStatusFunction) (DBusConnection *connection,
DBusDispatchStatus new_status,
void *data);
+/**
+ * Called when the main loop's thread should be notified that there's now work
+ * to do. Set with dbus_connection_set_wakeup_main_function().
+ */
typedef void (* DBusWakeupMainFunction) (void *data);
+/**
+ * Called during authentication on UNIX systems to check whether the given
+ * user ID is allowed to connect. Never called on Windows. Set with
+ * dbus_connection_set_unix_user_function().
+ */
typedef dbus_bool_t (* DBusAllowUnixUserFunction) (DBusConnection *connection,
unsigned long uid,
void *data);
-
+/**
+ * Called when a pending call now has a reply available. Set with
+ * dbus_pending_call_set_notify().
+ */
typedef void (* DBusPendingCallNotifyFunction) (DBusPendingCall *pending,
void *user_data);
-
+/**
+ * Called when a message needs to be handled. The result indicates whether or
+ * not more handlers should be run. Set with dbus_connection_add_filter().
+ */
typedef DBusHandlerResult (* DBusHandleMessageFunction) (DBusConnection *connection,
DBusMessage *message,
void *user_data);
/* Object tree functionality */
+/**
+ * Called when a #DBusObjectPathVTable is unregistered (or its connection is freed).
+ * Found in #DBusObjectPathVTable.
+ */
typedef void (* DBusObjectPathUnregisterFunction) (DBusConnection *connection,
void *user_data);
+/**
+ * Called when a message is sent to a registered object path. Found in
+ * #DBusObjectPathVTable which is registered with dbus_connection_register_object_path()
+ * or dbus_connection_register_fallback().
+ */
typedef DBusHandlerResult (* DBusObjectPathMessageFunction) (DBusConnection *connection,
DBusMessage *message,
void *user_data);
/**
* Virtual table that must be implemented to handle a portion of the
- * object path hierarchy.
+ * object path hierarchy. Attach the vtable to a particular path using
+ * dbus_connection_register_object_path() or
+ * dbus_connection_register_fallback().
*/
struct DBusObjectPathVTable
{
projects / thirdparty / dbus.git / commitdiff
