fdo-mirrors/dbus
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/dbus/dbus.git synced 2026-02-04 21:10:26 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

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

	* throughout: documentation improvements.
This commit is contained in:
Havoc Pennington 2006-10-21 17:08:08 +00:00
parent 65fcbd6287
commit afa4ffbd85
11 changed files with 1605 additions and 1259 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
ChangeLog
View file

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

217
dbus/dbus-bus.c
View file

@ -36,6 +36,21 @@
* @ingroup DBus
* @brief Functions for communicating with the message bus
*
* dbus_bus_get() allows all modules and libraries in a given
* process to share the same connection to the bus daemon by storing
* the connection globally.
*
* All other functions in this module are just convenience functions;
* most of them invoke methods on the bus daemon, by sending method
* call messages to #DBUS_SERVICE_DBUS. These convenience functions
* often make blocking method calls. If you don't want to block,
* you can send the method call messages manually in the same way
* you would any other method call message.
*
* This module is the only one in libdbus that's specific to
* communicating with the message bus daemon. The rest of the API can
* also be used for connecting to another application directly.
*
* @todo right now the default address of the system bus is hardcoded,
* so if you change it in the global config file suddenly you have to
* set DBUS_SYSTEM_BUS_ADDRESS env variable. Might be nice if the
@ -472,6 +487,11 @@ internal_bus_get (DBusBusType type,
* will exit if the connection closes. You can undo this
* by calling dbus_connection_set_exit_on_disconnect() yourself
* after you get the connection.
*
* dbus_bus_get() calls dbus_bus_register() for you.
*
* If returning a newly-created connection, this function will block
* until authentication and bus registration are complete.
*
* @param type bus type
* @param error address where an error can be returned.
@ -485,11 +505,11 @@ dbus_bus_get (DBusBusType type,
}
/**
* Connects to a bus daemon and registers the client with it as with dbus_bus_register().
* Unlike dbus_bus_get(), always creates a new connection. This connection
* will not be saved or recycled by libdbus. Caller owns a reference
* to the bus and must either close it or know it to be closed
* prior to releasing this reference.
* Connects to a bus daemon and registers the client with it as with
* dbus_bus_register(). Unlike dbus_bus_get(), always creates a new
* connection. This connection will not be saved or recycled by
* libdbus. Caller owns a reference to the bus and must either close
* it or know it to be closed prior to releasing this reference.
*
* See dbus_connection_open_private() for more details on when to
* close and unref this connection.
@ -500,6 +520,11 @@ dbus_bus_get (DBusBusType type,
* by calling dbus_connection_set_exit_on_disconnect() yourself
* after you get the connection.
*
* dbus_bus_get_private() calls dbus_bus_register() for you.
*
* This function will block until authentication and bus registration
* are complete.
*
* @param type bus type
* @param error address where an error can be returned.
* @returns a DBusConnection with new ref
@ -519,6 +544,13 @@ dbus_bus_get_private (DBusBusType type,
*
* If you use dbus_bus_get() or dbus_bus_get_private() this
* function will be called for you.
*
* If you open a bus connection with dbus_connection_open() or
* dbus_connection_open_private() you will have to dbus_bus_register()
* yourself, or make the appropriate registration method calls
* yourself.
*
* This function will block until registration is complete.
*
* @param connection the connection
* @param error place to store errors
@ -598,9 +630,11 @@ dbus_bus_register (DBusConnection *connection,
/**
* Sets the unique name of the connection. Can only be used if you
* registered with the bus manually (i.e. if you did not call
* dbus_bus_register()). Can only be called once per connection.
* Sets the unique name of the connection, as assigned by the message
* bus. Can only be used if you registered with the bus manually
* (i.e. if you did not call dbus_bus_register()). Can only be called
* once per connection. After the unique name is set, you can get it
* with dbus_bus_get_unique_name().
*
* @param connection the connection
* @param unique_name the unique name
@ -626,11 +660,17 @@ dbus_bus_set_unique_name (DBusConnection *connection,
}
/**
* Gets the unique name of the connection. Only possible after the
* connection has been registered with the message bus.
* Gets the unique name of the connection as assigned by the message
* bus. Only possible after the connection has been registered with
* the message bus.
*
* The name remains valid for the duration of the connection and
* The name remains valid until the connection is freed, and
* should not be freed by the caller.
*
* There are two ways to set the unique name; one is
* dbus_bus_register(), the other is dbus_bus_set_unique_name().
* You are responsible for calling dbus_bus_set_unique_name()
* if you register by hand instead of using dbus_bus_register().
*
* @param connection the connection
* @returns the unique name or NULL on error
@ -650,16 +690,22 @@ dbus_bus_get_unique_name (DBusConnection *connection)
}
/**
* Asks the bus to return the uid of the named
* connection.
* Asks the bus to return the uid of the named connection.
* Only works on UNIX; only works for connections on the same
* machine as the bus. If you are not on the same machine
* as the bus, then calling this is probably a bad idea,
* since the uid will mean little to your application.
*
* Not going to work on Windows, the bus should return
* an error then.
* For the system message bus you're guaranteed to be on the same
* machine since it only listens on a UNIX domain socket (at least,
* as shipped by default).
*
* This function will just return an error on Windows.
*
* @param connection the connection
* @param name a name owned by the connection
* @param error location to store the error
* @returns a result code, -1 if error is set
* @returns the unix user id, or ((unsigned)-1) if error is set
*/
unsigned long
dbus_bus_get_unix_user (DBusConnection *connection,
@ -734,17 +780,46 @@ dbus_bus_get_unix_user (DBusConnection *connection,
* result codes are discussed here, but the specification is the
* canonical version of this information.
*
* The #DBUS_NAME_FLAG_ALLOW_REPLACEMENT flag indicates that the caller
* will allow other services to take over the name from the current owner.
* First you should know that for each bus name, the bus stores
* a queue of connections that would like to own it. Only
* one owns it at a time - called the primary owner. If the primary
* owner releases the name or disconnects, then the next owner in the
* queue atomically takes over.
*
* The #DBUS_NAME_FLAG_REPLACE_EXISTING flag indicates that the caller
* would like to take over the name from the current owner.
* If the current name owner did not use #DBUS_NAME_FLAG_ALLOW_REPLACEMENT
* then this flag indicates that the caller would like to be placed
* in the queue to own the name when the current owner lets go.
* So for example if you have an application org.freedesktop.TextEditor
* and multiple instances of it can be run, you can have all of them
* sitting in the queue. The first one to start up will receive messages
* sent to org.freedesktop.TextEditor, but if that one exits another
* will become the primary owner and receive messages.
*
* The queue means you don't need to manually watch for the current owner to
* disappear and then request the name again.
*
* When requesting a name, you can specify several flags.
*
* #DBUS_NAME_FLAG_ALLOW_REPLACEMENT and #DBUS_NAME_FLAG_DO_NOT_QUEUE
* are properties stored by the bus for this connection with respect to
* each requested bus name. These properties are stored even if the
* connection is queued and does not become the primary owner.
* You can update these flags by calling RequestName again (even if
* you already own the name).
*
* #DBUS_NAME_FLAG_ALLOW_REPLACEMENT means that another requestor of the
* name can take it away from you by specifying #DBUS_NAME_FLAG_REPLACE_EXISTING.
*
* #DBUS_NAME_FLAG_DO_NOT_QUEUE means that if you aren't the primary owner,
* you don't want to be queued up - you only care about being the
* primary owner.
*
* Unlike the other two flags, #DBUS_NAME_FLAG_REPLACE_EXISTING is a property
* of the individual RequestName call, i.e. the bus does not persistently
* associate it with the connection-name pair. If a RequestName call includes
* the #DBUS_NAME_FLAG_REPLACE_EXISTING flag, and the current primary
* owner has #DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, then the current primary
* owner will be kicked off.
*
* If no flags are given, an application will receive the requested
* name only if the name is currently unowned; it will NOT give
* name only if the name is currently unowned; and it will NOT give
* up the name if another application asks to take it over using
* #DBUS_NAME_FLAG_REPLACE_EXISTING.
*
@ -770,7 +845,9 @@ dbus_bus_get_unix_user (DBusConnection *connection,
* #DBUS_NAME_FLAG_REPLACE_EXISTING.
*
* #DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER happens if an application
* requests a name it already owns.
* requests a name it already owns. (Re-requesting a name is useful if
* you want to change the #DBUS_NAME_FLAG_ALLOW_REPLACEMENT or
* #DBUS_NAME_FLAG_DO_NOT_QUEUE settings.)
*
* When a service represents an application, say "text editor," then
* it should specify #DBUS_NAME_FLAG_ALLOW_REPLACEMENT if it wants
@ -779,7 +856,19 @@ dbus_bus_get_unix_user (DBusConnection *connection,
* specify #DBUS_NAME_FLAG_REPLACE_EXISTING to either take over
* (last-started-wins) or be queued up (first-started-wins) according
* to whether #DBUS_NAME_FLAG_ALLOW_REPLACEMENT was given.
*
*
* Conventionally, single-instance applications often offer a command
* line option called --replace which means to replace the current
* instance. To implement this, always set
* #DBUS_NAME_FLAG_ALLOW_REPLACEMENT when you request your
* application's bus name. When you lose ownership of your bus name,
* you need to exit. Look for the signal "NameLost" from
* #DBUS_SERVICE_DBUS and #DBUS_INTERFACE_DBUS (the signal's first
* argument is the bus name that was lost). If starting up without
* --replace, do not specify #DBUS_NAME_FLAG_REPLACE_EXISTING, and
* exit if you fail to become the bus name owner. If --replace is
* given, ask to replace the old owner.
*
* @param connection the connection
* @param name the name to request
* @param flags flags
@ -855,10 +944,18 @@ dbus_bus_request_name (DBusConnection *connection,
/**
* Asks the bus to unassign the given name to this connection by invoking
* the ReleaseName method on the bus. This method is fully documented
* in the D-Bus specification.
* Asks the bus to unassign the given name from this connection by
* invoking the ReleaseName method on the bus. The "ReleaseName"
* method is canonically documented in the D-Bus specification.
*
* Possible results are: #DBUS_RELEASE_NAME_REPLY_RELEASED
* which means you owned the name or were in the queue to own it,
* and and now you don't own it and aren't in the queue.
* #DBUS_RELEASE_NAME_REPLY_NOT_OWNER which means someone else
* owns the name so you can't release it.
* #DBUS_RELEASE_NAME_REPLY_NON_EXISTENT
* which means nobody owned the name.
*
* @param connection the connection
* @param name the name to remove
* @param error location to store the error
@ -930,8 +1027,17 @@ dbus_bus_release_name (DBusConnection *connection,
}
/**
* Checks whether a certain name has an owner.
* Asks the bus whether a certain name has an owner.
*
* Using this can easily result in a race condition,
* since an owner can appear or disappear after you
* call this.
*
* If you want to request a name, just request it;
* if you want to avoid replacing a current owner,
* don't specify #DBUS_NAME_FLAG_REPLACE_EXISTING and
* you will get an error if there's already an owner.
*
* @param connection the connection
* @param name the name
* @param error location to store any errors
@ -1000,6 +1106,12 @@ dbus_bus_name_has_owner (DBusConnection *connection,
* The flags parameter is for future expansion, currently you should
* specify 0.
*
* It's often easier to avoid explicitly starting services, and
* just send a method call to the service's bus name instead.
* Method calls start a service to handle them by default
* unless you call dbus_message_set_auto_start() to disable this
* behavior.
*
* @param connection the connection
* @param name the name we want the new service to request
* @param flags the flags (should always be 0 for now)
@ -1119,11 +1231,13 @@ send_no_return_values (DBusConnection *connection,
* path='/bar/foo',destination=':452345.34'"
*
* Possible keys you can match on are type, sender,
* interface, member, path, destination and the special
* arg keys. Excluding a key from the rule indicates
* a wildcard match. For instance excluding the
* interface, member, path, destination and numbered
* keys to match message args (keys are 'arg0', 'arg1', etc.).
* Omitting a key from the rule indicates
* a wildcard match. For instance omitting
* the member from a match rule but adding a sender would
* let all messages from that sender through.
* let all messages from that sender through regardless of
* the member.
*
* Matches are inclusive not exclusive so as long as one
* rule matches the message will get through. It is important
@ -1132,12 +1246,31 @@ send_no_return_values (DBusConnection *connection,
* can cause performance problems such as draining batteries
* on embedded platforms.
*
* The special arg keys are used for further restricting the
* match based on the parameters sent by the signal or method.
* For instance arg1='foo' will check the first argument,
* arg2='bar' the second and so on. For performance reasons
* there is a set limit on the highest number parameter that
* can be checked which is set in dbus-protocol.h
* If you match message args ('arg0', 'arg1', and so forth)
* only string arguments will match. That is, arg0='5' means
* match the string "5" not the integer 5.
*
* Currently there is no way to match against non-string arguments.
*
* Matching on interface is tricky because method call
* messages only optionally specify the interface.
* If a message omits the interface, then it will NOT match
* if the rule specifies an interface name. This means match
* rules on method calls should not usually give an interface.
*
* However, signal messages are required to include the interface
* so when matching signals usually you should specify the interface
* in the match rule.
*
* For security reasons, you can match arguments only up to
* #DBUS_MAXIMUM_MATCH_RULE_ARG_NUMBER.
*
* Match rules have a maximum length of #DBUS_MAXIMUM_MATCH_RULE_LENGTH
* bytes.
*
* Both of these maximums are much higher than you're likely to need,
* they only exist because the D-Bus bus daemon has fixed limits on
* all resource usage.
*
* @param connection connection to the message bus
* @param rule textual form of match rule
@ -1181,6 +1314,10 @@ dbus_bus_add_match (DBusConnection *connection,
* recently-added identical rule gets removed). The "rule" argument
* is the string form of a match rule.
*
* The bus compares match rules semantically, not textually, so
* whitespace and ordering don't have to be identical to
* the rule you passed to dbus_bus_add_match().
*
* If you pass #NULL for the error, this function will not
* block; otherwise it will. See detailed explanation in
* docs for dbus_bus_add_match().

9
dbus/dbus-connection.c
View file

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

36
dbus/dbus-errors.c
View file

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

6
dbus/dbus-marshal-recursive.c
View file

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

51
dbus/dbus-memory.c
View file

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

2515
dbus/dbus-message.c
View file

File diff suppressed because it is too large Load diff

5
dbus/dbus-message.h
View file

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

3
dbus/dbus-timeout.c
View file

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

3
dbus/dbus-watch.c
View file

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

12
doc/dbus-specification.xml
View file

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