Commit afa4ffbd authored by Havoc Pennington's avatar Havoc Pennington

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

	* dbus/dbus-message.h: put #ifndef DBUS_DISABLE_DEPRECATED around
	dbus_message_iter_get_array_len().

	* throughout: documentation improvements.
parent 65fcbd62
2006-10-21 Havoc Pennington <hp@redhat.com>
* dbus/dbus-message.h: put #ifndef DBUS_DISABLE_DEPRECATED around
dbus_message_iter_get_array_len().
* throughout: documentation improvements.
2006-10-20 Havoc Pennington <hp@redhat.com>
* doc/TODO: remove the int64 thing from 1.0 since it doesn't
......
This diff is collapsed.
......@@ -2940,16 +2940,19 @@ _dbus_connection_send_unlocked_no_update (DBusConnection *connection,
* The function will never fail for other reasons; even if the
* connection is disconnected, you can queue an outgoing message,
* though obviously it won't be sent.
*
* The message serial is used by the remote application to send a
* reply; see dbus_message_get_serial() or the D-Bus specification.
*
* @param connection the connection.
* @param message the message to write.
* @param client_serial return location for client serial.
* @param serial return location for message serial, or #NULL if you don't care
* @returns #TRUE on success.
*/
dbus_bool_t
dbus_connection_send (DBusConnection *connection,
DBusMessage *message,
dbus_uint32_t *client_serial)
dbus_uint32_t *serial)
{
_dbus_return_val_if_fail (connection != NULL, FALSE);
_dbus_return_val_if_fail (message != NULL, FALSE);
......@@ -2958,7 +2961,7 @@ dbus_connection_send (DBusConnection *connection,
return _dbus_connection_send_and_unlock (connection,
message,
client_serial);
serial);
}
static dbus_bool_t
......
......@@ -124,6 +124,9 @@ message_from_error (const char *error)
* }
* @endcode
*
* By convention, all functions allow #NULL instead of a DBusError*,
* so callers who don't care about the error can ignore it.
*
* There are some rules. An error passed to a D-Bus function must
* always be unset; you can't pass in an error that's already set. If
* a function has a return code indicating whether an error occurred,
......@@ -137,13 +140,19 @@ message_from_error (const char *error)
* You can check the specific error that occurred using
* dbus_error_has_name().
*
* Errors will not be set for programming errors, such as passing
* invalid arguments to the libdbus API. Instead, libdbus will print
* warnings, exit on a failed assertion, or even crash in those cases
* (in other words, incorrect use of the API results in undefined
* behavior, possibly accompanied by helpful debugging output if
* you're lucky).
*
* @{
*/
/**
* Initializes a DBusError structure. Does not allocate
* any memory; the error only needs to be freed
* if it is set at some point.
* Initializes a DBusError structure. Does not allocate any memory;
* the error only needs to be freed if it is set at some point.
*
* @param error the DBusError.
*/
......@@ -190,11 +199,15 @@ dbus_error_free (DBusError *error)
/**
* Assigns an error name and message to a DBusError. Does nothing if
* error is #NULL. The message may be NULL, which means a default
* message will be deduced from the name. If the error name is unknown
* to D-Bus the default message will be totally useless, though.
* error is #NULL. The message may be #NULL, which means a default
* message will be deduced from the name. The default message will be
* totally useless, though, so using a #NULL message is not recommended.
*
* @param error the error.
* Because this function does not copy the error name or message, you
* must ensure the name and message are global data that won't be
* freed. You probably want dbus_set_error() instead, in most cases.
*
* @param error the error.or #NULL
* @param name the error name (not copied!!!)
* @param message the error message (not copied!!!)
*/
......@@ -297,14 +310,15 @@ dbus_error_is_set (const DBusError *error)
* Assigns an error name and message to a DBusError.
* Does nothing if error is #NULL.
*
* The format may be NULL, which means a default message will be
* deduced from the name. If the error name is unknown to D-Bus the
* default message will be totally useless, though.
* The format may be #NULL, which means a (pretty much useless)
* default message will be deduced from the name. This is not a good
* idea, just go ahead and provide a useful error message. It won't
* hurt you.
*
* If no memory can be allocated for the error message,
* an out-of-memory error message will be set instead.
*
* @param error the error.
* @param error the error.or #NULL
* @param name the error name
* @param format printf-style format string.
*/
......
......@@ -560,7 +560,7 @@ array_reader_next (DBusTypeReader *reader,
_dbus_assert (reader->value_pos >= reader->u.array.start_pos);
switch (_dbus_first_type_in_signature (reader->type_str,
reader->type_pos))
reader->type_pos))
{
case DBUS_TYPE_DICT_ENTRY:
case DBUS_TYPE_STRUCT:
......@@ -875,10 +875,10 @@ _dbus_type_reader_read_basic (const DBusTypeReader *reader,
}
/**
* Returns the number of values remaining in the current array reader.
* Returns the number of bytes in the array.
*
* @param reader the reader to read from
* @returns the number of elements remaining in the array
* @returns the number of bytes in the array
*/
int
_dbus_type_reader_get_array_length (const DBusTypeReader *reader)
......
......@@ -430,6 +430,9 @@ set_guards (void *real_block,
* on all platforms. Returns #NULL if the allocation fails.
* The memory must be released with dbus_free().
*
* dbus_malloc() memory is NOT safe to free with regular free() from
* the C library. Free it with dbus_free() only.
*
* @param bytes number of bytes to allocate
* @return allocated memory, or #NULL if the allocation fails.
*/
......@@ -481,6 +484,9 @@ dbus_malloc (size_t bytes)
* return #NULL if bytes is zero on all platforms. Returns #NULL if the
* allocation fails. The memory must be released with dbus_free().
*
* dbus_malloc0() memory is NOT safe to free with regular free() from
* the C library. Free it with dbus_free() only.
*
* @param bytes number of bytes to allocate
* @return allocated memory, or #NULL if the allocation fails.
*/
......@@ -741,16 +747,41 @@ _dbus_register_shutdown_func (DBusShutdownFunction func,
*/
/**
* The D-Bus library keeps some internal global variables, for example
* to cache the username of the current process. This function is
* used to free these global variables. It is really useful only for
* leak-checking cleanliness and the like. WARNING: this function is
* NOT thread safe, it must be called while NO other threads are using
* D-Bus. You cannot continue using D-Bus after calling this function,
* as it does things like free global mutexes created by
* dbus_threads_init(). To use a D-Bus function after calling
* dbus_shutdown(), you have to start over from scratch, e.g. calling
* dbus_threads_init() again.
* Frees all memory allocated internally by libdbus and
* reverses the effects of dbus_threads_init(). libdbus keeps internal
* global variables, for example caches and thread locks, and it
* can be useful to free these internal data structures.
*
* dbus_shutdown() does NOT free memory that was returned
* to the application. It only returns libdbus-internal
* data structures.
*
* You MUST free all memory and release all reference counts
* returned to you by libdbus prior to calling dbus_shutdown().
*
* You can't continue to use any D-Bus objects, such as connections,
* that were allocated prior to dbus_shutdown(). You can, however,
* start over; call dbus_threads_init() again, create new connections,
* and so forth.
*
* WARNING: dbus_shutdown() is NOT thread safe, it must be called
* while NO other threads are using D-Bus. (Remember, you have to free
* all D-Bus objects and memory before you call dbus_shutdown(), so no
* thread can be using libdbus.)
*
* The purpose of dbus_shutdown() is to allow applications to get
* clean output from memory leak checkers. dbus_shutdown() may also be
* useful if you want to dlopen() libdbus instead of linking to it,
* and want to be able to unload the library again.
*
* There is absolutely no requirement to call dbus_shutdown() - in fact,
* most applications won't bother and should not feel guilty.
*
* You have to know that nobody is using libdbus in your application's
* process before you can call dbus_shutdown(). One implication of this
* is that calling dbus_shutdown() from a library is almost certainly
* wrong, since you don't know what the rest of the app is up to.
*
*/
void
dbus_shutdown (void)
......
This diff is collapsed.
......@@ -163,7 +163,12 @@ void dbus_message_iter_recurse (DBusMessageIter *iter,
DBusMessageIter *sub);
void dbus_message_iter_get_basic (DBusMessageIter *iter,
void *value);
#ifndef DBUS_DISABLE_DEPRECATED
/* This function returns the wire protocol size of the array in bytes,
* you do not want to know that probably
*/
int dbus_message_iter_get_array_len (DBusMessageIter *iter);
#endif
void dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
void *value,
int *n_elements);
......
......@@ -384,6 +384,9 @@ _dbus_timeout_list_toggle_timeout (DBusTimeoutList *timeout_list,
* Types and functions related to DBusTimeout. A timeout
* represents a timeout that the main loop needs to monitor,
* as in Qt's QTimer or GLib's g_timeout_add().
*
* Use dbus_connection_set_timeout_functions() or dbus_server_set_timeout_functions()
* to be notified when libdbus needs to add or remove timeouts.
*
* @{
*/
......
......@@ -465,6 +465,9 @@ _dbus_watch_set_handler (DBusWatch *watch,
* Types and functions related to DBusWatch. A watch represents
* a file descriptor that the main loop needs to monitor,
* as in Qt's QSocketNotifier or GLib's g_io_add_watch().
*
* Use dbus_connection_set_watch_functions() or dbus_server_set_watch_functions()
* to be notified when libdbus needs to add or remove watches.
*
* @{
*/
......
......@@ -1184,7 +1184,8 @@
A signal emission is simply a single message of type <literal>SIGNAL</literal>.
It must have three header fields: <literal>PATH</literal> giving the object
the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
the fully-qualified name of the signal.
the fully-qualified name of the signal. The <literal>INTERFACE</literal> header is required
for signals, though it is optional for method calls.
</para>
</sect3>
......@@ -3014,7 +3015,9 @@
<entry><literal>interface</literal></entry>
<entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
<entry>Match messages sent over or to a particular interface. An example of an
interface match is interface='org.freedesktop.Hal.Manager'</entry>
interface match is interface='org.freedesktop.Hal.Manager'.
If a message omits the interface header, it must not match any rule
that specifies this key.</entry>
</row>
<row>
<entry><literal>member</literal></entry>
......@@ -3035,12 +3038,13 @@
example of a destination match is destination=':1.0'</entry>
</row>
<row>
<entry><literal>arg[1, 2, 3, ...]</literal></entry>
<entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>
<entry>Any string</entry>
<entry>Arg matches are special and are used for further restricting the
match based on the arguments in the body of a message. As of this time
only string arguments can be matched. An example of an argument match
would be arg3='Foo'.</entry>
would be arg3='Foo'. Only argument indexes from 0 to 63 should be
accepted.</entry>
</row>
</tbody>
</tgroup>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment