TpContactSearch: telepathy-glib API Reference Manual

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

## Functions

void | tp_contact_search_new_async ()
TpContactSearch * | tp_contact_search_new_finish ()
void | tp_contact_search_reset_async ()
const gchar * const * | tp_contact_search_reset_finish ()
void | tp_contact_search_start ()
const gchar * const * | tp_contact_search_get_search_keys ()
TpAccount * | tp_contact_search_get_account ()
guint | tp_contact_search_get_limit ()
const gchar * | tp_contact_search_get_server ()

## Properties

TpAccount * | account | Read / Write / Construct Only
guint | limit | Read / Write
char * | server | Read / Write / Construct Only
guint | state | Read

## Signals

void | search-results-received | Run Last

## Types and Values

struct | TpContactSearch
struct | TpContactSearchClass

## Object Hierarchy

        GObject
        ╰── TpContactSearch

## Implemented Interfaces

TpContactSearch implements GAsyncInitable.

## Includes

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

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

## Functions

### tp_contact_search_new_async ()

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

self | a contact search object |

#### Returns

The TpContactSearch:server property

Since: 0.13.11

## Types and Values

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

## Property Details

### The `“account”` property

      “account”                  TpAccount *

This search's account.

Owner: TpContactSearch

Flags: Read / Write / Construct Only

Since: 0.13.11

### The `“limit”` property

      “limit”                    guint

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

Owner: TpContactSearch

Flags: Read / Write

Default value: 0

Since: 0.13.11

### The `“server”` property

      “server”                   char *

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

Owner: TpContactSearch

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.13.11

### The `“state”` property

      “state”                    guint

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

Owner: TpContactSearch

Flags: Read

Default value: 0

Since: 0.13.11

## Signal Details

### The `“search-results-received”` signal

    void
    user_function (TpContactSearch *self,
                   gpointer         results,
                   gpointer         user_data)

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

#### Parameters

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

Flags: Run Last

Since: 0.13.11

## See Also

TpChannel