FolksPostalAddress: Reference Manual

## FolksPostalAddress FolksPostalAddress — Object representing a postal mail address. |

## Functions

gboolean | folks_postal_address_is_empty ()
gboolean | folks_postal_address_equal ()
gchar * | folks_postal_address_to_string ()
FolksPostalAddress * | folks_postal_address_new ()
const gchar * | folks_postal_address_get_po_box ()
void | folks_postal_address_set_po_box ()
const gchar * | folks_postal_address_get_extension ()
void | folks_postal_address_set_extension ()
const gchar * | folks_postal_address_get_street ()
void | folks_postal_address_set_street ()
const gchar * | folks_postal_address_get_locality ()
void | folks_postal_address_set_locality ()
const gchar * | folks_postal_address_get_region ()
void | folks_postal_address_set_region ()
const gchar * | folks_postal_address_get_postal_code ()
void | folks_postal_address_set_postal_code ()
const gchar * | folks_postal_address_get_country ()
void | folks_postal_address_set_country ()
const gchar * | folks_postal_address_get_address_format ()
void | folks_postal_address_set_address_format ()
const gchar * | folks_postal_address_get_uid ()
void | folks_postal_address_set_uid ()
FolksPostalAddressFieldDetails * | folks_postal_address_field_details_new ()
void | folks_postal_address_details_change_postal_addresses ()
void | folks_postal_address_details_change_postal_addresses_finish ()
GeeSet * | folks_postal_address_details_get_postal_addresses ()
void | folks_postal_address_details_set_postal_addresses ()

## Types and Values

#define | FOLKS_TYPE_POSTAL_ADDRESS
struct | FolksPostalAddress
struct | FolksPostalAddressClass
#define | FOLKS_TYPE_POSTAL_ADDRESS_FIELD_DETAILS
struct | FolksPostalAddressFieldDetails
struct | FolksPostalAddressFieldDetailsClass
| FolksPostalAddressDetails
struct | FolksPostalAddressDetailsIface

## Description

The components of the address are never `null`: an empty string indicates that a property is not set.

## Functions

### folks_postal_address_is_empty ()

    gboolean
    folks_postal_address_is_empty (FolksPostalAddress *self);

Whether none of the components is set.

#### Parameters

self | the FolksPostalAddress instance |

#### Returns

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

Since: 0.6.7

### folks_postal_address_equal ()

    gboolean
    folks_postal_address_equal (FolksPostalAddress *self,
                                FolksPostalAddress *with);

Compare if two postal addresses are equal. Addresses are equal if all their components are equal (where `null` compares equal only with `null`) and they have the same set of types (or both have no types).

This does not factor in the `uid`.

#### Parameters

with | another postal address to compare with |
self | the FolksPostalAddress instance |
@with |  |

#### Returns

`true` if the addresses are equal, `false` otherwise

### folks_postal_address_to_string ()

    gchar *
    folks_postal_address_to_string (FolksPostalAddress *self);

Get a formatted version of the address. The format is localised, and by default is comma-separated.

#### Parameters

self | the FolksPostalAddress instance |

#### Returns

a formatted address.

Since: 0.4.0

### folks_postal_address_new ()

    FolksPostalAddress *
    folks_postal_address_new (const gchar *po_box,
                              const gchar *extension,
                              const gchar *street,
                              const gchar *locality,
                              const gchar *region,
                              const gchar *postal_code,
                              const gchar *country,
                              const gchar *address_format,
                              const gchar *uid);

Create a PostalAddress.

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

#### Parameters

po_box | . the PO Box . | [in][allow-none]
extension | . the address extension . | [in][allow-none]
street | . the street name and number . | [in][allow-none]
locality | . the locality (city, town or village) name . | [in][allow-none]
region | . the region (state or province) name . | [in][allow-none]
postal_code | . the postal code . | [in][allow-none]
country | . the country name . | [in][allow-none]
address_format | . the address format . | [in][allow-none]
uid | . external UID for the address instance . | [in][allow-none]

Since: 0.5.1

### folks_postal_address_get_po_box ()

    const gchar *
    folks_postal_address_get_po_box (FolksPostalAddress *self);

Get and return the current value of the "po-box" property.

The PO Box.

The PO Box (also known as Postal office box or Postal box).

#### Parameters

self | the FolksPostalAddress instance to query |

#### Returns

the value of the "po-box" property

### folks_postal_address_set_po_box ()

    void
    folks_postal_address_set_po_box (FolksPostalAddress *self,
                                     const gchar *value);

Set the value of the "po-box" property to `value` .

The PO Box.

The PO Box (also known as Postal office box or Postal box).

#### Parameters

self | the FolksPostalAddress instance to modify |
value | the new value of the "po-box" property |

### folks_postal_address_get_extension ()

    const gchar *
    folks_postal_address_get_extension (FolksPostalAddress *self);

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

The address extension.

Any additional part of the address, for instance a flat number.

#### Parameters

self | the FolksPostalAddress instance to query |

#### Returns

the value of the "extension" property

### folks_postal_address_set_extension ()

    void
    folks_postal_address_set_extension (FolksPostalAddress *self,
                                        const gchar *value);

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

The address extension.

Any additional part of the address, for instance a flat number.

#### Parameters

self | the FolksPostalAddress instance to modify |
value | the new value of the "extension" property |

### folks_postal_address_get_street ()

    const gchar *
    folks_postal_address_get_street (FolksPostalAddress *self);

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

The street name and number.

The street name including the optional building number. The number can be before or after the street name based on the language and country.

#### Parameters

self | the FolksPostalAddress instance to query |

#### Returns

the value of the "street" property

### folks_postal_address_set_street ()

    void
    folks_postal_address_set_street (FolksPostalAddress *self,
                                     const gchar *value);

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

The street name and number.

The street name including the optional building number. The number can be before or after the street name based on the language and country.

#### Parameters

self | the FolksPostalAddress instance to modify |
value | the new value of the "street" property |

### folks_postal_address_get_locality ()

    const gchar *
    folks_postal_address_get_locality (FolksPostalAddress *self);

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

The locality.

The locality, for instance the city name.

#### Parameters

self | the FolksPostalAddress instance to query |

#### Returns

the value of the "locality" property

### folks_postal_address_set_locality ()

    void
    folks_postal_address_set_locality (FolksPostalAddress *self,
                                       const gchar *value);

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

The locality.

The locality, for instance the city name.

#### Parameters

self | the FolksPostalAddress instance to modify |
value | the new value of the "locality" property |

### folks_postal_address_get_region ()

    const gchar *
    folks_postal_address_get_region (FolksPostalAddress *self);

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

The region.

The region, for instance the name of the state or province.

#### Parameters

self | the FolksPostalAddress instance to query |

#### Returns

the value of the "region" property

### folks_postal_address_set_region ()

    void
    folks_postal_address_set_region (FolksPostalAddress *self,
                                     const gchar *value);

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

The region.

The region, for instance the name of the state or province.

#### Parameters

self | the FolksPostalAddress instance to modify |
value | the new value of the "region" property |

### folks_postal_address_get_postal_code ()

    const gchar *
    folks_postal_address_get_postal_code (FolksPostalAddress *self);

Get and return the current value of the "postal-code" property.

The postal code.

The postal code (also known as post code, postcode or ZIP code).

#### Parameters

self | the FolksPostalAddress instance to query |

#### Returns

the value of the "postal-code" property

### folks_postal_address_set_postal_code ()

    void
    folks_postal_address_set_postal_code (FolksPostalAddress *self,
                                          const gchar *value);

Set the value of the "postal-code" property to `value` .

The postal code.

The postal code (also known as post code, postcode or ZIP code).

#### Parameters

self | the FolksPostalAddress instance to modify |
value | the new value of the "postal-code" property |

### folks_postal_address_get_country ()

    const gchar *
    folks_postal_address_get_country (FolksPostalAddress *self);

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

The country.

The name of the country.

#### Parameters

self | the FolksPostalAddress instance to query |

#### Returns

the value of the "country" property

### folks_postal_address_set_country ()

    void
    folks_postal_address_set_country (FolksPostalAddress *self,
                                      const gchar *value);

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

The country.

The name of the country.

#### Parameters

self | the FolksPostalAddress instance to modify |
value | the new value of the "country" property |

### folks_postal_address_get_address_format ()

    const gchar *
    folks_postal_address_get_address_format
                                   (FolksPostalAddress *self);

Get and return the current value of the "address-format" property.

The address format.

The two letter country code that determines the format or exact meaning of the other fields.

#### Parameters

self | the FolksPostalAddress instance to query |

#### Returns

the value of the "address-format" property

### folks_postal_address_set_address_format ()

    void
    folks_postal_address_set_address_format
                                   (FolksPostalAddress *self,
                                    const gchar *value);

Set the value of the "address-format" property to `value` .

The address format.

The two letter country code that determines the format or exact meaning of the other fields.

#### Parameters

self | the FolksPostalAddress instance to modify |
value | the new value of the "address-format" property |

### folks_postal_address_get_uid ()

    const gchar *
    folks_postal_address_get_uid (FolksPostalAddress *self);

`folks_postal_address_get_uid` has been deprecated since version 0.6.5 and should not be used in newly-written code.

Replaced by “id”.

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

The UID of the Postal Address (if any).

#### Parameters

self | the FolksPostalAddress instance to query |

#### Returns

the value of the "uid" property

### folks_postal_address_set_uid ()

    void
    folks_postal_address_set_uid (FolksPostalAddress *self,
                                  const gchar *value);

`folks_postal_address_set_uid` has been deprecated since version 0.6.5 and should not be used in newly-written code.

Replaced by “id”.

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

The UID of the Postal Address (if any).

#### Parameters

self | the FolksPostalAddress instance to modify |
value | the new value of the "uid" property |

### folks_postal_address_field_details_new ()

    FolksPostalAddressFieldDetails *
    folks_postal_address_field_details_new
                                   (FolksPostalAddress *value,
                                    GeeMultiMap *parameters);

Create a new PostalAddressFieldDetails.

#### Parameters

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

#### Returns

a new PostalAddressFieldDetails

Since: 0.6.0

### folks_postal_address_details_change_postal_addresses ()

    void
    folks_postal_address_details_change_postal_addresses
                                   (FolksPostalAddressDetails *self,
                                    GeeSet *postal_addresses,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Change the contact's postal addresses.

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

FolksPropertyError will be returned in `error`

if setting the addresses failed

See also: `folks_postal_address_details_change_postal_addresses_finish()`

#### Parameters

self | the FolksPostalAddressDetails instance |
postal_addresses | . the set of postal 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_postal_address_details_change_postal_addresses_finish ()

    void
    folks_postal_address_details_change_postal_addresses_finish
                                   (FolksPostalAddressDetails *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Change the contact's postal addresses.

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

FolksPropertyError will be returned in `error`

if setting the addresses failed

See also: `folks_postal_address_details_change_postal_addresses()`

#### Parameters

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

Since: 0.6.2

### folks_postal_address_details_get_postal_addresses ()

    GeeSet *
    folks_postal_address_details_get_postal_addresses
                                   (FolksPostalAddressDetails *self);

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

The postal addresses of the contact.

A list of postal addresses associated to the contact.

#### Parameters

self | the FolksPostalAddressDetails instance to query |

#### Returns

the value of the "postal-addresses" property

Since: 0.5.1

### folks_postal_address_details_set_postal_addresses ()

    void
    folks_postal_address_details_set_postal_addresses
                                   (FolksPostalAddressDetails *self,
                                    GeeSet *value);

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

The postal addresses of the contact.

A list of postal addresses associated to the contact.

#### Parameters

self | the FolksPostalAddressDetails instance to modify |
value | the new value of the "postal-addresses" property |

Since: 0.5.1

## Types and Values

### FOLKS_TYPE_POSTAL_ADDRESS

    #define FOLKS_TYPE_POSTAL_ADDRESS (folks_postal_address_get_type ())

The type for FolksPostalAddress.

### struct FolksPostalAddress

    struct FolksPostalAddress {
    	GObject parent_instance;
    	FolksPostalAddressPrivate * priv;
    };

Object representing a postal mail address.

The components of the address are never `null`: an empty string indicates that a property is not set.

### struct FolksPostalAddressClass

    struct FolksPostalAddressClass {
    	GObjectClass parent_class;
    };

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

#### Members

### FOLKS_TYPE_POSTAL_ADDRESS_FIELD_DETAILS

    #define FOLKS_TYPE_POSTAL_ADDRESS_FIELD_DETAILS (folks_postal_address_field_details_get_type ())

The type for FolksPostalAddressFieldDetails.

### struct FolksPostalAddressFieldDetails

    struct FolksPostalAddressFieldDetails {
    	FolksAbstractFieldDetails parent_instance;
    	FolksPostalAddressFieldDetailsPrivate * priv;
    };

Object representing a PostalAddress value that can have some parameters associated with it.

See FolksAbstractFieldDetails for details on common parameter names and values.

Since: 0.6.0

### struct FolksPostalAddressFieldDetailsClass

    struct FolksPostalAddressFieldDetailsClass {
    	FolksAbstractFieldDetailsClass parent_class;
    };

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

#### Members

### FolksPostalAddressDetails

    typedef struct _FolksPostalAddressDetails FolksPostalAddressDetails;

Interface for classes that can provide postal addresses, such as FolksPersona and FolksIndividual.

### struct FolksPostalAddressDetailsIface

    struct FolksPostalAddressDetailsIface {
    	GTypeInterface parent_iface;
    	void (*change_postal_addresses) (FolksPostalAddressDetails* self, GeeSet* postal_addresses, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	void (*change_postal_addresses_finish) (FolksPostalAddressDetails* self, GAsyncResult* _res_, GError** error);
    	GeeSet* (*get_postal_addresses) (FolksPostalAddressDetails* self);
    	void (*set_postal_addresses) (FolksPostalAddressDetails* self, GeeSet* value);
    };

Interface for creating FolksPostalAddressDetails implementations.

#### Members

GTypeInterface `parent_iface`; | the parent interface structure |
`change_postal_addresses` () | virtual method called by `folks_postal_address_details_change_postal_addresses()` |
`change_postal_addresses_finish` () | asynchronous finish function for `change_postal_addresses`, called by `folks_postal_address_details_change_postal_addresses()` |
`get_postal_addresses` () | getter method for the abstract property "postal-addresses" |
`set_postal_addresses` () | setter method for the abstract property "postal-addresses" |