TpContactSearch

TpContactSearch — object for a Telepathy contact search channel

Functions

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

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

See Also

TpChannel