Interface Channel.Interface.Room2

Interface Index (Compact) | Summary | Description | Properties

Properties

RoomName s Read only Immutable, Requestable
Server s Read only Immutable, Requestable
Creator s Read only Immutable
CreatorHandle u ( Contact_Handle) Read only Immutable
CreationTimestamp x ( Unix_Timestamp64) Read only Immutable
Added in 0.24.0. (version 2)
Objects implementing this interface must also implement:

Description

Different IM protocols use a variety of ways to name chat rooms. The simplest example is perhaps IRC, where chat rooms have short, persistent, human-readable string names, and are generally global across the network. Skype chat rooms have persistent string names, so you can leave and re-join a room, but these names are opaque unique identifiers. MSN chat rooms are unnamed, and you can only join one by being invited. And XMPP wins the coveted “most complicated chat rooms” prize: chat rooms may be hosted by different servers with different DNS names; normally they have human-readable names, except that all MUCs on Google Talk's conference server have UUIDs as names, and XEP-0045 §10.1.4 Requesting a Unique Room Name defines a protocol for requesting a unique, opaque room name on the server. Note that this interface is not restricted to Text channels, and can also be used on Call channels.

This interface intends to support and differentiate these mechanisms more clearly than the TargetHandleType and TargetID properties can alone. It initially contains a pair of properties used to represent the human-readable parts of a Room_Handle's identifier, if any. The above examples for different protocols are represented as follows:

Requestable channel classes

If the connection supports joining text chat rooms by unique identifier, like Skype, it should advertise a Requestable_Channel_Class matching:

( Fixed = { ...ChannelType: ...Text,
            ...TargetHandleType: Room,
          },
  Allowed = [ ...TargetID,
              ...TargetHandle,
            ]
)

Channel requests must specify either TargetID or TargetHandle.

If, like IRC, the room identifiers are also human-readable, the RCCs should also include RoomName in Allowed_Properties:

( Fixed = { ...ChannelType: ...Text,
            ...TargetHandleType: Room,
          },
  Allowed = [ ...TargetID,
              ...TargetHandle,
              ...RoomName
            ]
),

( Fixed = { ...ChannelType: ...Text
          },
  Allowed = [ ...RoomName,
            ]
)

Requests may specify the RoomName in place of TargetID or TargetHandle . Note how RoomName appears in Allowed_Properties of a different RCC because when TargetHandleType is omitted (or is None), both TargetHandle and TargetID must also be omitted. RoomName is allowed in conjuction with TargetID or TargetHandle in some situations, as explained below in the Requesting room channels section.

If rooms may be on different servers, Server should also be included in the allowed properties, but CMs MUST use a reasonable default Server if not explicitly specified in a channel request. The CM's default server MAY be configurable by a connection parameter specified on a RequestConnection call, similarly to how the fallback conference server is specified on jabber connections in gabble.

If the protocol supports unnamed rooms, RoomName should be fixed to the empty string, and TargetHandleType should be None:

( Fixed = { ...ChannelType: ...Text,
            ...TargetHandleType: None,
            ...RoomName: "",
          },
  Allowed = [ ]
)

Requesting room channels

When explicitly joining a room, the CM cannot know whether the room ID is unique or not. As a result, if this is the case, adding an empty string RoomName into the channel request will ensure the CM knows. For example:

{ ...ChannelType: ...Text,
  ...TargetHandleType: Room,
  ...TargetID: "qwerasdfzxcv@conference.jabber.org",
  ...RoomName: ""
}

If RoomName features in Allowed_Properties then the only value allowed in conjunction with TargetID or TargetHandle is the empty string. Requests with conflicting TargetID and RoomName properties will fail with InvalidArgument.

To create a XEP-0045 §10.1.4 uniquely-named room channel on the conference.jabber.org server, then the following channel request should be made:

{ ...ChannelType: ...Text,
  ...RoomName: ""
  ...Server: "conference.jabber.org"
}

If everything is successful, then when the channel request is satisfied, a new channel will appear with the following properties:

{ ...ChannelType: ...Text,
  ...TargetHandleType: Room,
  ...TargetID: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org",
  ...RoomName: ""
  ...Server: "conference.jabber.org"
}

The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs) and then created a room with such a name on the said server. The empty RoomName property shows that the room name is not human-readable.

Properties

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

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

The human-readable identifier of a chat room. Note that if non-empty, this property (and perhaps also Server) should be sufficient in a channel request to join the room. XMPP MUCs have a room name concept which is more like a topic, except more persistent. This D-Bus property is not this XMPP room name, but the bit before the @ in the room jid; see RoomConfig1.Title for that concept.

This property cannot change during the lifetime of the channel. It should appear in the Allowed_Properties of a Requestable_Channel_Class for the connection if rooms on this connection have human-readable names, and can be joined by name.

(Permalink)

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

For protocols with a concept of chatrooms on multiple servers with different DNS names (like XMPP), the DNS name of the server hosting this channel (for example, "conference.jabber.org" or "groupchat.google.com"). For other protocols, the empty string.

This property cannot change during the lifetime of the channel. It should appear in the Allowed_Properties of a Requestable_Channel_Class for the connection if and only if non-empty values are supported.

(Permalink)

Creator — 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.
Added in 0.25.0.
The normalized contact ID representing who created the room; or the empty string if unknown.
(Permalink)

CreatorHandle — u (Contact_Handle)

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.
Added in 0.25.0.
The handle corresponding to Creator; or 0 if Creator is unknown.
(Permalink)

CreationTimestamp — x (Unix_Timestamp64)

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.
Added in 0.25.0.
A unix timestamp indicating when the room was created; or INT_MAX64 if unknown.