NAME

dbus - Tcl library for interacting with the DBus

SYNOPSIS

package require Tcl 8.5 9.0

package require dbus 4.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 key 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? ?-dest target? ?-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 buses. 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. In that case, the starter bus refers to bus on which the other application issued the method call. If the application was not started as a result of a method call by another application, starter is just another name for the session bus.

BUS IDS

Most subcommands take an optional busID argument. This may be specified in either of two ways: By DBus handle or by well-known bus name. A DBus handle is obtained using the dbus connect subcommand. The dbus library also maintains a per-interpreter set of three aliases, with the same names as the well-known buses. Whenever a connection is created on one of these well-known buses, a check is made whether the alias for that bus already refers to a connection. If not, the alias is assigned to the newly created connection. The assignment remains in effect for the lifetime of the connection. When the connection is closed, the alias becomes unassigned.

If the busID argument is omitted, it defaults to session.

DBUS SUBCOMMANDS

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

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. The details of the dbus response message are added to the interpreter's return options dictionary. The entries will be the same as those described for the event details in the Event Handlers section below.

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 CALL REPLY, followed by the dbus error name.

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.

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 buses ('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 possible to create multiple connections to the same DBus. But that should normally be avoided, unless there is a good reason. One good reason would be if the program uses normal DBus operations, but also needs to monitor the traffic on the DBus using the BecomeMonitor method.

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 key 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 key/value pairs. If there is no matching rule, the command is silently ignored. Available keys are: arg#, arg#path, arg0namespace, destination, eavesdrop, interface, member, path, path_namespace, sender, and type, where # represents an argument index (0 to 63). Using both path and path_namespace in the same match rule is not allowed. 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:

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.

In most cases it will be necessary to set up a filter to ensure the desired signals are delivered to the application. Otherwise only signals that are explicitly sent to the application will be received. Signals don't usually have a destination specified.

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.

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. By default, the error name is "org.freedesktop.DBus.Error.Failed". But the script may pass a -name option (along with -code error) to the Tcl return command to return a different error name. 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

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.

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

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 signal ?busID? ?-dest target? ?-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. Signals are normally broadcast on the bus. In specific scenarios, a signal may only need to be sent to a specific destination. This can be achieved by using the -dest option. 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.

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

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 separate 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 executed 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.

SEE ALSO

dbif

COPYRIGHT

Copyright (c) 2008 Schelte Bron