TpContactSearch

## TpContactSearch TpContactSearch — object for a Telepathy contact search channel |

## Synopsis

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

    struct              TpContactSearch;
    struct              TpContactSearchClass;
    void                tp_contact_search_new_async         (TpAccount *account,
                                                             const gchar *server,
                                                             guint limit,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    TpContactSearch *   tp_contact_search_new_finish        (GAsyncResult *result,
                                                             GError **error);
    void                tp_contact_search_reset_async       (TpContactSearch *self,
                                                             const gchar *server,
                                                             guint limit,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    const gchar * const * tp_contact_search_reset_finish    (TpContactSearch *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_contact_search_start             (TpContactSearch *self,
                                                             GHashTable *criteria);
    const gchar * const * tp_contact_search_get_search_keys (TpContactSearch *self);
    TpAccount *         tp_contact_search_get_account       (TpContactSearch *self);
    guint               tp_contact_search_get_limit         (TpContactSearch *self);
    const gchar *       tp_contact_search_get_server        (TpContactSearch *self);

## Object Hierarchy

      GObject
       +----TpContactSearch

## Implemented Interfaces

TpContactSearch implements GAsyncInitable.

## Properties

      "account"                  TpAccount*            : Read / Write / Construct Only
      "limit"                    guint                 : Read / Write
      "server"                   gchar*                : Read / Write / Construct Only
      "state"                    guint                 : Read

## Signals

      "search-results-received"                        : Run Last

## Description

TpContactSearch objects represent ongoing searches for contacts. They implement the GAsyncInitable interface, so the initialization may fail.

In normal circumstances, after creating a TpContactSearch object, you would connect to the "search-results-received" signal to get search results when a search happens. You would then call `tp_contact_search_get_search_keys()` to get the search keys, and then do a search using `tp_contact_search_start()`. When results are found, the "search-results-received" callback will be called.

You can check the search state by looking at the "state" property. If you want to be notified about changes, connect to the notify::state signal, see "notify" for details.

You can search as many times as you want on a TpContactSearch object, but you need to call `tp_contact_search_reset_async()` between searches.

## Details

### struct TpContactSearch

    struct TpContactSearch;

An object for Telepathy contact searches. There are no interesting public struct fields.

Since 0.13.11

### struct TpContactSearchClass

    struct TpContactSearchClass {
    };

The class of a TpContactSearch.

Since 0.13.11

### tp_contact_search_new_async ()

    void                tp_contact_search_new_async         (TpAccount *account,
                                                             const gchar *server,
                                                             guint limit,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`account` : | an account for the contact search
`server` : | the server on which to search for contacts, or `NULL`
`limit` : | The maximum number of results the server should return, or 0 for the server default.
`callback` : | a GAsyncReadyCallback to call when the initialization is finished
`user_data` : | data to pass to the callback function

Since 0.13.11

### tp_contact_search_new_finish ()

    TpContactSearch *   tp_contact_search_new_finish        (GAsyncResult *result,
                                                             GError **error);

`result` : | the GAsyncResult from the callback
`error` : | a GError location to store an error, or `NULL`
Returns : | a new contact search object, or `NULL` in case of error. [transfer full]

Since 0.13.11

### tp_contact_search_reset_async ()

    void                tp_contact_search_reset_async       (TpContactSearch *self,
                                                             const gchar *server,
                                                             guint limit,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Resets the contact search object so a new search can be performed. If another `tp_contact_search_reset_async()` call is in progress, it will be cancelled and `tp_contact_search_reset_finish()` will return an appropriate error.

`self` : | the TpContactSearch to reset
`server` : | the server on which to search for contacts, or `NULL`
`limit` : | The maximum number of results the server should return, or 0 for the server default.
`callback` : | a GAsyncReadyCallback to call when the initialization is finished
`user_data` : | data to pass to the callback function

Since 0.13.11

### tp_contact_search_reset_finish ()

    const gchar * const * tp_contact_search_reset_finish    (TpContactSearch *self,
                                                             GAsyncResult *result,
                                                             GError **error);

`self` : | the TpContactSearch that is being reset
`result` : | the GAsyncResult from the callback
`error` : | a GError location to store an error, or `NULL`
Returns : | the new search keys, or `NULL` in case of error. [transfer none]

Since 0.13.11

### tp_contact_search_start ()

    void                tp_contact_search_start             (TpContactSearch *self,
                                                             GHashTable *criteria);

Starts a search for the keys specified in `criteria`. Connect to the "search-results-received" signal before calling this function.

Before searching again on the same TpContactSearch, you must call `tp_contact_search_reset_async()`.

`self` : | a TpContactSearch
`criteria` : | a map from keys returned by `tp_contact_search_get_search_keys()` to values to search for. [transfer none][element-type utf8 utf8]

Since 0.13.11

### tp_contact_search_get_search_keys ()

    const gchar * const * tp_contact_search_get_search_keys (TpContactSearch *self);

Get the search keys for a contact search. The keys are vCard field names in lower case, except when they're one of the special cases from telepathy-spec like "tel;cell" or "x-n-given". See the Channel.Type.ContactSearch interface for a list of the special cases.

`self` : | the contact search object to get the keys from
Returns : | the new search keys, or `NULL`. [transfer none]

Since 0.13.11

### tp_contact_search_get_account ()

    TpAccount *         tp_contact_search_get_account       (TpContactSearch *self);

`self` : | a contact search object
Returns : | The TpContactSearch:account property. [transfer none]

Since 0.13.11

### tp_contact_search_get_limit ()

    guint               tp_contact_search_get_limit         (TpContactSearch *self);

`self` : | a contact search object
Returns : | The TpContactSearch:limit property

Since 0.13.11

### tp_contact_search_get_server ()

    const gchar *       tp_contact_search_get_server        (TpContactSearch *self);

`self` : | a contact search object
Returns : | The TpContactSearch:server property

Since 0.13.11

## Property Details

### The `"account"` property

      "account"                  TpAccount*            : Read / Write / Construct Only

This search's account.

Since 0.13.11

### The `"limit"` property

      "limit"                    guint                 : Read / Write

The maximum number of results that the server should return. This is only supported by some protocols; use `tp_capabilities_supports_contact_search()` to check if it's supported.

To change the limit after the object has been constructed, use `tp_contact_search_reset_async()`.

Default value: 0

Since 0.13.11

### The `"server"` property

      "server"                   gchar*                : Read / Write / Construct Only

The search server. This is only supported by some protocols; use `tp_capabilities_supports_contact_search()` to check if it's supported.

To change the server after the object has been constructed, use `tp_contact_search_reset_async()`.

Default value: NULL

Since 0.13.11

### The `"state"` property

      "state"                    guint                 : Read

This search's state, as a `TpChannelContactSearchState`.

Default value: 0

Since 0.13.11

## Signal Details

### The `"search-results-received"` signal

    void                user_function                      (TpContactSearch *self,
                                                            gpointer         results,
                                                            gpointer         user_data)      : Run Last

Emitted when search results are received. Note that this signal may be emitted multiple times for the same search.

`self` : | a contact search
`results` : | a GList with the search results. [type GLib.List][element-type TelepathyGLib.ContactSearchResult]
`user_data` : | user data set when the signal handler was connected.

Since 0.13.11

## See Also

TpChannel