TpChannelDispatcher

TpChannelDispatcher — proxy object for the Telepathy channel dispatcher

Synopsis

#include <telepathy-glib/telepathy-glib.h>

struct              TpChannelDispatcher;
struct              TpChannelDispatcherClass;
TpChannelDispatcher * tp_channel_dispatcher_new         (TpDBusDaemon *bus_daemon);
void                tp_channel_dispatcher_init_known_interfaces
                                                        (void);

TpProxyPendingCall * tp_cli_channel_dispatcher_interface_messages1_call_send_message
                                                        (TpChannelDispatcher *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Account,
                                                         const gchar *in_Target_ID,
                                                         const GPtrArray *in_Message,
                                                         guint in_Flags,
                                                         tp_cli_channel_dispatcher_interface_messages1_callback_for_send_message callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_dispatcher_interface_messages1_callback_for_send_message)
                                                        (TpChannelDispatcher *proxy,
                                                         const gchar *out_Token,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Object Hierarchy

  GObject
   +----TpProxy
         +----TpChannelDispatcher

Description

The TpChannelDispatcher object can be used to communicate with any implementation of the Telepathy ChannelDispatcher service to request new channels.

Details

struct TpChannelDispatcher

struct TpChannelDispatcher;

The Channel Dispatcher's main D-Bus API is used to request channels, which is done by calling tp_cli_channel_dispatcher_call_create_channel() or tp_cli_channel_dispatcher_call_ensure_channel() as appropriate.

The Telepathy Channel Dispatcher is also responsible for responding to new channels and launching client processes to handle them. However, clients that can work with incoming channels do not have to call methods on the channel dispatcher: instead, they must register with the channel dispatcher passively, by taking a bus name starting with TP_CLIENT_BUS_NAME_BASE and implementing the TpSvcClient interface. See the Telepathy D-Bus Interface Specification for details.

This proxy is usable but incomplete: convenience methods will be added in a later version of telepathy-glib.

Since 0.7.32


struct TpChannelDispatcherClass

struct TpChannelDispatcherClass {
};

The class of a TpChannelDispatcher.


tp_channel_dispatcher_new ()

TpChannelDispatcher * tp_channel_dispatcher_new         (TpDBusDaemon *bus_daemon);

Convenience function to create a new channel dispatcher proxy.

bus_daemon :

Proxy for the D-Bus daemon

Returns :

a new reference to a channel dispatcher proxy

tp_channel_dispatcher_init_known_interfaces ()

void                tp_channel_dispatcher_init_known_interfaces
                                                        (void);

Ensure that the known interfaces for TpChannelDispatcher 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_CHANNEL_DISPATCHER.

Since 0.7.32


tp_cli_channel_dispatcher_interface_messages1_call_send_message ()

TpProxyPendingCall * tp_cli_channel_dispatcher_interface_messages1_call_send_message
                                                        (TpChannelDispatcher *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Account,
                                                         const gchar *in_Target_ID,
                                                         const GPtrArray *in_Message,
                                                         guint in_Flags,
                                                         tp_cli_channel_dispatcher_interface_messages1_callback_for_send_message callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a SendMessage method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Submit a message to the server for sending, like the <tp:dbus-ref namespace="imt1.Channel.Type">Text.SendMessage</tp:dbus-ref> method.</p> <p>If the <var>Account</var> is connected and a Text channel to the <var>Target_ID</var> already exists, this method is equivalent to sending the same message via that channel.</p> <p>Otherwise, this method creates a channel (connecting the Account if appropriate), sends the desired message, and closes the channel as if via <tp:dbus-ref namespace="imt1">Channel.Close</tp:dbus-ref>, without acknowledging any messages received on that channel during that time.</p> <p>If any messages are received on that channel before it is closed, a correct connection manager implementation will reopen the channel when it is closed, resulting in those &quot;rescued&quot; messages being processed by the system's normal <tp:dbus-ref namespace="imt1.Client">Handler</tp:dbus-ref> for text channels. In particular, this deals with the situation where a successful or failed delivery report is received before the channel is closed.</p> <tp:rationale> <p>Expecting a trivial client (perhaps a send-only IRC bot, or a simple SMS-sending API) to go through all those steps to send a message seems somewhat unreasonable. Having this as a method in the ChannelDispatcher lets it take some short-cuts if required, and centralizes the implementation to reduce the risk of mistakes that cause message loss.</p> </tp:rationale> <p>The ChannelDispatcher SHOULD support this method for any connection manager that would accept channel requests of this form:</p> <pre> { …<tp:dbus-ref namespace="imt1">Channel.ChannelType</tp:dbus-ref>: …<tp:dbus-ref namespace="imt1">Channel.Type.Text</tp:dbus-ref>, …<tp:dbus-ref namespace="imt1">Channel.TargetHandleType</tp:dbus-ref>: <tp:value-ref type="Handle_Type">Contact</tp:value-ref>, …<tp:dbus-ref namespace="imt1">Channel.TargetID</tp:dbus-ref>: <var>Target_ID</var> }</pre> <p>However, if the connection manager provides additional APIs (such as a way to open &quot;send-only&quot; channels), the ChannelDispatcher MAY use those: it is not required to use those exact request parameters.</p> <p>This method may raise any error that would be raised by the <tp:dbus-ref namespace="imt1.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref> or <tp:dbus-ref namespace="imt1.Channel.Type">Text.SendMessage</tp:dbus-ref> methods, or signalled by the <tp:dbus-ref namespace="imt1.ChannelRequest">Failed</tp:dbus-ref> signal.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Account :

Used to pass an 'in' argument: The <tp:dbus-ref namespace="imt1">Account</tp:dbus-ref> through which to communicate.

in_Target_ID :

Used to pass an 'in' argument: The contact to send the message to.

in_Message :

Used to pass an 'in' argument: The parts of the message, the same as for <tp:dbus-ref namespace="imt1.Channel.Type">Text.SendMessage</tp:dbus-ref>.

in_Flags :

Used to pass an 'in' argument: Flags influencing how to send the message, the same as for <tp:dbus-ref namespace="imt1.Channel.Type">Text.SendMessage</tp:dbus-ref>.

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_dispatcher_interface_messages1_callback_for_send_message ()

void                (*tp_cli_channel_dispatcher_interface_messages1_callback_for_send_message)
                                                        (TpChannelDispatcher *proxy,
                                                         const gchar *out_Token,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

proxy :

the proxy on which the call was made

out_Token :

Used to return an 'out' argument if error is NULL: An opaque token equivalent to the one returned by <tp:dbus-ref namespace="imt1.Channel.Type">Text.SendMessage</tp:dbus-ref>.

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

See Also

TpChannelDispatchOperation, TpChannelRequest