Added in
version
Changed in
version
Changed in version
Deprecated
since version
This interface is
Implementations of this interface must also implement:
Interface has no methods.
Interface has no signals.
Accessed using the Telepathy Properties interface.
Interface has no Telepathy properties.
Accessed using the org.freedesktop.DBus.Properties interface.
Interface has no D-Bus core properties.
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 Lesser 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
Interface for channels where you may put the channel on hold. This only makes sense for channels where you are streaming media to or from the members.
If you place a channel on hold, this indicates that you do not wish to be sent media streams by any of its members and will be ignoring any media streams you continue to receive. It also requests that the connection manager free up any resources that are only needed for an actively used channel (e.g. in a GSM or PBX call, it will be necessary to place an active call on hold before you can start another call).
Request that the channel be put on hold (be instructed not to send any media streams to you) or be taken off hold.
If the connection manager can immediately tell that the requested state change could not possibly succeed, this method SHOULD return the NotAvailable error. If the requested state is the same as the current state, this method SHOULD return successfully without doing anything.
Otherwise, this method SHOULD immediately set the hold state to
Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold
(as appropriate), emitting
The eventual success or failure of the request is indicated by a subsequent HoldStateChanged signal, changing the hold state to Local_Hold_State_Held or Local_Hold_State_Unheld.
If the channel has multiple streams, and the connection manager succeeds in changing the hold state of one stream but fails to change the hold state of another, it SHOULD attempt to revert all streams to their previous hold states.
The following state transitions SHOULD be used, where appropriate:
Interface for managing channels that are used as conference members.
This interface augments com.nokia.Telepathy.Channel.Interface.Conference.
Joins this channel to an existing conference channel.
Returns the conference channel of which this channel is member.
The conference channel of which this channel is member, "/" if not a member.
Removes this channel from the conference. This implies that the media streams within the conference are put on hold and the media streams within the member channel leaving the conference are unhold.
This interface provides requestable channel properties that can be used to request Skype voicemail playback for individual stored messages.
The handle of the message sender.
The value is obtained from the header 'x-nokia-mail-sender' of the voicemail notification message.
The timestamp of the voicemail message.
The value is obtained from the header 'message-sent' of the voicemail notification message.
Interface for obtaining well known handles for emergency services and their aliases.
The emergency services are identified using a 'urn:service:sos' service urn, specified by RFC 5031. The aliases are used to identify the emergency service locally, e.g., "112", "911" or "999".
Return the service urns, corresponding to the emergency contacts, e.g., "urn:service:sos", a contact handle corresponding to it, and the list of local aliases identifying the emergency service, e.g., "911" or "112".
The list of available emergency service URNs and the local aliases identifying them, e.g., "urn:service:sos", a contact handle corresponding to it, and the list of local aliases identifying the emergency service, e.g., "911" or "112".
List the service urns, corresponding to the emergency contacts, e.g., "urn:service:sos", a contact handle corresponding to it, and the list of local aliases identifying the emergency service, e.g., "911" or "112".
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 Lesser 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
A dial string, made up of the following characters: 0-9, A-D, P, X, '*' and '#'.
This is exactly as used in RFC 4967, except that:
P represents a short pause, X represents "wait for call completion", and the rest are the same as the corresponding DTMF_Event.
Sends the dial string on the channel.
The channel will send the dial string using appropriate means, such as RFC 4733 audio events or SIP INFO payload.
A dial string is being sent on this stream. The signal is provided so that UIs can indicate the fact that the channel is currently being used to send dialtones and any audio input from the user is not actually getting sent through the audio stream.
Sending the dial string on this stream has been stopped. The signal is provided for feedback indicating the fact that the channel is no longer used to send dialtones and audio input from the user can be streamed again.
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 Lesser 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
This interface extends the Text interface to support more general messages, including:
Although this specification supports formatted (rich-text) messages with unformatted alternatives, implementations SHOULD NOT attempt to send formatted messages until the Telepathy specification has also been extended to cover capability discovery for message formatting.
This interface also replaces
If this interface is present, clients that support it SHOULD
listen for the
A list of MIME types supported by this channel, with more preferred MIME types appearing earlier in the list. The list MAY include "*/*" to indicate that attachments with arbitrary MIME types can be sent. This list MUST NOT be empty, since all Messages implementations MUST accept messages containing a single "text/plain" part.
Some examples of how this property interacts with the
Flags indicating the level of support for message parts on this channel. They are designed such that setting more flags always implies that the channel has more capabilities.
If no flags are set, this indicates that messages may contain a single message part whose content-type is any of the types from SupportedContentTypes, possibly with some alternatives.
There is no flag indicating support for alternatives. This is because the SendMessage implementation can always accept messages containing alternatives, even if the underlying protocol does not, by deleting all alternatives except the first (most preferred) that is supported.
See
Part of a message's content. In practice, this mapping never
appears in isolation - messages are represented by a list of
An example of how a message might look, in a Python-like syntax:
[
{
'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
'message-sender': 42,
'message-sent': 1210067943,
'message-received': 1210067947,
'message-type': 0, # = Channel_Text_Message_Type_Normal
'pending-message-id': 437,
},
{ 'alternative': 'main',
'content-type': 'text/html',
'content': 'Here is a photo of my cat:<br />' +
'<img src="cid:catphoto" alt="lol!" />' +
'<br />Isn't it cute?',
},
{ 'alternative': 'main',
'content-type': 'text/plain',
'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?',
},
{ 'identifier': 'catphoto',
'content-type': 'image/jpeg',
'size': 101000,
'needs-retrieval': True,
},
]
The first part of the message contains "headers" which refer to the entire message.
It is an error for a connection manager to put keys referring to the message as a whole in the second or subsequent Message_Part, but clients MUST recover from this error by ignoring these keys in the second and subsequent parts.
Instead of representing messages as aa{sv} where the first dictionary is special (a dictionary of headers), we could have used a signature like (a{sv}aa{sv}) to separate out the headers and the body parts.
However, this would make access to the messages more awkward.
In Python, the syntax for access to a header field would remain
message[0]['message-type'], but access to a body
field in the second body part would change from
message[2]['content'] to message[1][1]['content']. In GLib,
the message would change from being a
GPtrArray(GHashTable) to being a
GValueArray(GHashTable, GPtrArray(GHashTable)) which is rather
inconvenient to dereference.
Well-known keys for the message as a whole, and the corresponding value types, include:
The second and subsequent parts contain the message's content, including plain text, formatted text and/or attached files.
It is an error for a connection manager to put keys referring to the message body in the first Message_Part; clients MUST recover from this error by ignoring these keys in first part.
In any group of parts with the same non-empty value for the "alternative" key (which represent alternative versions of the same content), more faithful versions of the intended message MUST come before less faithful versions (note that this order is the opposite of MIME "multipart/alternative" parts). Clients SHOULD display the first alternative that they understand.
Specifying the preference order means that if the underlying protocol doesn't support alternatives, the CM can safely delete everything apart from the first supported alternative when sending messages.
The order is the reverse of MIME because MIME's rationale for placing the "plainest" part first (legibility in pre-MIME UAs) does not apply to us, and placing the most preferred part first simplifies display (a client can iterate the message in order, display the first alternative that it understands, and skip displaying all subsequent parts with the same "alternative" key).
Clients SHOULD present all parts that are not redundant alternatives in the order they appear in this array, possibly excluding parts that are referenced by another displayed part. It is implementation-specific how the parts are presented to the user.
This allows CMs to assume that all parts are actually shown to the user, even if they are not explicitly referenced - we do not yet recommend formatted text, and there is no way for plain text to reference an attachment since it has no concept of markup or references. This also forces clients to do something sensible with messages that consist entirely of "attachments", with no "body" at all.
For instance, when displaying the above example, a client that understands the HTML part should display the JPEG image once, between the two lines "Here is a photo of my cat:" and "Isn't it cute?"; it may additionally present the image in some way for a second time, after "Isn't it cute?", or may choose not to.
A client that does not understand HTML, displaying the same message, should display the plain-text part, followed by the JPEG image.
Well-known keys for the second and subsequent parts, and the corresponding value types, include:
If present, this part of the message is an alternative for all other parts with the same value for "alternative". Clients SHOULD only display one of them (this is expected to be used for XHTML messages in a future version of this specification).
If omitted, this part is not an alternative for any other part.
Parts of a message MAY reference the group of alternatives as a whole (i.e. a reference to whichever of them is chosen) by treating this identifier as if it were the MIME Content-ID of a multipart/alternative part, and using the cid: URI scheme.
The MIME type of this part. See the documentation for ReceivedMessage for notes on the special status of "text/plain" parts.
Connection managers MUST NOT signal parts without a 'content-type' key; if a protocol provides no way to determine the MIME type, the connection manager is responsible for guessing it, but MAY fall back to "text/plain" for text and "application/octet-stream" for non-text.
Clients MUST ignore parts without a 'content-type' key, which are reserved for future expansion.
Delivery reports are also represented as messages, of type Channel_Text_Message_Type_Delivery_Report, with the Non_Text_Content flag in the Text interface.
Whenever a message of type Channel_Text_Message_Type_Delivery_Report is signalled for a delivery error report, Channel.Type.Text.SendError SHOULD also be emitted; whenever Channel.Type.Text.SendError is emitted by a channel which supports this interface, a message of type Channel_Text_Message_Type_Delivery_Report MUST also be emitted.
The corresponding message in the Messages interface MUST contain "headers" for the delivery report, as specified below, in its first Message_Part.
An identifier for the message to which this delivery report refers. MUST NOT be an empty string. Omitted if not available.
Clients may match this against the token produced by the SendMessage method and MessageSent signal. A status report with no token could match any sent message, and a sent message with an empty token could match any status report. If multiple sent messages match, clients SHOULD use some reasonable heuristic.
The message content, as defined by the Messages interface. Omitted if no content is available. Content MAY have been truncated, message parts MAY have been removed, and message parts MAY have had their content removed (i.e. the message part metadata is present, but the 'content' key is not).
Unlike in the Messages interface, content not visible in the value for this key cannot be retrieved by another means, so the connection manager SHOULD be more aggressive about including (possibly truncated) message content in the 'content' key.
The second and subsequent Message_Part dictionaries, if present, are a human-readable report from the IM service.
Clients MUST NOT attempt to send delivery reports using the SendMessage method in the Messages API, and connection managers MUST NOT allow this to be done. If support for sending delivery reports is later added, it will be part of this interface.
Some example delivery reports in a Python-like syntax (in which arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2}) follow.
b9a991bd-8845-4d7f-a704-215186f43bb4 for an unknown
reason
[{
# header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Permanently_Failed,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
}
# no body
]
[{ # header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Temporarily_Failed,
'delivery-error': Channel_Text_Send_Error_Offline,
'delivery-echo':
[{ # header of original message
'message-sender': 1,
'message-sent': 1210067943,
},
{ # body of original message
'content-type': 'text/plain',
'content': 'Hello, world!',
}]
],
# no body
]
b9a991bd-8845-4d7f-a704-215186f43bb4 to a contact
with handle 123, but that handle represents a contact who does not
actually exist
[{ # header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Permanently_Failed,
'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
'delivery-echo':
[{ # header of original message
'message-sender': 1,
'message-sent': 1210067943,
},
{ # body of original message
'content-type': 'text/plain',
'content': 'Hello, world!',
}]
],
},
{ # message from server (alternative in English)
'alternative': '404',
'content-type': 'text/plain',
'lang': 'en',
'content': 'I have no contact with that name',
},
{ # message from server (alternative in German)
'alternative': '404'.
'content-type': 'text/plain',
'lang': 'de',
'content', 'Ich habe keinen Kontakt mit diesem Namen',
}
]
b9a991bd-8845-4d7f-a704-215186f43bb4
[{
# header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Delivered,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
}
# no body
]
An opaque token used to identify sent messages. As a special case, the empty string indicates that there is no particular identification for a message.
CM implementations SHOULD use an identifier expected to be unique, such as a UUID, if possible.
Some protocols can only track a limited number of sent messages in a small message-ID space. As a result, clients MUST NOT assume that message tokens will not be re-used, and SHOULD use some reasonable heuristic to assign delivery reports to messages, such as matching on message content or timestamp (if available), or assuming that the delivery report refers to the most recent message with that ID.
Submit a message to the server for sending.
If this method returns successfully, the message has been submitted
to the server and the
This method MUST return before the MessageSent signal is emitted.
This means that the process sending the message is the first
to see the
If this method fails, message submission to the server has failed and no signal on this interface (or the Text interface) is emitted.
Provide a successful delivery report if possible, even if this is not the default for this protocol. Ignored if delivery reports are not possible on this protocol.
In some protocols, like XMPP, it is not conventional to request or send positive delivery notifications.
Delivery failure reports SHOULD always be sent, but if this flag is present, the connection manager MAY also try harder to obtain failed delivery reports or allow them to be matched to outgoing messages.
Signals that a message has been submitted for sending. This
MUST be emitted exactly once per emission of the
This signal allows a process that is not the caller of SendMessage to log sent messages. The double signal-emission provides compatibility with older clients. Clients supporting Messages should listen for Messages.MessageSent only (if the channel has the Messages interface) or Text.Sent only (otherwise).
The message content (see
If the connection manager can predict that the message will be altered during transmission, this argument SHOULD reflect what other contacts will receive, rather than being a copy of the argument to SendMessage (if the message is truncated, formatting or alternatives are dropped, etc., then the edited version SHOULD appear in this signal).
Flags affecting how the message was sent. The flags might be a subset of those passed to SendMessage if the caller requested unsupported flags.
The content of the requested parts. The keys in this mapping
are positions in the array of message parts; the values are
either of type 's' or 'ay' (UTF-8 text string, or byte array),
following the same rules as for the value of the 'content' key in
the
If the one of the requested part numbers was greater than zero but referred to a part that had no content (i.e. it had no 'content-type' key or no 'content' key), it is simply omitted from this mapping; this is not considered to be an error condition.
The status of a message as indicated by a delivery report.
If this enum is extended in future specifications, this should only be to add new, non-overlapping conditions (i.e. all failures should still be signalled as either Temporarily_Failed or Permanently_Failed). If additional detail is required (e.g. distinguishing between the various types of permanent failure) this will be done using additional keys in the Message_Part.
Interface defines a methods to managing skype group chat, which includes leave an existing peer-to-peer or group chat. Get/Set the group chat topic and get the update for topic change.
Method to leave a peer-to-peer or group chat, which means after leaving the chat participant can not join the chat again until some authorised chat member add him again, and participant will also lose all the chat history
Group chat topic received from the protocol or set by user interface
Handle of chat member, which changes the current chat topic
New topic received from the protocol
Signal indicate that ongoing group topic has been changed.
This interface provides access to the short-message-related properties on Text channels.
ISDN Address for default Short Message Service Centre.
Default duration while keep trying to deliver an SMS.
0 means defaul value used by Short Message Service Centre.
If true, then this channel is specifically created for receiving class 0 SMS.
Used to fuzzily match new channel with existing channels.
Interface for requesting that the channel uses appropriate privacy services as defined by RFC 3323, RFC 3325, and further specifications.
See Connection.Interface.Privacy for the list of well-known privacy services.
When privacy services "user" or "id" are requested, Connection Manager should use an anonymous identity for the channel. E.g., SIP Connection Managers should use URI <sip:anonymous@anonymous.invalid>.
The list of initially requested privacy services on the channel, used with Requests interface.
The list of requested privacy services on the channel.
Signal indicates that the list of requested privacy services have changed from their initial values.
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 Lesser 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
A list of vCard type parameters applicable to this field, with their values. The type parameter names, and any values that are case-insensitive in vCard, MUST be in lower case. For example, a contact's preferred home address would have parameters 'type=home' and 'type=pref'.
Characters which are required to be escaped in vCard type parameters should not be escaped in this list. For instance, a field "X-FOO;SEMICOLON=\;:bar" in a vCard would become ('x-foo', ['semicolon=;'], ['bar']) in this interface.
For unstructured vCard fields (such as 'fn', a formatted name field), a single-element array containing the field's value.
For structured fields (such as 'adr', an address field), an array corresponding to the semicolon-separated elements of the field (with empty strings for empty elements).
A vCard field with multiple comma-separated values, such as
'nickname', should be represented by several
Characters which are required to be escaped in vCard values, such as semi-colons and newlines, should not be escaped in this list (e.g. if a value contains a newline, the data passed over D-Bus should contain a literal newline character).
Represents one piece of information about a contact, as modelled by a single vCard field. Of the fields defined in RFC 2426, common examples include:
For example, the following vCard:
BEGIN:vCard
VERSION:3.0
FN:Wee Ninja
N;LANGUAGE=ja:Ninja;Wee;;;-san
ORG:Collabora, Ltd.;Human Resources\; Company Policy Enforcement
ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire
;CB2 1SJ;UK
TEL;TYPE=VOICE,WORK:+44 1223 362967, +44 7700 900753
EMAIL;TYPE=INTERNET,PREF:wee.ninja@collabora.co.uk
EMAIL;TYPE=INTERNET:wee.ninja@example.com
URL:http://www.thinkgeek.com/geektoys/plush/8823/
NICKNAME:HR Ninja,Enforcement Ninja
END:vCard
would be represented by (in Python-like syntax):
[
('fn', [], ['Wee Ninja']),
('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']),
('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']),
('adr', ['type=work','type=postal','type=parcel'],
['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']),
('tel', ['type=voice','type=work'], ['+44 1223 362967']),
('tel', ['type=voice','type=work'], ['+44 7700 900753']),
('email', ['type=internet','type=pref'], ['wee.ninja@collabora.co.uk']),
('email', ['type=internet'], ['wee.ninja@example.com']),
('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
('nickname', [], ['HR Ninja']),
('nickname', [], ['Enforcement Ninja'])
]
Can_Set, and may only be passed fields conforming to
A list of field specifications describing the kinds of fields which may
be passed to
For example, an implementation of XEP-0054, which defines a mapping of vCards to XML for use over XMPP, would set this property to the empty list. A protocol whose notion of contact information is one each of personal phone number, mobile phone number, location, email address and date of birth, with no attributes allowed on each piece of information, would set this property to (in Python-like syntax):
[
('tel', ['home'], Parameters_Mandatory, 1),
('tel', ['cell'], Parameters_Mandatory, 1),
('adr', [], Parameters_Mandatory, 1),
('bday', [], Parameters_Mandatory, 1),
('email', ['internet'], Parameters_Mandatory, 1),
]
A protocol which allows users to specify up to four phone numbers,
which may be labelled as personal and/or mobile, would set this
property to [ ('tel', ['home', 'cell'], 0, 4), ].
Studying existing IM protocols shows that in practice protocols allow either a very restricted set of fields (such as MSN, which seems to correspond roughly to the largest example above) or something mapping 1-1 to vCard (such as XMPP).
If present, exactly the parameters indicated must be set on this field; in the case of an empty list of parameters, this implies that parameters may not be used.
If absent, and the list of allowed parameters is non-empty, any (possibly empty) subset of that list may be used.
If absent, and the list of allowed parameters is empty, any parameters may be used.
An interface for requesting information about a contact on a given
connection. Information is represented as a list of
Interface for requesting that the connection uses appropriate privacy services as defined by RFC 3323, RFC 3325, and further specifications.
The well-known privacy services are defined as follows:
A request for unknown privacy service should fail only if "critical" is included in the list of requested services.
Client can request a channel-specific privacy services with Channel.Interface.Privacy and Connection.Interface.Requests.
The list of privacy services supported by the connection.
The list of requested privacy services on the connection.
Signal indicates that the list of requested privacy services have changed.
This interface extends the Messages interface to support store-and-forward messaging protocols like email or SMS.
A store-and-forward protocol stores the incoming message permanently either locally within ConnectionManager or on a network server. The messages get removed from the storage only when explicitly expunged.
A store-and-forward protocol using this interface MUST insert the key 'message-token' in the first part of the message with an unique id as its value. The clients use ExpungeMessages when they want to remove the message from the permanent storage.
A store-and-forward protocol MUST also insert the key 'stored-message-received' in the first part of the message if the message is stored permanently.
If the message is presented first time to the client, the value of 'stored-message-received' should be identical to the value of 'message-received'. If the message might have been presented earlier, the value of 'stored-message-received' MAY differ from the value of the 'message-received' key.
If the message has been presented earlier during the Connection lifetime, a key 'rescued' with boolean value True SHOULD be present in the first part of the message.
A list of 'message-token' values for permanently stored incoming messages that have not been expunged. Its items can be removed using ExpungeMessages.
Unless expunged, the permanently stored messages may be presented to the clients again when the Connection restarts.
Ask server to deliver again stored messages.
Expunge messages from permanent storage.
Try to pause or continue reception.
True if client has run out of memory to store the incoming messages. The protocol will then pause receiving new messages as if it had run out of storage space itself.
If false the protocol will try to resume receiving new messages.
Please note that most protocols, including SMS, try eventually to resume receiving SMSs even after the client has indicated that it is out of memory.
This interface provides access to the properties specific to Telepathy-Ring.
International Mobile Subscriber Identifier.
Privacy services in use (id).
ISDN Address for Short Message Service Centre.
Duration while keep trying to deliver an SMS.
0 means default value.
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 Lesser 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
This interface contains functionality which we intend to incorporate
into the
The rationale is the same as for
If set to true in a channel request that will create a new channel,
the connection manager should immediately attempt to establish an
audio stream to the remote contact, making it unnecessary for the
client to call
If this property, or InitialVideo, is passed to EnsureChannel (as opposed to CreateChannel), the connection manager SHOULD ignore these properties when checking whether it can return an existing channel as suitable; these properties only become significant when the connection manager has decided to create a new channel.
If true on a requested channel, this indicates that the audio stream has already been requested and the client does not need to call RequestStreams, although it MAY still do so.
If true on an unrequested (incoming) channel, this indicates that
the remote contact initially requested an audio stream; this does
not imply that that audio stream is still active (as indicated by
This property is immutable (cannot change), and therefore SHOULD
appear wherever immutable properties are reported, e.g.
This reduces D-Bus round trips.
Connection managers capable of signalling audio calls to contacts
SHOULD include a channel class in
Not all protocols support signalling video calls, and it would be possible (although unlikely) to have a protocol where only video, and not audio, could be signalled.
Connection managers that support the
Not all clients support video calls, and it would also be possible (although unlikely) to have a client which could only stream video, not audio.
Clients that are willing to receive audio and/or video calls
SHOULD include the following filters if calling
Connection managers for protocols with capability discovery, like XMPP, need this information to advertise the appropriate capabilities for their protocol.
If { ChannelType = StreamedMedia } is passed to SetSelfCapabilities, but no more specific channel class for audio or video has been passed to that method (in the presence of a ChannelDispatcher, this would mean that there is at least one client with that channel class in its HandlerChannelFilter, but no installed client has the more specific channel classes in its HandlerChannelFilter), then the connection manager SHOULD advertise support for every content type (audio or video) that it supports.
This lowers the "barrier to entry" by allowing a simple client to say merely that it supports streamed media at all.
The same as
In particular, note that if this property is false, this does not imply that an active video stream has not been added, only that no video stream was active at the time the channel appeared.
This property is the correct way to discover whether connection managers, contacts etc. support video calls; it appears in capabilities structures in the same way as InitialAudio.
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 Lesser 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
A channel type for searching server-stored user directories. A new channel should be requested by a client for each search attempt, and closed when the search is completed or the required result has been found in order to free unused handles.
Before searching, the
Not_Started to In_Progress. As results are
returned by the server, the
Completed. If the search fails after Search
has been called, the state will change to Failed. A
running search can be cancelled by calling
If the protocol supports limiting the number of results returned by a
search and subsequently requesting more results, after
More_Available. Clients may
call
The client should call the channel's
Each channel can only be used for a single search; a new channel should be requested for each subsequent search. Connection managers MUST support multiple ContactSearch channels being open at once (even to the same server, if applicable).
It does not make sense to request this channel type using
A contact search channel that is already in use for a different search isn't useful.
Failed, the name of a D-Bus error
describing what went wrong. Otherwise, the empty string.
Additional information about the state transition, which may include the following well-known keys:
This argument allows for future extensions. For instance,
if moving to state Failed because the server
rejected one of our search terms, we could define a key
that indicates which terms were invalid.
Emitted when the
Not_Started → In_ProgressIn_Progress → More_AvailableMore_Available → In_ProgressIn_Progress → CompletedIn_Progress → FailedAny of the following search keys, with the indicated result for the search:
nickname would search nicknames, and
tel would search any available phone number,
regardless of its work/home/mobile/... status).;" and a
type=..."tel;type=mobile).x-telepathy-identifierx-jabber) or not exist at all.
x-genderx-n-familyn).
x-n-givenn).
x-n-family.
x-onlinex-adr-localityadr).
If supported by the protocol, the maximum number of results that
should be returned, where 0 represents no limit. If the
protocol does not support limiting results, this should be
0.
For example, if the terms passed to
2, the search service SHOULD only return Antonius
and Bridget.
This property cannot change during the lifetime of the channel.
This property SHOULD be in the Allowed_Properties of a
0 as the default if possible, or a protocol-specific
sensible default otherwise.
More_Available move back to state In_Progress
and continue listing up to More_Available.
Stop the current search. This may not be called while the
org.freedesktop.Telepathy.Errors.Cancelled.
Calling this method on a search in state Completed or Failed succeeds, but has no effect.
Specifying Stop to succeed when the search has finished means that
clients who call Stop just before receiving
Depending on the protocol, the connection manager may not be able to prevent the server from sending further results after this method returns; if this is the case, it MUST ignore any further results.
An array of fields representing information about this
contact, in the same format used in the
This array SHOULD include the x-telepathy-identifier
field, whose values matches the result of calling
UIs will most likely want to show the identifier to the user; while they could do this by inspecting the signalled handle, including it in this signal is cheap and removes a roundtrip to look it up.
For protocols which support searching for contacts on multiple servers with different DNS names (like XMPP), the DNS name of the server being searched by this channel, e.g. "characters.shakespeare.lit". Otherwise, the empty string.
XEP 0055 defines a mechanism for XMPP clients to search services of their choice for contacts, such as users.jabber.org (the "Jabber User Directory").
This property cannot change during the lifetime of the channel.
This property SHOULD be in the Allowed_Properties of a
This allows a client to perform searches on a protocol it knows nothing about without requiring the user to guess a valid server's hostname.
Interface for controlling muting of embedded audio stream.
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 Lesser 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
This interface extends the Text and Messages interfaces with improved sent-message status reporting.
This interface replaces Text.SendError, adding support for protocols where the message content is not echoed back to the sender on failure. It also adds support for receiving positive acknowledgements, and uses the Messages queue for state-recovery (ensuring that incoming delivery reports are not lost if there is not currently a process handling them).
If this interface and the Messages interface are both present, clients that support it SHOULD listen for the MessageReceived signal to get delivery reports, and ignore the SendError signal on the Text interface.
Delivery reports appear as messages of type Channel_Text_Message_Type_Delivery_Report in the Text and Messages interfaces. The message in the Text interface SHOULD have the Non_Text_Content flag.
Whenever a message of type Channel_Text_Message_Type_Delivery_Report is signalled for a delivery error report, Channel.Type.Text.SendError SHOULD also be emitted; whenever Channel.Type.Text.SendError is emitted by a channel which supports this interface, a message of type Channel_Text_Message_Type_Delivery_Report MUST also be emitted.
The corresponding message in the Messages interface MUST contain "headers" for the delivery report, as specified below, in its first Message_Part.
An identifier for the message to which this delivery report refers. MUST NOT be an empty string. Omitted if not available.
Clients may match this against the token produced by the SendMessage method and MessageSent signal on the Messages interface. A status report with no token could match any sent message, and a sent message with an empty token could match any status report. If multiple sent messages match, clients SHOULD use some reasonable heuristic.
The message content, as defined by the Messages interface. Omitted if no content is available. Content MAY have been truncated, message parts MAY have been removed, and message parts MAY have had their content removed (i.e. the message part metadata is present, but the 'content' key is not).
Unlike in the Messages interface, content not visible in the value for this key cannot be retrieved by another means, so the connection manager SHOULD be more aggressive about including (possibly truncated) message content in the 'content' key.
The second and subsequent Message_Part dictionaries, if present, are a human-readable report from the IM service.
It is an error for this interface to appear on channels of type other than Text, or on Text channels without the Messages interface. Clients MUST recover from this error by ignoring the presence of the DeliveryReporting interface.
Some example delivery reports in a Python-like syntax (in which arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2}) follow.
b9a991bd-8845-4d7f-a704-215186f43bb4 for an unknown
reason
[{
# header
'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Permanently_Failed,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
}
# no body
]
[{ # header
'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Temporarily_Failed,
'delivery-error': Channel_Text_Send_Error_Offline,
'delivery-echo':
[{ # header of original message
'message-sender': 1,
'message-sent': 1210067943,
},
{ # body of original message
'type': 'text/plain',
'content': 'Hello, world!',
}]
],
# no body
]
b9a991bd-8845-4d7f-a704-215186f43bb4 to a contact
with handle 123, but that handle represents a contact who does not
actually exist
[{ # header
'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Permanently_Failed,
'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
'delivery-echo':
[{ # header of original message
'message-sender': 1,
'message-sent': 1210067943,
},
{ # body of original message
'type': 'text/plain',
'content': 'Hello, world!',
}]
],
},
{ # message from server (alternative in English)
'alternative': '404',
'type': 'text/plain',
'lang': 'en',
'content': 'I have no contact with that name',
},
{ # message from server (alternative in German)
'alternative': '404'.
'type': 'text/plain',
'lang': 'de',
'content', 'Ich habe keinen Kontakt mit diesem Namen',
}
]
b9a991bd-8845-4d7f-a704-215186f43bb4
[{
# header
'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Delivered,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
}
# no body
]
The status of a message as indicated by a delivery report.
If this enum is extended in future specifications, this should only be to add new, non-overlapping conditions (i.e. all failures should still be signalled as either Temporarily_Failed or Permanently_Failed). If additional detail is required (e.g. distinguishing between the various types of permanent failure) this will be done using additional keys in the Message_Part.
Request that a delivery report is sent for the specified pending incoming message. Delivery reports cannot currently be sent for messages that have already been acknowledged.
The only use-case I can see for delivery reports on non-pending messages is a "read receipt" like in email's RFC 3798. Delivery reports on non-pending messages will also need a more complex API.
If they turn out to be needed, we can add a method like SendDeliveryReportByContent(aa{sv}: message) and add a flag to Delivery_Reporting_Support_Flags indicating that this method is implemented.
Clients SHOULD NOT attempt to send delivery reports that are not indicated to be supported using the DeliveryReportingSupport property.
Clients MUST NOT attempt to send delivery reports using the SendMessage method in the Messages API, and connection managers MUST NOT allow this to be done.
Interface for indicating that the channel is connected to an emergency answering point.
The emergency answering points are identified using a 'urn:service:sos' service urn, specified by RFC 5031.
The service urn corresponding to the emergency contact, e.g., "urn:service:sos.fire".
The generic 'sos' service urn urn:service:sos indicates an unknown or generic public safety answering point (PSAP).
An error indicates that the call is not considered as an emergency call by the connection manager.
The service urn corresponding to the emergency contact, e.g., "urn:service:sos.fire", or empty if the call is not connected to a well-known emergency service.
The generic 'sos' service urn urn:service:sos indicates an unknown or generic public safety answering point (PSAP).
The service urn corresponding to the emergency contact, e.g., "urn:service:sos.fire".
The generic 'sos' service urn urn:service:sos indicates an unknown or generic public safety answering point (PSAP).
The service urn corresponding to the initial contact, e.g., "urn:service:sos.fire", or empty if the call is not targeted to a well-known emergency service.
This property is used in channel properties to indicate that the channel target is a well-known emergency service. Please note that the network may forward calls to other contacts also to the emergency desk. CM may indicate such calls with EmergencyServiceChanged signal.
Interface for creating centralized conference with streamed media channels.
This interface assumes that you have a centralized conferencing server, either hosted locally or controlled within the network. The conference model assumes that you first set up connection to each conferencing party and then refer the parties to the conferencing server.
Not implemented. Going away in next release.
This interface defines a requestable channel property that can be used to persistently identify the channel beyond connection object lifetimes.
The identifier for the channel that is persistent. Channel objects created at different times, and possibly on different Connection object instances, and having the same value for this property, represent the same underlying communication channel in the protocol implementation.
The identifier MUST be unique across all connections for one particular protocol.
This interface extends the core Connection interface to provide credit balance information.
As an example, property values of Balance=1234, BalanceScale=2 and Currency=USD, can be used by UI to format the credit display like "12.34 USD".