Contact Search channels

Contact Search channels — client-side wrappers for the Contact Search channel type

Synopsis

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

TpProxyPendingCall * tp_cli_channel_type_contact_search_call_more
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_type_contact_search_callback_for_more callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_type_contact_search_call_search
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Terms,
                                                         tp_cli_channel_type_contact_search_callback_for_search callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_type_contact_search_call_stop
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_type_contact_search_callback_for_stop callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_type_contact_search_callback_for_more)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_type_contact_search_callback_for_search)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_type_contact_search_callback_for_stop)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_type_contact_search_connect_to_search_result_received
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_contact_search_signal_callback_search_result_received callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
TpProxySignalConnection * tp_cli_channel_type_contact_search_connect_to_search_state_changed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_contact_search_signal_callback_search_state_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
gboolean            tp_cli_channel_type_contact_search_run_more
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         GError **error,
                                                         GMainLoop **loop);
gboolean            tp_cli_channel_type_contact_search_run_search
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Terms,
                                                         GError **error,
                                                         GMainLoop **loop);
gboolean            tp_cli_channel_type_contact_search_run_stop
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_channel_type_contact_search_signal_callback_search_result_received)
                                                        (TpChannel *proxy,
                                                         GHashTable *arg_Result,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_type_contact_search_signal_callback_search_state_changed)
                                                        (TpChannel *proxy,
                                                         guint arg_State,
                                                         const gchar *arg_Error,
                                                         GHashTable *arg_Details,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Description

Some instant messaging protocols allow searching for contacts by name or other details. In Telepathy, each search attempt is represented as a Channel.

This section documents the auto-generated C wrappers for the Contact Search channel type.

Details

tp_cli_channel_type_contact_search_call_more ()

TpProxyPendingCall * tp_cli_channel_type_contact_search_call_more
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_type_contact_search_callback_for_more callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a More method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Request that a search in <tp:member-ref>SearchState</tp:member-ref> <code>More_Available</code> move back to state <code>In_Progress</code> and continue listing up to <tp:member-ref>Limit</tp:member-ref> more results.

proxy :

the TpProxy

timeout_ms :

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

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_type_contact_search_call_search ()

TpProxyPendingCall * tp_cli_channel_type_contact_search_call_search
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Terms,
                                                         tp_cli_channel_type_contact_search_callback_for_search callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a Search method call.

Send a request to start a search for contacts on this connection. This may only be called while the <tp:member-ref>SearchState</tp:member-ref> is Not_Started; a valid search request will cause the <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted with the state In_Progress.

proxy :

the TpProxy

timeout_ms :

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

in_Terms :

Used to pass an 'in' argument: A dictionary mapping search key names to the desired values

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_type_contact_search_call_stop ()

TpProxyPendingCall * tp_cli_channel_type_contact_search_call_stop
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_type_contact_search_callback_for_stop callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a Stop method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Stop the current search. This may not be called while the <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called while the SearchState is In_Progress, <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted, with the state Failed and the error <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Cancelled</tp:error-ref></code>.</p> <p>Calling this method on a search in state Completed or Failed succeeds, but has no effect.</p> <tp:rationale> <p>Specifying Stop to succeed when the search has finished means that clients who call Stop just before receiving <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to handle a useless error.</p> </tp:rationale> <p>Depending on the protocol, the connection manager may not be able to prevent the server from sending further results after this method returns; if this is the case, it MUST ignore any further results.</p>

proxy :

the TpProxy

timeout_ms :

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

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_type_contact_search_callback_for_more ()

void                (*tp_cli_channel_type_contact_search_callback_for_more)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_type_contact_search_callback_for_search ()

void                (*tp_cli_channel_type_contact_search_callback_for_search)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_type_contact_search_callback_for_stop ()

void                (*tp_cli_channel_type_contact_search_callback_for_stop)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_type_contact_search_connect_to_search_result_received ()

TpProxySignalConnection * tp_cli_channel_type_contact_search_connect_to_search_result_received
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_contact_search_signal_callback_search_result_received callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal SearchResultReceived.

Emitted when a some search results are received from the server. This signal can be fired arbitrarily many times so clients MUST NOT assume they'll get only one signal.

proxy :

A TpChannel 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_channel_type_contact_search_connect_to_search_state_changed ()

TpProxySignalConnection * tp_cli_channel_type_contact_search_connect_to_search_state_changed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_contact_search_signal_callback_search_state_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal SearchStateChanged.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when the <tp:member-ref>SearchState</tp:member-ref> property changes. The implementation MUST NOT make transitions other than the following:</p> <ul> <li><code>Not_Started</code> → <code>In_Progress</code></li> <li><code>In_Progress</code> → <code>More_Available</code></li> <li><code>More_Available</code> → <code>In_Progress</code></li> <li><code>In_Progress</code> → <code>Completed</code></li> <li><code>In_Progress</code> → <code>Failed</code></li> </ul>

proxy :

A TpChannel 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_channel_type_contact_search_run_more ()

gboolean            tp_cli_channel_type_contact_search_run_more
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

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

Call the method More 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"> Request that a search in <tp:member-ref>SearchState</tp:member-ref> <code>More_Available</code> move back to state <code>In_Progress</code> and continue listing up to <tp:member-ref>Limit</tp:member-ref> more results.

proxy :

A TpChannel or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

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_channel_type_contact_search_run_search ()

gboolean            tp_cli_channel_type_contact_search_run_search
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_Terms,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

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

Call the method Search 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.

Send a request to start a search for contacts on this connection. This may only be called while the <tp:member-ref>SearchState</tp:member-ref> is Not_Started; a valid search request will cause the <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted with the state In_Progress.

proxy :

A TpChannel or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

in_Terms :

Used to pass an 'in' argument: A dictionary mapping search key names to the desired values

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_channel_type_contact_search_run_stop ()

gboolean            tp_cli_channel_type_contact_search_run_stop
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

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

Call the method Stop 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>Stop the current search. This may not be called while the <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called while the SearchState is In_Progress, <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted, with the state Failed and the error <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Cancelled</tp:error-ref></code>.</p> <p>Calling this method on a search in state Completed or Failed succeeds, but has no effect.</p> <tp:rationale> <p>Specifying Stop to succeed when the search has finished means that clients who call Stop just before receiving <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to handle a useless error.</p> </tp:rationale> <p>Depending on the protocol, the connection manager may not be able to prevent the server from sending further results after this method returns; if this is the case, it MUST ignore any further results.</p>

proxy :

A TpChannel or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

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_channel_type_contact_search_signal_callback_search_result_received ()

void                (*tp_cli_channel_type_contact_search_signal_callback_search_result_received)
                                                        (TpChannel *proxy,
                                                         GHashTable *arg_Result,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal SearchResultReceived.

proxy :

The proxy on which tp_cli_channel_type_contact_search_connect_to_search_result_received() was called

arg_Result :

A mapping from contact identifier to an array of fields representing information about this contact.

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_channel_type_contact_search_signal_callback_search_state_changed ()

void                (*tp_cli_channel_type_contact_search_signal_callback_search_state_changed)
                                                        (TpChannel *proxy,
                                                         guint arg_State,
                                                         const gchar *arg_Error,
                                                         GHashTable *arg_Details,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal SearchStateChanged.

proxy :

The proxy on which tp_cli_channel_type_contact_search_connect_to_search_state_changed() was called

arg_State :

The new search state (TpChannelContactSearchState)

arg_Error :

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> If the new state is <code>Failed</code>, the name of a D-Bus error describing what went wrong. Otherwise, the empty string.

arg_Details :

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Additional information about the state transition, which may include the following well-known keys:</p> <dl> <dt>debug-message (s)</dt> <dd>Debugging information on the change, corresponding to the message part of a D-Bus error message, which SHOULD NOT be displayed to users under normal circumstances</dd> </dl> <tp:rationale> <p>This argument allows for future extensions. For instance, if moving to state <code>Failed</code> because the server rejected one of our search terms, we could define a key that indicates which terms were invalid.</p> </tp:rationale>

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

See Also

TpChannel