D 2018-01-19T12:04:17.752 L Tcl\sDBus\sInterface U schelte W 23199
dbif - Application layer around the Tcl D-Bus library
package require Tcl 8.5
package require dbus 2.1
package require dbif 1.3
dbif connect ?-bus bustype? ?-noqueue? ?-replace? ?-yield? ?name ...?
dbif default ?-bus bustype? ?-interface interface?
dbif delete ?-bus bustype? ?-interface interface? ?-single? path
dbif error messageID errormessage ?errorname?
dbif generate signalID ?arg ...?
dbif get messageID name
dbif listen ?-bus bustype? ?-interface interface? path name ?arglist? ?interp? body
dbif method ?-attributes attributes? ?-bus bustype? ?-interface interface? path name ?inputargs ?outputargs?? ?interp? body
dbif pave ?-bus bustype? ?-interface interface? path
dbif property ?-access mode? ?-attributes attributes? ?-bus bustype? ?-interface interface? path name?:signature? variable ??interp? body?
dbif return messageID returnvalue
dbif signal ?-attributes attributes? ?-bus bustype? ?-id signalID? ?-interface interface? path name ?arglist ??interp? args body??
Access to all functions of the dbif package from within a Tcl program is done using the dbif command. The command supports several subcommands that determine what action is carried out.
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 -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. If the dbus connection handle is needed, it can be obtained from the -bus return option.
The following code can be used to allow a new instance of a program to
replace the current one. This can be useful during program development:
An interface name must consist of at least two elements separated by a period ('.') character. Each element may 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".
The code in body will be executed in the namespace the dbif listen command was issued from. The arglist argument follows the special rules for dbif argument lists. See ARGUMENT LISTS below for more information.
Attributes may be specified via the -attributes option to provide hints to users of your API. See ATTRIBUTES below for more information.
The return value resulting from executing the body will normally 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.
The body 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 dbif return or dbif 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 code in body will be executed in the namespace the dbif method command was issued from. The inputargs and outputargs arguments follow the special rules for dbif argument lists. See ARGUMENT LISTS below for more information.
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.
Attributes may be specified via the -attributes option to provide hints to users of your API. See ATTRIBUTES below for more information.
The code in the optional body argument will be executed when the property is modified through the D-Bus. During the execution of body the global variable will still have its original value, if any. The new value for the property is passed to the script as an argument with the same name as the property. If execution of body results in an error, the global variable will not be modified. This allows restrictions to be imposed on the value for the property.
The code in body will be executed in the namespace the dbif property command was issued from or, if a slave interpreter was specified, in the current namespace of that slave interpreter at definition time.
Generating the property value only when needed can be implemented by putting
a read trace on the global variable. Example:
Attributes may be specified via the -attributes option to provide hints to users of your API. See ATTRIBUTES below for more information.
The command returns the SignalID of the newly created signal.
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 code in body will be executed in the namespace the dbif signal command was issued from. If any uncaught error happens during the execution of the body code, the dbif generate command will also throw an error with the same error message. When the body code comes to the conclusion that the signal doesn't need to be sent after all, it may abort the operation by returning using [return -code return]. The arglist argument follows the special rules for dbif argument lists. See ARGUMENT LISTS below for more information.
In addition to valid dbus paths, an empty string may be specified for the
path argument. This makes the signal available on all paths. In this
case a body must be provided and the body code must provide a path in the
-path option to the return command.
For example: The following helper proc could be used to allow providing a
path to the dbif generate command in front of the
signal arguments:
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.
The following argument types are available:
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.
All applicable property changes are collected and reported via a single PropertiesChanged signal per path/interface/bus combination when the application enters the idle loop. The signal may also be generated on demand via the command:
The functionality for automatically populating this signal is implemented via variable traces. If this feature is not needed, you can avoid the associated overhead by redefining the PropertiesChanged signal id to your own version. To completely get rid of the signal, you can use the following code snippet before defining any other part of your dbus interface:
package require dbif dbif signal -id PropertiesChanged / foobar dbif delete /
Some well-know attributes are (default, if any, shown in italics):
The value of this attribute, if specified, is also used internally to influence the automatic generation of the PropertiesChanged signal.