FolksImFieldDetails: Reference Manual

## FolksImFieldDetails FolksImFieldDetails — Object representing an IM address value that can have some parameters associated with it. |

## Functions

FolksImFieldDetails * | folks_im_field_details_new ()
void | folks_im_details_change_im_addresses ()
void | folks_im_details_change_im_addresses_finish ()
GeeMultiMap * | folks_im_details_get_im_addresses ()
void | folks_im_details_set_im_addresses ()
gchar * | folks_im_details_normalise_im_address ()

## Types and Values

#define | FOLKS_TYPE_IM_FIELD_DETAILS
struct | FolksImFieldDetails
struct | FolksImFieldDetailsClass
enum | FolksImDetailsError
| FolksImDetails
struct | FolksImDetailsIface

## Description

See FolksAbstractFieldDetails.

## Functions

### folks_im_field_details_new ()

    FolksImFieldDetails *
    folks_im_field_details_new (const gchar *value,
                                GeeMultiMap *parameters);

Create a new ImFieldDetails.

#### Parameters

value | . the value of the field, which should be a valid, non-empty IM address . | [in]
parameters | . initial parameters. See "parameters". A `null` value is equivalent to an empty map of parameters. . | [in][allow-none]

#### Returns

a new ImFieldDetails

Since: 0.6.0

### folks_im_details_change_im_addresses ()

    void
    folks_im_details_change_im_addresses (FolksImDetails *self,
                                          GeeMultiMap *im_addresses,
                                          GAsyncReadyCallback _callback_,
                                          gpointer _user_data_);

Change the contact's set of IM addresses.

It's preferred to call this rather than setting "im-addresses" directly, as this method gives error notification and will only return once the IM addresses have been written to the relevant backing store (or the operation's failed).

FolksPropertyError will be returned in `error`

if setting the IM addresses failed

See also: `folks_im_details_change_im_addresses_finish()`

#### Parameters

self | the FolksImDetails instance |
im_addresses | . the new map of protocols to IM addresses . | [in]
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to `_callback_` function. | [closure]

Since: 0.6.2

### folks_im_details_change_im_addresses_finish ()

    void
    folks_im_details_change_im_addresses_finish
                                   (FolksImDetails *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Change the contact's set of IM addresses.

It's preferred to call this rather than setting "im-addresses" directly, as this method gives error notification and will only return once the IM addresses have been written to the relevant backing store (or the operation's failed).

FolksPropertyError will be returned in `error`

if setting the IM addresses failed

See also: `folks_im_details_change_im_addresses()`

#### Parameters

self | the FolksImDetails instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore. | [error-domains FolksPropertyError]

Since: 0.6.2

### folks_im_details_get_im_addresses ()

    GeeMultiMap *
    folks_im_details_get_im_addresses (FolksImDetails *self);

Get and return the current value of the "im-addresses" property.

A mapping of IM protocol to an (unordered) set of IM addresses.

Each mapping is from an arbitrary protocol identifier to a set of IM addresses on that protocol for the contact, listed in no particular order.

There must be no duplicate IM addresses in each set, though a given IM address may be present in the sets for different protocols.

All the IM addresses must be normalised using `folks_im_details_normalise_im_address()` before being added to this property.

#### Parameters

self | the FolksImDetails instance to query |

#### Returns

the value of the "im-addresses" property

Since: 0.5.1

### folks_im_details_set_im_addresses ()

    void
    folks_im_details_set_im_addresses (FolksImDetails *self,
                                       GeeMultiMap *value);

Set the value of the "im-addresses" property to `value` .

A mapping of IM protocol to an (unordered) set of IM addresses.

Each mapping is from an arbitrary protocol identifier to a set of IM addresses on that protocol for the contact, listed in no particular order.

There must be no duplicate IM addresses in each set, though a given IM address may be present in the sets for different protocols.

All the IM addresses must be normalised using `folks_im_details_normalise_im_address()` before being added to this property.

#### Parameters

self | the FolksImDetails instance to modify |
value | the new value of the "im-addresses" property |

Since: 0.5.1

### folks_im_details_normalise_im_address ()

    gchar *
    folks_im_details_normalise_im_address (const gchar *im_address,
                                           const gchar *protocol,
                                           GError **error);

Normalise an IM address so that it's suitable for string comparison.

IM addresses for various protocols can be represented in different ways, only one of which is canonical. In order to allow simple string comparisons of IM addresses to work, the IM addresses must be normalised beforehand.

If the provided IM address is invalid, `FOLKS_IM_DETAILS_ERROR_INVALID_IM_ADDRESS` will be thrown. Note that this isn't guaranteed to be thrown for all invalid addresses, but if it is thrown, the address is guaranteed to be invalid.

FolksImDetailsError will be returned in `error`

if the provided IM address was invalid

#### Parameters

im_address | . the address to normalise . | [in]
protocol | . the protocol of this im_address . | [in]
error | location to store the error occurring, or `NULL` to ignore. | [error-domains FolksImDetailsError]

Since: 0.2.0

## Types and Values

### FOLKS_TYPE_IM_FIELD_DETAILS

    #define FOLKS_TYPE_IM_FIELD_DETAILS (folks_im_field_details_get_type ())

The type for FolksImFieldDetails.

### struct FolksImFieldDetails

    struct FolksImFieldDetails {
    	FolksAbstractFieldDetails parent_instance;
    	FolksImFieldDetailsPrivate * priv;
    };

Object representing an IM address value that can have some parameters associated with it.

See FolksAbstractFieldDetails.

Since: 0.6.0

### struct FolksImFieldDetailsClass

    struct FolksImFieldDetailsClass {
    	FolksAbstractFieldDetailsClass parent_class;
    };

The class structure for `FOLKS_TYPE_IM_FIELD_DETAILS`. All the fields in this structure are private and should never be accessed directly.

#### Members

### enum FolksImDetailsError

Errors related to IM addresses and IM address handling.

#### Members

FOLKS_IM_DETAILS_ERROR_INVALID_IM_ADDRESS | The specified IM address could not be parsed. |

### FolksImDetails

    typedef struct _FolksImDetails FolksImDetails;

IM addresses exposed by an object implementing FolksPresenceDetails.

Since: 0.1.13

### struct FolksImDetailsIface

    struct FolksImDetailsIface {
    	GTypeInterface parent_iface;
    	void (*change_im_addresses) (FolksImDetails* self, GeeMultiMap* im_addresses, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	void (*change_im_addresses_finish) (FolksImDetails* self, GAsyncResult* _res_, GError** error);
    	GeeMultiMap* (*get_im_addresses) (FolksImDetails* self);
    	void (*set_im_addresses) (FolksImDetails* self, GeeMultiMap* value);
    };

Interface for creating FolksImDetails implementations.

#### Members

GTypeInterface `parent_iface`; | the parent interface structure |
`change_im_addresses` () | virtual method called by `folks_im_details_change_im_addresses()` |
`change_im_addresses_finish` () | asynchronous finish function for `change_im_addresses`, called by `folks_im_details_change_im_addresses()` |
`get_im_addresses` () | getter method for the abstract property "im-addresses" |
`set_im_addresses` () | setter method for the abstract property "im-addresses" |