## Contact Search channels

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

## Functions

TpProxyPendingCall * | tp_cli_channel_type_contact_search_call_more ()
TpProxyPendingCall * | tp_cli_channel_type_contact_search_call_search ()
TpProxyPendingCall * | tp_cli_channel_type_contact_search_call_stop ()
void | (*tp_cli_channel_type_contact_search_callback_for_more) ()
void | (*tp_cli_channel_type_contact_search_callback_for_search) ()
void | (*tp_cli_channel_type_contact_search_callback_for_stop) ()
TpProxySignalConnection * | tp_cli_channel_type_contact_search_connect_to_search_result_received ()
TpProxySignalConnection * | tp_cli_channel_type_contact_search_connect_to_search_state_changed ()
gboolean | tp_cli_channel_type_contact_search_run_more ()
gboolean | tp_cli_channel_type_contact_search_run_search ()
gboolean | tp_cli_channel_type_contact_search_run_stop ()
void | (*tp_cli_channel_type_contact_search_signal_callback_search_result_received) ()
void | (*tp_cli_channel_type_contact_search_signal_callback_search_state_changed) ()

## Includes

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

## 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.

## Functions

### 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.

#### Parameters

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.

#### Parameters

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>

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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>

#### Parameters

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);

`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.

#### Parameters

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);

`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.

#### Parameters

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);

`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>

#### Parameters

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.

#### Parameters

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.

#### Parameters

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