dbus/dbus dbus-address.c, 1.22, 1.23 dbus-address.h, 1.6,
1.7 dbus-connection.c, 1.145, 1.146 dbus-connection.h, 1.45,
1.46 dbus-errors.h, 1.27, 1.28 dbus-marshal-validate.h, 1.13,
1.14 dbus-message.h, 1.64, 1.65 dbus-server.h, 1.19, 1.20
Havoc Pennington
hp at kemper.freedesktop.org
Sat Oct 21 11:51:32 PDT 2006
Update of /cvs/dbus/dbus/dbus
In directory kemper:/tmp/cvs-serv9881/dbus
Modified Files:
dbus-address.c dbus-address.h dbus-connection.c
dbus-connection.h dbus-errors.h dbus-marshal-validate.h
dbus-message.h dbus-server.h
Log Message:
2006-10-21 Havoc Pennington <hp at redhat.com>
* Document a bunch of undocumented stuff
Index: dbus-address.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-address.c,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -d -r1.22 -r1.23
--- dbus-address.c 20 Oct 2006 03:04:59 -0000 1.22
+++ dbus-address.c 21 Oct 2006 18:51:30 -0000 1.23
@@ -214,7 +214,9 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
* 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 @@
/**
* 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
Index: dbus-address.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-address.h,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- dbus-address.h 21 Oct 2006 18:17:02 -0000 1.6
+++ dbus-address.h 21 Oct 2006 18:51:30 -0000 1.7
@@ -37,6 +37,7 @@
* @{
*/
+/** 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,
Index: dbus-connection.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-connection.c,v
retrieving revision 1.145
retrieving revision 1.146
diff -u -d -r1.145 -r1.146
--- dbus-connection.c 21 Oct 2006 17:08:08 -0000 1.145
+++ dbus-connection.c 21 Oct 2006 18:51:30 -0000 1.146
@@ -4578,13 +4578,13 @@
}
/**
- * 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 @@
* 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
Index: dbus-connection.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-connection.h,v
retrieving revision 1.45
retrieving revision 1.46
diff -u -d -r1.45 -r1.46
--- dbus-connection.h 21 Oct 2006 18:17:02 -0000 1.45
+++ dbus-connection.h 21 Oct 2006 18:51:30 -0000 1.46
@@ -39,13 +39,22 @@
* @{
*/
+/* 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 @@
* 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 @@
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 @@
/* 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
{
Index: dbus-errors.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-errors.h,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -d -r1.27 -r1.28
--- dbus-errors.h 21 Oct 2006 18:17:02 -0000 1.27
+++ dbus-errors.h 21 Oct 2006 18:51:30 -0000 1.28
@@ -38,6 +38,7 @@
* @{
*/
+/** Mostly-opaque type representing an error that occurred */
typedef struct DBusError DBusError;
/**
@@ -45,8 +46,8 @@
*/
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 */
Index: dbus-marshal-validate.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-marshal-validate.h,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -d -r1.13 -r1.14
--- dbus-marshal-validate.h 21 Oct 2006 18:17:02 -0000 1.13
+++ dbus-marshal-validate.h 21 Oct 2006 18:51:30 -0000 1.14
@@ -161,7 +161,7 @@
#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)
Index: dbus-message.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-message.h,v
retrieving revision 1.64
retrieving revision 1.65
diff -u -d -r1.64 -r1.65
--- dbus-message.h 21 Oct 2006 18:17:02 -0000 1.64
+++ dbus-message.h 21 Oct 2006 18:51:30 -0000 1.65
@@ -42,6 +42,7 @@
*/
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;
/**
Index: dbus-server.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-server.h,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -d -r1.19 -r1.20
--- dbus-server.h 21 Oct 2006 18:17:02 -0000 1.19
+++ dbus-server.h 21 Oct 2006 18:51:30 -0000 1.20
@@ -41,6 +41,9 @@
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);
More information about the dbus-commit
mailing list