Interface Channel.Type.DBusTube

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Types

Methods

Offer (a{sv}: parameters, u: access_control) → s: address
Accept (u: access_control) → s: address

Signals

DBusNamesChanged (a{us}: Added, au: Removed)

Properties

ServiceName s Read only Immutable, Requestable
DBusNames a{us} ( DBus_Tube_Participants) Read only
SupportedAccessControls au ( Socket_Access_Control_List) Read only Immutable

Types

DBus_Tube_Participants Mapping a{us}
Objects implementing this interface must also implement:

Description

A D-Bus tube is an ordered reliable transport, for transporting D-Bus traffic.

For each D-Bus tube, the connection manager listens on a D-Bus server address, as detailed in the D-Bus specification. On this address, it emulates a bus upon which each tube participant appears as an endpoint.

The objects and interfaces which are expected to exist on the emulated bus depend on the well-known name; typically, either the participant who initiated the tube is expected to export the same objects/interfaces that would be exported by a service of that name on a bus, or all participants are expected to export those objects/interfaces.

In a multi-user context (Handle_Type_Room) the tube behaves like the D-Bus bus daemon, so participants can send each other private messages, or can send broadcast messages which are received by everyone in the tube (including themselves). Each participant has a D-Bus unique name; connection managers MUST prevent participants from sending messages with the wrong sender unique name, and SHOULD attempt to avoid participants receiving messages not intended for them.

In a 1-1 context (Handle_Type_Contact) the tube behaves like a peer-to-peer D-Bus connection - arbitrary D-Bus messages with any sender and/or destination can be sent by each participant, and each participant receives all messages sent by the other participant.

Methods

(Permalink)

Offer (a{sv}: parameters, u: access_control) → s: address

Parameters

Returns

  • address — s
    • The string describing the address of the private bus. The client SHOULD NOT attempt to connect to the address until the tube is open.
Offers a D-Bus tube providing the service specified.

Possible Errors

  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Not Available
    • The contact associated with this channel doesn't have tubes capabilities.
(Permalink)

Accept (u: access_control) → s: address

Parameters

  • access_control — u (Socket_Access_Control)
    • The access control the connection manager applies to the D-Bus socket.

Returns

  • address — s
    • The string describing the address of the private bus. The client SHOULD NOT attempt to connect to the address until the tube is open.
Accept a D-Bus tube that's in the "local pending" state. The connection manager will attempt to open the tube. The tube remains in the "local pending" state until the TubeChannelStateChanged signal is emitted.

Signals

(Permalink)

DBusNamesChanged (a{us}: Added, au: Removed)

Parameters

Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a participant opens or closes the tube. This provides change notification for the DBusNames property.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

ServiceName — s

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannel signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

A string representing the service name that will be used over the tube. It SHOULD be a well-known D-Bus service name, of the form com.example.ServiceName.

When the tube is offered, the service name is transmitted to the other end.

When requesting a channel with CreateChannel, this property MUST be included in the request.

(Permalink)

DBusNames — a{us} (DBus_Tube_Participants)

Read only
For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping between contact handles and their unique bus names on this tube. For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty dictionary. Change notification is via DBusNamesChanged.
(Permalink)

SupportedAccessControls — au (Socket_Access_Control_List)

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannel signals.

A list of the access control types that are supported with this channel. Note that only Socket_Access_Control_Localhost and Socket_Access_Control_Credentials can be used with D-Bus tubes. Using Socket_Access_Control_Credentials is recommended.

Rationale:

Socket_Access_Control_Credentials is easy to implement for a D-Bus tube, because typical D-Bus library implementations like libdbus and GDBus already have to support it to be able to connect to the system or session bus, and usually enable it by default; so there's typically no good reason to relax access control to Localhost.

When requesting a channel with Connection.Interface.Requests.CreateChannel, this property MUST NOT be included in the request.

Types

Mapping (Permalink)

DBus_Tube_Participants — a{us}

Represents the participants in a multi-user D-Bus tube, as used by the DBusNames property and the DBusNamesChanged signal.