Contact Search channels

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

## Synopsis

    #include <telepathy-glib/channel.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