telepathy-python - Base classes defining the interfaces of the Telepathy framework Copyright (C) 2005 Collabora Limited Copyright (C) 2005 Nokia Corporation This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
A D-Bus service which allows connections to be created. The manager
processes are intended to be started by D-Bus service activation. The
names of these services, the protocols they support, and the parameters
understood by that protocol are intended to be discovered by reading files
on disk which are provided along with the connection manager. These are
documented elsewhere.
Once a connection manager service has been activated, the object
path of the manager object implementing this interface is always:
/org/freedesktop/Telepathy/ConnectionManager/name
Where name is the identifier for the connection manager.
It is not required that a connection manager be able to support multiple
protocols, or even multiple connections. When a connection is made, a
service name where the connection object can be found is returned. A
manager which can only make one connection may then remove itself from its
well-known bus name, causing a new connection manager to be activated when
somebody attempts to make a new connection.
Get a list of the parameters which must or may be provided to the
RequestConnection method when connecting to the given protocol,
or registering (the boolean "register" parameter is available, and
set to true).
Parameters may have the following flags:
1 - CONN_MGR_PARAM_FLAG_REQUIRED
This parameter is required for connecting to the server.
2 - CONN_MGR_PARAM_FLAG_REGISTER
This parameter is required for registering an account on the
server.
Returns:
an array of structs containing:
a string parameter name
a bitwise OR of the parameter flags (as defined above)
a string D-Bus type signature
a variant boxed default value
Potential Errors:
NotImplemented (the requested protocol is not supported by this manager)
Get a list of protocol identifiers that are implemented by this
connection manager. The following well-known values should be used
when applicable:
aim - AOL Instant Messenger
gadugadu - Gadu-Gadu
groupwise - Novell Groupwise
icq - ICQ
irc - Internet Relay Chat
jabber - Jabber (XMPP)
msn - MSN Messenger
napster - Napster
silc - SILC
sip - Session Initiation Protocol (SIP)
trepia - Trepia
yahoo - Yahoo! Messenger
zephyr - Zephyr
Returns:
an dictionary mapping parameter identifiers to type signatures
Potential Errors:
NotImplemented (the requested protocol is not supported by this manager)
Request a Connection object representing a given account on a given
protocol with the given parameters. The method returns the bus name
and the object path where the new Connection object can be found, which
should have the status of CONNECTION_STATUS_DISCONNECTED, to allow
signal handlers to be attached before connecting is started with the
Connect method.
In order to allow Connection objects to be discovered by new clients,
the bus name and object path must be of the form:
/org/freedesktop/Telepathy/Connection/manager/proto/account
And:
org.freedesktop.Telepathy.Connection.manager.proto.account
Where manager and proto are the identifiers for this manager and this
protocol, and account is a series of elements formed such that any
valid distinct connection instance on this protocol has a distinct
name. This might be formed by including the server name followed by the
user name, or on protocols where connecting multiple times is
permissable, a per-connection identifier is also necessary to ensure
uniqueness.
The parameters which must and may be provided in the parameters
dictionary can be discovered with the GetParameters method. These
parameters, their types, and their default values may be cached
in files so that all available connection managers do not need to be
started to discover which protocols are available.
To request values for these parameters from the user, a client must
have prior knowledge of the meaning of the parameter names, so the
following well-known names and types should be used where appropriate:
s:account - the identifier for the user's account on the server.
s:server - a fully qualified domain name or numeric IPv4 or IPv6
address. Using the fully-qualified domain name form is recommended
whenever possible. If this parameter is specified and the account
for that protocol also specifies a server, this parameter should
override that in the user id.
q:port - a TCP or UDP port number. If this parameter is specified
and the account for that protocol also specifies a port, this
parameter should override that in the account.
s:password - a password associated with the account.
b:require-encryption - require encryption for this connection. A
connection should fail to connect if require-encryption is set
and an encrypted connection is not possible.
b:register - this account should be created on the server if it
does not already exist.
s:ident - the local username to report to the server if
necessary, such as in IRC.
s:fullname - the user's full name if the service requires this
when authenticating or registering.
Parameters:
proto - the protocol identifier
parameters - a dictionary mapping parameter name to the variant boxed value
Returns:
a D-Bus service name where the new Connection object can be found
the D-Bus object path to the Connection on this service
Potential Errors:
NetworkError, NotImplemented (unknown protocol), NotAvailable (the requested connection already appears to exist), InvalidArgument (unrecognised connection parameters)
Emitted when a new Connection object is created.
Parameters:
bus_name - the D-Bus service where the connection object can be found
object_path - the object path of the Connection object on this service
proto - the identifier for the protocol this connection uses
This models a connection to a single user account on a communication
service. Its basic capability is to provide the facility to request and
receive channels of differing types (such as text channels or streaming
media channels) which are used to carry out further communication.
As well as the methods and signatures below, arbitrary interfaces may be
provided by the Connection object to represent extra connection-wide
functionality, such as the Connection.Interface.Presence for receiving and
reporting presence information, and Connection.Interface.Aliasing for
connections where contacts may set and change an alias for themselves.
These interfaces can be discovered using GetInterfaces after the
connection, has been established and must not change subsequently at
runtime.
Contacts, rooms, and server-stored lists (such as subscribed contacts,
block lists, or allow lists) on a service are all represented by
immutable handles, which are unsigned non-zero integers which are valid
only for the lifetime of the connection object, and are used throughout the
protocol where these entities are represented, allowing simple testing of
equality within clients. Connection manager implementations should
reference count these handles to determine if they are in use either by any
active clients or any open channels, and may deallocate them when this
ceases to be true. Clients may request handles of a given type and name
with the RequestHandles method, inspect the entity name of handles
with the InspectHandles method, keep handles from being released with
HoldHandles, and notify that they are no longer storing handles with
ReleaseHandles.
Request that the connection be established. This will be done
asynchronously and errors will be returned by emitting StatusChanged
signals.
Potential Errors:
NotAvailable (the connection is already connecting or connected)
Request that the connection be closed. This does nothing if the
connection is not connected.
Get the optional interfaces supported by this connection.
Returns:
an array of D-Bus interface names
Get the protocol this connection is using.
Returns:
a string identifier for the protocol
Potential Errors:
Disconnected
Get the handle which represents the user on this connection, which will
remain valid for the lifetime of this connection or until the user's
identifier changes. This is always a CONTACT type handle.
Returns:
an integer handle representing the user
Potential Errors:
Disconnected
Get the current status as defined in the StatusChanged signal.
Returns:
an integer representing the current status
Notify the connection manger that your client is holding a copy
of handles which may not be in use in any existing channel or
list, and were not obtained by using the RequestHandles method. For
example, a handle observed in an emitted signal, or displayed
somewhere in the UI that is not associated with a channel. The
connection manager must not deallocate a handle where any clients
have used this method to indicate it is in use until the ReleaseHandle
method is called, or the clients disappear from the bus.
Parameters:
handle_type - an integer representing the handle type
handle - a array of integer handles to hold
Potential Errors:
Disconnected, InvalidArgument (the handle type is invalid),
InvalidHandle (the given handle is not valid)
Return a string representation for a number of handles of a given
type.
Parameters:
handle_type - an integer handle type (as defined in RequestHandles)
handles - an array of integer handles of this type
Returns:
an array of handle names in the same order as the given numbers
Potential Errors:
Disconnected, InvalidArgument (the given type is not valid),
InvalidHandle (a given handle is not valid on this connection)
List all the channels which currently exist on this connection.
Returns:
an array of structs containing:
a D-Bus object path for the channel object on this service
a D-Bus interface name representing the channel type
an integer representing the handle type this channel communicates with, or zero
an integer handle representing the contact, room or list this channel communicates with, or zero
Potential Errors:
Disconnected
Explicitly notify the connection manager that your client is no
longer holding any references to the given handles, and that they
may be deallocated if they are not held by any other clients or
referenced by any existing channels.
Parameters:
handle_type - an integer representing the handle type
handle - an array of integer handles being held by the client
Potential Errors:
Disconnected, InvalidArgument (the given handle type is invalid),
InvalidHandle (the given handle is not valid), NotAvailable (the given
handle is not held by this client)
Request a channel satisfying the specified type and communicating with
the contact, room or list indicated by the given handle. The handle may
be zero to request the creation of a new, empty channel, which may or
may not be available depending on the protocol and channel type. May
return an existing channel object, create a new channel, or fail if the
request cannot be satisfied.
Parameters:
type - a D-Bus interface name representing base channel type
handle_type - an integer representing the handle type, or zero if no handle is being specified
handle - an integer handle representing a contact, room or list, or zero
suppress_handler - a boolean indicating that the requesting client intends to take responsibility for displaying the channel to the user, so that no other handler needs to be launched
Returns:
the D-Bus object path for the channel created or retrieved
Possible Errors:
Disconnected, NetworkError, NotImplemented (unknown channel type),
InvalidHandle (the given handle does not exist or cannot be created),
NotAvailable (the requested channel type cannot be created with the given handle),
Channel.Banned, Channel.Full, Channel.InviteOnly
Request several handles from the connection manager which represent a
number of contacts, rooms or server-stored lists on the service. The
connection manager should record that these handles are in use by the
client who invokes this method, and must not deallocate the handles
until the client disconnects from the bus or calls the ReleaseHandle
method. Where the name refers to an entity that already has a handle
in this connection manager, this handle should be returned instead.
The handle number 0 must not be returned by the connection manager.
The type value may be one of the following:
0 - CONNECTION_HANDLE_TYPE_NONE
1 - CONNECTION_HANDLE_TYPE_CONTACT
2 - CONNECTION_HANDLE_TYPE_ROOM
3 - CONNECTION_HANDLE_TYPE_LIST
Parameters:
type - an integer handle type
name - an array of names of entities to request handles for
Returns:
an array of integer handle numbers in the same order as given strings
Potential Errors:
Disconnected, InvalidArgument (the given type is not valid), NotAvailable (the given name is not a valid entity of the given type)
Emitted when a new Channel object is created, either through user
request or incoming information from the service. The suppress_handler
boolean indicates if the channel was requested by an existing client,
or is an incoming communication and needs to have a handler launched.
Parameters:
object_path - a D-Bus object path for the channel object on this service
channel_type - a D-Bus interface name representing the channel type
handle_type - an integer representing the type of handle this channel communicates with, which is zero if no handle is specified
handle - a handle indicating the specific contact, room or list this channel communicates with, or zero if it is an anonymous channel
suppress_handler - a boolean indicating that the channel was requested by a client that intends to display it to the user, so no handler needs to be launched
Emitted when the status of the connection changes. All states and
reasons have numerical values, as defined here:
0 - CONNECTION_STATUS_CONNECTED
The connection is alive and all methods are available.
1 - CONNECTION_STATUS_CONNECTING
The connection has not yet been established, or has been
severed and reconnection is being attempted. Some methods may fail
until the connection has been established.
2 - CONNECTION_STATUS_DISCONNECTED
The connection has been severed and no method calls are
valid. The object may be removed from the bus at any time.
The reason should be one of the following:
0 - CONNECTION_STATUS_REASON_NONE_SPECIFIED
There is no reason set for this state change.
1 - CONNECTION_STATUS_REASON_REQUESTED
The change is in response to a user request.
2 - CONNECTION_STATUS_REASON_NETWORK_ERROR
There was an error sending or receiving on the network socket.
3 - CONNECTION_STATUS_REASON_AUTHENTICATION_FAILED
The username or password was invalid.
4 - CONNECTION_STATUS_REASON_ENCRYPTION_ERROR
There was an error negotiating SSL on this connection, or
encryption was unavailable and require-encryption was set when the
connection was created.
5 - CONNECTION_STATUS_REASON_NAME_IN_USE
Someone is already connected to the server using the name
you are trying to connect with.
6 - CONNECTION_STATUS_REASON_CERT_NOT_PROVIDED
The server did not provide a SSL certificate.
7 - CONNECTION_STATUS_REASON_CERT_UNTRUSTED
The server's SSL certificate could not be trusted.
8 - CONNECTION_STATUS_REASON_CERT_EXPIRED
The server's SSL certificate has expired.
9 - CONNECTION_STATUS_REASON_CERT_NOT_ACTIVATED
The server's SSL certificate is not yet valid.
10 - CONNECTION_STATUS_REASON_CERT_HOSTNAME_MISMATCH
The server's SSL certificate did not match its hostname.
11 - CONNECTION_STATUS_REASON_CERT_FINGERPRINT_MISMATCH
The server's SSL certificate does not have the expected
fingerprint.
12 - CONNECTION_STATUS_REASON_CERT_SELF_SIGNED
The server's SSL certificate is self-signed.
13 - CONNECTION_STATUS_REASON_CERT_OTHER_ERROR
There was some other error validating the server's SSL certificate.
Parameters:
status - an integer indicating the new status
reason - an integer indicating the reason for the status change
An interface on connections to support protocols where contacts have an
alias which they can change at will, but their underlying unique identifier
remains unchanged. Provides a method for the user to set their own alias,
and a signal which should be emitted when a contact's alias is changed
or first discovered.
On connections where the user is allowed to set aliases for contacts and
store them on the server, the GetAliasFlags method will have the
CONNECTION_ALIAS_FLAG_USER_SET flag set, and the SetAliases method
may be called on contact handles other than the user themselves.
Return a logical OR of flags detailing the behaviour of aliases on this
connection. Valid flags are:
1 - CONNECTION_ALIAS_FLAG_USER_SET
The aliases of contacts on this connection are specified by the user
of the service, not the contacts themselves. This is the case on
eg Jabber.
Returns:
a integer with a logical OR of flags as defined above
Potential Errors:
Disconnected
Request the value of several contacts' aliases at once.
Parameters:
contacts - an array of the handle representing contacts
Returns:
a dictionary of contact handles to aliases in the same order
Possible Errors:
Disconnected, NetworkError, NotAvailable, InvalidHandle
Request that the alias of the given contact be changed. Success will be
indicated by emitting an AliasUpdate signal. On connections where the
CONNECTION_ALIAS_FLAG_USER_SET flag is not set, this method will only
ever succeed if contact is the user's own handle (as returned by
GetSelfHandle on the Connection interface).
Parameters:
a dictionary mapping:
integer handles of contacts
strings of the new alias to set
Possible Errors:
Disconnected, NetworkError, InvalidArgument, NotAvailable, PermissionDenied
Signal emitted when a contact's alias (or that of the user) is changed.
Parameters:
aliases - an array containing structs of:
the handle representing the contact
the new alias
An interface for connections where it is possible to know what channel
types may be requested before the request is made to the connection object.
Each capability represents a commitment by the connection manager that it
will ordinarily be able to create a channel when given a request with the
given type and handle.
Capabilities can pertain to a certain contact handle, representing
activities such as having a text chat or a voice call with the user, or can
be on the connection itself (where the handle will be zero), where they
represent the ability to create channels for chat rooms or activities such
as searching and room listing.
The following capability flags are defined:
1 - CONNECTION_CAPABILITY_FLAG_CREATE
The given channel type and handle can be given to RequestChannel to
create a new channel of this type.
2 - CONNECTION_CAPABILITY_FLAG_INVITE
The given contact can be invited to an existing channel of this type.
This interface also provides for user interfaces notifying the connection
manager of what capabilities to advertise for the user. This is done by
using the AdvertiseCapabilities method, and deals only with the interface
names of channel types which are implemented by available client processes.
Used by user interfaces to indicate which channel types they are able
to handle on this connection. Because these may be provided by
different client processes, this method accepts channel types to add
and remove from the set already advertised on this connection. The type
of advertised capabilities (create versus invite) is protocol-dependent
and hence cannot be set by the this method.
Upon a successful invocation of this method, the CapabilitiesChanged
signal will be emitted for the user's own handle (as returned by
GetSelfHandle) the by the connection manager to indicate the changes
that have been made. This signal should also be monitored to ensure
that the set is kept accurate - for example, a client may remove
capabilities when it exits which are still provided by another client.
Parameters:
add - an array of D-Bus interface names of channel types to add
remove - an array of D-Bus interface names of channel types to remove
Returns:
an array of the D-Bus interface names of currently supported channel types
Potential Errors:
NetworkError, Disconnected
Returns an array of capabilities for the given contact handles, or
the connection itself (where handle is zero).
Parameters:
handle - a contact handle for this connection, or zero for channel types available on the connection itself
Returns:
an array of structs containing:
an integer handle representing the contact
a D-Bus interface name representing the channel type
a bitwise OR of capability flags pertaining to this channel type
Possible Errors:
Disconnected, NetworkError, InvalidHandle (the handle does not represent a contact), PermissionDenied
Announce the availability or the removal of capabilities on the
given handle, or on the connection itself if the handle is zero.
Parameters:
an array of structures containing:
an integer handle representing the contact
a string channel type
a bitwise OR of capability flags which have been added
a bitwise OR of capability flags which have been removed
An interface for requesting information about a contact on a given
connection. Information is returned as a vCard represented as an XML
string, in the format defined by JEP-0054: vcard-temp specifiation
from the Jabber Software Foundation (this is derived from the
aborted IETF draft draft-dawson-vcard-xml-dtd-01).
Implementations using PHOTO or SOUND elements should use the URI encoding
where possible, and not provide base64 encoded data to avoid unnecessary
bus traffic. Clients should not implement support for these encoded forms.
A separate interface will be provided for transferring user avatars.
The following extended element names are also added to represent
information from other systems which are not based around vCards:
USERNAME - the username of the contact on their local system (used on IRC for example)
HOSTNAME - the fully qualified hostname, or IPv4 or IPv6 address of the contact in dotted quad or colon-separated form
Request information for a given contact. The function will return
after a GotContactInfo signal has been emitted for the contact, or
an error returned.
Parameters:
contact - an integer handle for the contact to request info for
Possible Errors:
Disconnected, NetworkError, InvalidHandle, PermissionDenied, NotAvailable
Emitted when information has been received from the server with
the details of a particular contact.
Parameters:
contact - an integer handle of the contact ID on the server
vcard - the XML string containing their vcard information
A connection interface for services which can signal to contacts
that they should instead contact a different user ID, effectively
forwarding all incoming communication channels to another contact on
the service.
Returns the current forwarding contact handle, or zero if none is set.
Returns:
an integer contact handle to whom incoming communication is forwarded
Possible Errors:
Disconnected, NetworkError, NotAvailable
Set a contact handle to forward incoming communications to. A zero
handle disables forwarding.
Parameters:
forward_to - an integer contact handle to forward incoming communications to
Possible Errors:
Disconnected, NetworkError, PermissionDenied, NotAvailable, InvalidHandle
Emitted when the forwarding contact handle for this connection has been
changed. An zero handle indicates forwarding is disabled.
Parameters:
forward_to - an integer contact handle to forward communication to
This interface is for services which have a concept of presence which can
be published for yourself and monitored on your contacts. Telepathy's
definition of presence based on that used by the Galago project
(see http://www.galago-project.org/).
Presence on an individual (yourself or one of your contacts) is modelled as
an last activity time along with a set of zero or more statuses, each of
which may have arbitrary key/value parameters. Valid statuses are defined
per connection, and a list of them can be obtained with the GetStatuses
method.
Each status has an arbitrary string identifier which should have an agreed
meaning between the connection manager and any client which is expected to
make use of it. The following well-known values (in common with those in
Galago) should be used where possible to allow clients to identify common
choices:
- available
- away
- brb (Be Right Back)
- busy
- dnd (Do Not Disturb),
- xa (Extended Away)
- hidden (aka Invisible)
- offline
As well as these well-known status identifiers, every status also has a
numerical type value which can be used by the client to classify even
unknown statuses into different fundamental types:
1 - CONNECTION_PRESENCE_TYPE_OFFLINE
2 - CONNECTION_PRESENCE_TYPE_AVAILABLE
3 - CONNECTION_PRESENCE_TYPE_AWAY
4 - CONNECTION_PRESENCE_TYPE_EXTENDED_AWAY
5 - CONNECTION_PRESENCE_TYPE_HIDDEN
These numerical types exist so that even if a client does not understand
the string identifier being used, and hence cannot present the presence to
the user to set on themselves, it may display an approximation of the
presence if it is set on a contact.
The dictionary of variant types allows the connection manager to exchange
further protocol-specific information with the client. It is recommended
that the string (s) argument 'message' be interpreted as an optional
message which can be associated with a presence status.
If the connection has a 'subscribe' contact list, PresenceUpdate signals
should be emitted to indicate changes of contacts on this list, and should
also be emitted for changes in your own presence. Depending on the
protocol, the signal may also be emitted for others such as people with
whom you are communicating, and any user interface should be updated
accordingly.
On some protocols, RequestPresence may only succeed on contacts on your
'subscribe' list, and other contacts will cause a PermissionDenied error.
On protocols where there is no 'subscribe' list, and RequestPresence
succeeds, a client may poll the server intermittently to update any display
of presence information.
Request that a single presence status is published for the user, along
with any desired parameters. Changes will be indicated by PresenceUpdate
signals being emitted.
Parameters:
status - the string identifier of the desired status
parms - a dictionary of optional parameter names mapped to their variant-boxed values
Possible Errors:
Disconnected, NetworkError, InvalidArgument, NotAvailable, PermissionDenied
Request that all of a user's presence statuses be removed. Be aware
that this request may simply result in the statuses being replaced by a
default available status. Changes will be indicated by PresenceUpdate
signals being emitted.
Possible Errors:
Disconnected, NetworkError, PermissionDenied
Get a dictionary of the valid presence statuses for this connection.
This is only available when online because only some statuses will
be available on some servers.
Returns:
a dictionary of string identifiers mapped to a struct for each status, containing:
- a type value from one of the values above
- a boolean to indicate if this status may be set on yourself
- a boolean to indicate if this is an exclusive status which you may not set alongside any other
- a dictionary of valid optional string argument names mapped to their types
Possible Errors:
Disconnected, NetworkError
Request that the given presence status is no longer published for the
user. Changes will be indicated by PresenceUpdate signals being
emitted. As with ClearStatus, removing a status may actually result in
it being replaced by a default available status.
Parameters:
status - the string identifier of the status not to publish anymore for the user
Possible Errors:
Disconnected, NetworkError, PermissionDenied, InvalidArgument (if the status
requested is not currently set)
Request the presence for contacts on this connection. A PresenceUpdate
signal will be emitted when they are received. This is not the same as
subscribing to the presence of a contact, which must be done using the
'subscription' Channel.Type.ContactList, and on some protocols presence
information may not be available unless a subscription exists.
Parameters:
contacts - an array of the contacts whose presence should be obtained
Possible Errors:
Disconnected, NetworkError, InvalidHandle, PermissionDenied, NotAvailable (if the presence of the requested contacts is not reported to this connection)
Request that the recorded last activity time for the user be updated on
the server.
Parameters:
time - a UNIX timestamp of the user's last activity time (in UTC)
Possible Errors:
Disconnected, NetworkError, NotImplemented (this protocol has no concept of idle time)
Request that the user's presence be changed to the given statuses and
desired parameters. Changes will be reflected by PresenceUpdate
signals being emitted. On certain protocols, this method may be
called on a newly-created connection which is still in the
DISCONNECTED state, and will sign on with the requested status.
If the requested status is not available after signing on,
NotAvailable will be returned and the connection will remain
offline, or if the protocol does not support signing on with
a certain status, Disconnected will be returned.
Parameters:
a dictionary of status identifiers mapped to:
a dictionary of optional parameter names mapped to their variant-boxed values
Possible Errors:
Disconnected, NetworkError, InvalidArgument, NotAvailable, PermissionDenied
This signal should be emitted when your own presence has been changed,
or the presence of the member of any of the connection's channels has
been changed, or when the presence requested by RequestPresence is available.
Parameters:
a dictionary of contact handles mapped to a struct containing:
- a UNIX timestamp of the last activity time (in UTC)
- a dictionary mapping the contact's current status identifiers to:
a dictionary of optional parameter names mapped to their
variant-boxed values
An interface to support getting and setting privacy modes to configure
situations such as not being contactable by people who are not on your
subscribe list. If this interface is not implemented, the default can be
presumed to be allow-all (as defined in GetPrivacyModes).
Return the current privacy mode, which must be one of the values
returned by GetPrivacyModes.
Returns:
a string of the current privacy mode
Possible Errors:
Disconnected, NetworkError
Returns the privacy modes available on this connection. The following
well-known names should be used where appropriate:
allow-all - any contact may initiate communication
allow-specified - only contacts on your 'allow' list may initiate communication
allow-subscribed - only contacts on your subscription list may initiate communication
Returns:
an array of valid privacy modes for this connection
Request that the privacy mode be changed to the given value, which
must be one of the values returned by GetPrivacyModes. Success is
indicated by the method returning and the PrivacyModeChanged
signal being emitted.
Parameters:
mode - the desired privacy mode
Possible Errors:
Disconnected, NetworkError, PermissionDenied, InvalidArgument
Emitted when the privacy mode is changed or the value has been
initially received from the server.
Parameters:
mode - the current privacy mode
An interface on connections to support protocols where the unique
identifiers of contacts can change. Because handles are immutable,
this is represented by a pair of handles, that representing the
old name, and that representing the new one.
Request that the users own identifier is changed on the server. Success
is indicated by a Renamed signal being emitted. A new handle will be
allocated for the user's new identifier, and remain valid for the
lifetime of the connection.
Parameters:
name - a string of the desired identifier
Possible Errors:
Disconnected, NetworkError, NotAvailable, InvalidArgument, PermissionDenied
Emitted when the unique identifier of a contact on the server changes.
Parameters:
original - the handle of the original identifier
new - the handle of the new identifier
All communication in the Telepathy framework is carried out via channel
objects which are created and managed by connections. This interface must
be implemented by all channel objects, along with one single channel type,
such as Channel.Type.ContactList which represents a list of people (such
as a buddy list) or a Channel.Type.Text which represents a channel over
which textual messages are sent and received.
Each channel may have an immutable handle associated with it, which may
be any handle type, such as a contact, room or list handle, indicating
that the channel is for communicating with that handle. If a channel does
not have a handle, it means that the channel is defined by some other
terms, such as it may be a transient group defined only by its members
as visible through the Channel.Interface.Group interface.
Other optional interfaces can be implemented to indicate other available
functionality, such as Channel.Interface.Group if the channel contains
a number of contacts, Channel.Interface.Password to indicate
that a channel may have a password set to require entry, and
Properties for extra data about channels which represent chat
rooms or voice calls. The interfaces implemented may not vary after the
channel's creation has been signalled to the bus (with the connection's
NewChannel signal).
Specific connection manager implementations may implement channel types and
interfaces which are not contained within this specification in order to
support further functionality. To aid interoperability between client and
connection manager implementations, the interfaces specified here should be
used wherever applicable, and new interfaces made protocol-independent
wherever possible. Because of the potential for 3rd party interfaces adding
methods or signals with conflicting names, the D-Bus interface names should
always be used to invoke methods and bind signals.
Request that the channel be closed. This is not the case until
the Closed signal has been emitted, and depending on the connection
manager this may simply remove you from the channel on the server,
rather than causing it to stop existing entirely. Some channels
such as contact list channels may not be closed.
Possible Errors:
Disconnected, NetworkError, NotImplemented
Returns the interface name for the type of this channel.
Returns the handle type and number if this channel represents a
communication with a particular contact, room or server-stored list, or
zero if it is transient and defined only by its contents.
Get the optional interfaces implemented by the channel.
Returns:
an array of the D-Bus interface names
Emitted when the channel has been closed. Method calls on the
channel are no longer valid after this signal has been emitted,
and the connection manager may then remove the object from the bus
at any point.
A channel type for representing a list of people on the server which is
not used for communication. This is intended for use with the interface
Channel.Interface.Group for managing buddy lists and privacy lists
on the server. This channel type has no methods because all of the
functionality it represents is available via the group interface.
Singleton instances of this channel type should be created by the
connection manager at connection time if the list exists on the server, or
may be requested by using the appropriate handle. These handles can be
obtained using RequestHandle with a handle type of
CONNECTION_HANDLE_TYPE_LIST and one of the following identifiers:
subscribe - the group of contacts for whom you wish to receive presence
publish - the group of contacts who may receive your presence
hide - a group of contacts who are on the publish list but are temporarily disallowed from receiving your presence
allow - a group of contacts who may send you messages
deny - a group of contacts who may not send you messages
Interface has no methods.
Interface has no signals.
A channel type for searching server-stored user directories. A new channel
should be requested by a client for each search attempt, and it should be
closed when the search is completed or the required result has been found
in order to free unused handles. The search can be cancelled at any time
by calling the channel Close method, although depending upon the protocol
the connection manager may not be able to prevent the server from sending
further results.
Before searching, the GetSearchKeys method should be used to discover any
instructions sent by the server, and the valid search keys which can be
provided to the Search method. A search request is then started by
providing some of these terms to the Search method, and the search status
will be set to CHANNEL_CONTACT_SEARCH_STATE_DURING. When results are
returned by the server, the SearchResultReceived signal is emitted for each
contact found, and when the search is complete, the search status will be
set to CHANNEL_SEARCH_STATE_AFTER.
Returns any instructions from the server along with a dictionary of
search key names to their types, and a boolean indicating if the key is
mandatory. The following well-known search key names should be used
where appropriate:
s:first - the desired contact's given name
s:last - the desired contact's family name
s:nick - the desired contact's nickname
s:email - the e-mail address of the desired contact
Returns:
a string with any instructions from the server
a dictionary mapping string search key names to an array of:
booleans indicating if the search key is mandatory
type signature of the value for this search key
Possible Errors:
Disconnected, NetworkError, NotAvailable
Returns the current state of this search channel object. One of the
following values:
0 - CHANNEL_CONTACT_SEARCH_STATE_BEFORE
the search has not started
1 - CHANNEL_CONTACT_SEARCH_STATE_DURING
the search is in progress
2 - CHANNEL_CONTACT_SEARCH_STATE_AFTER
the search has been completed
Returns:
an integer representing the search state
Send a request to start a search for contacts on this connection. A
valid search request will cause the SearchStateChanged signal to be
emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING.
Parameters:
a dictionary mapping search key names to the desired values
Possible Errors:
Disconnected, NetworkError, InvalidArgument
Emitted when a search result is received from the server.
Parameters:
an integer handle for the contact
a dictionary mapping search key names to values for this contact
Emitted when the search state (as returned by the GetSearchState
method) changes.
Parameters:
state - an integer representing the new search state
A channel that can send and receive streamed media such as audio or video.
The negotiation interface is based off the Farsight project's API for
negotiating ICE-style connection candidates, but should be applicable
to most streaming media systems.
When the negotiations are completed, the ReceivedMediaParameters signal is
emitted, containing the 'local' media parameters, which contain the SDP
information for the local user's media streams, and the 'remote' media
parameters which contains the same information for the remote user's
streams.
Returns all currently active session handlers on this channel
as a list of (member, session_handler_path, type).
Returns an array of structs of contact handles, stream identifiers
accompanying stream types and the current state of the stream.
Stream identifiers are unsigned integers and are unique for
each contact.
Stream types are identified by the following values:
MEDIA_STREAM_TYPE_AUDIO = 0
MEDIA_STREAM_TYPE_VIDEO = 1
Stream states are identified by
MEDIA_STREAM_STATE_STOPPED =0
MEDIA_STREAM_STATE_PLAYING = 1
MEDIA_STREAM_STATE_CONNECTING = 2
MEDIA_STREAM_STATE_CONNECTED = 3
Signal that a session handler object has been created for a member
of this channel. The client should then service this session handler
object to provide streaming services.
Parameter:
member - member that the MediaSessionHandler is created for
session_handler - object path of the MediaSessionHandler object
type - string indicating type of session, eg "rtp"
Possible Errors:
Disconnected, InvalidHandle, NotAvailable (if the contact has sent nothing to us on this channel)
Signal emitted when a memeber's stream's state changes, as defined
in GetStreams
Parameters:
stream_id - stream ID as returned by GetStreams
stream_state - new stream state
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.
Check to see if there is already a room list request in progress
on this channel.
Returns:
a boolean indicating if room listing is in progress
Request the list of rooms from the server. The ListingRooms signal
should be emitted when this request is being processed, GotRooms when
any room information is received, and ListingRooms when the request
is complete.
Possible Errors:
Disconnected, NetworkError, NotAvailable, PermissionDenied
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 CONNECTION_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:
s:name - the name of the room if different from the handle
s:subject - the subject of the room
u:members - the number of members of the room
b:password - true if the room requires a password to enter
b:invite-only - true if you cannot join the room, but must be invited
Parameters:
rooms - an array of structs containing:
an integer room handle
a string representing the D-Bus interface name of the channel type
an dictionary mapping string keys to variant boxed information
Emitted to indicate whether or not room listing request is currently
in progress.
Parameters:
listing - a boolean indicating if room listing is in progress
A channel type for sending and receiving messages in plain text, with no
formatting.
When a message is received, an identifier is assigned and a Received signal
emitted, and the message placed in a pending queue which can be inspected
with GetPendingMessages. A client which has handled the message by showing
it to the user (or equivalent) should acknowledge the receipt using the
AcknowledgePendingMessage method, and the message will then be removed from
the pending queue. Numeric identifiers for received messages may be reused
over the lifetime of the channel.
Each message has an associated 'type' value, which should be one of the
following:
0 - CHANNEL_TEXT_MESSAGE_TYPE_NORMAL
a standard message
1 - CHANNEL_TEXT_MESSAGE_TYPE_ACTION
an action which might be presented to the user as *
2 - CHANNEL_TEXT_MESSAGE_TYPE_NOTICE
an one-off or automated message not necessarily expecting a reply
3 - CHANNEL_TEXT_MESSAGE_TYPE_AUTO_REPLY
an automatically-generated reply message
Each message also has a flags value, which is a bitwise OR of the
following:
1 - CHANNEL_TEXT_MESSAGE_FLAG_TRUNCATED
The incoming message was truncated to a shorter length by the
server or the connection manager.
Sending messages can be requested using the Send method, which will return
and cause the Sent signal to be emitted when the message has been delivered
to the server, or SendError if there is a failure.
Inform the channel that you have handled messages by displaying them to
the user (or equivalent), so they can be removed from the pending queue.
Parameters:
ids - the message to acknowledge
Possible Errors:
InvalidArgument (a given message ID was not found, no action taken)
Return an array indicating which types of message may be sent on this
channel.
Returns:
an array of integer message types as defined above
List the messages currently in the pending queue, and optionally
remove then all.
Parameters:
clear - a boolean indicating whether the queue should be cleared
Returns:
an array of structs containing:
a numeric identifier
a unix timestamp indicating when the message was received
an integer handle of the contact who sent the message
an integer of the message type
a bitwise OR of the message flags
a string of the text of the message
Request that a message be sent on this channel. The Sent signal will be
emitted when the message has been sent, and this method will return.
Parameters:
type - an integer indicating the type of the message
text - the message to send
Possible Errors:
Disconnected, NetworkError, InvalidArgument, PermissionDenied
This signal is emitted to indicate that an incoming message was
not able to be stored and forwarded by the connection manager
due to lack of memory.
Signals that a message with the given id, timestamp, sender, type
and text has been received on this channel. Applications that catch
this signal and reliably inform the user of the message should
acknowledge that they have dealt with the message with the
AcknowledgePendingMessage method.
Parameters:
id - a numeric identifier for acknowledging the message
timestamp - a unix timestamp indicating when the message was received
sender - the handle of the contact who sent the message
type - the type of the message (normal, action, notice, etc)
flags - a bitwise OR of the message flags as defined above
text - the text of the message
Signals that an outgoing message has failed to send. The error
will be one of the following values:
0 - CHANNEL_TEXT_SEND_ERROR_UNKNOWN
An unknown error occured.
1 - CHANNEL_TEXT_SEND_ERROR_OFFLINE
The requested contact was offline.
2 - CHANNEL_TEXT_SEND_ERROR_INVALID_CONTACT
The requested contact is not valid.
3 - CHANNEL_TEXT_SEND_ERROR_PERMISSION_DENIED
The user does not have permission to speak on this channel.
4 - CHANNEL_TEXT_SEND_ERROR_TOO_LONG
The outgoing message was too long and was rejected by the
server.
Parameters:
error - one of the above integer errors
timestamp - the unix timestamp indicating when the message was sent
type - the message the (normal, action, notice, etc)
text - the text of the message
Signals that a message has been sent on this channel.
Parameters:
timestamp - the unix timestamp indicating when the message was sent
type - the message type (normal, action, notice, etc)
text - the text of the message
An interface that gives a Channel the ability to send or receive DTMF
signalling tones. This usually only makes sense for channels transporting
audio.
Requests that a DTMF tone is sent.
Parameters:
signal - a numeric signal number
duration - a numeric duration in milliseconds
Possible Errors:
Disconnected, NetworkError, NotAvailable, InvalidArgument
Signals that this channel received a DTMF tone.
Parameters:
signal - a numeric signal number
duration - a numeric duration in milliseconds
Interface for channels which have multiple members, and where the members
of the channel can change during its lifetime. Your presence in the channel
cannot be presumed by the channel's existence (for example, a channel you
may request membership of but your request may not be granted).
This interface implements three lists: a list of current members, and two
lists of local pending and remote pending members. Contacts on the remote
pending list have been invited to the channel, but the remote user has not
accepted the invitation. Contacts on the local pending list have requested
membership of the channel, but the local user of the framework must accept
their request before they may join. A single contact should never appear on
more than one of the three lists. The lists are empty when the channel is
created, and the MembersChanged signal should be emitted when information
is retrieved from the server, or changes occur.
Addition of members to the channel may be requested by using AddMembers. If
remote acknowledgement is required, use of the AddMembers method will cause
users to appear on the remote pending list. If no acknowledgement is
required, AddMembers will add contacts to the member list directly. If a
contact is awaiting authorisation on the local pending list, AddMembers
will grant their membership request.
Removal of contacts from the channel may be requested by using
RemoveMembers. If a contact is awaiting authorisation on the local pending
list, RemoveMembers will refuse their membership request. If a contact is
on the remote pending list but has not yet accepted the invitation,
RemoveMembers will rescind the request if possible.
It should not be presumed that the requester of a channel implementing this
interface is immediately granted membership, or indeed that they are a
member at all, unless they appear in the list. They may, for instance,
be placed into the remote pending list until a connection has been
established or the request acknowledged remotely.
Invite all the given contacts into the channel, or accept requests for
channel membership for contacts on the pending local list. A message
may be provided along with the request, which will be sent to the
server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and
CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT flags to see in which cases this
message should be provided.
Parameters:
contacts - an array of contact handles to invite to the channel
message - a string message, which can be blank if desired
Possible Errors:
Disconnected, NetworkError, NotAvailable, PermissionDenied, InvalidHandle,
Channel.Full, Channel.InviteOnly, Channel.Banned
Returns arrays all current, local and remote pending channel
members.
Returns:
array of handles of current members
array of handles of local pending members
array of handles of remote pending members
Possible Errors:
Disconnected, NetworkError
Returns an integer representing the logical or of flags on this
channel. The user interface can use this to present information about
which operations are currently valid.
These can be:
1 - CHANNEL_GROUP_FLAG_CAN_ADD
The AddMembers method can be used to add or invite members who are
not already in the local pending list (which is always valid).
2 - CHANNEL_GROUP_FLAG_CAN_REMOVE
The RemoveMembers method can be used to remove channel members
(removing those on the pending local list is always valid).
4 - CHANNEL_GROUP_FLAG_CAN_RESCIND
The RemoveMembers method can be used on people on the remote
pending list.
8 - CHANNEL_GROUP_FLAG_MESSAGE_ADD
A message may be sent to the server when calling AddMembers on
contacts who are not currently pending members.
16 - CHANNEL_GROUP_FLAG_MESSAGE_REMOVE
A message may be sent to the server when calling RemoveMembers on
contacts who are currently channel members.
32 - CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT
A message may be sent to the server when calling AddMembers on
contacts who are locally pending.
64 - CHANNEL_GROUP_FLAG_MESSAGE_REJECT
A message may be sent to the server when calling RemoveMembers on
contacts who are locally pending.
128 - CHANNEL_GROUP_FLAG_MESSAGE_RESCIND
A message may be sent to the server when calling RemoveMembers on
contacts who are remote pending.
256 - CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES
The members of this group have handles which are specific to
this channel, and are not valid as general-purpose handles on
the connection. Depending on the channel, it may be possible to
call GetHandleOwners to find the owners of these handles, which
should be done if you wish to eg subscribe to the contact's
presence.
Returns:
an integer of flags or'd together
Possible Errors:
Disconnected, NetworkError
If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on
the channel, then the handles of the group members are specific
to this channel, and are not meaningful in a connection-wide
context such as contact lists. This method allows you to find
the owner of the handle if it can be discovered in this channel,
or 0 if the owner is not available.
Parameters:
handles - a list of integer handles representing members of the
channel
Returns:
an array of integer handles representing the owner handle of
the the given room members, in the same order, or 0 if the
owner is not available
Possible Errors:
Disconnected, NetworkError, InvalidHandle, InvalidArgument (one
of the given handles is not a member)
Returns an array of handles representing contacts requesting
channel membership and awaiting local approval with AddMembers.
Possible Errors:
Disconnected, NetworkError
Returns an array of handles for the members of this channel.
Possible Errors:
Disconnected, NetworkError
Returns an array of handles representing contacts who have been
invited to the channel and are awaiting remote approval.
Possible Errors:
Disconnected, NetworkError
Returns the handle for the user on this channel if they are pending
(local or remote) or a current member, and 0 if not. Note that this
is different from the connection GetSelfHandle on some protocols,
so the value of this handle should always be used with the methods
of this interface.
Possible Errors:
Disconnected, NetworkError
Requests the removal of contacts from a channel, reject their request
for channel membership on the pending local list, or rescind their
invitation on the pending remote list. A message may be provided along
with the request, which will be sent to the server if supported. See
the CHANNEL_GROUP_FLAG_MESSAGE_REMOVE,
CHANNEL_GROUP_FLAG_MESSAGE_REJECT and
CHANNEL_GROUP_FLAG_MESSAGE_RESCIND flags to see in which cases this
message should be provided.
Parameters:
contacts - an array of contact handles to remove from the channel
message - a string message, which can be blank if desired
Possible Errors:
Disconnected, NetworkError, NotAvailable, PermissionDenied, InvalidHandle
Emitted when the flags as returned by GetGroupFlags are changed.
The user interface should be updated as appropriate.
Parameters:
added - a logical OR of the flags which have been set
removed - a logical OR of the flags which have been cleared
Emitted when contacts join any of the three lists (members, local
pending or remote pending). Contacts are listed in the removed
list when they leave any of the three lists. There may also be
a message from the server regarding this change, which may be
displayed to the user if desired.
The reason value will be one of the following:
0 - CHANNEL_GROUP_CHANGE_REASON_NONE
No reason was provided for this change.
1 - CHANNEL_GROUP_CHANGE_REASON_OFFLINE
The change is due to a user going offline.
2 - CHANNEL_GROUP_CHANGE_REASON_KICKED
The change is due to a kick operation.
3 - CHANNEL_GROUP_CHANGE_REASON_BUSY
The change is due to a busy indication.
4 - CHANNEL_GROUP_CHANGE_REASON_INVITED
The change is due to an invitation.
Parameters:
message - a string message from the server, or blank if not
added - a list of members added to the channel
removed - a list of members removed from the channel
local_pending - a list of members who are pending local approval
remote_pending - a list of members who are pending remote approval
actor - the contact handle of the person who made the change, or 0
if not known
reason - a reason for the change from one of the above values
Interface for channels where members may put you on hold, or you may put
members on hold. This usually only makes sense for channels where you are
streaming media to or from the members. Hold is defined as requesting
that you are not sent any media streams by another, so these states
indicate whether or not you are sending and receiving media streams
to each member of the channel.
Given a member of the channel, return their current hold state. This
can be one of the following values:
0 - CHANNEL_HOLD_STATE_NONE
Neither the local user and the remote member are on hold, and media
is being sent bidirectionally.
1 - CHANNEL_HOLD_STATE_SEND_ONLY
The local user has put the remote member on hold, so is sending
media but has arranged not to receive any media streams.
2 - CHANNEL_HOLD_STATE_RECV_ONLY
The user has been put on hold by the remote member, so is receiving
media but has arranged not to send any media streams.
3 - CHANNEL_HOLD_STATE_BOTH
Both the local user and the remote member have agreed not to send
any media streams to each other.
Parameters:
member - the handle of a member of the channel
Returns:
state - an integer representing the hold state, as defined above
Potential Errors:
Disconnected, InvalidHandle
Request that a certain member be put on hold (be instructed not to send
any media streams to you) or be taken off hold. Success is indicated
by the HoldStateChanged signal being emitted.
Parameters:
member - the integer handle of a member of the channel
hold - an boolean indicating whether or not the user should be on hold
Potential Errors:
Disconnected, NetworkError, InvalidHandle
Emitted to indicate that the hold state (as defined in GetHoldState
above) has changed for a member of this channel. This may occur as
a consequence of you requesting a change with RequestHold, or the
state changing as a result of a request from the remote member
or another process.
Parameters:
member - the integer handle of a member of the channel
state - an integer representing the new hold state
Interface for channels that may have a password set that users need
to provide before being able to join, or may be able to view or change
once they have joined the channel.
The GetPasswordFlags method and the associated PasswordFlagsChanged
signal indicate whether the channel has a password, whether the user
must now provide it to join, and whether it can be viewed or changed
by the user.
Returns the logical OR of the flags relevant to the password on this
channel. The user interface can use this to present information about
which operations are currently valid.
These can be:
8 - CHANNEL_PASSWORD_FLAG_PROVIDE
the ProvidePassword method must be called now for the user to join the channel
Returns:
an integer with the logical OR of all the flags set
Possible Errors:
Disconnected, NetworkError
Provide the password so that the channel can be joined. Must be
called with the correct password in order for channel joining to
proceed if the 'provide' password flag is set.
Parameters:
password - the password
Returns:
a boolean indicating whether or not the password was correct
Possible Errors:
Disconnected, NetworkError, InvalidArgument
Emitted when the flags as returned by GetPasswordFlags are changed.
The user interface should be updated as appropriate.
Parameters:
added - a logical OR of the flags which have been set
removed - a logical OR of the flags which have been cleared
An interface for channels where you may request that one of the members
connects to somewhere else instead.
Request that the given channel member instead connects to a different
contact ID.
Parameters:
member - the handle of the member to transfer
destination - the handle of the destination contact
Possible Errors:
Disconnected, NetworkError, NotAvailable, InvalidHandle, PermissionDenied
Interface has no signals.
A media session handler is an object that handles a number of synchronised
media streams.
Inform the connection manager that an error occured in this session.
Inform the connection manager that a client is ready to handle
this SessionHandler.
Emitted when a new media stream handler has been created for this
session.
Parameters:
stream_handler - an object path to a new MediaStreamHandler
media_type - enum for type of media that this stream should handle
MEDIA_STREAM_TYPE_AUDIO = 0
MEDIA_STREAM_TYPE_VIDEO = 1
direction - enum for direction of this stream
MEDIA_STREAM_DIRECTION_NONE = 0
MEDIA_STREAM_DIRECTION_SEND = 1
MEDIA_STREAM_DIRECTION_RECEIVE = 2
MEDIA_STREAM_DIRECTION_BIDIRECTIONAL = 3
Handles ths lifetime of a media stream. A client should provide
information to this handler as and when is it ready.
Inform the connection manager of the current codec choice.
Inform the connection manager that an error occured in this stream.
Parameters:
errno - id of error, one of the following:
MEDIA_STREAM_ERROR_UNKNOWN = 0
MEDIA_STREAM_ERROR_EOS = 1
message - string describing the error
Informs the connection manager that all possible native candisates
have been discovered for the moment.
Informs the connection manager that a valid candidate pair
has been discovered and streaming is in progress.
Inform this MediaStreamHandler that a new native transport candidate
has been ascertained.
Parameters:
candidate_id - string identifier for this candidate
transports - array of transports for this candidate with fields:
component number
ip (as a string)
port
enum for base network protocol
MEDIA_STREAM_BASE_PROTO_UDP = 0
MEDIA_STREAM_BASE_PROTO_TCP = 1
string specifying proto subtype (e.g RTP)
string specifying proto profile (e.g AVP)
our preference value of this transport (double in range 0-1
inclusive)
1 signals most preferred transport
transport type, one of the following:
MEDIA_STREAM_TRANSPORT_TYPE_LOCAL = 0
a local address
MEDIA_STREAM_TRANSPORT_TYPE_DERIVED = 1
an external address derived by a method such as STUN
MEDIA_STREAM_TRANSPORT_TYPE_RELAY = 2
an external stream relay
username - string to specify a username if authentication
is required
password - string to specify a password if authentication
is required
Inform the connection manager that a client is ready to handle
this StreamHandler. Also provide it with info about all supported
codecs.
Parameters:
codecs - as for SupportedCodecs
Informs the connection manager of the stream's current state
State is as specified in ChannelTypeStreamedMedia::GetStreams.
Inform the connection manager of the supported codecs for this session.
This is called after the connection manager has emitted SetRemoteCodecs
to notify what codecs are supported by the peer, and will thus be an
intersection of all locally supported codecs (passed to Ready)
and those supported by the peer.
Parameters:
codecs - list of codec info structures containing
id of codec
codec name
media type
clock rate of codec
number of supported channels
string key-value pairs for supported optional parameters
Signal emitted when the connection manager wishes to inform the
client of a new remote candidate.
Parameters:
candidate_id - string identifier for this candidate
transports - array of transports for this candidate with fields,
as defined in NewNativeCandidate
Signal emitted when the connection manager wishes to inform the
client that the remote end has removed a previously usable
candidate.
Parameters:
candidate_id - string identifier for remote candidate to drop
Emitted by the connection manager to inform the client that a
valid candidate pair has been discovered by the remote end
and streaming is in progress.
Signal emitted when the connection manager wishes to inform the
client of all the available remote candidates at once.
Parameters:
remote_candidates - a list of candidate id and a list of transports
as defined in NewNativeCandidate
Signal emitted when the connectoin manager wishes to inform the
client of the codecs supported by the remote end.
Parameters:
codecs - as for SupportedCodecs
Signal emitted when the connection manager wishes to set the
stream playing or stopped.
Interface for channels and other objects, to allow querying and setting
properties. ListProperties returns which properties are valid for
the given channel, including their type, and an integer handle used to
refer to them in GetProperties, SetProperties, and the PropertiesChanged
signal. The values are represented by D-Bus variant types, and are
accompanied by flags indicating whether or not the property is readable or
writable.
When applied to channels such as chat rooms, the following property
types and names should be used where appropriate, but implementations may
add extra properties to communicate data with particular clients:
b:invite-only
true if people may not join the channel until they have been invited
u:limit
the limit to the number of members, if limited is true
b:limited
true if there is a limit to the number of channel members
b:moderated
true if channel membership is not sufficient to allow participation
s:name
a human-visible name for the channel, if it differs to the handle
s:password
the password required to enter the channel if password-required is true
b:password-required
true if a password must be provided to enter the channel
b:private
true if the channel is not visible to non-members
s:subject
a human-readable description of the channel
u:subject-timestamp
a unix timestamp indicating when the subject was last modified
u:subject-contact
a contact handle representing who last modified the subject
Each property also has a flags value to indicate what methods are
available. This is a bitwise OR of the following values:
1 - PROPERTY_FLAG_READ
the property can be read
2 - PROPERTY_FLAG_WRITE
the property can be written
Returns a dictionary of variants containing the current values of the
given properties.
If any given property identifiers are invalid, InvalidArgument will be
returned. All properties must have the PROPERTY_FLAG_READ flag, or
PermissionDenied will be returned.
Parameters:
properties - an array of property identifiers
Returns:
an array of structs containing:
integer identifiers
variant boxed values
Potential Errors:
Disconnected, InvalidArgument, PermissionDenied
Returns a dictionary of the properties available on this channel.
Returns:
an array of structs containing:
integer identifiers
a string property name
a string representing the D-Bus signature of this property
a bitwise OR of the flags applicable to this property
Takes a dictionary of variants containing desired values to set the given
properties. In the case of any errors, no properties will be changed.
When the changes have been acknowledged by the server, the
PropertiesChanged signal will be emitted.
All properties given must have the PROPERTY_FLAG_WRITE flag, or
PermissionDenied will be returned. If any variants are of the wrong
type, NotAvailable will be returned. If any given property identifiers
are invalid, InvalidArgument will be returned.
Parameters:
properties - a dictionary mapping integer identifiers to:
variant boxed values
Potential Errors:
Disconnected, InvalidArgument, NotAvailable, PermissionDenied, NetworkError
Emitted when the value of readable properties has changed.
Parameters:
properties - an array of structs containing:
integer identifiers
variant boxed values
Emitted when the flags of some room properties have changed.
Parameters:
properties - an array of structs containing:
integer identifiers
a bitwise OR of the current flags
The connection is not currently connected and cannot be used.
Raised when one of the provided arguments is invalid.
The contact name specified is unknown on this channel or connection.
Raised when there is an error reading from or writing to the network.
Raised when the requested functionality is temporarily unavailable.
Raised when the requested method, channel, etc is not available on this connection.
The user is not permitted to perform the requested operation.
You are banned from the channel.
The channel is full.
The requested channel is invite only.