D 2018-01-19T13:38:59.242 L Manual\spage U schelte W 28834
dbus - Tcl library for interacting with the DBus
package require Tcl 8.5
package require dbus 2.1
dbus call ?busID? ?-autostart ?boolean?? ?-dest target? ?-details ?boolean?? ?-handler script? ?-signature string? ?-timeout ms? path interface method ?arg ...?
dbus close ?busID?
dbus connect ?address?
dbus error ?busID? ?-name string? destination serial ?message?
dbus filter ?busID? subcommand -option value ?...?
dbus info ?busID? option
dbus listen ?busID? ?-details? ?path ?member ?script???
dbus method ?busID? ?-details? ?path ?member ?script???
dbus monitor ?busID? ?-details? script
dbus name ?busID? ?-option ...? name
dbus release ?busID? name
dbus return ?busID? ?-signature string? destination serial ?arg ...?
dbus signal ?busID? ?-signature string? object interface name ?arg ...?
dbus unknown ?busID? ?-details? ?path ?script??
dbus validate class string
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.
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.
The -details option specifies how variant arguments in the return value are represented. With the default value of FALSE, only the value of a variant argument is provided. But in some situations the Tcl code may need to be able to also obtain the argument type. When this option is set to TRUE, each variant argument is represented as a list with two elements. The first list element contains the signature of the argument and the second list element is the value.
When employing this subcommand, make sure the result of the dbus method script isn't automatically returned to the caller by using the -async option of the return command. See dbus method 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.
The -details option causes variant arguments to be represented as a list with two elements: The first list element contains the signature of the argument and the second list element is the value.
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.
When script is evaluated, the return value of the script will normally be returned to the caller using a DBus method_return message in a string argument. 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 TRUE, no method_return or error message will be returned.
The script 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 dbus return or dbus error subcommands.
This method provides more advanced control over the returned messages. It allows for more complex data structures than just a string to be returned. It also makes it possible to generate a return message some time after script has already finished. Additionally, any dbus errors while sending back the return message can be detected and handled.
The -details option causes variant arguments to be represented as a list with two elements: The first list element contains the signature of the argument and the second list element is the value.
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.
The -details option causes variant arguments to be represented as a list with two elements: The first list element contains the signature of the argument and the second list element is the value.
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 following command can be used to exit the application when the name is
taken over by another process:
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.
When employing this subcommand, make sure the result of the dbus method script isn't automatically returned to the caller by using the -async option of the return command. See dbus method for more information.
If the path argument is an empty string, script will be executed whenever an unknown method call message is received for any path, unless a dedicated unknown handler for the exact path has been defined. If script is an empty string, the currently registered command for the specified 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 an unknown handler for the exact same path. See Slave Interpreters below for more information.
If the script argument is not specified, the currently registered command for the specified path, if any, is returned. If no path argument is specified, a list of all paths and their registered unknown handlers is returned.
An unknown handler will usually return an error, but it is also possible to return a non-error response. The dbus error and dbus return subcommands should be used for this purpose. Contrary to the dbus method subcommand, the return value of the handler will not automatically be returned to the caller. Any uncaught error in the evaluation of script will be reported back to the caller.
The -details option causes variant arguments to be represented as a list with two elements: The first list element contains the signature of the argument and the second list element is the value.
It will generally not be necessary to set up unknown handlers. If no unknown handler is specified, the package returns an org.freedesktop.dbus.error.unknownmethod error back to the caller of an unknown method.
The dict with the event details contains the following information:
The signature for a variant argument has to specify a single complete type. The value of the second list element must match the signature, otherwise an error will be reported.
If the value provided for a variant argument is not a two-element list, or the first element is not a valid signature for a single complete type, the code will attempt to automatically determine the type of the provided value. It does this by selecting a signature based on the internal representation of the value according to the following table:
On input, a new channel will be created and its name passed to the script. The new channel is opened for both reading and writing. If this is not desired, either direction may be closed using the appropriate half-close version of the close command.
The channel name is likely to be different in the two involved applications. When finished with the channel, both parties are responsible for closing the channel using their own channel reference.
It is not a problem if multiple interpreters register a listener for the exact same signal. The dbus 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. Z 7eac8c0335ff719d1b74ffd22268cf41