summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--ChangeLog4
-rw-r--r--dbus/dbus-address.c16
-rw-r--r--dbus/dbus-address.h1
-rw-r--r--dbus/dbus-connection.c18
-rw-r--r--dbus/dbus-connection.h78
-rw-r--r--dbus/dbus-errors.h5
-rw-r--r--dbus/dbus-marshal-validate.h2
-rw-r--r--dbus/dbus-message.h1
-rw-r--r--dbus/dbus-server.h3
9 files changed, 111 insertions, 17 deletions
diff --git a/ChangeLog b/ChangeLog
index dc84b989..5766ecf9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -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);