FolksStructuredName: Reference Manual

## FolksStructuredName FolksStructuredName — Structured name representation for human names. |

## Functions

gboolean | folks_structured_name_is_empty ()
gboolean | folks_structured_name_equal ()
gchar * | folks_structured_name_to_string ()
gchar * | folks_structured_name_to_string_with_format ()
FolksStructuredName * | folks_structured_name_new ()
FolksStructuredName * | folks_structured_name_new_simple ()
const gchar * | folks_structured_name_get_family_name ()
void | folks_structured_name_set_family_name ()
const gchar * | folks_structured_name_get_given_name ()
void | folks_structured_name_set_given_name ()
const gchar * | folks_structured_name_get_additional_names ()
void | folks_structured_name_set_additional_names ()
const gchar * | folks_structured_name_get_prefixes ()
void | folks_structured_name_set_prefixes ()
const gchar * | folks_structured_name_get_suffixes ()
void | folks_structured_name_set_suffixes ()
void | folks_name_details_change_structured_name ()
void | folks_name_details_change_structured_name_finish ()
void | folks_name_details_change_full_name ()
void | folks_name_details_change_full_name_finish ()
void | folks_name_details_change_nickname ()
void | folks_name_details_change_nickname_finish ()
FolksStructuredName * | folks_name_details_get_structured_name ()
void | folks_name_details_set_structured_name ()
const gchar * | folks_name_details_get_full_name ()
void | folks_name_details_set_full_name ()
const gchar * | folks_name_details_get_nickname ()
void | folks_name_details_set_nickname ()

## Types and Values

#define | FOLKS_TYPE_STRUCTURED_NAME
struct | FolksStructuredName
struct | FolksStructuredNameClass
| FolksNameDetails
struct | FolksNameDetailsIface

## Description

Represents a full name split in its constituent parts (given name, family name, etc.). This structure corresponds to the "N" field in vCards. The parts of the name are never `null`: an empty string indicates that a property is not set.

## Functions

### folks_structured_name_is_empty ()

    gboolean
    folks_structured_name_is_empty (FolksStructuredName *self);

Whether none of the components is set.

#### Parameters

self | the FolksStructuredName instance |

#### Returns

`true` if all the components are the empty string, `false` otherwise.

Since: 0.3.5

### folks_structured_name_equal ()

    gboolean
    folks_structured_name_equal (FolksStructuredName *self,
                                 FolksStructuredName *other);

Whether two StructuredNames are the same.

#### Parameters

self | the FolksStructuredName instance |
other | . the other structured name to compare with . | [in]

#### Returns

`true` if all the components are the same, `false` otherwise.

Since: 0.5.0

### folks_structured_name_to_string ()

    gchar *
    folks_structured_name_to_string (FolksStructuredName *self);

Formatted version of the structured name.

#### Parameters

self | the FolksStructuredName instance |

#### Returns

name formatted according to the current locale

Since: 0.4.0

### folks_structured_name_to_string_with_format ()

    gchar *
    folks_structured_name_to_string_with_format
                                   (FolksStructuredName *self,
                                    const gchar *name_fmt);

Formatted version of the structured name.

This allows a custom format string to be specified, using the placeholders described on http://lh.2xlibre.net/values/name_fmt/. This `name_fmt` must almost always be translated to the current locale. (Ideally it would be translated to the locale of the persona whose name is being formatted, but such locale information isn’t available.)

#### Parameters

self | the FolksStructuredName instance |
name_fmt | . format string for the name . | [in]

#### Returns

name formatted according to the given format

Since: 0.9.7

### folks_structured_name_new ()

    FolksStructuredName *
    folks_structured_name_new (const gchar *family_name,
                               const gchar *given_name,
                               const gchar *additional_names,
                               const gchar *prefixes,
                               const gchar *suffixes);

Create a StructuredName.

You can pass `null` if a component is not set.

#### Parameters

family_name | . the family (last) name . | [in][allow-none]
given_name | . the given (first) name . | [in][allow-none]
additional_names | . additional names . | [in][allow-none]
prefixes | . prefixes of the name . | [in][allow-none]
suffixes | . suffixes of the name . | [in][allow-none]

#### Returns

a new StructuredName

Since: 0.3.5

### folks_structured_name_new_simple ()

    FolksStructuredName *
    folks_structured_name_new_simple (const gchar *family_name,
                                      const gchar *given_name);

Create a StructuredName.

Shorthand for the common case of just having the family and given name of a contact. It's equivalent to calling `folks_structured_name_new()` and passing `null` for all the other components.

#### Parameters

family_name | . the family (last) name . | [in][allow-none]
given_name | . the given (first) name . | [in][allow-none]

#### Returns

a new StructuredName

Since: 0.3.5

### folks_structured_name_get_family_name ()

    const gchar *
    folks_structured_name_get_family_name (FolksStructuredName *self);

Get and return the current value of the "family-name" property.

The family name.

The family name (also known as surname or last name) of a contact.

#### Parameters

self | the FolksStructuredName instance to query |

#### Returns

the value of the "family-name" property

Since: 0.3.5

### folks_structured_name_set_family_name ()

    void
    folks_structured_name_set_family_name (FolksStructuredName *self,
                                           const gchar *value);

Set the value of the "family-name" property to `value` .

The family name.

The family name (also known as surname or last name) of a contact.

#### Parameters

self | the FolksStructuredName instance to modify |
value | the new value of the "family-name" property |

Since: 0.3.5

### folks_structured_name_get_given_name ()

    const gchar *
    folks_structured_name_get_given_name (FolksStructuredName *self);

Get and return the current value of the "given-name" property.

The given name.

The family name (also known as first name) of a contact.

#### Parameters

self | the FolksStructuredName instance to query |

#### Returns

the value of the "given-name" property

Since: 0.3.5

### folks_structured_name_set_given_name ()

    void
    folks_structured_name_set_given_name (FolksStructuredName *self,
                                          const gchar *value);

Set the value of the "given-name" property to `value` .

The given name.

The family name (also known as first name) of a contact.

#### Parameters

self | the FolksStructuredName instance to modify |
value | the new value of the "given-name" property |

Since: 0.3.5

### folks_structured_name_get_additional_names ()

    const gchar *
    folks_structured_name_get_additional_names
                                   (FolksStructuredName *self);

Get and return the current value of the "additional-names" property.

Additional names.

The additional names of a contact, for instance the contact's middle name.

#### Parameters

self | the FolksStructuredName instance to query |

#### Returns

the value of the "additional-names" property

Since: 0.3.5

### folks_structured_name_set_additional_names ()

    void
    folks_structured_name_set_additional_names
                                   (FolksStructuredName *self,
                                    const gchar *value);

Set the value of the "additional-names" property to `value` .

Additional names.

The additional names of a contact, for instance the contact's middle name.

#### Parameters

self | the FolksStructuredName instance to modify |
value | the new value of the "additional-names" property |

Since: 0.3.5

### folks_structured_name_get_prefixes ()

    const gchar *
    folks_structured_name_get_prefixes (FolksStructuredName *self);

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

The prefixes of a name.

The prefixes used in front of the name (for instance "Mr", "Mrs", "Doctor" or honorific titles).

#### Parameters

self | the FolksStructuredName instance to query |

#### Returns

the value of the "prefixes" property

Since: 0.3.5

### folks_structured_name_set_prefixes ()

    void
    folks_structured_name_set_prefixes (FolksStructuredName *self,
                                        const gchar *value);

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

The prefixes of a name.

The prefixes used in front of the name (for instance "Mr", "Mrs", "Doctor" or honorific titles).

#### Parameters

self | the FolksStructuredName instance to modify |
value | the new value of the "prefixes" property |

Since: 0.3.5

### folks_structured_name_get_suffixes ()

    const gchar *
    folks_structured_name_get_suffixes (FolksStructuredName *self);

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

The suffixes of a name.

The suffixes used after a name (for instance "PhD" or "Junior").

#### Parameters

self | the FolksStructuredName instance to query |

#### Returns

the value of the "suffixes" property

Since: 0.3.5

### folks_structured_name_set_suffixes ()

    void
    folks_structured_name_set_suffixes (FolksStructuredName *self,
                                        const gchar *value);

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

The suffixes of a name.

The suffixes used after a name (for instance "PhD" or "Junior").

#### Parameters

self | the FolksStructuredName instance to modify |
value | the new value of the "suffixes" property |

Since: 0.3.5

### folks_name_details_change_structured_name ()

    void
    folks_name_details_change_structured_name
                                   (FolksNameDetails *self,
                                    FolksStructuredName *name,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Change the contact's structured name.

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

FolksPropertyError will be returned in `error`

if setting the structured name failed

See also: `folks_name_details_change_structured_name_finish()`

#### Parameters

self | the FolksNameDetails instance |
name | . the structured name (`null` to unset it) . | [in][allow-none]
_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_name_details_change_structured_name_finish ()

    void
    folks_name_details_change_structured_name_finish
                                   (FolksNameDetails *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Change the contact's structured name.

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

FolksPropertyError will be returned in `error`

if setting the structured name failed

See also: `folks_name_details_change_structured_name()`

#### Parameters

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

Since: 0.6.2

### folks_name_details_change_full_name ()

    void
    folks_name_details_change_full_name (FolksNameDetails *self,
                                         const gchar *full_name,
                                         GAsyncReadyCallback _callback_,
                                         gpointer _user_data_);

Change the contact's full name.

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

FolksPropertyError will be returned in `error`

if setting the full name failed

See also: `folks_name_details_change_full_name_finish()`

#### Parameters

self | the FolksNameDetails instance |
full_name | . the full name (empty string to unset it) . | [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_name_details_change_full_name_finish ()

    void
    folks_name_details_change_full_name_finish
                                   (FolksNameDetails *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Change the contact's full name.

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

FolksPropertyError will be returned in `error`

if setting the full name failed

See also: `folks_name_details_change_full_name()`

#### Parameters

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

Since: 0.6.2

### folks_name_details_change_nickname ()

    void
    folks_name_details_change_nickname (FolksNameDetails *self,
                                        const gchar *nickname,
                                        GAsyncReadyCallback _callback_,
                                        gpointer _user_data_);

Change the contact's nickname.

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

FolksPropertyError will be returned in `error`

if setting the nickname failed

See also: `folks_name_details_change_nickname_finish()`

#### Parameters

self | the FolksNameDetails instance |
nickname | . the nickname (empty string to unset it) . | [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_name_details_change_nickname_finish ()

    void
    folks_name_details_change_nickname_finish
                                   (FolksNameDetails *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Change the contact's nickname.

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

FolksPropertyError will be returned in `error`

if setting the nickname failed

See also: `folks_name_details_change_nickname()`

#### Parameters

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

Since: 0.6.2

### folks_name_details_get_structured_name ()

    FolksStructuredName *
    folks_name_details_get_structured_name
                                   (FolksNameDetails *self);

Get and return the current value of the "structured-name" property.

The contact name split in its constituent parts.

Note that most of the time the structured name is not set (i.e. it's `null`) or just some of the components are set. The components are immutable. To get notification of changes of the structured name, you just have to connect to the `notify` signal of this property.

#### Parameters

self | the FolksNameDetails instance to query |

#### Returns

the value of the "structured-name" property

Since: 0.3.5

### folks_name_details_set_structured_name ()

    void
    folks_name_details_set_structured_name
                                   (FolksNameDetails *self,
                                    FolksStructuredName *value);

Set the value of the "structured-name" property to `value` .

The contact name split in its constituent parts.

Note that most of the time the structured name is not set (i.e. it's `null`) or just some of the components are set. The components are immutable. To get notification of changes of the structured name, you just have to connect to the `notify` signal of this property.

#### Parameters

self | the FolksNameDetails instance to modify |
value | the new value of the "structured-name" property |

Since: 0.3.5

### folks_name_details_get_full_name ()

    const gchar *
    folks_name_details_get_full_name (FolksNameDetails *self);

Get and return the current value of the "full-name" property.

The full name of the contact.

The full name is the name of the contact written in the way the contact prefers. For instance for English names this is usually the given name followed by the family name, but Chinese names are usually the family name followed by the given name. The full name could or could not contain additional names (like a middle name), prefixes or suffixes.

The full name must not be `null`: the empty string represents an unset full name.

#### Parameters

self | the FolksNameDetails instance to query |

#### Returns

the value of the "full-name" property

Since: 0.3.5

### folks_name_details_set_full_name ()

    void
    folks_name_details_set_full_name (FolksNameDetails *self,
                                      const gchar *value);

Set the value of the "full-name" property to `value` .

The full name of the contact.

The full name is the name of the contact written in the way the contact prefers. For instance for English names this is usually the given name followed by the family name, but Chinese names are usually the family name followed by the given name. The full name could or could not contain additional names (like a middle name), prefixes or suffixes.

The full name must not be `null`: the empty string represents an unset full name.

#### Parameters

self | the FolksNameDetails instance to modify |
value | the new value of the "full-name" property |

Since: 0.3.5

### folks_name_details_get_nickname ()

    const gchar *
    folks_name_details_get_nickname (FolksNameDetails *self);

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

The nickname of the contact.

The nickname is the name that the contact chose for himself. This is different from "alias" as aliases can be chosen by the user and not by the contacts themselves.

Consequently, setting the nickname only makes sense in the context of an address book when updating the information a contact has specified about themselves.

The nickname must not be `null`: the empty string represents an unset nickname.

#### Parameters

self | the FolksNameDetails instance to query |

#### Returns

the value of the "nickname" property

Since: 0.3.5

### folks_name_details_set_nickname ()

    void
    folks_name_details_set_nickname (FolksNameDetails *self,
                                     const gchar *value);

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

The nickname of the contact.

The nickname is the name that the contact chose for himself. This is different from "alias" as aliases can be chosen by the user and not by the contacts themselves.

Consequently, setting the nickname only makes sense in the context of an address book when updating the information a contact has specified about themselves.

The nickname must not be `null`: the empty string represents an unset nickname.

#### Parameters

self | the FolksNameDetails instance to modify |
value | the new value of the "nickname" property |

Since: 0.3.5

## Types and Values

### FOLKS_TYPE_STRUCTURED_NAME

    #define FOLKS_TYPE_STRUCTURED_NAME (folks_structured_name_get_type ())

The type for FolksStructuredName.

### struct FolksStructuredName

    struct FolksStructuredName {
    	GObject parent_instance;
    	FolksStructuredNamePrivate * priv;
    };

Structured name representation for human names.

Represents a full name split in its constituent parts (given name, family name, etc.). This structure corresponds to the "N" field in vCards. The parts of the name are never `null`: an empty string indicates that a property is not set.

Since: 0.3.5

### struct FolksStructuredNameClass

    struct FolksStructuredNameClass {
    	GObjectClass parent_class;
    };

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

#### Members

### FolksNameDetails

    typedef struct _FolksNameDetails FolksNameDetails;

Interface for classes which represent contacts with names, such as FolksPersona and FolksIndividual.

Since: 0.3.5

### struct FolksNameDetailsIface

    struct FolksNameDetailsIface {
    	GTypeInterface parent_iface;
    	void (*change_structured_name) (FolksNameDetails* self, FolksStructuredName* name, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	void (*change_structured_name_finish) (FolksNameDetails* self, GAsyncResult* _res_, GError** error);
    	void (*change_full_name) (FolksNameDetails* self, const gchar* full_name, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	void (*change_full_name_finish) (FolksNameDetails* self, GAsyncResult* _res_, GError** error);
    	void (*change_nickname) (FolksNameDetails* self, const gchar* nickname, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	void (*change_nickname_finish) (FolksNameDetails* self, GAsyncResult* _res_, GError** error);
    	FolksStructuredName* (*get_structured_name) (FolksNameDetails* self);
    	void (*set_structured_name) (FolksNameDetails* self, FolksStructuredName* value);
    	const gchar* (*get_full_name) (FolksNameDetails* self);
    	void (*set_full_name) (FolksNameDetails* self, const gchar* value);
    	const gchar* (*get_nickname) (FolksNameDetails* self);
    	void (*set_nickname) (FolksNameDetails* self, const gchar* value);
    };

Interface for creating FolksNameDetails implementations.

#### Members

GTypeInterface `parent_iface`; | the parent interface structure |
`change_structured_name` () | virtual method called by `folks_name_details_change_structured_name()` |
`change_structured_name_finish` () | asynchronous finish function for `change_structured_name`, called by `folks_name_details_change_structured_name()` |
`change_full_name` () | virtual method called by `folks_name_details_change_full_name()` |
`change_full_name_finish` () | asynchronous finish function for `change_full_name`, called by `folks_name_details_change_full_name()` |
`change_nickname` () | virtual method called by `folks_name_details_change_nickname()` |
`change_nickname_finish` () | asynchronous finish function for `change_nickname`, called by `folks_name_details_change_nickname()` |
`get_structured_name` () | getter method for the abstract property "structured-name" |
`set_structured_name` () | setter method for the abstract property "structured-name" |
`get_full_name` () | getter method for the abstract property "full-name" |
`set_full_name` () | setter method for the abstract property "full-name" |
`get_nickname` () | getter method for the abstract property "nickname" |
`set_nickname` () | setter method for the abstract property "nickname" |