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
gchar *	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”                   gchar *

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