dbus-intf - Application layer around the Tcl D-Bus library
The dbus-intf package provides a higher level wrapper around the low-level D-Bus commands provided by the dbus-tcl package. The package also handles calls to a number of standard D-Bus interfaces. The following interfaces are supported:
org.freedesktop.DBus.Peer
org.freedesktop.DBus.Introspectable
org.freedesktop.DBus.Properties
Access to all functions of the dbus-intf package from within a Tcl program is done using the dbif command. The command supports several subcommands that determine what action is carried out.
Connect to a message bus and optionally request the D-Bus server to assign one or more names to the current application.
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 the 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.
The command returns a list of names that have successfully been acquired.
Generally an application will perform several dbif commands related to the same message bus and interface. To avoid having to pass the same values for the -bus and -interface options with all those commands, their defaults can be setup with the dbif default subcommand.
Valid values for bustype are session and system. An interface name has to consist of at least two elements separated by a period ('.') character. Each element must only contain the characters "[A-Z][a-z][0-9]_" and must not begin with a digit.
The initial value for -bus is session. The initial value for -interface is taken from the first name requested for the application in a dbif connect command. If no name was ever requested with the connect subcommand, it defaults to "com.tclcode.default".
Send a D-Bus error message in response to a D-Bus method call. If the errorname argument is not specified, it defaults to "org.freedesktop.DBus.Error.Failed".
Generate a signal as defined by a previous dbif signal command. If a body was specified with the signal definition, the provided arguments must match the args definition for the body. Otherwise they must match the arglist specified during the definition of the signal.
Access additional information about a D-Bus message. Recognized names are bus, member, interface, path, sender, destination, messagetype, signature, serial, replyserial, noreply, autostart, and errorname.
Start listening for the specified signal and execute body when such a signal appears on the D-Bus.
The arglist argument follows the special rules for dbif argument lists. See ARGUMENT LISTS below for more information.
Define a method that may be accessed through the D-Bus and execute body when the method is invoked. The inputargs argument specifies which arguments must be provided by the caller. The outputargs argument indicates the type of result the method returns.
If the body code doesn't generate a response message using the dbif return or dbif error subcommands, the return value resulting from executing the body will be returned to the caller in a D-Bus return message. If an uncaught error occurs or the result of body doesn't match outputargs, an error message will be returned to the caller instead.
When the -async option is specified, the result of the method body will not automatically be returned to the caller. In this case the body code must arrange for a result to be sent back to the caller using the return, or error subcommands.
An additional variable msgid will be passed to the method body. This variable contains a messageID that may be used in combination with the get, return, or error subcommands. The messageID remains valid for a period of time (default 25 seconds), or until a response has been returned to the caller, whichever happens first.
The inputargs and outputargs arguments follow the special rules for dbif argument lists. See ARGUMENT LISTS below for more information.
Define a property that may be accessed through the D-Bus using methods defined by the org.freedesktop.DBus.Properties standard interface. The variable argument defines the global variable holding the value of the property. The code in the optional body argument will be executed when the property is modified through the D-Bus. The global variable is changed before the body code is invoked, allowing restrictions to be imposed on the value for the property.
The -access option specifies whether the property can be viewed and/or modified through the D-Bus. Valid access modes are read, write, and readwrite. If no access mode is specified, it defaults to readwrite.
Two or three variables will be passed to body: name, containing the property name, new, containing the new value for the property, and old, containing the previous value of the property. If the property did not previously have a value, the old variable will default to the empty string. This situation can be recognized by examining the output of the info level 0 command.
Send a D-Bus return message in response to a D-Bus method call.
Define a signal that the application may emit. This command returns a signal identifier that may be used with the dbif generate subcommand to actually send the signal onto the D-Bus. If the optional args and body arguments are specified, body will be executed when the signal is transmitted on the D-Bus as a result of the dbif generate subcommand. It is the responsibility of the body code to produce a return value that matches the specified arglist.
The arglist argument follows the special rules for dbif argument lists. See ARGUMENT LISTS below for more information.
The dbus-intf package enforces some limitations on names used with the dbif subcommands. All names must only use the characters "[A-Z][a-z][0-9]_". This limitation applies to method names, property names, signal names, and argument names. Out of this group, only argument names may begin with a digit.
Interface names and error names must consist of at least two elements separated by a period ('.') character. Each element must only contain the characters "[A-Z][a-z][0-9]_" and must not begin with a digit.
D-Bus names for applications must follow the same rules as interface names, except that also dash ('-') characters are allowed. Unique D-Bus names begin with a colon (':'). The elements of unique D-Bus names are allowed to begin with a digit.
Paths must start with a slash ('/') and must consist of elements separated by slash characters. Each element must only contain the characters "[A-Z][a-z][0-9]_". Empty elements are not allowed.
Due to the fact that the D-Bus specification works with typed arguments, a slightly modified method for specifying argument lists has been adopted for the dbus-intf package. The normal Tcl argument list as used with the proc and apply commands may still be used. In that case all arguments will be of the string type. To specify a different type, the variable name must be followed by a colon and the D-Bus signature specification for that argument. Example: to define the count argument as a 32-bit integer, it should be specified as count:i.
The following argument types are available:
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. 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.
Argument lists may contain optional arguments. The use of optional arguments will result in multiple prototypes being reported for the object when introspected. The special meaning of the args argument does not translate well in the D-Bus concept. For that reason using args as the last argument of an argument list should be avoided.
Copyright © 2008-2009 Schelte Bron