telepathy-glib API Reference Manual | ||||
---|---|---|---|---|
Top | Description |
Contact Search channelsContact Search channels — client-side wrappers for the Contact Search channel type |
#include <telepathy-glib/telepathy-glib-dbus.h> TpProxyPendingCall * tp_cli_channel_type_contact_search_call_more (TpChannel *proxy
,gint timeout_ms
,tp_cli_channel_type_contact_search_callback_for_more callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
); TpProxyPendingCall * tp_cli_channel_type_contact_search_call_search (TpChannel *proxy
,gint timeout_ms
,GHashTable *in_Terms
,tp_cli_channel_type_contact_search_callback_for_search callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
); TpProxyPendingCall * tp_cli_channel_type_contact_search_call_stop (TpChannel *proxy
,gint timeout_ms
,tp_cli_channel_type_contact_search_callback_for_stop callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
); void (*tp_cli_channel_type_contact_search_callback_for_more) (TpChannel *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
); void (*tp_cli_channel_type_contact_search_callback_for_search) (TpChannel *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
); void (*tp_cli_channel_type_contact_search_callback_for_stop) (TpChannel *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
); TpProxySignalConnection * tp_cli_channel_type_contact_search_connect_to_search_result_received (TpChannel *proxy
,tp_cli_channel_type_contact_search_signal_callback_search_result_received callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
,GError **error
); TpProxySignalConnection * tp_cli_channel_type_contact_search_connect_to_search_state_changed (TpChannel *proxy
,tp_cli_channel_type_contact_search_signal_callback_search_state_changed callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
,GError **error
); gboolean tp_cli_channel_type_contact_search_run_more (TpChannel *proxy
,gint timeout_ms
,GError **error
,GMainLoop **loop
); gboolean tp_cli_channel_type_contact_search_run_search (TpChannel *proxy
,gint timeout_ms
,GHashTable *in_Terms
,GError **error
,GMainLoop **loop
); gboolean tp_cli_channel_type_contact_search_run_stop (TpChannel *proxy
,gint timeout_ms
,GError **error
,GMainLoop **loop
); void (*tp_cli_channel_type_contact_search_signal_callback_search_result_received) (TpChannel *proxy
,GHashTable *arg_Result
,gpointer user_data
,GObject *weak_object
); void (*tp_cli_channel_type_contact_search_signal_callback_search_state_changed) (TpChannel *proxy
,guint arg_State
,const gchar *arg_Error
,GHashTable *arg_Details
,gpointer user_data
,GObject *weak_object
);
Some instant messaging protocols allow searching for contacts by name or other details. In Telepathy, each search attempt is represented as a Channel.
This section documents the auto-generated C wrappers for the Contact Search channel type.
TpProxyPendingCall * tp_cli_channel_type_contact_search_call_more (TpChannel *proxy
,gint timeout_ms
,tp_cli_channel_type_contact_search_callback_for_more callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a More method call.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Request that a search in <tp:member-ref>SearchState</tp:member-ref> <code>More_Available</code> move back to state <code>In_Progress</code> and continue listing up to <tp:member-ref>Limit</tp:member-ref> more results.
|
the TpProxy |
|
the timeout in milliseconds, or -1 to use the default |
|
called when the method call succeeds or fails;
may be NULL to make a "fire and forget" call with no
reply tracking |
|
user-supplied data passed to the callback;
must be NULL if callback is NULL
|
|
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be NULL if callback is NULL
|
|
If not NULL , a GObject which will be
weakly referenced; if it is destroyed, this call
will automatically be cancelled. Must be NULL if
callback is NULL
|
Returns : |
a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid. |
TpProxyPendingCall * tp_cli_channel_type_contact_search_call_search (TpChannel *proxy
,gint timeout_ms
,GHashTable *in_Terms
,tp_cli_channel_type_contact_search_callback_for_search callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a Search method call.
Send a request to start a search for contacts on this connection. This may only be called while the <tp:member-ref>SearchState</tp:member-ref> is Not_Started; a valid search request will cause the <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted with the state In_Progress.
|
the TpProxy |
|
the timeout in milliseconds, or -1 to use the default |
|
Used to pass an 'in' argument: A dictionary mapping search key names to the desired values |
|
called when the method call succeeds or fails;
may be NULL to make a "fire and forget" call with no
reply tracking |
|
user-supplied data passed to the callback;
must be NULL if callback is NULL
|
|
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be NULL if callback is NULL
|
|
If not NULL , a GObject which will be
weakly referenced; if it is destroyed, this call
will automatically be cancelled. Must be NULL if
callback is NULL
|
Returns : |
a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid. |
TpProxyPendingCall * tp_cli_channel_type_contact_search_call_stop (TpChannel *proxy
,gint timeout_ms
,tp_cli_channel_type_contact_search_callback_for_stop callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a Stop method call.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Stop the current search. This may not be called while the <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called while the SearchState is In_Progress, <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted, with the state Failed and the error <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Cancelled</tp:error-ref></code>.</p> <p>Calling this method on a search in state Completed or Failed succeeds, but has no effect.</p> <tp:rationale> <p>Specifying Stop to succeed when the search has finished means that clients who call Stop just before receiving <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to handle a useless error.</p> </tp:rationale> <p>Depending on the protocol, the connection manager may not be able to prevent the server from sending further results after this method returns; if this is the case, it MUST ignore any further results.</p>
|
the TpProxy |
|
the timeout in milliseconds, or -1 to use the default |
|
called when the method call succeeds or fails;
may be NULL to make a "fire and forget" call with no
reply tracking |
|
user-supplied data passed to the callback;
must be NULL if callback is NULL
|
|
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be NULL if callback is NULL
|
|
If not NULL , a GObject which will be
weakly referenced; if it is destroyed, this call
will automatically be cancelled. Must be NULL if
callback is NULL
|
Returns : |
a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid. |
void (*tp_cli_channel_type_contact_search_callback_for_more) (TpChannel *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a More method call succeeds or fails.
|
the proxy on which the call was made |
|
NULL on success, or an error on failure |
|
user-supplied data |
|
user-supplied object |
void (*tp_cli_channel_type_contact_search_callback_for_search) (TpChannel *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a Search method call succeeds or fails.
|
the proxy on which the call was made |
|
NULL on success, or an error on failure |
|
user-supplied data |
|
user-supplied object |
void (*tp_cli_channel_type_contact_search_callback_for_stop) (TpChannel *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a Stop method call succeeds or fails.
|
the proxy on which the call was made |
|
NULL on success, or an error on failure |
|
user-supplied data |
|
user-supplied object |
TpProxySignalConnection * tp_cli_channel_type_contact_search_connect_to_search_result_received (TpChannel *proxy
,tp_cli_channel_type_contact_search_signal_callback_search_result_received callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
,GError **error
);
Connect a handler to the signal SearchResultReceived.
Emitted when a some search results are received from the server. This signal can be fired arbitrarily many times so clients MUST NOT assume they'll get only one signal.
|
A TpChannel or subclass |
|
Callback to be called when the signal is received |
|
User-supplied data for the callback |
|
Destructor for the user-supplied data, which
will be called when this signal is disconnected, or
before this function returns NULL
|
|
A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected |
|
If not NULL , used to raise an error if NULL is
returned |
Returns : |
a TpProxySignalConnection containing all of the
above, which can be used to disconnect the signal; or
NULL if the proxy does not have the desired interface
or has become invalid. |
TpProxySignalConnection * tp_cli_channel_type_contact_search_connect_to_search_state_changed (TpChannel *proxy
,tp_cli_channel_type_contact_search_signal_callback_search_state_changed callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
,GError **error
);
Connect a handler to the signal SearchStateChanged.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when the <tp:member-ref>SearchState</tp:member-ref> property changes. The implementation MUST NOT make transitions other than the following:</p> <ul> <li><code>Not_Started</code> → <code>In_Progress</code></li> <li><code>In_Progress</code> → <code>More_Available</code></li> <li><code>More_Available</code> → <code>In_Progress</code></li> <li><code>In_Progress</code> → <code>Completed</code></li> <li><code>In_Progress</code> → <code>Failed</code></li> </ul>
|
A TpChannel or subclass |
|
Callback to be called when the signal is received |
|
User-supplied data for the callback |
|
Destructor for the user-supplied data, which
will be called when this signal is disconnected, or
before this function returns NULL
|
|
A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected |
|
If not NULL , used to raise an error if NULL is
returned |
Returns : |
a TpProxySignalConnection containing all of the
above, which can be used to disconnect the signal; or
NULL if the proxy does not have the desired interface
or has become invalid. |
gboolean tp_cli_channel_type_contact_search_run_more (TpChannel *proxy
,gint timeout_ms
,GError **error
,GMainLoop **loop
);
tp_cli_channel_type_contact_search_run_more
is deprecated and should not be used in newly-written code.
Call the method More and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Request that a search in <tp:member-ref>SearchState</tp:member-ref> <code>More_Available</code> move back to state <code>In_Progress</code> and continue listing up to <tp:member-ref>Limit</tp:member-ref> more results.
|
A TpChannel or subclass |
|
Timeout in milliseconds, or -1 for default |
|
If not NULL , used to return errors if FALSE
is returned |
|
If not NULL , set before re-entering
the main loop, to point to a GMainLoop
which can be used to cancel this call with
g_main_loop_quit() , causing a return of
FALSE with error set to TP_DBUS_ERROR_CANCELLED
|
Returns : |
TRUE on success, FALSE and sets error on error |
gboolean tp_cli_channel_type_contact_search_run_search (TpChannel *proxy
,gint timeout_ms
,GHashTable *in_Terms
,GError **error
,GMainLoop **loop
);
tp_cli_channel_type_contact_search_run_search
is deprecated and should not be used in newly-written code.
Call the method Search and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.
Send a request to start a search for contacts on this connection. This may only be called while the <tp:member-ref>SearchState</tp:member-ref> is Not_Started; a valid search request will cause the <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted with the state In_Progress.
|
A TpChannel or subclass |
|
Timeout in milliseconds, or -1 for default |
|
Used to pass an 'in' argument: A dictionary mapping search key names to the desired values |
|
If not NULL , used to return errors if FALSE
is returned |
|
If not NULL , set before re-entering
the main loop, to point to a GMainLoop
which can be used to cancel this call with
g_main_loop_quit() , causing a return of
FALSE with error set to TP_DBUS_ERROR_CANCELLED
|
Returns : |
TRUE on success, FALSE and sets error on error |
gboolean tp_cli_channel_type_contact_search_run_stop (TpChannel *proxy
,gint timeout_ms
,GError **error
,GMainLoop **loop
);
tp_cli_channel_type_contact_search_run_stop
is deprecated and should not be used in newly-written code.
Call the method Stop and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Stop the current search. This may not be called while the <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called while the SearchState is In_Progress, <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted, with the state Failed and the error <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Cancelled</tp:error-ref></code>.</p> <p>Calling this method on a search in state Completed or Failed succeeds, but has no effect.</p> <tp:rationale> <p>Specifying Stop to succeed when the search has finished means that clients who call Stop just before receiving <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to handle a useless error.</p> </tp:rationale> <p>Depending on the protocol, the connection manager may not be able to prevent the server from sending further results after this method returns; if this is the case, it MUST ignore any further results.</p>
|
A TpChannel or subclass |
|
Timeout in milliseconds, or -1 for default |
|
If not NULL , used to return errors if FALSE
is returned |
|
If not NULL , set before re-entering
the main loop, to point to a GMainLoop
which can be used to cancel this call with
g_main_loop_quit() , causing a return of
FALSE with error set to TP_DBUS_ERROR_CANCELLED
|
Returns : |
TRUE on success, FALSE and sets error on error |
void (*tp_cli_channel_type_contact_search_signal_callback_search_result_received) (TpChannel *proxy
,GHashTable *arg_Result
,gpointer user_data
,GObject *weak_object
);
Represents the signature of a callback for the signal SearchResultReceived.
|
The proxy on which tp_cli_channel_type_contact_search_connect_to_search_result_received()
was called |
|
A mapping from contact identifier to an array of fields representing information about this contact. |
|
User-supplied data |
|
User-supplied weakly referenced object |
void (*tp_cli_channel_type_contact_search_signal_callback_search_state_changed) (TpChannel *proxy
,guint arg_State
,const gchar *arg_Error
,GHashTable *arg_Details
,gpointer user_data
,GObject *weak_object
);
Represents the signature of a callback for the signal SearchStateChanged.
|
The proxy on which tp_cli_channel_type_contact_search_connect_to_search_state_changed()
was called |
|
The new search state (TpChannelContactSearchState) |
|
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> If the new state is <code>Failed</code>, the name of a D-Bus error describing what went wrong. Otherwise, the empty string. |
|
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Additional information about the state transition, which may include the following well-known keys:</p> <dl> <dt>debug-message (s)</dt> <dd>Debugging information on the change, corresponding to the message part of a D-Bus error message, which SHOULD NOT be displayed to users under normal circumstances</dd> </dl> <tp:rationale> <p>This argument allows for future extensions. For instance, if moving to state <code>Failed</code> because the server rejected one of our search terms, we could define a key that indicates which terms were invalid.</p> </tp:rationale> |
|
User-supplied data |
|
User-supplied weakly referenced object |