Interface Channel.Type.StreamTube

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

Methods

Offer (u: address_type, v: address, u: access_control, a{sv}: parameters) → nothing
Accept (u: address_type, u: access_control, v: access_control_param) → v: address

Signals

NewRemoteConnection (u: Handle, v: Connection_Param, u: Connection_ID)
NewLocalConnection (u: Connection_ID)
ConnectionClosed (u: Connection_ID, s: Error, s: Message)

Properties

Service s Read only Immutable, Requestable
SupportedSocketTypes a{uau} ( Supported_Socket_Map) Read only Immutable

Types

Stream_Tube_Connection_ID Simple Type u
Objects implementing this interface must also implement:

Description

A stream tube is a transport for ordered, reliable data transfer, similar to SOCK_STREAM sockets.

When offering a stream tube, the initiating client creates a local listening socket and offers it to the recipient client using the Offer method. When a recipient accepts a stream tube using the Accept method, the recipient's connection manager creates a new local listening socket. Each time the recipient's client connects to this socket, the initiator's connection manager proxies this connection to the originally offered socket.

Methods

(Permalink)

Offer (u: address_type, v: address, u: access_control, a{sv}: parameters) → nothing

Parameters

  • address_type — u (Socket_Address_Type)
    • The type of the listening address of the local service, as a member of Socket_Address_Type.
  • address — v
    • The listening address of the local service, as indicated by the address_type.
  • access_control — u (Socket_Access_Control)
    • The access control the local service applies to the local socket, specified so the connection manager can behave appropriately when it connects.
  • parameters — a{sv} (String_Variant_Map)
    • The dictionary of arbitrary Parameters to send with the tube offer.
Offer a stream tube exporting the local socket 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 tube capabilities.
  • Not Implemented
    • The connection manager doesn't support the given address type or access-control type.
(Permalink)

Accept (u: address_type, u: access_control, v: access_control_param) → v: address

Parameters

  • address_type — u (Socket_Address_Type)
    • The type of address the connection manager should listen on.
  • access_control — u (Socket_Access_Control)

    • The type of access control the connection manager should apply to the socket.

    Note that if you plan to establish more than one connection through the tube, the Socket_Access_Control_Port access control can't be used as you can't connect more than once from the same port.

  • access_control_param — v
    • A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

Returns

  • address — v
    • The address on which the connection manager will listen for connections to this tube. The client should not attempt to connect to the address until the tube is open.
Accept a stream 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.

Possible Errors

  • Invalid Argument
    • The access_control_param is invalid with the given access_control.
  • Not Implemented
    • The given address type or access-control mechanism is not supported.

Signals

(Permalink)

NewRemoteConnection (u: Handle, v: Connection_Param, u: Connection_ID)

Parameters

  • Handle — u (Contact_Handle)
    • The handle of the participant who opened the new connection
  • Connection_Param — v

    • A parameter which can be used by the listening process to identify the connection. Note that this parameter has a meaningful value only in the Socket_Access_Control_Port and Socket_Access_Control_Credentials cases. If a different Socket_Access_Control has been chosen when offering the tube, this parameter should be ignored.

    In the Socket_Access_Control_Port case, the variant contains a struct Socket_Address_IPv4 (or Socket_Address_IPv6) containing the address from which the CM is connected to the client application.

    In the Socket_Access_Control_Credentials case, the variant contains the byte (D-Bus signature 'y') that has been sent with the credentials.

  • Connection_ID — u (Stream_Tube_Connection_ID)
    • The unique ID associated with this connection. This ID will be used to identifiy the connection when reporting errors with ConnectionClosed.

Emitted each time a participant opens a new connection to its socket.

This signal is only fired on the offering side.

(Permalink)

NewLocalConnection (u: Connection_ID)

Parameters

Emitted when the tube application connects to the CM's socket.

This signal is only fired on the accepting side.

(Permalink)

ConnectionClosed (u: Connection_ID, s: Error, s: Message)

Parameters

  • Connection_ID — u (Stream_Tube_Connection_ID)
    • The ID of the connection.
  • Error — s (DBus_Error_Name)

    • The name of a D-Bus error describing the error that occurred.

    The following errors can be used:

    • org.freedesktop.Telepathy.Error.Cancelled: user closed the socket or the tube.
    • org.freedesktop.Telepathy.Error.ConnectionLost: the bytestream relaying connection's data has been broken.
    • org.freedesktop.Telepathy.Error.ConnectionRefused: the tube offer refused the connection.
  • Message — s
    • A debug message.

Emitted when a connection has been closed.

Properties

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

Service — 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 TCP service name as defined by http://www.iana.org/assignments/port-numbers or http://www.dns-sd.org/ServiceTypes.html, for instance "rsync" or "daap".

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

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

(Permalink)

SupportedSocketTypes — a{uau} (Supported_Socket_Map)

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 mapping from address types (members of Socket_Address_Type) to arrays of access-control type (members of Socket_Access_Control) that the connection manager supports for stream tubes with that address type. For simplicity, if a CM supports offering a particular type of tube, it is assumed to support accepting it.

A typical value for a host without IPv6 support:

          {
            Socket_Address_Type_IPv4:
              [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
               Socket_Access_Control_Netmask],
            Socket_Address_Type_Unix:
              [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
          }

Connection Managers MUST support at least IPv4 with the localhost access control.

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

Types

Simple Type (Permalink)

Stream_Tube_Connection_ID — u

An identifier for a stream tube connection. These are defined with the NewLocalConnection or NewRemoteConnection signals and are used by ConnectionClosed to identify the closed connection.