diff options
| -rw-r--r-- | ChangeLog | 4 | ||||
| -rw-r--r-- | dbus/dbus-address.c | 16 | ||||
| -rw-r--r-- | dbus/dbus-address.h | 1 | ||||
| -rw-r--r-- | dbus/dbus-connection.c | 18 | ||||
| -rw-r--r-- | dbus/dbus-connection.h | 78 | ||||
| -rw-r--r-- | dbus/dbus-errors.h | 5 | ||||
| -rw-r--r-- | dbus/dbus-marshal-validate.h | 2 | ||||
| -rw-r--r-- | dbus/dbus-message.h | 1 | ||||
| -rw-r--r-- | dbus/dbus-server.h | 3 |
9 files changed, 111 insertions, 17 deletions
@@ -1,5 +1,9 @@ 2006-10-21 Havoc Pennington <hp@redhat.com> + * Document a bunch of undocumented stuff + +2006-10-21 Havoc Pennington <hp@redhat.com> + * Clean up Doxygen group markers for public API so Doxygen finds everything (not comprehensively fixed for private API). Means all remaining Doxygen warnings are just about missing docs diff --git a/dbus/dbus-address.c b/dbus/dbus-address.c index d92209d9..bb2a5899 100644 --- a/dbus/dbus-address.c +++ b/dbus/dbus-address.c @@ -214,7 +214,9 @@ create_entry (void) } /** - * 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 @@ -227,8 +229,12 @@ dbus_address_entry_get_method (DBusAddressEntry *entry) } /** - * 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. @@ -342,6 +348,9 @@ append_unescaped_value (DBusString *unescaped, * 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. @@ -589,7 +598,8 @@ dbus_address_escape_value (const char *value) /** * 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 diff --git a/dbus/dbus-address.h b/dbus/dbus-address.h index 8940be5b..8480e56a 100644 --- a/dbus/dbus-address.h +++ b/dbus/dbus-address.h @@ -37,6 +37,7 @@ DBUS_BEGIN_DECLS * @{ */ +/** Opaque type representing one of the semicolon-separated items in an address */ typedef struct DBusAddressEntry DBusAddressEntry; dbus_bool_t dbus_parse_address (const char *address, diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c index 81c7cadf..9cd645b8 100644 --- a/dbus/dbus-connection.c +++ b/dbus/dbus-connection.c @@ -4578,13 +4578,13 @@ dbus_connection_set_timeout_functions (DBusConnection *connection, } /** - * 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 @@ -4628,6 +4628,10 @@ dbus_connection_set_wakeup_main_function (DBusConnection *connection, * 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 diff --git a/dbus/dbus-connection.h b/dbus/dbus-connection.h index 465cdbf4..401154c1 100644 --- a/dbus/dbus-connection.h +++ b/dbus/dbus-connection.h @@ -39,13 +39,22 @@ DBUS_BEGIN_DECLS * @{ */ +/* 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 */ @@ -54,9 +63,14 @@ typedef enum * 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. */ @@ -64,30 +78,75 @@ typedef enum 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); @@ -220,15 +279,26 @@ void dbus_connection_send_preallocated (DBusConnection /* 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 { diff --git a/dbus/dbus-errors.h b/dbus/dbus-errors.h index 3ea12f0c..e4548604 100644 --- a/dbus/dbus-errors.h +++ b/dbus/dbus-errors.h @@ -38,6 +38,7 @@ DBUS_BEGIN_DECLS * @{ */ +/** Mostly-opaque type representing an error that occurred */ typedef struct DBusError DBusError; /** @@ -45,8 +46,8 @@ typedef struct DBusError DBusError; */ struct DBusError { - const char *name; /**< error name */ - const char *message; /**< error message */ + const char *name; /**< public error name field */ + const char *message; /**< public error message field */ unsigned int dummy1 : 1; /**< placeholder */ unsigned int dummy2 : 1; /**< placeholder */ diff --git a/dbus/dbus-marshal-validate.h b/dbus/dbus-marshal-validate.h index 3436b6ce..e5f0bdae 100644 --- a/dbus/dbus-marshal-validate.h +++ b/dbus/dbus-marshal-validate.h @@ -161,7 +161,7 @@ dbus_bool_t _dbus_validate_signature (const DBusString *str, #else /* !DBUS_DISABLE_CHECKS */ /** A name check is used in _dbus_return_if_fail(), it's not suitable - * for validating untrusted data. use _dbus_validate_##what for that. + * for validating untrusted data. use _dbus_validate_whatever for that. */ #define DECLARE_DBUS_NAME_CHECK(what) \ dbus_bool_t _dbus_check_is_valid_##what (const char *name) diff --git a/dbus/dbus-message.h b/dbus/dbus-message.h index 16d2272a..8fe07d8d 100644 --- a/dbus/dbus-message.h +++ b/dbus/dbus-message.h @@ -42,6 +42,7 @@ DBUS_BEGIN_DECLS */ typedef struct DBusMessage DBusMessage; +/** Opaque type representing a message iterator. Can be copied by value, and contains no allocated memory so never needs to be freed and can be allocated on the stack. */ typedef struct DBusMessageIter DBusMessageIter; /** diff --git a/dbus/dbus-server.h b/dbus/dbus-server.h index caea4d70..58e00289 100644 --- a/dbus/dbus-server.h +++ b/dbus/dbus-server.h @@ -41,6 +41,9 @@ DBUS_BEGIN_DECLS typedef struct DBusServer DBusServer; +/** Called when a new connection to the server is available. Must reference and save the new + * connection, or close the new connection. Set with dbus_server_set_new_connection_function(). + */ typedef void (* DBusNewConnectionFunction) (DBusServer *server, DBusConnection *new_connection, void *data); |