NAME

dbus - Tcl library for interacting with the DBus

SYNOPSIS

package require Tcl 8.5

package require dbus 2.1

dbus call ?busID? ?-autostart ?boolean?? ?-dest target? ?-details ?boolean?? ?-handler script? ?-signature string? ?-timeout ms? path interface method ?arg ...?

dbus close ?busID?

dbus connect ?address?

dbus error ?busID? ?-name string? destination serial ?message?

dbus filter ?busID? subcommand -option value ?...?

dbus info ?busID? option

dbus listen ?busID? ?-details? ?path ?member ?script???

dbus method ?busID? ?-details? ?path ?member ?script???

dbus monitor ?busID? ?-details? script

dbus name ?busID? ?-option ...? name

dbus release ?busID? name

dbus return ?busID? ?-signature string? destination serial ?arg ...?

dbus signal ?busID? ?-signature string? object interface name ?arg ...?

dbus unknown ?busID? ?-details? ?path ?script??

dbus validate class string

DESCRIPTION

The dbus 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.

The -details option specifies how variant arguments in the return value are represented. With the default value of FALSE, only the value of a variant argument is provided. But in some situations the Tcl code may need to be able to also obtain the argument type. When this option is set to TRUE, 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.

dbus close ?busID?

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.

dbus connect ?address?

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.

dbus error ?busID? ?-name string? destination serial ?message?

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". The values for destination and serial can be obtained from event information fields 'sender' and 'serial' correspondingly. See Event Handlers below for more information.

When employing this subcommand, make sure the result of the dbus method script isn't automatically returned to the caller by using the -async option of the return command. See dbus method for more information.

dbus filter ?busID? subcommand -option value ?...?

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, -eavesdrop, -interface, -member, -path, -sender, and -type. The command returns the match rule passed to libdbus.

dbus info ?busID? option

The info command can be used to obtain information about the DBus. Available info options are:

capabilities: Returns a dict describing the capabilities of the dbus connection. Currently only one capability has been defined: unixfd, which indicates if file descriptor passing is supported on the dbus connection.
local: The object path used in local/in-process-generated messages (/org/freedesktop/DBus/Local).
machineid: Get the UUID of the local machine.
name: Get the unique name of the connection as assigned by the message bus.
path: The object path used to talk to the bus itself (/org/freedesktop/DBus).
pending: Report if any messages are in the queue to be sent.
serverid: Get the UUID of the server we are authenticated to.
service: The bus name used to talk to the bus itself (org.freedesktop.DBus).
version: Returns the version of libdbus.

dbus listen ?busID? ?-details? ?path ?member ?script???

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.

The -details option causes variant arguments to be 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.

dbus method ?busID? ?-details? ?path ?member ?script???

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.

When script is evaluated, the return value of the script will normally be returned to the caller using a DBus method_return message in a string argument. 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 TRUE, no method_return or error message will be returned.

The script code recognizes an additional -async option for the Tcl return command. When that option is specified with a true boolean value (true, yes, 1), the return value from the body will not automatically be returned to the caller. A response message should then be generated using the dbus return or dbus error subcommands.

This method provides more advanced control over the returned messages. It allows for more complex data structures than just a string to be returned. It also makes it possible to generate a return message some time after script has already finished. Additionally, any dbus errors while sending back the return message can be detected and handled.

The -details option causes variant arguments to be 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.

dbus monitor ?busID? ?-details? script

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.

The -details option causes variant arguments to be 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.

dbus name ?busID? ?-option ...? name

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 NameLost signal when it loses ownership of the name. The following command can be used to exit the application when the name is taken over by another process:

dbus listen [dbus info path] [dbus info service].NameLost \
  [list apply {{name info str} {if {$str eq $name} exit}} $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.

dbus release ?busID? name

Asks the bus to unassign the given name from this connection.

dbus return ?busID? ?-signature string? destination serial ?arg ...?

Send a DBus method_return message with the specified serial and destination. The values for destination and serial can be obtained from event information fields 'sender' and 'serial' correspondingly. See Event Handlers below for more information.

dbus signal ?busID? ?-signature string? object interface name ?arg ...?

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.

dbus unknown ?busID? ?-details? ?path ?script??

Register a script to be called when an unknown method 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 an unknown method call message is received for any path, unless a dedicated unknown handler for the exact path has been defined. If script is an empty string, the currently registered command for the specified 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 an unknown handler for the exact same path. See Slave Interpreters below for more information.

If the script argument is not specified, the currently registered command for the specified path, if any, is returned. If no path argument is specified, a list of all paths and their registered unknown handlers is returned.

An unknown handler will usually return an error, but it is also possible to return a non-error response. The dbus error and dbus return subcommands should be used for this purpose. Contrary to the dbus method subcommand, the return value of the handler will not automatically be returned to the caller. Any uncaught error in the evaluation of script will be reported back to the caller.

The -details option causes variant arguments to be 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.

It will generally not be necessary to set up unknown handlers. If no unknown handler is specified, the package returns an org.freedesktop.dbus.error.unknownmethod error back to the caller of an unknown method.

dbus validate class string

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

interface: 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.
member: A string that only contains the ASCII characters "[A-Z][a-z][0-9]_" and does not begin with a digit.
name: 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.
path: 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]_".
signature: A valid D-Bus message type signature. See Signatures below for more information on what constitutes a valid signature.

EVENT HANDLERS

The call, listen, method, monitor, and unknown 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:

member: The interface member being invoked (for methods) or emitted (for signals).
interface: The interface this message is being sent to (for methods) or being emitted from (for signals). The interface name is fully-qualified.
path: The object path this message is being sent to (for methods) or being emitted from (for signals).
sender: 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.
destination: The destination of a message or the empty string if there is none set.
messagetype: The type of a message. Possible values are method_call, method_return, error, and signal.
signature: The type signature of the message, i.e. the type specification of the arguments in the message payload. See Signatures below for more information.
serial: 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 library.
replyserial: The serial that the message is a reply to or 0 if none.
noreply: Flag indicating if the sender expects a reply. Set to 1 if a reply is not required.
autostart: Flag indicating if the message will cause an owner for destination name to be auto-started.
errorname: 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.

SIGNATURES

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:

s: A UTF-8 encoded, nul-terminated Unicode string.
b: A boolean, FALSE (0), or TRUE (1).
y: A byte (8-bit unsigned integer).
n: A 16-bit signed integer.
q: A 16-bit unsigned integer.
i: A 32-bit signed integer.
u: A 32-bit unsigned integer.
x: A 64-bit signed integer.
t: A 64-bit unsigned integer.
d: An 8-byte double in IEEE 754 format.
h: A file descriptor.
g: A type signature.
o: An object path.
a#: 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.
v: 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.

VARIANT ARGUMENTS

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:

string: s
int: i
wideInt: x
double: d
boolean: b
list: as
dict: a{ss}
anything else: s

FILE DESCRIPTORS

On output, the value provided for a file handler argument must be an open Tcl channel (such as has been created with the open or socket commands). An error will be thrown if the value does not represent an open channel, or if the dbus connection does not support passing file handler arguments.

On input, a new channel will be created and its name passed to the script. The new channel is opened for both reading and writing. If this is not desired, either direction may be closed using the appropriate half-close version of the close command.

The channel name is likely to be different in the two involved applications. When finished with the channel, both parties are responsible for closing the channel using their own channel reference.

SLAVE INTERPRETERS

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

Copyright (c) 2008-2015 Schelte Bron