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
Generated by GTK-Doc V1.19