dbus-tcl(n)                   Tcl DBus extension                   dbus-tcl(n)



______________________________________________________________________________

NAME
       dbus-tcl - Tcl library for interacting with the DBus

SYNOPSIS
       package require Tcl  8.5

       package require dbus-tcl  1.1

       dbus call ?busID? ?-autostart boolean? ?-dest target? ?-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? ?path ?member ?script???

       dbus method ?busID? ?-async? ?path ?member ?script???

       dbus monitor ?busID? 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 validate class string

______________________________________________________________________________

DESCRIPTION
       The dbus-tcl package provides commands to interact with DBus message
       busses. There are three well-known bus names: session, system, and
       starter. The starter bus only applies when the application has been
       started as a result of a method call from another application. A
       connection to the starter bus will effectively be an alternative
       connection to either the session or the system bus.

       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.

       dbus call ?busID? ?-autostart boolean? ?-dest target? ?-handler script?
       ?-signature string? ?-timeout ms? path interface method ?arg ...?
              Send a method call onto the dbus and optionally wait for a
              reply.  If the signature of the DBus method_return reply only
              contains one top-level element, the arguments of the
              method_return message are returned as a single value. More
              complex structures are returned as a list.

              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.

       dbus close ?busID?
              Close the connection to the DBus. This will cleanup all
              handlers, listeners, and the optional monitor script registered
              for the busID. The actual bus connection of the application will
              not really be terminated if busID is one of the three so-called
              well-known busses, as this is not supported by libdbus.
              Reconnecting to one of those busses will result in reusing the
              same unique name as before.

       dbus connect ?address?
              Connect to the DBus. The address argument specifies the bus to
              connect to. This can be either one of the well-known busses
              ('session', 'system' or 'starter'), or a transport name followed
              by a colon, and then an optional, comma-separated list of keys
              and values in the form key=value.  The command returns a handle
              that can be used as the busID argument in other dbus commands.
              It is legal to run this command when already connected.

       dbus error ?busID? ?-name string? destination serial ?message?
              Send a DBus error message with the specified serial and
              destination. If the -name option is not specified, it defaults
              to "org.freedesktop.DBus.Error.Failed".  This method is
              targetted to be used in combination with a script registered
              using the dbus method subcommand with the -async option.  The
              values for destination and serial can be obtained from event
              information fields 'sender' and 'serial' correspondingly.  See
              Event Handlers below for more information.

       dbus filter ?busID? subcommand -option value ?...?
              The add subcommand adds a match rule to match messages going
              through the message bus. The remove subcommand removes the most
              recently added rule that exactly matches the specified option
              settings. If there is no matching rule, the command is silently
              ignored. Available options are: -destination, -interface,
              -member, -path, -sender, and -type.  The command returns the
              match rule passed to libdbus.

       dbus info ?busID? option
              The info command can be used to obtain information about the
              DBus.  Available info options are:

              machineid
                     Get the UUID of the local machine.

              local  The object path used in local/in-process-generated
                     messages (/org/freedesktop/DBus/Local).

              name   Get the unique name of the connection as assigned by the
                     message bus.

              path   The object path used to talk to the bus itself
                     (/org/freedesktop/DBus).

              pending
                     Report if any messages are in the queue to be sent.

              serverid
                     Get the UUID of the server we are authenticated to.

              service
                     The bus name used to talk to the bus itself
                     (org.freedesktop.DBus).

              version
                     Returns the version of libdbus.


       dbus listen ?busID? ?path ?member ?script???
              Register a script to be called when the signal named "member" at
              path appears on the DBus.  See Event Handlers below 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.

       dbus method ?busID? ?-async? ?path ?member ?script???
              Register a script to be called when method member is invoked at
              the specified path.  See Event Handlers below for more
              information.

              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.

              In the simple case, when script is evaluated because of a
              method_call, the result of the script will be returned to the
              caller as a string in a DBus method_return message. 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 FALSE, no method_return or error message will
              be returned.

              For more advanced control over the returned messages the -async
              option can be specified while registering the script. First of
              all, as the name suggests, this option allows results or errors
              to be returned from code outside of script. The dbus return and
              dbus error subcommands should be used for that.  The dbus return
              subcommand can also be used to return more complex data
              structures than a string from script. In that case the -async
              option ensures that the return value of script is suppressed.
              Even when returning a string to the caller from within script it
              may still be useful to specify the -async option and use the
              dbus return subcommand. This allows handling of dbus errors
              while sending back the return message.

              When evaluation of script ends in an error, the error will
              always be returned to the caller unless the no_reply flag was
              set to TRUE. The setting of the -async option has no influence
              on this behaviour.

       dbus monitor ?busID? script
              Register a script to be executed when any DBus message is
              received.  See Event Handlers below for more information.

              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.

       dbus name ?busID? ?-option ...? name
              Request the bus to assign a given name to the connection. The
              command will generate an error in all cases where it was
              unsuccessful in making the application the primary owner of the
              name.

              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 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.

       dbus release ?busID? name
              Asks the bus to unassign the given name from this connection.

       dbus return ?busID? ?-signature string? destination serial ?arg ...?
              Send a DBus method_return message with the specified serial and
              destination. This method is targetted to be used in combination
              with a script registered using the dbus method subcommand with
              the -async option.  The values for destination and serial can be
              obtained from event information fields 'sender' and 'serial'
              correspondingly.  See Event Handlers below for more information.

       dbus signal ?busID? ?-signature string? object interface name ?arg ...?
              Send a signal onto the dbus with the specified type signature.
              If no -signature option is provided, all args will be sent as
              strings. The command returns the serial number of the dbus
              message.

       dbus validate class string
              Validates string against the rules of the D-Bus specification
              for the type of value specified by class. Returns 1 if
              validation passes, otherwise returns 0. The following classes
              are recognized (the class name can be abbreviated):

              interface
                     Two or more dot-separated non-empty elements.  Each
                     element only contains the ASCII characters "[A-Z][a-
                     z][0-9]_" and does not begin with a digit.

              member A string that only contains the ASCII characters "[A-
                     Z][a-z][0-9]_" and does not begin with a digit.

              name   Either a unique connection name, or a well-known
                     connection name. Unique connection names begin with a
                     colon and consist of at least two dot-separated non-empty
                     elements. Each element only contains the ASCII characters
                     "[A-Z][a-z][0-9]_".  Well-known connection names consist
                     of at least two dot-separated non-empty elements. Each
                     element only contains the ASCII characters "[A-Z][a-
                     z][0-9]_" and does not begin with a digit.

              path   A slash followed by zero or more slash-separated non-
                     empty elements. Each element only contains the ASCII
                     characters "[A-Z][a-z][0-9]_".

              signature
                     A valid D-Bus message type signature. See Signatures
                     below for more information on what constitutes a valid
                     signature.


EVENT HANDLERS
       The call, listen, method and monitor methods provide the ability to
       define event handlers. The specified script will be used as the prefix
       for a command that will be evaluated whenever the corresponding DBus
       event occurs. When the DBus event occurs, a Tcl command will be
       generated by concatenating the script with one or more arguments. The
       first argument is a dict containing information about the event. If the
       DBus event contained any arguments they will be appended to the command
       as seperate arguments.

       The dict with the event details contains the following information:

       member The interface member being invoked (for methods) or emitted (for
              signals).

       interface
              The interface this message is being sent to (for methods) or
              being emitted from (for signals). The interface name is fully-
              qualified.

       path   The object path this message is being sent to (for methods) or
              being emitted from (for signals).

       sender The unique name of the connection which originated this message,
              or the empty string if unknown or inapplicable. The sender is
              filled in by the message bus. Note, the returned sender is
              always the unique bus name.  Connections may own multiple other
              bus names, but those are not found in the sender field.

       destination
              The destination of a message or the empty string if there is
              none set.

       messagetype
              The type of a message. Possible values are method_call,
              method_return, error, and signal.

       signature
              The type signature of the message, i.e. the type specification
              of the arguments in the message payload. See Signatures below
              for more information.

       serial The serial of a message or 0 if none has been specified. The
              message's serial number is provided by the application sending
              the message and is used to identify replies to this message. All
              messages received on a connection will have a serial provided by
              the remote application. When sending messages a serial will
              automatically be assigned by the dbus-tcl library.

       replyserial
              The serial that the message is a reply to or 0 if none.

       noreply
              Flag indicating if the sender expects a reply. Set to 1 if a
              reply is not required.

       autostart
              Flag indicating if the message will cause an owner for
              destination name to be auto-started.

       errorname
              The error name of a received error message. An empty string for
              all other message types.

       The event handlers are excuted at global level (outside the context of
       any Tcl procedure) in the interpreter in which the event handler was
       installed.

SIGNATURES
       The DBus specification defines typed arguments. This doesn't fit well
       with the Tcl philosophy of everything is a string. To be able to
       closely control the type of the arguments to be sent onto the DBus a
       signature can be supplied. The signature definition is exactly the same
       as in the DBus specification. A signature is a string where a single
       character or group of characters specifies the type of an argument. The
       following types exist:

       s      A UTF-8 encoded, nul-terminated Unicode string.

       b      A boolean, FALSE (0), or TRUE (1).

       y      A byte (8-bit unsigned integer).

       n      A 16-bit signed integer.

       q      A 16-bit unsigned integer.

       i      A 32-bit signed integer.

       u      A 32-bit unsigned integer.

       x      A 64-bit signed integer.

       t      A 64-bit unsigned integer.

       d      An 8-byte double in IEEE 754 format.

       g      A type signature.

       o      An object path.

       a#     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.

       v      A D-Bus variant type. The provided value should be a two-element
              list, containing a signature and the actual value. See Variant
              Arguments for more information.

       (...)  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.

       Example: The signature 'vaas(id)a{i(ss)}' specifies four arguments and
       translates to Tcl terminology as follows: The type of the first
       argument ('v') is extracted from its value. The second argument ('aas')
       is a list containing lists of strings. The third argument ('(id)') is a
       list containing an integer and a double. The last argument ('a{i(ss)}')
       is a dict (an array of dict entries) with integer keys and each value
       is a list of two strings.

   VARIANT ARGUMENTS
       When a signature specifies that an argument is of type "variant", the
       argument can still be almost anything. Additional information needs to
       be located to determine how to package the value for transmission onto
       the dbus. The preferred way is for the argument to be a two-element
       list where the first element specifies the signature for the value and
       the second element is the actual value.

       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:

       string: s

       int: i

       wideInt: x

       double: d

       boolean: b

       list: as

       dict: a{ss}

       anything else: s

VARIABLES
       dbus::variantdetails
              Normally the dbus-tcl library only provides the value of a
              variant argument. But in some situations the Tcl code may need
              to be able to also obtain the argument type. When this variable
              is set to 1, 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.

SLAVE INTERPRETERS
       The standard D-Bus library libdbus will only assign a single unique bus
       name per application. This means that slave interpreters that connect
       to the D-Bus will get the same unique bus name as the main interpreter,
       or any other slave interpreter that has connected to the D-Bus.

       It is not a problem if multiple interpreters register a listener for
       the exact same signal. The dbus-tcl 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.

COPYRIGHT
       Copyright (c) 2008-2012 Schelte Bron




dbus-tcl                              1.1                          dbus-tcl(n)
