Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
dbus(n)			      Tcl DBus extension		       dbus(n)

______________________________________________________________________________

NAME
       dbus - Tcl library for interacting with the DBus

SYNOPSIS
       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 in-
       terface 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

______________________________________________________________________________

DESCRIPTION
       The  dbus  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  con-
       nection	to  the	starter	bus will effectively be	an alternative connec-
       tion to either the session or the system	bus.

       Most subcommands	take a busID argument. This is the DBus	handle as  re-
       turned  by  the	dbus connect subcommand. For the well-known busses the
       handle matches the name of the bus. If the busID	argument is not	speci-
       fied, it	defaults to session.

       dbus  call  ?busID?  ?-autostart	 ?boolean??  ?-dest  target? ?-details
       ?boolean?? ?-handler script? ?-signature	string?	?-timeout ms? path in-
       terface method ?arg ...?
	      Send  a  method call onto	the dbus and optionally	wait for a re-
	      ply.  If the signature of	the DBus method_return reply only con-
	      tains  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 er-
	      rorCode 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 re-
	      sponse.  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  re-
	      turn  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 ar-
	      gument  is  represented  as  a list with two elements. The first
	      list element contains the	signature of the argument and the sec-
	      ond list element is the value.

       dbus close ?busID?
	      Close  the  connection  to  the DBus. This will cleanup all han-
	      dlers, 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.	Recon-
	      necting 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 destina-
	      tion. If the -name option	 is  not  specified,  it  defaults  to
	      "org.freedesktop.DBus.Error.Failed".  The	values for destination
	      and  serial  can	be  obtained  from  event  information	fields
	      'sender' and 'serial' correspondingly.  See Event	Handlers below
	      for more information.

	      When employing this subcommand, make sure	the result of the dbus
	      method  script isn't automatically returned to the caller	by us-
	      ing the -async option of the return command. See dbus method 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, -eavesdrop, -in-
	      terface, -member,	-path, -sender,	and -type.   The  command  re-
	      turns 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:

	      capabilities
		     Returns a dict describing the capabilities	 of  the  dbus
		     connection.  Currently  only  one capability has been de-
		     fined: unixfd, which indicates if file descriptor passing
		     is	supported on the dbus connection.

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

	      machineid
		     Get the UUID of the local machine.

	      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? ?-details? ?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 in-
	      formation.

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

	      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 com-
	      mand 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 reg-
	      istered 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.

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

	      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 in-
	      terface,	unless another handler is specified for	the method in-
	      cluding the interface.  If script	is an empty string,  the  cur-
	      rently 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	regis-
	      tered command for	the specified method and path, if any, is  re-
	      turned.  If no member argument is	specified a list of all	regis-
	      tered 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  re-
	      turned.

	      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.  Ad-
	      ditionally,  any	dbus errors while sending back the return mes-
	      sage 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.

       dbus monitor ?busID? ?-details? script
	      Register	a  script  to be executed when any DBus	message	is re-
	      ceived.  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 moni-
	      toring 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.

       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	unsuc-
	      cessful 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 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:

	      dbus listen [dbus	info path] [dbus info service].NameLost	\
		[list apply {{name info	str} {if {$str eq $name} exit}}	$name]

	      The -replace option indicates that the application wants to take
	      over the ownership of the	name from the application that is cur-
	      rently the primary owner,	if any.	This request will only be hon-
	      oured  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  op-
	      tion  has	 not been specified, or	the -replace option was	speci-
	      fied but the current owner is unwilling to give  up  its	owner-
	      ship,  the  name	request	will normally be queued. Then when the
	      name is released by current owner	it is assigned to the next re-
	      quester  in  the	queue  and a signal is sent to inform that re-
	      quester that it is now the primary owner of the name.  The  -no-
	      queue  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.   The  values for destination and serial can	be ob-
	      tained from event	information fields 'sender' and	'serial'  cor-
	      respondingly.  See Event Handlers	below for more information.

	      When employing this subcommand, make sure	the result of the dbus
	      method script isn't automatically	returned to the	caller by  us-
	      ing the -async option of the return command. See dbus method 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  mes-
	      sage.

       dbus unknown ?busID? ?-details? ?path ?script??
	      Register a script	to be called when an unknown method is invoked
	      at the specified path.  See Event	Handlers below for more	infor-
	      mation.

	      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  reg-
	      istered 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	regis-
	      tered  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.

       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 valida-
	      tion passes, otherwise returns 0.	The following classes are rec-
	      ognized (the class name can be abbreviated):

	      interface
		     Two  or more dot-separated	non-empty elements.  Each ele-
		     ment  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  connec-
		     tion 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 be-
		     low for more information on what constitutes a valid sig-
		     nature.

EVENT HANDLERS
       The call, listen, method	and monitor methods provide the	ability	to de-
       fine 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	gener-
       ated  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 be-
	      ing 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  al-
	      ways  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  au-
	      tomatically be assigned by the dbus 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 re-
	      ply is not required.

       autostart
	      Flag indicating if the message will cause	an owner for  destina-
	      tion 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.

       h      A	file descriptor.

       g      A	type signature.

       o      An object	path.

       a#     A	D-Bus array type, which	is similar to a	Tcl list. The #	speci-
	      fies  the	 type of the array elements. This can be any type, in-
	      cluding 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 combina-
	      tion 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	 argu-
       ment  ('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 in-
       ternal 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

   FILE	DESCRIPTORS
       On output, the value provided for a file	handler	argument  must	be  an
       open Tcl	channel	(such as has been created with the open	or socket com-
       mands). An error	will be	thrown if the value does not represent an open
       channel,	 or  if	the dbus connection does not support passing file han-
       dler arguments.

       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 applica-
       tions.  When finished with the channel, both  parties  are  responsible
       for closing the channel using their own channel reference.

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 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-2015 Schelte Bron

dbus				      2.1			       dbus(n)

NAME | SYNOPSIS | DESCRIPTION | EVENT HANDLERS | SIGNATURES | SLAVE INTERPRETERS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dbus&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help