telepathy-glib API Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
#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
);
"account" TpAccount* : Read / Write / Construct Only "limit" guint : Read / Write "server" gchar* : Read / Write / Construct Only "state" guint : Read
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.
struct TpContactSearch;
An object for Telepathy contact searches. There are no interesting public struct fields.
Since 0.13.11
struct TpContactSearchClass { };
The class of a TpContactSearch.
Since 0.13.11
void tp_contact_search_new_async (TpAccount *account
,const gchar *server
,guint limit
,GAsyncReadyCallback callback
,gpointer user_data
);
|
an account for the contact search |
|
the server on which to search for contacts, or NULL
|
|
The maximum number of results the server should return, or 0 for the server default. |
|
a GAsyncReadyCallback to call when the initialization is finished |
|
data to pass to the callback function |
Since 0.13.11
TpContactSearch * tp_contact_search_new_finish (GAsyncResult *result
,GError **error
);
|
the GAsyncResult from the callback |
|
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
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.
|
the TpContactSearch to reset |
|
the server on which to search for contacts, or NULL
|
|
The maximum number of results the server should return, or 0 for the server default. |
|
a GAsyncReadyCallback to call when the initialization is finished |
|
data to pass to the callback function |
Since 0.13.11
const gchar * const * tp_contact_search_reset_finish (TpContactSearch *self
,GAsyncResult *result
,GError **error
);
|
the TpContactSearch that is being reset |
|
the GAsyncResult from the callback |
|
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
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()
.
|
a TpContactSearch |
|
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
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.
|
the contact search object to get the keys from |
Returns : |
the new search keys, or NULL . [transfer none]
|
Since 0.13.11
TpAccount * tp_contact_search_get_account (TpContactSearch *self
);
|
a contact search object |
Returns : |
The TpContactSearch:account property. [transfer none] |
Since 0.13.11
guint tp_contact_search_get_limit (TpContactSearch *self
);
|
a contact search object |
Returns : |
The TpContactSearch:limit property |
Since 0.13.11
const gchar * tp_contact_search_get_server (TpContactSearch *self
);
|
a contact search object |
Returns : |
The TpContactSearch:server property |
Since 0.13.11
"account"
property"account" TpAccount* : Read / Write / Construct Only
This search's account.
Since 0.13.11
"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
"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
"state"
property "state" guint : Read
This search's state, as a TpChannelContactSearchState
.
Default value: 0
Since 0.13.11
"search-results-received"
signalvoid 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.
|
a contact search |
|
a GList with the search results. [type GLib.List][element-type TelepathyGLib.ContactSearchResult] |
|
user data set when the signal handler was connected. |
Since 0.13.11