FolksAbstractFieldDetails: Reference Manual

## FolksAbstractFieldDetails FolksAbstractFieldDetails — Object representing any type of value that can have some vCard-like parameters associated with it. |

## Functions

GeeCollection * | folks_abstract_field_details_get_parameter_values ()
void | folks_abstract_field_details_add_parameter ()
void | folks_abstract_field_details_set_parameter ()
void | folks_abstract_field_details_extend_parameters ()
void | folks_abstract_field_details_remove_parameter_all ()
gboolean | folks_abstract_field_details_equal ()
gboolean | folks_abstract_field_details_parameters_equal ()
gboolean | folks_abstract_field_details_values_equal ()
guint | folks_abstract_field_details_hash ()
gconstpointer | folks_abstract_field_details_get_value ()
void | folks_abstract_field_details_set_value ()
GType | folks_abstract_field_details_get_value_type ()
const gchar * | folks_abstract_field_details_get_id ()
void | folks_abstract_field_details_set_id ()
GeeMultiMap * | folks_abstract_field_details_get_parameters ()
void | folks_abstract_field_details_set_parameters ()
gboolean | folks_abstract_field_details_equal_static ()
guint | folks_abstract_field_details_hash_static ()

## Types and Values

#define | FOLKS_TYPE_ABSTRACT_FIELD_DETAILS
#define | FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE
#define | FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_HOME
#define | FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_WORK
#define | FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_OTHER
struct | FolksAbstractFieldDetails
struct | FolksAbstractFieldDetailsClass

## Description

Some contact details, like phone numbers or URLs, can have some extra details associated with them. For instance, a phone number expressed in vcard notation as `tel;type=work,voice:(111) 555-1234` would be represented as a AbstractFieldDetails with value "(111) 555-1234" and with parameters `['type': ('work', 'voice')]`.

The parameter name "type" with values "work", "home", or "other" are common amongst most vCard attributes (and thus most AbstractFieldDetails-derived classes). A "type" of "pref" may be used to indicate a preferred "value" amongst many. See specific classes for information on additional parameters and values specific to that class.

See RFC2426 for more details on pre-defined parameter names and values.

## Functions

### folks_abstract_field_details_get_parameter_values ()

    GeeCollection *
    folks_abstract_field_details_get_parameter_values
                                   (FolksAbstractFieldDetails *self,
                                    const gchar *parameter_name);

Get the values for a parameter

#### Parameters

self | the FolksAbstractFieldDetails instance |
parameter_name | . the parameter name . | [in]

#### Returns

a collection of values for `parameter_name` or `null` (i.e. no collection) if there are no such parameters.

Since: 0.6.0

### folks_abstract_field_details_add_parameter ()

    void
    folks_abstract_field_details_add_parameter
                                   (FolksAbstractFieldDetails *self,
                                    const gchar *parameter_name,
                                    const gchar *parameter_value);

Add a new value for a parameter.

If there is already a parameter called `parameter_name` then `parameter_value` is added to the existing ones.

#### Parameters

self | the FolksAbstractFieldDetails instance |
parameter_name | . the name of the parameter . | [in]
parameter_value | . the value to add . | [in]

Since: 0.6.0

### folks_abstract_field_details_set_parameter ()

    void
    folks_abstract_field_details_set_parameter
                                   (FolksAbstractFieldDetails *self,
                                    const gchar *parameter_name,
                                    const gchar *parameter_value);

Set the value of a parameter.

Sets the parameter called `parameter_name` to be `parameter_value`. If there were already parameters with the same name they are replaced.

#### Parameters

self | the FolksAbstractFieldDetails instance |
parameter_name | . the name of the parameter . | [in]
parameter_value | . the value to add . | [in]

Since: 0.6.0

### folks_abstract_field_details_extend_parameters ()

    void
    folks_abstract_field_details_extend_parameters
                                   (FolksAbstractFieldDetails *self,
                                    GeeMultiMap *additional);

Extend the existing parameters.

Merge the parameters from `additional` into the existing ones.

#### Parameters

self | the FolksAbstractFieldDetails instance |
additional | . the parameters to add . | [in]

Since: 0.6.0

### folks_abstract_field_details_remove_parameter_all ()

    void
    folks_abstract_field_details_remove_parameter_all
                                   (FolksAbstractFieldDetails *self,
                                    const gchar *parameter_name);

Remove all instances of a parameter.

#### Parameters

self | the FolksAbstractFieldDetails instance |
parameter_name | . the name of the parameter . | [in]

Since: 0.6.0

### folks_abstract_field_details_equal ()

    gboolean
    folks_abstract_field_details_equal (FolksAbstractFieldDetails *self,
                                        FolksAbstractFieldDetails *that);

A fairly-strict equality function for FolksAbstractFieldDetails.

This function compares:

- "value"s

- "parameters"

And does not compare:

- "id"s

See the description of `folks_abstract_field_details_values_equal()` for details on the value comparison.

To check equality not including the parameters, see `folks_abstract_field_details_values_equal()`.

See also: `folks_abstract_field_details_parameters_equal()`, `folks_abstract_field_details_values_equal()`

#### Parameters

self | the FolksAbstractFieldDetails instance |
that | . another FolksAbstractFieldDetails . | [in]

#### Returns

whether the elements are equal

Since: 0.6.0

### folks_abstract_field_details_parameters_equal ()

    gboolean
    folks_abstract_field_details_parameters_equal
                                   (FolksAbstractFieldDetails *self,
                                    FolksAbstractFieldDetails *that);

An equality function which only considers parameters.

This function compares:

- "parameters"

And does not compare:

- "value"s

- "id"s

See also: `folks_abstract_field_details_equal()`, `folks_abstract_field_details_values_equal()`

#### Parameters

self | the FolksAbstractFieldDetails instance |
that | . another FolksAbstractFieldDetails . | [in]

#### Returns

whether the elements' "value"s are equal.

Since: 0.6.5

### folks_abstract_field_details_values_equal ()

    gboolean
    folks_abstract_field_details_values_equal
                                   (FolksAbstractFieldDetails *self,
                                    FolksAbstractFieldDetails *that);

An equality function which does not consider parameters.

Specific classes may override this function to provide "smart" value comparisons (eg, considering the phone number values "+1 555 123 4567" and "123-4567" equal). If you wish to do strict comparisons, simply compare the "value"s directly.

This function compares:

- "value"s

And does not compare:

- "parameters"

- "id"s

This defaults to string comparison of the "value"s if the generic type is string; otherwise, direct pointer comparison of the "value"s.

See also: `folks_abstract_field_details_equal()`, `folks_abstract_field_details_parameters_equal()`

#### Parameters

self | the FolksAbstractFieldDetails instance |
that | . another FolksAbstractFieldDetails . | [in]

#### Returns

whether the elements' "value"s are equal.

Since: 0.6.5

### folks_abstract_field_details_hash ()

    guint
    folks_abstract_field_details_hash (FolksAbstractFieldDetails *self);

A hash function for the FolksAbstractFieldDetails.

This defaults to a string hash of the "value" if the generic type is string; otherwise, direct hash of the "value".

#### Parameters

self | the FolksAbstractFieldDetails instance |

#### Returns

the hash value

Since: 0.6.0

### folks_abstract_field_details_get_value ()

    gconstpointer
    folks_abstract_field_details_get_value
                                   (FolksAbstractFieldDetails *self);

Get and return the current value of the "value" property.

The value of the field.

The value of the field, the exact type and content of which depends on what the structure is used for.

#### Parameters

self | the FolksAbstractFieldDetails instance to query |

#### Returns

the value of the "value" property of type “t-type”

Since: 0.6.0

### folks_abstract_field_details_set_value ()

    void
    folks_abstract_field_details_set_value
                                   (FolksAbstractFieldDetails *self,
                                    gconstpointer value);

Set the value of the "value" property to `value` .

The value of the field.

The value of the field, the exact type and content of which depends on what the structure is used for.

#### Parameters

self | the FolksAbstractFieldDetails instance to modify |
value | the new value of the "value" property of type “t-type” |

Since: 0.6.0

### folks_abstract_field_details_get_value_type ()

    GType
    folks_abstract_field_details_get_value_type
                                   (FolksAbstractFieldDetails *self);

Get and return the current value of the "value-type" property.

The GType of the "value".

This is particularly useful for treating collections of different types of FolksAbstractFieldDetails in a uniform way without needing to name them explicitly.

#### Parameters

self | the FolksAbstractFieldDetails instance to query |

#### Returns

the value of the "value-type" property

Since: 0.6.5

### folks_abstract_field_details_get_id ()

    const gchar *
    folks_abstract_field_details_get_id (FolksAbstractFieldDetails *self);

Get and return the current value of the "id" property.

A unique ID (if any) for this specific detail.

This is primarily intended for FolksPersonaStores which need to track specific instances of details (because their backing store is wacky).

In most cases, this will be an empty string.

The content of this is opaque to all but the package which set it.

#### Parameters

self | the FolksAbstractFieldDetails instance to query |

#### Returns

the value of the "id" property

Since: 0.6.5

### folks_abstract_field_details_set_id ()

    void
    folks_abstract_field_details_set_id (FolksAbstractFieldDetails *self,
                                         const gchar *value);

Set the value of the "id" property to `value` .

A unique ID (if any) for this specific detail.

This is primarily intended for FolksPersonaStores which need to track specific instances of details (because their backing store is wacky).

In most cases, this will be an empty string.

The content of this is opaque to all but the package which set it.

#### Parameters

self | the FolksAbstractFieldDetails instance to modify |
value | the new value of the "id" property |

Since: 0.6.5

### folks_abstract_field_details_get_parameters ()

    GeeMultiMap *
    folks_abstract_field_details_get_parameters
                                   (FolksAbstractFieldDetails *self);

Get and return the current value of the "parameters" property.

The parameters associated with the value.

A multi-map of the parameters associated with "value". The keys are the names of the parameters, while the values are a list of strings.

#### Parameters

self | the FolksAbstractFieldDetails instance to query |

#### Returns

the value of the "parameters" property

Since: 0.6.0

### folks_abstract_field_details_set_parameters ()

    void
    folks_abstract_field_details_set_parameters
                                   (FolksAbstractFieldDetails *self,
                                    GeeMultiMap *value);

Set the value of the "parameters" property to `value` .

The parameters associated with the value.

A multi-map of the parameters associated with "value". The keys are the names of the parameters, while the values are a list of strings.

#### Parameters

self | the FolksAbstractFieldDetails instance to modify |
value | the new value of the "parameters" property |

Since: 0.6.0

### folks_abstract_field_details_equal_static ()

    gboolean
    folks_abstract_field_details_equal_static
                                   (FolksAbstractFieldDetails *left,
                                    FolksAbstractFieldDetails *right);

Same as `folks_abstract_field_details_equal()`, but static, so we can use libgee 0.8 without an API break.

See 673918 This can and should be removed next time we break the API. Note: This uses Gee.EqualDataFunc signature, to avoid having to cast.

#### Parameters

left | . one FolksAbstractFieldDetails to compare . | [in]
right | . another FolksAbstractFieldDetails to compare . | [in]

#### Returns

whether the elemants are equal

Since: 0.9.0

### folks_abstract_field_details_hash_static ()

    guint
    folks_abstract_field_details_hash_static
                                   (FolksAbstractFieldDetails *value);

Same as `folks_abstract_field_details_hash()`, but static, so we can use libgee 0.8 without an API break.

See 673918 This can and should be removed next time we break the API. Note: This uses Gee.HashDataFunc signature, to avoid having to cast.

#### Parameters

value | . the value to hash . | [in]

#### Returns

the hash value

Since: 0.9.0

## Types and Values

### FOLKS_TYPE_ABSTRACT_FIELD_DETAILS

    #define FOLKS_TYPE_ABSTRACT_FIELD_DETAILS (folks_abstract_field_details_get_type ())

The type for FolksAbstractFieldDetails.

### FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE

    #define FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE "type"

Parameter name for classifying the type of value this field contains.

For example, the value could be relevant to the contact's home life, or to their work life; values of `FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_HOME` and `FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_WORK` would be used for the `FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE` parameter, respectively, in those cases.

Since: 0.6.3

### FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_HOME

    #define FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_HOME "home"

Parameter value for home-related field values.

Value for a parameter with name `FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE`.

Since: 0.6.3

### FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_WORK

    #define FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_WORK "work"

Parameter value for work-related field values.

Value for a parameter with name `FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE`.

Since: 0.6.3

### FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_OTHER

    #define FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE_OTHER "other"

Parameter value for miscellaneous field values.

Value for a parameter with name `FOLKS_ABSTRACT_FIELD_DETAILS_PARAM_TYPE`.

Since: 0.6.3

### struct FolksAbstractFieldDetails

    struct FolksAbstractFieldDetails {
    	GObject parent_instance;
    	FolksAbstractFieldDetailsPrivate * priv;
    };

Object representing any type of value that can have some vCard-like parameters associated with it.

Some contact details, like phone numbers or URLs, can have some extra details associated with them. For instance, a phone number expressed in vcard notation as `tel;type=work,voice:(111) 555-1234` would be represented as a AbstractFieldDetails with value "(111) 555-1234" and with parameters `['type': ('work', 'voice')]`.

The parameter name "type" with values "work", "home", or "other" are common amongst most vCard attributes (and thus most AbstractFieldDetails-derived classes). A "type" of "pref" may be used to indicate a preferred "value" amongst many. See specific classes for information on additional parameters and values specific to that class.

See RFC2426 for more details on pre-defined parameter names and values.

Since: 0.6.0

### struct FolksAbstractFieldDetailsClass

    struct FolksAbstractFieldDetailsClass {
    	GObjectClass parent_class;
    	gboolean (*equal) (FolksAbstractFieldDetails* self, FolksAbstractFieldDetails* that);
    	gboolean (*parameters_equal) (FolksAbstractFieldDetails* self, FolksAbstractFieldDetails* that);
    	gboolean (*values_equal) (FolksAbstractFieldDetails* self, FolksAbstractFieldDetails* that);
    	guint (*hash) (FolksAbstractFieldDetails* self);
    	gconstpointer (*get_value) (FolksAbstractFieldDetails* self);
    	void (*set_value) (FolksAbstractFieldDetails* self, gconstpointer value);
    	const gchar* (*get_id) (FolksAbstractFieldDetails* self);
    	void (*set_id) (FolksAbstractFieldDetails* self, const gchar* value);
    	GeeMultiMap* (*get_parameters) (FolksAbstractFieldDetails* self);
    	void (*set_parameters) (FolksAbstractFieldDetails* self, GeeMultiMap* value);
    };

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

#### Members

`equal` () | virtual method called by `folks_abstract_field_details_equal()` |
`parameters_equal` () | virtual method called by `folks_abstract_field_details_parameters_equal()` |
`values_equal` () | virtual method called by `folks_abstract_field_details_values_equal()` |
`hash` () | virtual method called by `folks_abstract_field_details_hash()` |
`get_value` () | getter method for the abstract property "value" |
`set_value` () |  |
`get_id` () | getter method for the abstract property "id" |
`set_id` () | setter method for the abstract property "id" |
`get_parameters` () | getter method for the abstract property "parameters" |
`set_parameters` () |  |