Protocol.I.Addressing.DRAFT — Telepathy D-Bus Interface Specification

# Interface Protocol.Interface.Addressing.DRAFT

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

### Methods

NormalizeVCardAddress | (s: VCard_Field, s: VCard_Address) | → | s: Normalized_VCard_Address |
NormalizeURI | (s: URI) | → | s: Normalized_URI |

### Properties

AddressableVCardFields | as | Read only |  |
AddressableURISchemes | as | Read only |  |

WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Added in 0.19.12. (as draft)

### Description

An interface for protocols that support multiple forms of addressing contacts, for example through vCard addresses and URIs.

If the ConnectionManager has a `.manager` file, and it supports this interface, the interface's immutable properties must be represented in the file; the representation is described as part of the documentation for each property.

For instance, a SIP connection manager might have the following lines in the `.manager` file.

    [Protocol sip]
    AddressableVCardFields=tel;x-sip;
    AddressableURISchemes=tel;sip;

# Methods

(Permalink)

## NormalizeVCardAddress (s: VCard_Field, s: VCard_Address) → s: Normalized_VCard_Address

### Parameters

- VCard_Field — s
The vCard field of the address we are normalizing. The field name SHOULD be in lower case, and MUST appear in AddressableVCardFields.
- VCard_Address — s
The address to normalize.

### Returns

- Normalized_VCard_Address — s
The vCard address, normalized as much as possible.

Attempt to normalize the given vCard address. Where possible, this SHOULD return an address that would appear in the `org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/addresses` attribute for a contact on a connected Connection.

If full normalization requires network activity or is otherwise impossible to do without a Connection, this method SHOULD perform a best-effort normalization.

An example would be a vCard TEL field with a formatted number in the form of `+1 (206) 555 1234`, this would be normalized to `+12065551234`.

This method MAY simply raise NotImplemented on some protocols, if it has no use.

### Possible Errors

- Not Implemented
The vCard field is not supported (it is not in AddressableVCardFields).
- Invalid Argument
The address is syntactically incorrect.

(Permalink)

## NormalizeURI (s: URI) → s: Normalized_URI

### Parameters

- URI — s
The URI to normalize. The URI's scheme (i.e. the part before the first colon) MUST appear in AddressableURISchemes.

### Returns

- Normalized_URI — s
A URI, normalized as much as possible.

Attempt to normalize the given contact URI. Where possible, this SHOULD return an address that would appear in the `org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/uris` attribute for a contact on a connected Connection.

If full normalization requires network activity or is otherwise impossible to do without a Connection, this method SHOULD perform a best-effort normalization.

Example: `xmpp:eitan@EXAMPLE.COM` would be normalized to `xmpp:eitan@example.com`.

This method MAY simply raise NotImplemented on some protocols, if it has no use.

### Possible Errors

- Not Implemented
The URI scheme is not supported (it is not in AddressableURISchemes).
- Invalid Argument
The URI is syntactically incorrect.

# Properties

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

## AddressableVCardFields — as

Read only

The vCard fields that can be used to request a contact with normalized to lower case. If the `URL` vCard field is addressable, a colon, followed by the supported URI schemes will be concatenated.

For example: `["tel", "x-sip"]`.

The `url` vCard field MUST NOT appear here; see AddressableURISchemes instead.

##### Rationale:

In practice, protocols have a limited set of URI schemes that make sense to resolve as a contact.

This property should only be used when the connection is offline. When it is connected the addressable fields should be retrieved from the Requests.RequestableChannelClasses's TargetVCardField fixed-property instead.

Connection managers with a `.manager` file MUST cache this property in the protocol's section of the `.manager` file if it is non-empty, using the key `AddressableVCardFields`. The corresponding value is a list of strings, each followed with a semicolon and in the syntax of the "localestring" type from the Desktop Entry Specification.

Well-known vCard fields:

`tel`
  The TEL vCard field. Used for phone numbers.
`x-sip`
  The X-SIP vCard field. Used for SIP addresses.
`x-aim`
  The X-AIM vCard field. Used for AIM user IDs.
`x-icq`
  The X-ICQ vCard field. Used for ICQ UINs.
`x-skype`
  The X-SKYPE vCard field. Used for Skype user names or telephone numbers. There is also a X-SKYPE-USERNAME field, but for Telepathy purposes, `x-skype` is preferred
`x-groupwise`
  The X-GROUPWISE vCard field. Used for Groupwise contacts.
`x-gadugadu`
  The X-GADUGADU vCard field. Used for Gadu-Gadu contacts.
`x-jabber`
  The X-JABBER vCard field. Used for XMPP JIDs.
`x-msn`
  The X-MSN vCard field. Used for MSN contacts.
`x-yahoo`
  The X-YAHOO vCard field. Used for Yahoo! IDs.

(Permalink)

## AddressableURISchemes — as

Read only

The URI schemes that are supported by this protocol.

For example: `["tel", "sip"]`.

This property should only be used when the connection is offline. When it is connected the addressable URI schemes should be retrieved from the Requests.RequestableChannelClasses's TargetURIScheme fixed-property instead.

Connection managers with a `.manager` file MUST cache this property in the protocol's section of the `.manager` file if it is non-empty, using the key `AddressableURISchemes`. The corresponding value is a list of strings, each followed with a semicolon and in the syntax of the "localestring" type from the Desktop Entry Specification.

Well-known URI schemes:

`sip`
  SIP protocol. For example: `sip:julien@example.com`.
`sips`
  Secure (encrypted) SIP protocol. For example: `sips:julien@example.com`.
`tel`
  Used for telephone numbers. For example: `tel:+12065551234`.
`xmpp`
  XMPP protocol. For example: `xmpp:julien@example.com`.
`msnim`
  For the purposes of Protocol.Interface.Addressing.DRAFT, Connection.Interface.Addressing.DRAFT, and Channel.Interface.Addressing.DRAFT, the verb part is ignored, and SHOULD be `add`; the `contact` field in the query string is used to identify the contact. For example: `msnim:add?contact=julien`.
`aim`
  For the purposes of Protocol.Interface.Addressing.DRAFT, Connection.Interface.Addressing.DRAFT, and Channel.Interface.Addressing.DRAFT, the verb part is ignored, and SHOULD be `addbuddy`; the `screenname` field in the query string is used to identify the contact. For example: `aim:addbuddy?screenname=julien`.
`skype`
  Skype protocol. For example: `skype:julien`.
`ymsgr`
  For the purposes of Protocol.Interface.Addressing.DRAFT, Connection.Interface.Addressing.DRAFT, and Channel.Interface.Addressing.DRAFT, the verb part is ignored, and SHOULD be `addfriend`; the query string is used to identify the contact. For example: `ymsgr:addfriend?julien`.
`gg`
  Gadu-Gadu protocol. For example: `gg:julien`.