dbus-tcl - Tcl library for interacting with the DBus
The dbus-tcl package provides commands to interact with DBus message busses. There are three well-known bus names: session, system, and starter. The starter bus only applies when the application has been started as a result of a method call from another application. A connection to the starter bus will effectively be an alternative connection to either the session or the system bus.
Most subcommands take a busID argument. This is the DBus handle as returned by the dbus connect subcommand. For the well-known busses the handle matches the name of the bus. If the busID argument is not specified, it defaults to session.
Send a method call onto the dbus and optionally wait for a reply. If the signature of the DBus method_return reply only contains one top-level element, the arguments of the method_return message are returned as a single value. More complex structures are returned as a list.
If the response to the DBus method_call message is a DBus error message, the command will produce an error. In that case the errorCode variable will be set to DBUS DBUS_MESSAGE_TYPE_ERROR.
The -autostart option specifies whether the bus server should attempt to start an associated application if the destination name does not currently exist on the bus. Boolean may have any proper boolean value, such as 1 or no. Defaults to 1 (true).
The -timeout option specifies the maximum time to wait for a response. A negative timeout indicates that no response should be requested.
If a script is specified with the -handler option, the call will be asynchronous. In that case the command returns the serial of the request. The script will be executed when a response comes back or when there is an error.
The -signature option defines the types of arguments to be sent on the dbus. See the Signatures section for more information. If no signature is specified, all arguments will be sent as strings.
Close the connection to the DBus. This will cleanup all handlers, listeners, and the optional monitor script registered for the busID. The actual bus connection of the application will not really be terminated if busID is one of the three so-called well-known busses, as this is not supported by libdbus. Reconnecting to one of those busses will result in reusing the same unique name as before.
Connect to the DBus. The address argument specifies the bus to connect to. This can be either one of the well-known busses ('session', 'system' or 'starter'), or a transport name followed by a colon, and then an optional, comma-separated list of keys and values in the form key=value. The command returns a handle that can be used as the busID argument in other dbus commands. It is legal to run this command when already connected.
Send a DBus error message with the specified serial and destination. If the -name option is not specified, it defaults to "org.freedesktop.DBus.Error.Failed". This method is targetted to be used in combination with a script registered using the dbus method subcommand with the -async option. The values for destination and serial can be obtained from event information fields 'sender' and 'serial' correspondingly. See Event Handlers below for more information.
The add subcommand adds a match rule to match messages going through the message bus. The remove subcommand removes the most recently added rule that exactly matches the specified option settings. If there is no matching rule, the command is silently ignored. Available options are: -destination, -interface, -member, -path, -sender, and -type. The command returns the match rule passed to libdbus.
The info command can be used to obtain information about the DBus. Available info options are:
Get the UUID of the local machine.
The object path used in local/in-process-generated messages (/org/freedesktop/DBus/Local).
Get the unique name of the connection as assigned by the message bus.
The object path used to talk to the bus itself (/org/freedesktop/DBus).
Report if any messages are in the queue to be sent.
Get the UUID of the server we are authenticated to.
The bus name used to talk to the bus itself (org.freedesktop.DBus).
Returns the version of libdbus.
Register a script to be called when the signal named "member" at path appears on the DBus. See Event Handlers below for more information.
If the path argument is an empty string, script will be executed whenever a signal message is received for any path, unless a dedicated listener for the exact path has been defined. The member argument may be specified as either a signal name or an interface and signal name joined by a period. If no interface is specified, the script will be called for signals with any interface.
If script is an empty string, the currently registered command for the specified signal and path will be unregistered. If the script argument is not specified, the currently registered command for the specified signal and path, if any, is returned. If no member argument is specified a list of all registered signals and associated commands at the specified path is returned. If no path argument is specified a list of all paths and their registered signals and associated commands is returned.
Register a script to be called when method member is invoked at the specified path. See Event Handlers below for more information.
If the path argument is an empty string, script will be executed whenever a method call message is received for any path, unless a dedicated method handler for the exact path has been defined. The member argument may be specified as either a method name or an interface and method name joined by a period. If no interface is specified, the script will be called for methods with any interface, unless another handler is specified for the method including the interface. If script is an empty string, the currently registered command for the specified method and path will be unregistered.
When a script argument is specified, even if it is an empty string, the command may fail if another interpreter has already registered a handler for the exact same path, interface and method. See Slave Interpreters below for more information.
If the script argument is not specified, the currently registered command for the specified method and path, if any, is returned. If no member argument is specified a list of all registered methods and associated commands at the specified path is returned. If no path argument is specified a list of all paths and their registered methods and associated commands is returned.
In the simple case, when script is evaluated because of a method_call, the result of the script will be returned to the caller as a string in a DBus method_return message. If the execution of script ends with an error, the error message is returned to the caller in a DBus error message. Any DBus errors that happen while sending these messages back to the caller are silently ignored. If the caller specified the no_reply flag in the method_call as FALSE, no method_return or error message will be returned.
For more advanced control over the returned messages the -async option can be specified while registering the script. First of all, as the name suggests, this option allows results or errors to be returned from code outside of script. The dbus return and dbus error subcommands should be used for that. The dbus return subcommand can also be used to return more complex data structures than a string from script. In that case the -async option ensures that the return value of script is suppressed. Even when returning a string to the caller from within script it may still be useful to specify the -async option and use the dbus return subcommand. This allows handling of dbus errors while sending back the return message.
When evaluation of script ends in an error, the error will always be returned to the caller unless the no_reply flag was set to TRUE. The setting of the -async option has no influence on this behaviour.
Register a script to be executed when any DBus message is received. See Event Handlers below for more information.
This can be useful for building special purpose programs that need to see all activity on the DBus, for example a DBus monitoring program. If script is an empty string, the currently configured monitor script will be removed.
Request the bus to assign a given name to the connection. The command will generate an error in all cases where it was unsuccessful in making the application the primary owner of the name.
The -yield option specifies that the application will release the requested name when some other application requests the same name and has indicated that it wants to take over ownership of the name. The application will be informed by a signal when it loses ownership of the name.
The -replace option indicates that the application wants to take over the ownership of the name from the application that is currently the primary owner, if any. This request will only be honoured if the current owner has indicated that it will release the name on request. See also the -yield option.
If the requested name is currently in use and the -replace option has not been specified, or the -replace option was specified but the current owner is unwilling to give up its ownership, the name request will normally be queued. Then when the name is released by current owner it is assigned to the next requester in the queue and a signal is sent to inform that requester that it is now the primary owner of the name. The -noqueue option may be specified to indicate that the name request should not be queued.
Note that even if the request has been queued, the command will generate an error because the goal of becoming the primary owner of the name has not been achieved.
Asks the bus to unassign the given name from this connection.
Send a DBus method_return message with the specified serial and destination. This method is targetted to be used in combination with a script registered using the dbus method subcommand with the -async option. The values for destination and serial can be obtained from event information fields 'sender' and 'serial' correspondingly. See Event Handlers below for more information.
Send a signal onto the dbus with the specified type signature. If no -signature option is provided, all args will be sent as strings. The command returns the serial number of the dbus message.
Validates string against the rules of the D-Bus specification for the type of value specified by class. Returns 1 if validation passes, otherwise returns 0. The following classes are recognized (the class name can be abbreviated):
Two or more dot-separated non-empty elements. Each element only contains the ASCII characters "[A-Z][a-z][0-9]_" and does not begin with a digit.
A string that only contains the ASCII characters "[A-Z][a-z][0-9]_" and does not begin with a digit.
Either a unique connection name, or a well-known connection name. Unique connection names begin with a colon and consist of at least two dot-separated non-empty elements. Each element only contains the ASCII characters "[A-Z][a-z][0-9]_". Well-known connection names consist of at least two dot-separated non-empty elements. Each element only contains the ASCII characters "[A-Z][a-z][0-9]_" and does not begin with a digit.
A slash followed by zero or more slash-separated non-empty elements. Each element only contains the ASCII characters "[A-Z][a-z][0-9]_".
A valid D-Bus message type signature. See Signatures below for more information on what constitutes a valid signature.
The call, listen, method and monitor methods provide the ability to define event handlers. The specified script will be used as the prefix for a command that will be evaluated whenever the corresponding DBus event occurs. When the DBus event occurs, a Tcl command will be generated by concatenating the script with one or more arguments. The first argument is a dict containing information about the event. If the DBus event contained any arguments they will be appended to the command as seperate arguments.
The dict with the event details contains the following information:
The interface member being invoked (for methods) or emitted (for signals).
The interface this message is being sent to (for methods) or being emitted from (for signals). The interface name is fully-qualified.
The object path this message is being sent to (for methods) or being emitted from (for signals).
The unique name of the connection which originated this message, or the empty string if unknown or inapplicable. The sender is filled in by the message bus. Note, the returned sender is always the unique bus name. Connections may own multiple other bus names, but those are not found in the sender field.
The destination of a message or the empty string if there is none set.
The type of a message. Possible values are method_call, method_return, error, and signal.
The type signature of the message, i.e. the type specification of the arguments in the message payload. See Signatures below for more information.
The serial of a message or 0 if none has been specified. The message's serial number is provided by the application sending the message and is used to identify replies to this message. All messages received on a connection will have a serial provided by the remote application. When sending messages a serial will automatically be assigned by the dbus-tcl library.
The serial that the message is a reply to or 0 if none.
Flag indicating if the sender expects a reply. Set to 1 if a reply is not required.
Flag indicating if the message will cause an owner for destination name to be auto-started.
The error name of a received error message. An empty string for all other message types.
The event handlers are excuted at global level (outside the context of any Tcl procedure) in the interpreter in which the event handler was installed.
The DBus specification defines typed arguments. This doesn't fit well with the Tcl philosophy of everything is a string. To be able to closely control the type of the arguments to be sent onto the DBus a signature can be supplied. The signature definition is exactly the same as in the DBus specification. A signature is a string where a single character or group of characters specifies the type of an argument. The following types exist:
A UTF-8 encoded, nul-terminated Unicode string.
A boolean, FALSE (0), or TRUE (1).
A byte (8-bit unsigned integer).
A 16-bit signed integer.
A 16-bit unsigned integer.
A 32-bit signed integer.
A 32-bit unsigned integer.
A 64-bit signed integer.
A 64-bit unsigned integer.
An 8-byte double in IEEE 754 format.
A type signature.
An object path.
A D-Bus array type, which is similar to a Tcl list. The # specifies the type of the array elements. This can be any type, including another array, a struct or a dict entry.
A D-Bus variant type. The provided value should be a two-element list, containing a signature and the actual value. See Variant Arguments for more information.
A struct. The string inside the parentheses defines the types of the arguments within the struct, which may consist of a combination of any of the existing types.
A dict entry. Dict entries may only occur as array elements. The first # specifies the type of the dict key. This must be a basic type (one of 'sbynqiuxtdgo'). The second # specifies the type of the dict value. This can again be any existing type.
Example: The signature 'vaas(id)a{i(ss)}' specifies four arguments and translates to Tcl terminology as follows: The type of the first argument ('v') is extracted from its value. The second argument ('aas') is a list containing lists of strings. The third argument ('(id)') is a list containing an integer and a double. The last argument ('a{i(ss)}') is a dict (an array of dict entries) with integer keys and each value is a list of two strings.
When a signature specifies that an argument is of type "variant", the argument can still be almost anything. Additional information needs to be located to determine how to package the value for transmission onto the dbus. The preferred way is for the argument to be a two-element list where the first element specifies the signature for the value and the second element is the actual value.
The signature for a variant argument has to specify a single complete type. The value of the second list element must match the signature, otherwise an error will be reported.
If the value provided for a variant argument is not a two-element list, or the first element is not a valid signature for a single complete type, the code will attempt to automatically determine the type of the provided value. It does this by selecting a signature based on the internal representation of the value according to the following table:
Normally the dbus-tcl library only provides the value of a variant argument. But in some situations the Tcl code may need to be able to also obtain the argument type. When this variable is set to 1, each variant argument is represented as a list with two elements. The first list element contains the signature of the argument and the second list element is the value.
The standard D-Bus library libdbus will only assign a single unique bus name per application. This means that slave interpreters that connect to the D-Bus will get the same unique bus name as the main interpreter, or any other slave interpreter that has connected to the D-Bus.
It is not a problem if multiple interpreters register a listener for the exact same signal. The dbus-tcl package will execute the commands for all interpreters (in an undefined order). The same applies to monitor commands registered by different interpreters. However, a method call generally causes a result being returned to the caller. Therefor there should only be exactly one handler registered for a specific method. If any interpreter tries to register a method handler for an interface and member at a path that is already registered by another interpreter, the request will be denied.
Copyright © 2008-2012 Schelte Bron