Methods
| CreateChannelWithHints | (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler, a{sv}: Hints) | → | o: Request | |
| EnsureChannelWithHints | (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler, a{sv}: Hints) | → | o: Request |
Properties
| SupportsRequestHints | b | Read only |
Description
This interface contains functionality which we intend to incorporate into the ChannelDispatcher interface in future. It should be considered to be conceptually part of the core ChannelDispatcher interface, but without API or ABI guarantees.
Methods
CreateChannelWithHints (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler, a{sv}: Hints) → o: Request
Parameters
- Account — o
- Requested_Properties — a{sv} (Qualified_Property_Value_Map)
- User_Action_Time — x (User_Action_Timestamp)
- Preferred_Handler — s (DBus_Well_Known_Name)
- Hints — a{sv}
A dictionary containing desirable properties. This has the same semantics as the corresponding parameter to Connection.Interface.Requests.CreateChannel.
Certain properties will not necessarily make sense in this dictionary: for instance, TargetHandle can only be given if the requester is able to interact with a Connection to the desired account.
The time at which user action occurred, or 0 if this channel
request is for some reason not involving user action.
The UserActionTime
property will be set to this value, and it will eventually be
passed as the User_Action_Time parameter of HandleChannels.
Either the well-known bus name (starting with
org.freedesktop.Telepathy.Client.)
of the preferred handler for this
channel, or an empty string to indicate that any handler would be
acceptable. The channel dispatcher SHOULD dispatch as many as
possible of the resulting channels (ideally, all of them)
to that handler—irrespective of whether that handler's HandlerChannelFilter
matches the channel—and SHOULD remember the preferred handler
so it can try to dispatch subsequent channels in the same bundle
to the same handler.
Rationale:
This must be the well-known bus name, not the unique name, to ensure that all handlers do indeed have the Client API, and the Client object on the handler can be located easily.
This is partly so the channel dispatcher can call HandleChannels on it, and partly so the channel dispatcher can recover state if it crashes and is restarted.
The filter should be disregarded for ease of use of this interface: clients will usually use this argument to request channels be sent to themself, and this should trump the filter not matching. This also allows a client to become the handler for a channel produced by one of its own requests, while not being a candidate to handle other channels of that type.
If this is a well-known bus name and the handler has the Requests interface, the channel dispatcher SHOULD call AddRequest on that Handler after this method has returned.
Rationale:
This ordering allows a Handler which calls CreateChannel with itself as the preferred handler to associate the call to AddRequest with that call.
This is copied to the ChannelRequest that is returned, as the PreferredHandler property.
Additional information about the channel request, which will be used as the value for the resulting request's Hints property, but will not otherwise be interpreted by the Channel Dispatcher.
Rationale:
See the Hints property's documentation for rationale.
Returns
- Request — o
Start a request to create a channel. This initially just creates a ChannelRequest object, which can be used to continue the request and track its success or failure.
Rationale:
The request can take a long time - in the worst case, the channel dispatcher has to ask the account manager to put the account online, the account manager has to ask the operating system to obtain an Internet connection, and the operating system has to ask the user whether to activate an Internet connection using an on-demand mechanism like dialup.
This means that using a single D-Bus method call and response to represent the whole request will tend to lead to that call timing out, which is not the behaviour we want.
If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until ChannelRequest.Proceed is called, at which point ChannelRequest.Failed is emitted with an appropriate error.
Rationale:
This means there's only one code path for errors, apart from InvalidArgument for "that request makes no sense".
It also means that the request will proceed if the account is enabled after calling CreateChannel, but before calling Proceed.
Possible Errors
- Invalid Argument
org.freedesktop.Telepathy.Client.,
the Account does not exist, or one of the Requested_Properties
is invalid
EnsureChannelWithHints (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler, a{sv}: Hints) → o: Request
Parameters
- Account — o
- Requested_Properties — a{sv} (Qualified_Property_Value_Map)
- User_Action_Time — x (User_Action_Timestamp)
- Preferred_Handler — s (DBus_Well_Known_Name)
- Hints — a{sv}
A dictionary containing desirable properties. This has the same semantics as the corresponding parameter to Connection.Interface.Requests.EnsureChannel.
Certain properties will not necessarily make sense in this dictionary: for instance, TargetHandle can only be given if the requester is able to interact with a Connection to the desired account.
The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.
This parameter is used in the same way as the corresponding parameter to CreateChannelWithHints.
Either the well-known bus name (starting with
org.freedesktop.Telepathy.Client.)
of the preferred handler for this
channel, or an empty string to indicate that any handler would be
acceptable. The behaviour and rationale are the same as for the
corresponding parameter to
CreateChannelWithHints, except
as noted here.
If any new channels are created in response to this
request, the channel dispatcher SHOULD dispatch as many as
possible of the resulting channels (ideally, all of them)
to that handler, and SHOULD remember the preferred handler
so it can try to dispatch subsequent channels in the same bundle
to the same handler. If the requested channel already exists (that
is, Connection.Interface.Requests.EnsureChannel
returns Yours=False) then the channel dispatcher
SHOULD re-dispatch the channel to its existing handler, and MUST
NOT dispatch it to this client (unless it is the existing handler);
the request is still deemed to have succeeded in this case.
Rationale:
An address book application, for example, might call EnsureChannel
to ensure that a text channel with a particular contact is
displayed to the user; it does not care whether a new channel was
made. An IM client might call EnsureChannel
in response to the user double-clicking an entry in the contact
list, with itself as the Preferred_Handler; if the
user already has a conversation with that contact in another
application, they would expect the existing window to be
presented, rather than their double-click leading to an error
message. So the request should succeed, even if its
Preferred_Handler is not used.
Returns
- Request — o
Start a request to ensure that a channel exists, creating it if necessary. This initially just creates a ChannelRequest object, which can be used to continue the request and track its success or failure.
If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until ChannelRequest.Proceed is called, at which point ChannelRequest.Failed is emitted with an appropriate error.
Rationale:
The rationale is as for CreateChannel.
Possible Errors
- Invalid Argument
org.freedesktop.Telepathy.Client.,
the Account does not exist, or one of the Requested_Properties
is invalid
Properties
SupportsRequestHints — b
True, the channel dispatcher is new enough to support
CreateChannelWithHints and
EnsureChannelWithHints, in addition
to the older CreateChannel
and EnsureChannel.
methods. If False or missing, only the metadata-less
variants are supported.