Interface Channel.Type.RoomList

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

Methods

GetListingRooms () → b: In_Progress
ListRooms () → nothing
StopListing () → nothing

Signals

GotRooms (a(usa{sv}): Rooms)
ListingRooms (b: Listing)

Properties

Server s Read only

Types

Room_Info Struct (usa{sv})
Objects implementing this interface must also implement:

Description

A channel type for listing named channels available on the server. Once the ListRooms method is called, it emits signals for rooms present on the server, until you Close this channel. In some cases, it may not be possible to stop the deluge of information from the server. This channel should be closed when the room information is no longer being displayed, so that the room handles can be freed.

This channel type may be implemented as a singleton on some protocols, so clients should be prepared for the eventuality that they are given a channel that is already in the middle of listing channels. The ListingRooms signal, or GetListingRooms method, can be used to check this.

Methods

(Permalink)

GetListingRooms () → b: In_Progress

Returns

  • In_Progress — b
    • A boolean indicating if room listing is in progress
Check to see if there is already a room list request in progress on this channel.
(Permalink)

ListRooms () → nothing

Request the list of rooms from the server. The ListingRooms (True) signal should be emitted when this request is being processed, GotRooms when any room information is received, and ListingRooms (False) when the request is complete.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Not Available
    • Raised when the requested functionality is temporarily unavailable.
  • Permission Denied
    • The user is not permitted to perform the requested operation.
(Permalink)

StopListing () → nothing

Stop the room listing if it's in progress, but don't close the channel. The ListingRooms (False) signal should be emitted when the listing stops.

Signals

(Permalink)

GotRooms (a(usa{sv}): Rooms)

Parameters

  • Rooms — a(usa{sv}) (Room_Info_List)
    • An array of structs containing:
    • an integer room handle
    • a string representing the D-Bus interface name of the channel type
    • a dictionary mapping string keys to variant boxed information

Emitted when information about rooms on the server becomes available. The array contains the room handle (as can be passed to the RequestChannel method with HANDLE_TYPE_ROOM), the channel type, and a dictionary containing further information about the room as available. The following well-known keys and types are recommended for use where appropriate:

handle-name (s)
The identifier of the room (as would be returned by InspectHandles). This property is mandatory.
name (s)
The human-readable name of the room if different from the handle
description (s)
A description of the room's overall purpose
subject (s)
The current subject of conversation in the room (as would be returned by getting the string part of the Subject property)
members (u)
The number of members in the room
password (b)
True if the room requires a password to enter
invite-only (b)
True if you cannot join the room, but must be invited
room-id (s)
The human-readable identifier of a chat room (as would be returned by getting the RoomName property)
server (s)
The DNS name of the server hosting these channels (as would be returned by getting the Server property)
(Permalink)

ListingRooms (b: Listing)

Parameters

  • Listing — b
    • A boolean indicating if room listing is in progress
Emitted to indicate whether or not room listing request is currently in progress.

Properties

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

Server — s

Read only

For protocols with a concept of chatrooms on multiple servers with different DNS names (like XMPP), the DNS name of the server whose rooms are listed by this channel, e.g. "conference.jabber.org". Otherwise, the empty string.

This property cannot change during the lifetime of the channel.

Types

Struct (Permalink)

Room_Info — (usa{sv})