fdo-mirrors/dbus
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/dbus/dbus.git synced 2026-05-05 06:28:00 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

2006-10-21 Havoc Pennington <hp@redhat.com>

Browse source 
* Document a bunch of undocumented stuff
This commit is contained in:
Havoc Pennington 2006-10-21 18:51:30 +00:00
parent e19ebac55d
commit fed8880c6f
9 changed files with 111 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
ChangeLog
View file

@ -1,3 +1,7 @@
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

16
dbus/dbus-address.c
View file

@ -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

1
dbus/dbus-address.h
View file

@ -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,

18
dbus/dbus-connection.c
View file

@ -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

78
dbus/dbus-connection.h
View file

@ -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
{

5
dbus/dbus-errors.h
View file

@ -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 */

2
dbus/dbus-marshal-validate.h
View file

@ -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)

1
dbus/dbus-message.h
View file

@ -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;
/**

3
dbus/dbus-server.h
View file

@ -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);