Connection Requests interface

Connection Requests interface — client-side wrappers for the Requests interface

Synopsis

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

TpProxyPendingCall * tp_cli_connection_interface_requests_call_create_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Request,
                                                         tp_cli_connection_interface_requests_callback_for_create_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_interface_requests_call_ensure_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Request,
                                                         tp_cli_connection_interface_requests_callback_for_ensure_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_requests_callback_for_create_channel)
                                                        (TpConnection *proxy,
                                                         const gchar *out_Channel,
                                                         GHashTable *out_Properties,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_requests_callback_for_ensure_channel)
                                                        (TpConnection *proxy,
                                                         gboolean out_Yours,
                                                         const gchar *out_Channel,
                                                         GHashTable *out_Properties,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_connection_interface_requests_connect_to_channel_closed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_interface_requests_signal_callback_channel_closed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
TpProxySignalConnection * tp_cli_connection_interface_requests_connect_to_new_channels
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_interface_requests_signal_callback_new_channels callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
gboolean            tp_cli_connection_interface_requests_run_create_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Request,
                                                         gchar **out_Channel,
                                                         GHashTable **out_Properties,
                                                         GError **error,
                                                         GMainLoop **loop);
gboolean            tp_cli_connection_interface_requests_run_ensure_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Request,
                                                         gboolean *out_Yours,
                                                         gchar **out_Channel,
                                                         GHashTable **out_Properties,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_interface_requests_signal_callback_channel_closed)
                                                        (TpConnection *proxy,
                                                         const gchar *arg_Removed,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_requests_signal_callback_new_channels)
                                                        (TpConnection *proxy,
                                                         const GPtrArray *arg_Channels,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Description

This interface allows a client to request new channels from a connection, and to listen to signals indicating that channels have been created and closed.

This section documents the auto-generated C wrappers for the Requests interface, used with TpConnection objects.

Details

tp_cli_connection_interface_requests_call_create_channel ()

TpProxyPendingCall * tp_cli_connection_interface_requests_call_create_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Request,
                                                         tp_cli_connection_interface_requests_callback_for_create_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a CreateChannel method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Request that an entirely new channel is created. <tp:rationale> There is deliberately no flag corresponding to the suppress_handler argument to <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>, because passing a FALSE value for that argument is deprecated. Requests made using this interface always behave as though suppress_handler was TRUE. </tp:rationale>

`proxy` :	the TpProxy
`timeout_ms` :	the timeout in milliseconds, or -1 to use the default
`in_Request` :	Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A dictionary containing desirable properties, which MUST include <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>. Some properties are defined such that only an exact match makes sense, and connection managers MUST NOT satisfy a request with a channel where that property does not match; some properties are defined such that the connection manager MAY treat the request as merely a hint, and make a best-effort attempt to satisfy it. This is documented separately for each property.</p> <p>If this dictionary contains a property whose semantics are not known to the connection manager, this method MUST fail without side-effects (in particular it must not create a new channel).</p> <tp:rationale> <p>This is necessary if we want to be able to invent properties in future that, when used in a request, are hard requirements rather than just hints. A connection manager that did not know the semantics of those properties could incorrectly return a new channel that did not satisfy the requirements.</p> </tp:rationale> <p>The connection manager MUST NOT respond successfully, and SHOULD NOT create a new channel or cause any other side-effects, unless it can create a new channel that satisfies the client's requirements.</p> <p>Properties that will be set by this argument need not have write access after the channel has been created - indeed, it is expected that most will be read-only.</p>
`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_connection_interface_requests_call_ensure_channel ()

TpProxyPendingCall * tp_cli_connection_interface_requests_call_ensure_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Request,
                                                         tp_cli_connection_interface_requests_callback_for_ensure_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a EnsureChannel method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Request that channels are ensured to exist. <tp:rationale> The connection manager is in the best position to determine which existing channels could satisfy which requests. </tp:rationale>

`proxy` :	the TpProxy
`timeout_ms` :	the timeout in milliseconds, or -1 to use the default
`in_Request` :	Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A dictionary containing desirable properties, with the same semantics as the corresponding parameter to <tp:member-ref>CreateChannel</tp:member-ref>.</p>
`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_connection_interface_requests_callback_for_create_channel ()

void                (*tp_cli_connection_interface_requests_callback_for_create_channel)
                                                        (TpConnection *proxy,
                                                         const gchar *out_Channel,
                                                         GHashTable *out_Properties,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

`proxy` :	the proxy on which the call was made
`out_Channel` :	Used to return an 'out' argument if `error` is `NULL`: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The Channel object, which MUST NOT be signalled with <tp:member-ref>NewChannels</tp:member-ref> until after this method returns.</p> <tp:rationale> <p>This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.</p> </tp:rationale>
`out_Properties` :	Used to return an 'out' argument if `error` is `NULL`: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Properties of the channel that was produced, equivalent to the properties in <tp:type>Channel_Details</tp:type>. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in <tp:type>Channel_Details</tp:type>.</p>
`error` :	`NULL` on success, or an error on failure
`user_data` :	user-supplied data
`weak_object` :	user-supplied object

tp_cli_connection_interface_requests_callback_for_ensure_channel ()

void                (*tp_cli_connection_interface_requests_callback_for_ensure_channel)
                                                        (TpConnection *proxy,
                                                         gboolean out_Yours,
                                                         const gchar *out_Channel,
                                                         GHashTable *out_Properties,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

`proxy` :	the proxy on which the call was made
`out_Yours` :	Used to return an 'out' argument if `error` is `NULL`: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If false, the caller of EnsureChannel MUST assume that some other process is handling this channel; if true, the caller of EnsureChannel SHOULD handle it themselves or delegate it to another client.</p> <p>If the creation of a channel makes several calls to EnsureChannel (and no other requests) successful, exactly one of those calls MUST return a true value for this argument.</p> <p>If the creation of a channel makes other requests successful, the value returned for this argument MUST be such that exactly one of the clients making requests ends up responsible for the channel. In particular, if <tp:member-ref>CreateChannel</tp:member-ref> returns a channel <em>C</em>, any EnsureChannel calls that also return <em>C</em> MUST return a false value for this argument.</p>
`out_Channel` :	Used to return an 'out' argument if `error` is `NULL`: The Channel object. If it was created as a result of this method call, it MUST NOT be signalled by <tp:member-ref>NewChannels</tp:member-ref> until after this method returns. <tp:rationale> <p>This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.</p> </tp:rationale>
`out_Properties` :	Used to return an 'out' argument if `error` is `NULL`: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Properties of the channel that was produced, equivalent to the properties in <tp:type>Channel_Details</tp:type>. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in <tp:type>Channel_Details</tp:type>.</p>
`error` :	`NULL` on success, or an error on failure
`user_data` :	user-supplied data
`weak_object` :	user-supplied object

tp_cli_connection_interface_requests_connect_to_channel_closed ()

TpProxySignalConnection * tp_cli_connection_interface_requests_connect_to_channel_closed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_interface_requests_signal_callback_channel_closed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal ChannelClosed.

Emitted when a channel is closed and hence disappears from the <tp:member-ref>Channels</tp:member-ref> property. <tp:rationale> This is redundant with the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref> signal on the channel itself, but it does provide full change notification for the Channels property. </tp:rationale>

`proxy` :	A TpConnection or subclass
`callback` :	Callback to be called when the signal is received
`user_data` :	User-supplied data for the callback
`destroy` :	Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
`weak_object` :	A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
`error` :	If not `NULL`, used to raise an error if `NULL` is returned
Returns :	a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or `NULL` if the proxy does not have the desired interface or has become invalid.

tp_cli_connection_interface_requests_connect_to_new_channels ()

TpProxySignalConnection * tp_cli_connection_interface_requests_connect_to_new_channels
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_interface_requests_signal_callback_new_channels callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal NewChannels.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> New channels have been created. The connection manager SHOULD emit a single signal for any group of closely related channels that are created at the same time, so that the channel dispatcher can try to dispatch them to a handler as a unit. In particular, if additional channels are created as a side-effect of a call to <tp:member-ref>CreateChannel</tp:member-ref>, these channels SHOULD appear in the same NewChannels signal as the channel that satisfies the request. <tp:rationale> Joining a MUC Tube in XMPP requires joining the corresponding MUC (chatroom), so a <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> channel can be created as a side-effect. </tp:rationale> Every time NewChannels is emitted, it MUST be followed by a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> signal for each channel. <tp:rationale> The double signal emission is for the benefit of older Telepathy clients, which won't be listening for NewChannels. The more informative NewChannels signal comes first so that clients that did not examine the connection to find out whether Requests is supported will see the more informative signal for each channel first, and then ignore the less informative signal because it announces a new channel of which they are already aware. </tp:rationale>

`proxy` :	A TpConnection or subclass
`callback` :	Callback to be called when the signal is received
`user_data` :	User-supplied data for the callback
`destroy` :	Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
`weak_object` :	A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
`error` :	If not `NULL`, used to raise an error if `NULL` is returned
Returns :	a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or `NULL` if the proxy does not have the desired interface or has become invalid.

tp_cli_connection_interface_requests_run_create_channel ()

gboolean            tp_cli_connection_interface_requests_run_create_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Request,
                                                         gchar **out_Channel,
                                                         GHashTable **out_Properties,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_interface_requests_run_create_channel is deprecated and should not be used in newly-written code.

Call the method CreateChannel and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

`proxy` :	A TpConnection or subclass
`timeout_ms` :	Timeout in milliseconds, or -1 for default
`in_Request` :	Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A dictionary containing desirable properties, which MUST include <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>. Some properties are defined such that only an exact match makes sense, and connection managers MUST NOT satisfy a request with a channel where that property does not match; some properties are defined such that the connection manager MAY treat the request as merely a hint, and make a best-effort attempt to satisfy it. This is documented separately for each property.</p> <p>If this dictionary contains a property whose semantics are not known to the connection manager, this method MUST fail without side-effects (in particular it must not create a new channel).</p> <tp:rationale> <p>This is necessary if we want to be able to invent properties in future that, when used in a request, are hard requirements rather than just hints. A connection manager that did not know the semantics of those properties could incorrectly return a new channel that did not satisfy the requirements.</p> </tp:rationale> <p>The connection manager MUST NOT respond successfully, and SHOULD NOT create a new channel or cause any other side-effects, unless it can create a new channel that satisfies the client's requirements.</p> <p>Properties that will be set by this argument need not have write access after the channel has been created - indeed, it is expected that most will be read-only.</p>
`out_Channel` :	Used to return an 'out' argument if `TRUE` is returned: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The Channel object, which MUST NOT be signalled with <tp:member-ref>NewChannels</tp:member-ref> until after this method returns.</p> <tp:rationale> <p>This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.</p> </tp:rationale>
`out_Properties` :	Used to return an 'out' argument if `TRUE` is returned: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Properties of the channel that was produced, equivalent to the properties in <tp:type>Channel_Details</tp:type>. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in <tp:type>Channel_Details</tp:type>.</p>
`error` :	If not `NULL`, used to return errors if `FALSE` is returned
`loop` :	If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns :	TRUE on success, FALSE and sets `error` on error

tp_cli_connection_interface_requests_run_ensure_channel ()

gboolean            tp_cli_connection_interface_requests_run_ensure_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Request,
                                                         gboolean *out_Yours,
                                                         gchar **out_Channel,
                                                         GHashTable **out_Properties,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_interface_requests_run_ensure_channel is deprecated and should not be used in newly-written code.

Call the method EnsureChannel and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

`proxy` :	A TpConnection or subclass
`timeout_ms` :	Timeout in milliseconds, or -1 for default
`in_Request` :	Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A dictionary containing desirable properties, with the same semantics as the corresponding parameter to <tp:member-ref>CreateChannel</tp:member-ref>.</p>
`out_Yours` :	Used to return an 'out' argument if `TRUE` is returned: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If false, the caller of EnsureChannel MUST assume that some other process is handling this channel; if true, the caller of EnsureChannel SHOULD handle it themselves or delegate it to another client.</p> <p>If the creation of a channel makes several calls to EnsureChannel (and no other requests) successful, exactly one of those calls MUST return a true value for this argument.</p> <p>If the creation of a channel makes other requests successful, the value returned for this argument MUST be such that exactly one of the clients making requests ends up responsible for the channel. In particular, if <tp:member-ref>CreateChannel</tp:member-ref> returns a channel <em>C</em>, any EnsureChannel calls that also return <em>C</em> MUST return a false value for this argument.</p>
`out_Channel` :	Used to return an 'out' argument if `TRUE` is returned: The Channel object. If it was created as a result of this method call, it MUST NOT be signalled by <tp:member-ref>NewChannels</tp:member-ref> until after this method returns. <tp:rationale> <p>This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.</p> </tp:rationale>
`out_Properties` :	Used to return an 'out' argument if `TRUE` is returned: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Properties of the channel that was produced, equivalent to the properties in <tp:type>Channel_Details</tp:type>. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in <tp:type>Channel_Details</tp:type>.</p>
`error` :	If not `NULL`, used to return errors if `FALSE` is returned
`loop` :	If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns :	TRUE on success, FALSE and sets `error` on error

tp_cli_connection_interface_requests_signal_callback_channel_closed ()

void                (*tp_cli_connection_interface_requests_signal_callback_channel_closed)
                                                        (TpConnection *proxy,
                                                         const gchar *arg_Removed,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal ChannelClosed.

`proxy` :	The proxy on which `tp_cli_connection_interface_requests_connect_to_channel_closed()` was called
`arg_Removed` :	The channel which has been removed from the Channels property
`user_data` :	User-supplied data
`weak_object` :	User-supplied weakly referenced object

tp_cli_connection_interface_requests_signal_callback_new_channels ()

void                (*tp_cli_connection_interface_requests_signal_callback_new_channels)
                                                        (TpConnection *proxy,
                                                         const GPtrArray *arg_Channels,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal NewChannels.

`proxy` :	The proxy on which `tp_cli_connection_interface_requests_connect_to_new_channels()` was called
`arg_Channels` :	The channels and their details. All channels that are signalled together like this MUST have the same <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref> property, which may either refer to an existing bundle, or establish a new bundle.
`user_data` :	User-supplied data
`weak_object` :	User-supplied weakly referenced object

			telepathy-glib API Reference Manual
Top \| Description