![]() |
![]() |
![]() |
telepathy-glib Reference Manual | ![]() |
---|---|---|---|---|
Connection Requests interfaceConnection Requests interface — client-side wrappers for the Requests interface |
#include <telepathy-glib/connection.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); 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); 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); 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);
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.
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"> <p>Request that an entirely new channel is created.</p> <tp:rationale> <p>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.</p> </tp:rationale>
|
the TpProxy |
|
the timeout in milliseconds, or -1 to use the default |
|
Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A dictionary containing desirable properties. 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> |
|
called when the method call succeeds or fails;
may be NULL to make a "fire and forget" call with no
reply tracking
|
|
user-supplied data passed to the callback;
must be NULL if callback is NULL
|
|
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be NULL if callback is NULL
|
|
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. |
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.
|
the proxy on which the call was made |
|
Used to return an 'out' argument if error is NULL : The Channel object, which MUST already have been signalled with <tp:member-ref>NewChannels</tp:member-ref> by the time this method returns.
|
|
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>
|
|
NULL on success, or an error on failure
|
|
user-supplied data |
|
user-supplied 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);
Connect a handler to the signal ChannelClosed.
Emitted when a channel is closed and hence disappears from the Channels property. <tp:rationale> This is redundant with the Close signal on the channel itself, but it does provide full change notification for the Channels property. </tp:rationale>
|
A TpConnection or subclass |
|
Callback to be called when the signal is received |
|
User-supplied data for the callback |
|
Destructor for the user-supplied data, which
will be called when this signal is disconnected, or
before this function returns NULL
|
|
A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected |
|
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.
|
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"> <p>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.</p> <p>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.</p> <tp:rationale> <p>Joining a MUC Tube in XMPP requires joining the corresponding MUC (chatroom), so a Text channel can be created as a side-effect.</p> </tp:rationale>
|
A TpConnection or subclass |
|
Callback to be called when the signal is received |
|
User-supplied data for the callback |
|
Destructor for the user-supplied data, which
will be called when this signal is disconnected, or
before this function returns NULL
|
|
A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected |
|
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.
|
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);
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.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request that an entirely new channel is created.</p> <tp:rationale> <p>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.</p> </tp:rationale>
|
A TpConnection or subclass |
|
Timeout in milliseconds, or -1 for default |
|
Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A dictionary containing desirable properties. 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> |
|
Used to return an 'out' argument if TRUE is returned: The Channel object, which MUST already have been signalled with <tp:member-ref>NewChannels</tp:member-ref> by the time this method returns.
|
|
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>
|
|
If not NULL , used to return errors if FALSE
is returned
|
|
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
|
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.
|
The proxy on which tp_cli_connection_interface_requests_connect_to_channel_closed()
was called
|
|
The channel which has been removed from the Channels property |
|
User-supplied data |
|
User-supplied weakly referenced object |
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.
|
The proxy on which tp_cli_connection_interface_requests_connect_to_new_channels()
was called
|
|
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-supplied data |
|
User-supplied weakly referenced object |