The RoomList channel is used to access the available named chatrooms available on a server (e.g. XMPP multiuser chats, IRC chatrooms).
RoomList channels are stateful, so they should be created (see Section 6.1 ― Requesting Channels). On protocols that support multiple conference servers (e.g. XMPP), the Server property can be included in the request.
Example 6-14 shows an example property map that might be used to request a room list. Omitting the Server property will cause the server's default conference server to be used. If the server does not provide a default, the configured fallback for the connection will be used. If this is unset an error will occur (NotAvailable). Example 6-15 shows a code example.
You can discover the default conferencing server by omitting the Server property and then reading the value on the newly created channel.
| Key | Value | Notes |
|---|---|---|
| org.freedesktop.Telepathy.Channel.ChannelType | org.freedesktop.Telepathy.Channel.Type.RoomList | |
| org.freedesktop.Telepathy.Channel.TargetHandleType | Handle_Type_None | |
| org.freedesktop.Telepathy.Channel.Type.RoomList.Server | conference.xmpp.example.com | Optional |
/* request a RoomList channel */ GHashTable *map = tp_asv_new ( TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING, TP_IFACE_CHANNEL_TYPE_ROOM_LIST, TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, G_TYPE_UINT, TP_HANDLE_TYPE_NONE, /* we omit TargetHandle because it's anonymous */ NULL); tp_cli_connection_interface_requests_call_create_channel ( TP_CONNECTION (conn), -1, map, create_roomlist_cb, NULL, NULL, NULL); g_hash_table_destroy (map);
RoomList channels are anonymous. You must not provide a value for TargetHandle (unless you are using the deprecated RequestChannel method, in which case use the value 0).
It can take some time for the information on the available rooms to be collected, thus the room list is returned via the GotRooms signal. Clients should connect this signal before calling ListRooms. See Example 6-16.
The channel should be closed once it's finished with, so that the room handles (Handle_Type_Room) can be released.
GotRooms returns a list of handles of type Handle_Type_Room, channel types (as D-Bus interfaces, e.g. org.freedesktop.Telepathy.Channel.Type.Text and property maps. Known keys in the property map are:
| handle-name | String | The name of the handle, as returned by InspectHandles |
| name | String | The human readable name of the channel. |
| description | String | The description of the room's purpose. |
| subject | String | The current subject or topic of conversation. |
| members | Unsigned integer | The number of members in the room. |
| password | Boolean | If a password is required for this channel. See Section 6.5.1 ― Private Channels. |
| invite-only | Boolean | If true, you must be invited to this channel. |
def got_roomlist(self, channel_path): print 'Got Roomlist Channel' channel = telepathy.client.Channel(self.conn.service_name, channel_path) # end ex.channel.requestchannel channel[CHANNEL_TYPE_ROOM_LIST].connect_to_signal('GotRooms', self.got_rooms) channel[CHANNEL_TYPE_ROOM_LIST].connect_to_signal('ListingRooms', lambda *args: self.listing_rooms(channel, *args)) channel[CHANNEL_TYPE_ROOM_LIST].ListRooms(reply_handler = generic_handler, error_handler = self.error) def got_rooms(self, rooms): for handle, channel_type, info in rooms: print " - %(name)s (%(members)i) :: %(subject)s" % info def listing_rooms(self, channel, listing): print "listing rooms", listing if listing == False: # close the room list channel channel[CHANNEL].Close(reply_handler = generic_handler, error_handler = self.error)