dbus-tcl(n) 0.8 dbus-tcl "Tcl DBus extension"
dbus-tcl - Tcl library for interacting with the DBus
TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
EVENT HANDLERS
SIGNATURES
SLAVE INTERPRETERS
COPYRIGHT
package require Tcl 8.5
package require dbus-tcl 0.8
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.
- dbus call ?busID? ?-autostart boolean? ?-dest target? ?-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.
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.
- 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".
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.
- 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, -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:
- machineid
- Get the UUID of the local machine.
- local
- The object path used in local/in-process-generated
messages (/org/freedesktop/DBus/Local).
- 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? ?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.
- dbus method ?busID? ?-async? ?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.
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.
- dbus monitor ?busID? 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.
- 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 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.
- 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. 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.
- 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 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.
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:
- 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-tcl
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.
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.
- 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. Specifying this type will cause the code to
automatically determine the type of the provided value (by looking at the
internal representation).
- (...)
- 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 determined based on 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.
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-2009 Schelte Bron, Alexander Galanin