FolksPostalAddress

FolksPostalAddress — Object representing a postal mail address.

Functions

Properties

gchar * address-format Read / Write / Construct
gchar * country Read / Write / Construct
gchar * extension Read / Write / Construct
gchar * locality Read / Write / Construct
gchar * po-box Read / Write / Construct
gchar * postal-code Read / Write / Construct
gchar * region Read / Write / Construct
gchar * street Read / Write / Construct
gchar * uid Read / Write / Construct
gchar * id Read / Write
GeeSet * postal-addresses Read / Write

Types and Values

Object Hierarchy

    GInterface
    ╰── FolksPostalAddressDetails
    GObject
    ├── FolksAbstractFieldDetails
       ╰── FolksPostalAddressFieldDetails
    ╰── FolksPostalAddress

Prerequisites

FolksPostalAddressDetails requires GObject.

Known Implementations

FolksPostalAddressDetails is implemented by FolksIndividual.

Description

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

Functions

FOLKS_TYPE_POSTAL_ADDRESS

#define FOLKS_TYPE_POSTAL_ADDRESS (folks_postal_address_get_type ())

The type for FolksPostalAddress.


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

self

the FolksPostalAddress instance

 

with

 .

another postal address to compare with

.

[in]

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_TYPE_POSTAL_ADDRESS_FIELD_DETAILS

#define FOLKS_TYPE_POSTAL_ADDRESS_FIELD_DETAILS (folks_postal_address_field_details_get_type ())

The type for FolksPostalAddressFieldDetails.


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 occuring, 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

struct FolksPostalAddress

struct FolksPostalAddress;

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

GObjectClass parent_class;

the parent class structure

 

struct FolksPostalAddressFieldDetails

struct FolksPostalAddressFieldDetails;

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

FolksAbstractFieldDetailsClass parent_class;

the parent class structure

 

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"

 

Property Details

The “address-format” property

  “address-format”           gchar *

The address format.

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

Flags: Read / Write / Construct

Default value: NULL


The “country” property

  “country”                  gchar *

The country.

The name of the country.

Flags: Read / Write / Construct

Default value: NULL


The “extension” property

  “extension”                gchar *

The address extension.

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

Flags: Read / Write / Construct

Default value: NULL


The “locality” property

  “locality”                 gchar *

The locality.

The locality, for instance the city name.

Flags: Read / Write / Construct

Default value: NULL


The “po-box” property

  “po-box”                   gchar *

The PO Box.

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

Flags: Read / Write / Construct

Default value: NULL


The “postal-code” property

  “postal-code”              gchar *

The postal code.

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

Flags: Read / Write / Construct

Default value: NULL


The “region” property

  “region”                   gchar *

The region.

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

Flags: Read / Write / Construct

Default value: NULL


The “street” property

  “street”                   gchar *

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.

Flags: Read / Write / Construct

Default value: NULL


The “uid” property

  “uid”                      gchar *

The UID of the Postal Address (if any).

FolksPostalAddress:uid has been deprecated since version 0.6.5 and should not be used in newly-written code.

Replaced by “id”.

Flags: Read / Write / Construct

Default value: NULL


The “id” property

  “id”                       gchar *

id.

Flags: Read / Write

Default value: NULL


The “postal-addresses” property

  “postal-addresses”         GeeSet *

The postal addresses of the contact.

A list of postal addresses associated to the contact.

Flags: Read / Write

Since 0.5.1