Interface ChannelRequest.Interface.Hints.DRAFT

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

Signals

SucceededWithChannel (o: Connection, a{sv}: Connection_Properties, o: Channel, a{sv}: Channel_Properties)

Properties

Hints a{sv} Read only
WARNING: This interface is a staging area for future functionality 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.
Objects implementing this interface must also implement:

Description

This interface contains functionality which we intend to incorporate into the ChannelRequest interface in future. It should be considered to be conceptually part of the core ChannelRequest interface, but without API or ABI guarantees.

Signals

(Permalink)

SucceededWithChannel (o: Connection, a{sv}: Connection_Properties, o: Channel, a{sv}: Channel_Properties)

Changed in 0.21.UNRELEASED. (Properties arguments added)

Parameters

  • Connection — o

    • The Connection owning the channel.

  • Connection_Properties — a{sv} (Qualified_Property_Value_Map)

    • A subset of the Connection's properties, currently unused. This parameter may be used in future.

  • Channel — o

    • The channel which has been created.

  • Channel_Properties — a{sv} (Qualified_Property_Value_Map)

    • The same immutable properties of the Channel that would appear in a NewChannels signal.

Variant of the Succeeded signal allowing to get the channel which has been created.

Properties

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

Hints — a{sv}

Read only
Added in 0.19.12. (as draft)

A dictionary of metadata provided by the channel requester, which the handler and other clients MAY choose to interpret. Currently no standard keys are defined; clients MAY choose to use platform-specific keys for their own purposes, but MUST ignore unknown keys and MUST cope with expected keys being missing. Clients SHOULD namespace hint names by having them start with a reversed domain name, in the same way as D-Bus interface names.

Rationale:
This property might be used to pass a contact ID for a telephone number shared between two contacts from the address book to the call UI, so that if you try to call “Mum”, the call UI knows this rather than having to guess or show “Calling Mum or Dad”. The format of these contact IDs would be platform-specific, so we leave the definition of the dictionary entry up to the platform in question. But third-party channel requesters might not include the contact ID, so the call UI has to be able to deal with it not being there.

The channel dispatcher does not currently interpret any of these hints: they are solely for communication between cooperating clients. If hints that do affect the channel dispatcher are added in future, their names will start with an appropriate reversed domain name (e.g. org.freedesktop.Telepathy for hints defined by this specification, or an appropriate vendor name for third-party plugins).

This property may be set when the channel request is created, and can never change. Since it is immutable, it SHOULD be included in the dictionary of properties passed to AddRequest by the ChannelDispatcher.