dbusclient - Client side DBus interactions
This manpage describes the dbusclient package which is a Tcl script extension that simplifies client side programing for access to services on the DBus.
The two TclOO class commands are exported from the dbusclient namespace and they form the subcommands of a namespace ensemble on the ::dbusclient namespace.
The Connection command creates a new instance and connects to the DBus specified by address. The return value of the commands is the fully qualified connection object command name, which is to be used when opening a service on the bus. On most systems where the DBus daemon is run, there are two well known busses named, system and session.
Connection create sysBus system
The Service command creates a new service instance for the service defined on the connobj bus. The return value of the commands is the fully qualified service object command name, which is to be used when accessing provided services. Although the service object may be named arbitrarily, it is most convenient to create a Service object that has the same name as the service with it accesses.
The following methods are available for Connection objects.
The destructor for a Connection object disconnects from the bus to which it was associated and cleans up any internal resources. Any Service objects using the connection are also destroyed.
The call method invokes the method method which belongs to the interface interface on the object instance specified by path which resides on the service target. The sig argument give the DBus signature for the method. If sig is specified as the empty string, no signature is used in the conversion of Tcl strings to the underlying data types required by method. The remaining argN arguments are passed as arguments to the method.
The listen method registers script to be invoked when signal on path is seen on the DBus. If script is not specified, the currently registered script is returned. If script is the empty string, then the currently registered script is removed. When script is invoked, a dictionary of the event details is supplied as an additional argument. See the dbus package documentation for the details of the event dictionary.
The following methods are available for Service objects.
The destructor for a Service object cleans up any internal resources.
The connectedTo method returns the Connection object command name for the service.
The pathList method returns a list of object instance path names for the service.
The findPathsByPropertyValue method returns a list of object path names specified by the interface and property arguments where expression also evaluates to true. The expression is evaluated in the context of the caller and may reference variables named Path, Interface, Property, Value, or Valid. The values of these variables is set for each property value that also matches the values of interface and property before expression is evaluated. This method provides a means of finding object paths whose property values match a specified expression. For example,
set conn [Connection create sysBus system] Service create DBus org.freedesktop.DBus $conn DBus findPathsByPropertyValue org.freedesktop.DBus Interfaces {"org.freedesktop.DBus.Monitoring" in $Value}
returns the object whose path is /org/freedesktop/DBus.
The pathInterfaces method returns a list of interfaces that are implemented for path.
The pathProperties method returns a list of property names that are implemented by interface for the object specified by path.
The interfaceMethods method returns a list of methods supported by the specified interface.
The methodSignature method returns the DBus signature string for the specified interface and method.
The interfaceProperties method returns a list of properties defined by interface.
The interfaceSignals method returns a list of signals defined by interface.
The call method invokes the method method that is contained in interface on the the object specified by path. Additional optional argN arguments are passes as arguments to the called method. The return value of the call method is the return value of the underlying service method from the DBus.
The property method reads and optionally updates the value of the property property for path that is part of interface. If value is specified, then property is set to that value (if possible). The return value of the method is the new value of property.
Note that writing property values to services on the DBus is an asynchronous operation and usually results in a property changed signal being sent. The dbusclient package handles such asynchronous updates but the Tcl event loop must be entered in order to do so.
The trace method causes Tcl commands to be executed when certain conditions on the DBus are met. The interface for this method is modeled after the core trace command. Legal operation argument values are:
The legal values for the type trace type are path, signal, or property. The return value of the command is a trace identifier, which can be used to remove or query the trace. Multiple traces may be added of any type and the parameters of the trace may be the same. Traces are executed in order from youngest (most recently added) to oldest.
Arranges for cmdprefix to be invoked whenever an object instance whose name matches pathpattern is added or removed from the service. The matching against pathpattern is done in the same manner as the string match command. When invoked, cmdprefix is supplied with two additional arguments, a status, which has a value of either added or removed, and the name of the added or removed path.
Arranges for cmdprefix to be invoked when the signal from interface on an object instance matching pathpattern is detected on the bus. The matching against pathpattern is done in the same manner as the string match command. When invoked, cmdprefix is supplied with additional arguments. The first argument is a dictionary of event information as described in the Event Handlers section of the dbus package documentation. Any arguments of the signal itself follow.
Arranges for cmdprefix to be invoked when the property associated with interface for an object instance matching pathpattern is reported. The matching against pathpattern is done in the same manner as the string match command. When invoked, cmdprefix is supplied with up to five additional arguments. The first argument is a status value of changed or invalidated, indicating if the property value has changed or is no longer valid. The second argument is the path name of the object instance whose property was affected. The third argument is the name of the interface of which the property was part. The fourth argument is the name of the property that was affected. If the status was changed, a fifth argument is supplied giving the new value of the property.
Removes the trace identified by traceid. It is not an error to remove a non-existant trace.
Returns a dictionary containing information about the trace specified by traceid. The keys of the dictionary are:
Specifies the type of trace as either path, signal, or property.
Specifies the pattern that object instance path names must match to trigger the trace.
Specifies the command prefix to invoke when the trace performed.
For signal type traces additional keys are:
Specifies the interface that will trigger the trace.
Specifies the name of the signal that will trigger the trace.
For property type traces additional keys are:
Specifies the interface that will trigger the trace.
Specifies the name of the property that will trigger the trace.
For path type traces no additional information is provided.
The waitForProperty method establishes a property trace on the property property in interface matching pathpattern. These arguments are interpreted in the same manner as for the trace add method. Then the script specified by trigger is executed in the call stack of the caller. Then the Tcl event loop is entered waiting for the property change to occur. If timeout is specified it is the number of milliseconds to wait for the property change notification. A timeout value of 0 is interpreted to mean to wait forever. The default timeout value is 5000. If trigger executes successfully and the DBus notification is received before any timeout, then the return value of the command is a dictionary giving the details of the property change. The keys to the dictionary are:
A status element value of changed, indicates the property value has changed and the new value is given by the value element. A status element value of invalidated, indicates the property no longer has a valid value and in this case no value element is included in the dictionary.
The path name of the object to which the change occurred.
The interface of the changed property.
The name of the changed property.
The new value of the property if the status element has a value of changed.
The waitForSignal method establishes a signal trace on the signal signal in interface matching pathpattern. These arguments are interpreted in the same manner as for the trace add method. Then the script specified by trigger is executed in the call stack of the caller. Then the Tcl event loop is entered waiting for the signal notification to occur. If timeout is specified it is the number of milliseconds to wait for the property change notification. A timeout value of 0 is interpreted to mean to wait forever. The default timeout value is 5000. If trigger executes successfully and the DBus signal is received before any timeout, then the return value of the command is a dictionary giving the details of the signal. The keys to the dictionary are:
The path name of the object to which the change occurred.
The interface of the changed property.
The name of the received signal.
The sender of the signal.
The argument signature of the signal.
A list of argument values that came with the signal.
The waitForPath method establishes a path trace on the object instance matching pathpattern. Then the script specified by trigger is executed in the call stack of the caller. Then the Tcl event loop is entered waiting for the path change to occur. If timeout is specified it is the number of milliseconds to wait for the property change notification. A timeout value of 0 is interpreted to mean to wait forever. The default timeout value is 5000. If trigger executes successfully and the DBus notification is received before any timeout, then the return value of the command is a dictionary giving the details of the path change. The keys to the dictionary are:
A status element value of added, indicates the path is newly created and the value is given by the path element. A status element value of removed, indicates the path was deleted and the value of the deleted path is given by the path element.
The path name of the object which was added or removed.
The dbusclient package depends upon three binary Tcl packages.
dbus is the Tcl bindings to the DBus library.
tcom is used to parse XML returned during introspection.
ral is used to manage the introspection data.
DBus