Connection ContactInfo interface: telepathy-glib API Reference Manual

## Connection ContactInfo interface Connection ContactInfo interface — client-side wrappers for the ContactInfo interface |

## Functions

TpProxyPendingCall * | tp_cli_connection_interface_contact_info_call_get_contact_info ()
TpProxyPendingCall * | tp_cli_connection_interface_contact_info_call_refresh_contact_info ()
TpProxyPendingCall * | tp_cli_connection_interface_contact_info_call_request_contact_info ()
TpProxyPendingCall * | tp_cli_connection_interface_contact_info_call_set_contact_info ()
void | (*tp_cli_connection_interface_contact_info_callback_for_get_contact_info) ()
void | (*tp_cli_connection_interface_contact_info_callback_for_refresh_contact_info) ()
void | (*tp_cli_connection_interface_contact_info_callback_for_request_contact_info) ()
void | (*tp_cli_connection_interface_contact_info_callback_for_set_contact_info) ()
TpProxySignalConnection * | tp_cli_connection_interface_contact_info_connect_to_contact_info_changed ()
gboolean | tp_cli_connection_interface_contact_info_run_get_contact_info ()
gboolean | tp_cli_connection_interface_contact_info_run_refresh_contact_info ()
gboolean | tp_cli_connection_interface_contact_info_run_request_contact_info ()
gboolean | tp_cli_connection_interface_contact_info_run_set_contact_info ()
void | (*tp_cli_connection_interface_contact_info_signal_callback_contact_info_changed) ()

## Includes

    #include <telepathy-glib/telepathy-glib-dbus.h>

## Description

An interface for requesting information about a contact on a given connection. The information is represented as a list of fields forming a structured representation of a vCard (as defined by RFC 2426), using field names and semantics defined therein.

This section documents the auto-generated C wrappers for the ContactInfo interface, used with TpConnection objects.

## Functions

### tp_cli_connection_interface_contact_info_call_get_contact_info ()

    TpProxyPendingCall *
    tp_cli_connection_interface_contact_info_call_get_contact_info
                                   (TpConnection *proxy,
                                    gint timeout_ms,
                                    const GArray *in_Contacts,
                                    tp_cli_connection_interface_contact_info_callback_for_get_contact_info callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a GetContactInfo method call.

Request information on several contacts at once. This SHOULD only return cached information, omitting handles for which no information is cached from the returned map.

#### Parameters

proxy | the TpProxy |
timeout_ms | the timeout in milliseconds, or -1 to use the default |
in_Contacts | Used to pass an 'in' argument: An array of handles representing contacts. |
callback | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking |
user_data | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL` |
destroy | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL` |
weak_object | 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.

### tp_cli_connection_interface_contact_info_call_refresh_contact_info ()

    TpProxyPendingCall *
    tp_cli_connection_interface_contact_info_call_refresh_contact_info
                                   (TpConnection *proxy,
                                    gint timeout_ms,
                                    const GArray *in_Contacts,
                                    tp_cli_connection_interface_contact_info_callback_for_refresh_contact_info callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a RefreshContactInfo method call.

Retrieve information for the given contact, requesting it from the network if an up-to-date version is not cached locally. This method SHOULD return immediately, emitting <tp:member-ref>ContactInfoChanged</tp:member-ref> when the contacts' updated contact information is returned. <tp:rationale> This method allows a client with cached contact information to update its cache after a number of days. </tp:rationale>

#### Parameters

proxy | the TpProxy |
timeout_ms | the timeout in milliseconds, or -1 to use the default |
in_Contacts | Used to pass an 'in' argument: Integer handles for contacts. |
callback | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking |
user_data | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL` |
destroy | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL` |
weak_object | 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.

### tp_cli_connection_interface_contact_info_call_request_contact_info ()

    TpProxyPendingCall *
    tp_cli_connection_interface_contact_info_call_request_contact_info
                                   (TpConnection *proxy,
                                    gint timeout_ms,
                                    guint in_Contact,
                                    tp_cli_connection_interface_contact_info_callback_for_request_contact_info callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a RequestContactInfo method call.

Retrieve information for a contact, requesting it from the network if it is not cached locally. <tp:rationale> This method is appropriate for an explicit user request to show a contact's information; it allows a UI to wait for the contact info to be returned. </tp:rationale>

#### Parameters

proxy | the TpProxy |
timeout_ms | the timeout in milliseconds, or -1 to use the default |
in_Contact | Used to pass an 'in' argument: An integer handle for a contact. (TpContactHandle) |
callback | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking |
user_data | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL` |
destroy | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL` |
weak_object | 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.

### tp_cli_connection_interface_contact_info_call_set_contact_info ()

    TpProxyPendingCall *
    tp_cli_connection_interface_contact_info_call_set_contact_info
                                   (TpConnection *proxy,
                                    gint timeout_ms,
                                    const GPtrArray *in_ContactInfo,
                                    tp_cli_connection_interface_contact_info_callback_for_set_contact_info callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a SetContactInfo method call.

Set new contact information for this connection, replacing existing information. This method is only suppported if <tp:member-ref>ContactInfoFlags</tp:member-ref> contains <code>Can_Set</code>, and may only be passed fields conforming to <tp:member-ref>SupportedFields</tp:member-ref>.

#### Parameters

proxy | the TpProxy |
timeout_ms | the timeout in milliseconds, or -1 to use the default |
in_ContactInfo | Used to pass an 'in' argument: The new information to be set. |
callback | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking |
user_data | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL` |
destroy | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL` |
weak_object | 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.

### tp_cli_connection_interface_contact_info_callback_for_get_contact_info ()

    void
    (*tp_cli_connection_interface_contact_info_callback_for_get_contact_info)
                                   (TpConnection *proxy,
                                    GHashTable *out_ContactInfo,
                                    const GError *error,
                                    gpointer user_data,
                                    GObject *weak_object);

Signature of the callback called when a GetContactInfo method call succeeds or fails.

#### Parameters

proxy | the proxy on which the call was made |
out_ContactInfo | Used to return an 'out' argument if `error` is `NULL`: A dictionary mapping contact handles to information, whose keys are the subset of the requested list of handles for which information was cached. |
error | `NULL` on success, or an error on failure |
user_data | user-supplied data |
weak_object | user-supplied object |

### tp_cli_connection_interface_contact_info_callback_for_refresh_contact_info ()

    void
    (*tp_cli_connection_interface_contact_info_callback_for_refresh_contact_info)
                                   (TpConnection *proxy,
                                    const GError *error,
                                    gpointer user_data,
                                    GObject *weak_object);

Signature of the callback called when a RefreshContactInfo method call succeeds or fails.

#### Parameters

proxy | the proxy on which the call was made |
error | `NULL` on success, or an error on failure |
user_data | user-supplied data |
weak_object | user-supplied object |

### tp_cli_connection_interface_contact_info_callback_for_request_contact_info ()

    void
    (*tp_cli_connection_interface_contact_info_callback_for_request_contact_info)
                                   (TpConnection *proxy,
                                    const GPtrArray *out_Contact_Info,
                                    const GError *error,
                                    gpointer user_data,
                                    GObject *weak_object);

Signature of the callback called when a RequestContactInfo method call succeeds or fails.

#### Parameters

proxy | the proxy on which the call was made |
out_Contact_Info | Used to return an 'out' argument if `error` is `NULL`: Information about that contact. |
error | `NULL` on success, or an error on failure |
user_data | user-supplied data |
weak_object | user-supplied object |

### tp_cli_connection_interface_contact_info_callback_for_set_contact_info ()

    void
    (*tp_cli_connection_interface_contact_info_callback_for_set_contact_info)
                                   (TpConnection *proxy,
                                    const GError *error,
                                    gpointer user_data,
                                    GObject *weak_object);

Signature of the callback called when a SetContactInfo method call succeeds or fails.

#### Parameters

proxy | the proxy on which the call was made |
error | `NULL` on success, or an error on failure |
user_data | user-supplied data |
weak_object | user-supplied object |

### tp_cli_connection_interface_contact_info_connect_to_contact_info_changed ()

    TpProxySignalConnection *
    tp_cli_connection_interface_contact_info_connect_to_contact_info_changed
                                   (TpConnection *proxy,
                                    tp_cli_connection_interface_contact_info_signal_callback_contact_info_changed callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object,
                                    GError **error);

Connect a handler to the signal ContactInfoChanged.

Emitted when a contact's information has changed or been received for the first time on this connection.

#### Parameters

proxy | A TpConnection or subclass |
callback | Callback to be called when the signal is received |
user_data | User-supplied data for the callback |
destroy | Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL` |
weak_object | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected |
error | 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.

### tp_cli_connection_interface_contact_info_run_get_contact_info ()

    gboolean
    tp_cli_connection_interface_contact_info_run_get_contact_info
                                   (TpConnection *proxy,
                                    gint timeout_ms,
                                    const GArray *in_Contacts,
                                    GHashTable **out_ContactInfo,
                                    GError **error,
                                    GMainLoop **loop);

`tp_cli_connection_interface_contact_info_run_get_contact_info` is deprecated and should not be used in newly-written code.

Call the method GetContactInfo 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.

Request information on several contacts at once. This SHOULD only return cached information, omitting handles for which no information is cached from the returned map.

#### Parameters

proxy | A TpConnection or subclass |
timeout_ms | Timeout in milliseconds, or -1 for default |
in_Contacts | Used to pass an 'in' argument: An array of handles representing contacts. |
out_ContactInfo | Used to return an 'out' argument if `TRUE` is returned: A dictionary mapping contact handles to information, whose keys are the subset of the requested list of handles for which information was cached. |
error | If not `NULL`, used to return errors if `FALSE` is returned |
loop | 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

### tp_cli_connection_interface_contact_info_run_refresh_contact_info ()

    gboolean
    tp_cli_connection_interface_contact_info_run_refresh_contact_info
                                   (TpConnection *proxy,
                                    gint timeout_ms,
                                    const GArray *in_Contacts,
                                    GError **error,
                                    GMainLoop **loop);

`tp_cli_connection_interface_contact_info_run_refresh_contact_info` is deprecated and should not be used in newly-written code.

Call the method RefreshContactInfo 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.

Retrieve information for the given contact, requesting it from the network if an up-to-date version is not cached locally. This method SHOULD return immediately, emitting <tp:member-ref>ContactInfoChanged</tp:member-ref> when the contacts' updated contact information is returned. <tp:rationale> This method allows a client with cached contact information to update its cache after a number of days. </tp:rationale>

#### Parameters

proxy | A TpConnection or subclass |
timeout_ms | Timeout in milliseconds, or -1 for default |
in_Contacts | Used to pass an 'in' argument: Integer handles for contacts. |
error | If not `NULL`, used to return errors if `FALSE` is returned |
loop | 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

### tp_cli_connection_interface_contact_info_run_request_contact_info ()

    gboolean
    tp_cli_connection_interface_contact_info_run_request_contact_info
                                   (TpConnection *proxy,
                                    gint timeout_ms,
                                    guint in_Contact,
                                    GPtrArray **out_Contact_Info,
                                    GError **error,
                                    GMainLoop **loop);

`tp_cli_connection_interface_contact_info_run_request_contact_info` is deprecated and should not be used in newly-written code.

Call the method RequestContactInfo 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.

Retrieve information for a contact, requesting it from the network if it is not cached locally. <tp:rationale> This method is appropriate for an explicit user request to show a contact's information; it allows a UI to wait for the contact info to be returned. </tp:rationale>

#### Parameters

proxy | A TpConnection or subclass |
timeout_ms | Timeout in milliseconds, or -1 for default |
in_Contact | Used to pass an 'in' argument: An integer handle for a contact. (TpContactHandle) |
out_Contact_Info | Used to return an 'out' argument if `TRUE` is returned: Information about that contact. |
error | If not `NULL`, used to return errors if `FALSE` is returned |
loop | 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

### tp_cli_connection_interface_contact_info_run_set_contact_info ()

    gboolean
    tp_cli_connection_interface_contact_info_run_set_contact_info
                                   (TpConnection *proxy,
                                    gint timeout_ms,
                                    const GPtrArray *in_ContactInfo,
                                    GError **error,
                                    GMainLoop **loop);

`tp_cli_connection_interface_contact_info_run_set_contact_info` is deprecated and should not be used in newly-written code.

Call the method SetContactInfo 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.

Set new contact information for this connection, replacing existing information. This method is only suppported if <tp:member-ref>ContactInfoFlags</tp:member-ref> contains <code>Can_Set</code>, and may only be passed fields conforming to <tp:member-ref>SupportedFields</tp:member-ref>.

#### Parameters

proxy | A TpConnection or subclass |
timeout_ms | Timeout in milliseconds, or -1 for default |
in_ContactInfo | Used to pass an 'in' argument: The new information to be set. |
error | If not `NULL`, used to return errors if `FALSE` is returned |
loop | 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

### tp_cli_connection_interface_contact_info_signal_callback_contact_info_changed ()

    void
    (*tp_cli_connection_interface_contact_info_signal_callback_contact_info_changed)
                                   (TpConnection *proxy,
                                    guint arg_Contact,
                                    const GPtrArray *arg_ContactInfo,
                                    gpointer user_data,
                                    GObject *weak_object);

Represents the signature of a callback for the signal ContactInfoChanged.

#### Parameters

proxy | The proxy on which `tp_cli_connection_interface_contact_info_connect_to_contact_info_changed()` was called |
arg_Contact | An integer handle for the contact whose info has changed. (TpContactHandle) |
arg_ContactInfo | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of fields representing information about this contact. |
user_data | User-supplied data |
weak_object | User-supplied weakly referenced object |

## See Also

TpConnection