dbusclient(n) 1.0 dbusclient "DBus Client Commands"

Name

dbusclient - Client side DBus interactions

Table Of Contents

Synopsis

Description

This manpage describes the dbusclient package which is a Tcl script extension that simplifies client side programing for access to services on the DBus.

Commands

The two TclOO class commands are exported from the dbusclient namespace and they form the subcommands of a namespace ensemble on the ::dbusclient namespace.

dbusclient Connection create connobj address
dbusclient Connection new address

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
dbusclient Service create service connobj
dbusclient Service new connobj

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.

Connection object methods

The following methods are available for Connection objects.

connobj destroy

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.

connobj call target path interface method sig ?arg1 arg2 ...?

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.

connobj listen path signal ?script?

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.

connobj filter subcmd ?arg1 arg2 ...?

Service object methods

The following methods are available for Service objects.

svcobj destroy

The destructor for a Service object cleans up any internal resources.

svcobj connectedTo

The connectedTo method returns the Connection object command name for the service.

svcobj pathList

The pathList method returns a list of object instance path names for the service.

svcobj findPathsByPropertyValue interface property expression

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.

svcobj pathInterfaces path

The pathInterfaces method returns a list of interfaces that are implemented for path.

svcobj pathProperties path interface

The pathProperties method returns a list of property names that are implemented by interface for the object specified by path.

svcobj interfaceMethods interface

The interfaceMethods method returns a list of methods supported by the specified interface.

svcobj methodSignature interface method

The methodSignature method returns the DBus signature string for the specified interface and method.

svcobj interfaceProperties interface

The interfaceProperties method returns a list of properties defined by interface.

svcobj interfaceSignals interface

The interfaceSignals method returns a list of signals defined by interface.

svcobj call path interface method ?arg1 arg2 ...?

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.

svcobj property path interface property ?value?

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.

svcobj trace operation type ?args?

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:

svcobj trace add type ?args?

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.

svcobj trace add path pathpattern cmdprefix

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.

svcobj trace add signal interface signal pathpattern cmdprefix

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.

svcobj trace add property interface property pathpattern cmdprefix

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.

svcobj trace remove traceid

Removes the trace identified by traceid. It is not an error to remove a non-existant trace.

svcobj trace info traceid

Returns a dictionary containing information about the trace specified by traceid. The keys of the dictionary are:

Type

Specifies the type of trace as either path, signal, or property.

PathMatch

Specifies the pattern that object instance path names must match to trigger the trace.

CmdPrefix

Specifies the command prefix to invoke when the trace performed.

For signal type traces additional keys are:

Interface

Specifies the interface that will trigger the trace.

Signal

Specifies the name of the signal that will trigger the trace.

For property type traces additional keys are:

Interface

Specifies the interface that will trigger the trace.

Property

Specifies the name of the property that will trigger the trace.

For path type traces no additional information is provided.

svcobj waitForProperty interface property pathpattern trigger ?timeout?

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:

status

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.

path

The path name of the object to which the change occurred.

interface

The interface of the changed property.

property

The name of the changed property.

value

The new value of the property if the status element has a value of changed.

svcobj waitForSignal interface signal pathpattern trigger ?timeout?

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:

path

The path name of the object to which the change occurred.

interface

The interface of the changed property.

signal

The name of the received signal.

sender

The sender of the signal.

signature

The argument signature of the signal.

args

A list of argument values that came with the signal.

svcobj waitForPath pathpattern trigger ?timeout?

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:

status

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.

path

The path name of the object which was added or removed.

Dependencies

The dbusclient package depends upon three binary Tcl packages.

Keywords

DBus