org.freedesktop.DBus Interface

org.freedesktop.DBus Interface — Message bus daemon interface

Methods

Flags        RequestNameFlags
Enumeration  RequestNameReply
Enumeration  ReleaseNameReply
Enumeration  StartServiceByNameReply

Hello                               (OUT String                   assigned_name)
RequestName                         (IN  String                   name,
                                     IN  RequestNameFlags         flags,
                                     OUT RequestNameReply         value)
ReleaseName                         (IN  String                   name,
                                     OUT ReleaseNameReply         value)
StartServiceByName                  (IN  String                   name,
                                     IN  UInt32                   flags,
                                     OUT StartServiceByNameReply  value)
UpdateActivationEnvironment         (IN  Dict<String,String>      env_hash)
NameHasOwner                        (IN  String                   name,
                                     OUT Boolean                  has_owner)
ListNames                           (OUT Array<String>            names)
ListActivatableNames                (OUT Array<String>            activatable_names)
AddMatch                            (IN  String                   rule)
RemoveMatch                         (IN  String                   rule)
GetNameOwner                        (IN  String                   name,
                                     OUT String                   unique_name)
ListQueuedOwners                    (IN  String                   name,
                                     OUT Array<String>            queued_owners)
GetConnectionUnixUser               (IN  String                   name,
                                     OUT UInt32                   uid)
GetConnectionUnixProcessID          (IN  String                   name,
                                     OUT UInt32                   pid)
GetAdtAuditSessionData              (IN  String                   name,
                                     OUT Array<Byte>              data)
GetConnectionSELinuxSecurityContext (IN  String                   name,
                                     OUT Array<Byte>              security_context)
ReloadConfig                        ()
GetId                               (OUT String                   unique_id)

Signals

NameOwnerChanged (String  name,
                  String  old_owner,
                  String  new_owner)
NameLost         (String  name)
NameAcquired     (String  name)

Description

The org.freedesktop.DBus D-Bus interface is implemented by message bus daemons. Normally applications only use the RequestName() method to claim a well-known name on the message bus.

Enumerations

The RequestNameFlags Flags

{
  None             = 0x00000000,
  AllowReplacement = 0x00000001,
  ReplaceExisting  = 0x00000002,
  DoNotQueue       = 0x00000004
}

Flags used in the RequestName() method.

`None`	No flags set.
`AllowReplacement`	If an application A specifies this flag and succeeds in becoming the owner of the name, and another application B later calls RequestName() with the RequestNameFlags.ReplaceExisting flag, then application A will lose ownership and receive a "NameLost" signal, and application B will become the new owner. If RequestNameFlags.AllowReplacement is not specified by application A, or RequestNameFlags.ReplaceExisting is not specified by application B, then application B will not replace application A as the owner.
`ReplaceExisting`	Try to replace the current owner if there is one. If this flag is not set the application will only become the owner of the name if there is no current owner. If this flag is set, the application will replace the current owner if the current owner specified RequestNameFlags.AllowReplacement.
`DoNotQueue`	Without this flag, if an application requests a name that is already owned, the application will be placed in a queue to own the name when the current owner gives it up. If this flag is given, the application will not be placed in the queue, the request for the name will simply fail. This flag also affects behavior when an application is replaced as name owner; by default the application moves back into the waiting queue, unless this flag was provided when the application became the name owner.

The RequestNameReply Enumeration

{
  PrimaryOwner = 1,
  InQueue      = 2,
  Exists       = 3,
  AlreadyOwned = 4
}

Return values for the RequestName() method

`PrimaryOwner`	The caller is now the primary owner of the name, replacing any previous owner. Either the name had no owner before, or the caller specified RequestNameFlags.ReplaceExisting and the current owner specified RequestNameFlags.AllowReplacement.
`InQueue`	The name already had an owner, RequestNameFlags.DoNotQueue was not specified, and either the current owner did not specify RequestNameFlags.AllowReplacement or the requesting application did not specify RequestNameFlags.ReplaceExisting.
`Exists`	The name already has an owner, RequestNameFlags.DoNotQueue was specified, and either RequestNameFlags.AllowReplacement was not specified by the current owner, or RequestNameFlags.ReplaceExisting was not specified by the requesting application.
`AlreadyOwned`	The application trying to request ownership of a name is already the owner of it

The ReleaseNameReply Enumeration

{
  Released    = 1,
  NonExistant = 2,
  NotOwner    = 3
}

Return values for the ReleaseName() method.

`Released`	The caller has released his claim on the given name. Either the caller was the primary owner of the name, and the name is now unused or taken by somebody waiting in the queue for the name, or the caller was waiting in the queue for the name and has now been removed from the queue.
`NonExistant`	The given name does not exist on this bus.
`NotOwner`	The caller was not the primary owner of this name, and was also not waiting in the queue to own this name.

The StartServiceByNameReply Enumeration

{
  Success        = 1,
  AlreadyRunning = 2
}

Return values for the StartServiceByName() method.

`Success`	The service was successfully started.
`AlreadyRunning`	A connection already owns the given name.

Method Details

Hello ()

Hello (OUT String  assigned_name)

Before an application is able to send messages to other applications it must invoke this method on the message bus to obtain a unique name. If an application without a unique name tries to send a message to another application, or a message to the message bus itself that isn't the Hello() method, it will be disconnected from the bus. There is no corresponding disconnect request; if a client wishes to disconnect from the bus, it simply closes the socket (or other communication channel).

OUT String assigned_name:

Unique name assigned to the connection.

RequestName ()

RequestName (IN  String            name,
             IN  RequestNameFlags  flags,
             OUT RequestNameReply  value)

This method call should be invoked on the org.freedesktop.DBus name to request the message bus to assign the given name to the method caller. Each name maintains a queue of possible owners, where the head of the queue is the primary or current owner of the name. Each potential owner in the queue maintains the RequestNameFlags.AllowReplacement and RequestNameFlags.DoNotQueue settings from its latest RequestName() call. See the D-Bus specification for more details.

`IN String name`:	Name to request.
`IN RequestNameFlags flags`:	Flags.
`OUT RequestNameReply value`:	Return value.

ReleaseName ()

ReleaseName (IN  String            name,
             OUT ReleaseNameReply  value)

This method call should be invoked on the org.freedesktop.DBus name to request the message bus to release the method caller's claim to the given name. If the caller is the primary owner, a new primary owner will be selected from the queue if any other owners are waiting. If the caller is waiting in the queue for the name, the caller will removed from the queue and will not be made an owner of the name if it later becomes available. If there are no other owners in the queue for the name, it will be removed from the bus entirely.

`IN String name`:	Name to release.
`OUT ReleaseNameReply value`:	Return value.

StartServiceByName ()

StartServiceByName (IN  String                   name,
                    IN  UInt32                   flags,
                    OUT StartServiceByNameReply  value)

Tries to launch the executable associated with name. See the D-Bus specification for more details on service activation.

`IN String name`:	Name of the service to start.
`IN UInt32 flags`:	Flags (currently not used).
`OUT StartServiceByNameReply value`:	Reply

UpdateActivationEnvironment ()

UpdateActivationEnvironment (IN  Dict<String,String>  env_hash)

Normally, session bus activated services inherit the environment of the bus daemon. This method adds to or modifies that environment when activating services. Some bus instances, such as the standard system bus, may disable access to this method for some or all callers.

IN Dict<String,String> env_hash:

Environment to add or update.

NameHasOwner ()

NameHasOwner (IN  String   name,
              OUT Boolean  has_owner)

Checks if the specified name exists (currently has an owner).

`IN String name`:	Name to check.
`OUT Boolean has_owner`:	`TRUE` only if `name` exists.

ListNames ()

ListNames (OUT Array<String>  names)

Returns a list of all currently-owned names on the bus.

OUT Array<String> names:

Array of strings where each string is a bus name.

ListActivatableNames ()

ListActivatableNames (OUT Array<String>  activatable_names)

Returns a list of all names that can be activated on the bus.

OUT Array<String> activatable_names:

Array of strings where each string is a bus name.

AddMatch ()

AddMatch (IN  String  rule)

Adds a match rule to match messages going through the message bus. If the bus does not have enough resources the %org.freedesktop.DBus.Error.OOM error is returned. See the D-Bus specification for more information about match rules.

IN String rule:

Match rule to add to the connection.

RemoveMatch ()

RemoveMatch (IN  String  rule)

Removes the first rule that matches. If the rule is not found the %org.freedesktop.DBus.Error.MatchRuleNotFound error is returned. See the D-Bus specification for more information about match rules.

IN String rule:

Match rule to remove from the connection.

GetNameOwner ()

GetNameOwner (IN  String  name,
              OUT String  unique_name)

Returns the unique connection name of the primary owner of the name given. If the requested name doesn't have an owner, returns a %org.freedesktop.DBus.Error.NameHasNoOwner error.

`IN String name`:	Name to get owner of.
`OUT String unique_name`:	The unique name that owns `name`.

ListQueuedOwners ()

ListQueuedOwners (IN  String         name,
                  OUT Array<String>  queued_owners)

Lists the names waiting in queue to own name.

`IN String name`:	A well-known name.
`OUT Array<String> queued_owners`:	Array of unique names in queue to own `name`.

GetConnectionUnixUser ()

GetConnectionUnixUser (IN  String  name,
                       OUT UInt32  uid)

Returns the UNIX user id of the process connected to the server. If unable to determine it, a %org.freedesktop.DBus.Error.Failed error is returned.

`IN String name`:	Name of the connection to query.
`OUT UInt32 uid`:	UNIX user id.

GetConnectionUnixProcessID ()

GetConnectionUnixProcessID (IN  String  name,
                            OUT UInt32  pid)

Returns the UNIX process id of the process connected to the server. If unable to determine it, a %org.freedesktop.DBus.Error.Failed error is returned.

`IN String name`:	Name of the connection to query.
`OUT UInt32 pid`:	UNIX process id.

GetAdtAuditSessionData ()

GetAdtAuditSessionData (IN  String       name,
                        OUT Array<Byte>  data)

Returns the Solaris/ADT auditing data of the process connected to the server. If unable to determine it, a %org.freedesktop.DBus.Error.AdtAuditDataUnknown error is returned.

`IN String name`:	Name of the connection to query.
`OUT Array<Byte> data`:	An array of bytes (typically a string of undefined encoding).

GetConnectionSELinuxSecurityContext ()

GetConnectionSELinuxSecurityContext (IN  String       name,
                                     OUT Array<Byte>  security_context)

Returns the SELinux security context of the process connected to the server. If unable to determine it, a %org.freedesktop.DBus.Error.SELinuxSecurityContextUnknown error is returned.

`IN String name`:	Name of the connection to query.
`OUT Array<Byte> security_context`:	An array of bytes (typically a string of undefined encoding).

ReloadConfig ()

ReloadConfig ()

Asks the message bus to reload configuration files.

GetId ()

GetId (OUT String  unique_id)

Gets the unique ID of the bus. The unique ID here is shared among all addresses the bus daemon is listening on (TCP, UNIX domain socket, etc.). Each address the bus is listening on also has its own unique ID. The per-bus and per-address IDs are not related. For a desktop session bus, the bus ID can be used as a way to uniquely identify a user's session. See the D-Bus specification for more information about unique IDs.

OUT String unique_id:

Unique ID identifying the bus daemon

Signal Details

The "NameOwnerChanged" signal

NameOwnerChanged (String  name,
                  String  old_owner,
                  String  new_owner)

This signal indicates that the owner of a name has changed. It's also the signal to use to detect the appearance of new names on the bus.

`String name`:	Name with new owner.
`String old_owner`:	Old owner or empty string if none.
`String new_owner`:	New owner or empty string if none.

The "NameLost" signal

NameLost (String  name)

This signal is sent to a specific application when it loses ownership of a name.

String name:

Name which was lost.

The "NameAcquired" signal

NameAcquired (String  name)

This signal is sent to a specific application when it gains ownership of a name.

String name:

Name which was acquired.

			EggDBus Reference Manual
Top \| Description \| Signals