TpClient

typedef struct _TpClient TpClient;

Each client to which the ChannelDispatcher can send channels must implement the Client interface. This object represents such a client, and is mainly useful in the implementation of the ChannelDispatcher itself.

This proxy is usable but very incomplete: accessors for D-Bus properties will be added in a later version of telepathy-glib, along with a mechanism similar to tp_connection_call_when_ready().

Many operations performed on a Client are done via D-Bus properties. Until convenience methods for this are implemented, use of the generic tp_cli_dbus_properties_call_get_all() and tp_cli_dbus_properties_call_set() methods is recommended.

Since 0.7.32

TpClientClass

typedef struct {
} TpClientClass;

The class of a TpClient.

tp_client_init_known_interfaces ()

void                tp_client_init_known_interfaces     (void);

Ensure that the known interfaces for TpClient have been set up. This is done automatically when necessary, but for correct overriding of library interfaces by local extensions, you should call this function before calling tp_proxy_or_subclass_hook_on_interface_add() with first argument TP_TYPE_CLIENT.

Since 0.7.32

tp_cli_client_observer_callback_for_observe_channels ()

void                (*tp_cli_client_observer_callback_for_observe_channels)
                                                        (TpClient *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a ObserveChannels method call succeeds or fails.

tp_cli_client_observer_call_observe_channels ()

TpProxyPendingCall * tp_cli_client_observer_call_observe_channels
                                                        (TpClient *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Account,
                                                         const gchar *in_Connection,
                                                         const GPtrArray *in_Channels,
                                                         const gchar *in_Dispatch_Operation,
                                                         const GPtrArray *in_Requests_Satisfied,
                                                         GHashTable *in_Observer_Info,
                                                         tp_cli_client_observer_callback_for_observe_channels callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a ObserveChannels method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the channel dispatcher when channels in which the observer has registered an interest are announced in a <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> signal.</p> <p>If the same NewChannels signal announces some channels that match the filter, and some that do not, then only a subset of the channels (those that do match the filter) are passed to this method.</p> <p>If the channel dispatcher will split up the channels from a single NewChannels signal and dispatch them separately (for instance because no installed Handler can handle all of them), it will call ObserveChannels several times.</p> <p>The observer MUST NOT return from this method call until it is ready for a handler for the channel to run (which may change the channel's state).</p> <tp:rationale> <p>The channel dispatcher must wait for observers to start up, to avoid the following race: text channel logger (observer) gets ObserveChannels, text channel handler gets <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> channel handler starts up faster and acknowledges messages, logger never sees those messages.</p> </tp:rationale> <p>The channel dispatcher SHOULD NOT change its behaviour based on whether this method succeeds or fails: there are no defined D-Bus errors for this method, and if it fails, this only indicates that an Observer is somehow broken.</p> <tp:rationale> <p>The expected error response in the channel dispatcher is to log a warning, and otherwise continue as though this method had succeeded.</p> </tp:rationale>

tp_cli_client_handler_callback_for_handle_channels ()

void                (*tp_cli_client_handler_callback_for_handle_channels)
                                                        (TpClient *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a HandleChannels method call succeeds or fails.

tp_cli_client_handler_call_handle_channels ()

TpProxyPendingCall * tp_cli_client_handler_call_handle_channels
                                                        (TpClient *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Account,
                                                         const gchar *in_Connection,
                                                         const GPtrArray *in_Channels,
                                                         const GPtrArray *in_Requests_Satisfied,
                                                         guint64 in_User_Action_Time,
                                                         GHashTable *in_Handler_Info,
                                                         tp_cli_client_handler_callback_for_handle_channels callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a HandleChannels method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the channel dispatcher when this client should handle these channels, or when this client should present channels that it is already handling to the user (e.g. bring them into the foreground).</p> <tp:rationale> <p>Clients are expected to know what channels they're already handling, and which channel object path corresponds to which window or tab. This can easily be done using a hash table keyed by channels' object paths.</p> </tp:rationale> <p>This method can raise any D-Bus error. If it does, the handler is assumed to have failed or crashed, and the channel dispatcher MUST recover in an implementation-specific way; it MAY attempt to dispatch the channels to another handler, or close the channels.</p> <p>If closing the channels, it is RECOMMENDED that the channel dispatcher attempts to close the channels using <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>, but resorts to calling <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref> (if available) or ignoring the channel (if not) if the same handler repeatedly fails to handle channels.</p> <p>After HandleChannels returns successfully, the client process is considered to be responsible for the channel until it its unique name disappears from the bus.</p> <tp:rationale> <p>If a process has multiple Client bus names - some temporary and some long-lived - and drops one of the temporary bus names in order to reduce the set of channels that it will handle, any channels that it is already handling should remain unaffected.</p> </tp:rationale>

tp_cli_client_interface_requests_callback_for_add_request ()

void                (*tp_cli_client_interface_requests_callback_for_add_request)
                                                        (TpClient *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a AddRequest method call succeeds or fails.

tp_cli_client_interface_requests_call_add_request ()

TpProxyPendingCall * tp_cli_client_interface_requests_call_add_request
                                                        (TpClient *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Request,
                                                         GHashTable *in_Properties,
                                                         tp_cli_client_interface_requests_callback_for_add_request callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a AddRequest method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the ChannelDispatcher to indicate that channels have been requested, and that if the request is successful, they will probably be handled by this Handler. The ChannelDispatcher SHOULD only call this method on one handler per request.</p> <tp:rationale> <p>This allows the UI to start preparing to handle the channels in advance (e.g. render a window with an &quot;in progress&quot; message), improving perceived responsiveness.</p> <p>The use of &quot;probably&quot; is because you can't necessarily tell from a channel request which handler will handle particular channels. A reasonable heuristic would be to match the request against the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>, and respect the preferred handler (if any).</p> </tp:rationale> <p>If the request succeeds and is given to the expected Handler, the Requests_Satisfied parameter to <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> can be used to match the channel to a previous AddRequest call.</p> <tp:rationale> <p>This lets the UI direct the channels to the window that it already opened.</p> </tp:rationale> <p>If the request fails, the expected handler is notified by the channel dispatcher calling its <tp:member-ref>RemoveRequest</tp:member-ref> method.</p> <tp:rationale> <p>This lets the UI close the window or display the error.</p> </tp:rationale> <p>The channel dispatcher SHOULD remember which handler was notified, and if the channel request succeeds, it SHOULD dispatch the channels to the expected handler, unless the channels do not match that handler's <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>. If the channels are not dispatched to the expected handler, the handler that was expected is notified by the channel dispatcher calling its <tp:member-ref>RemoveRequest</tp:member-ref> method with the NotYours error.</p> <tp:rationale> <p>Expected handling is for the UI to close the window it previously opened.</p> </tp:rationale> <p>Handlers SHOULD NOT return an error from this method; errors returned from this method SHOULD NOT alter the channel dispatcher's behaviour.</p> <tp:rationale> <p>Calls to this method are merely a notification.</p> </tp:rationale>

tp_cli_client_interface_requests_callback_for_remove_request ()

void                (*tp_cli_client_interface_requests_callback_for_remove_request)
                                                        (TpClient *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a RemoveRequest method call succeeds or fails.

tp_cli_client_interface_requests_call_remove_request ()

TpProxyPendingCall * tp_cli_client_interface_requests_call_remove_request
                                                        (TpClient *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Request,
                                                         const gchar *in_Error,
                                                         const gchar *in_Message,
                                                         tp_cli_client_interface_requests_callback_for_remove_request callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a RemoveRequest method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the ChannelDispatcher to indicate that a request previously passed to <tp:member-ref>AddRequest</tp:member-ref> has failed and should be disregarded.</p> <p>Handlers SHOULD NOT return an error from this method; errors returned from this method SHOULD NOT alter the channel dispatcher's behaviour.</p> <tp:rationale> <p>Calls to this method are merely a notification.</p> </tp:rationale>

tp_cli_client_approver_callback_for_add_dispatch_operation ()

void                (*tp_cli_client_approver_callback_for_add_dispatch_operation)
                                                        (TpClient *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a AddDispatchOperation method call succeeds or fails.

tp_cli_client_approver_call_add_dispatch_operation ()

TpProxyPendingCall * tp_cli_client_approver_call_add_dispatch_operation
                                                        (TpClient *proxy,
                                                         gint timeout_ms,
                                                         const GPtrArray *in_Channels,
                                                         const gchar *in_DispatchOperation,
                                                         GHashTable *in_Properties,
                                                         tp_cli_client_approver_callback_for_add_dispatch_operation callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a AddDispatchOperation method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the channel dispatcher when a ChannelDispatchOperation in which the approver has registered an interest is created, or when the approver starts up while such channel dispatch operations already exist.</p> <p>The channel dispatcher SHOULD call this method on all approvers at the same time. If an approver returns an error from this method, the approver is assumed to be faulty.</p> <p>If no approvers return from this method successfully (including situations where there are no matching approvers at all), the channel dispatcher SHOULD consider this to be an error, and recover by dispatching the channel to the most preferred handler.</p> <tp:rationale> Processes that aren't approvers (or don't at least ensure that there is some approver) probably shouldn't be making connections anyway, so there should always be at least one approver running. </tp:rationale>