FolksRole: Reference Manual

## FolksRole FolksRole — Role a contact has in an organisation. |

## Functions

gboolean | folks_role_is_empty ()
gchar * | folks_role_to_string ()
FolksRole * | folks_role_new ()
const gchar * | folks_role_get_organisation_name ()
void | folks_role_set_organisation_name ()
const gchar * | folks_role_get_title ()
void | folks_role_set_title ()
const gchar * | folks_role_get_role ()
void | folks_role_set_role ()
const gchar * | folks_role_get_uid ()
void | folks_role_set_uid ()
gboolean | folks_role_equal ()
guint | folks_role_hash ()
FolksRoleFieldDetails * | folks_role_field_details_new ()
void | folks_role_details_change_roles ()
void | folks_role_details_change_roles_finish ()
GeeSet * | folks_role_details_get_roles ()
void | folks_role_details_set_roles ()

## Types and Values

#define | FOLKS_TYPE_ROLE
struct | FolksRole
struct | FolksRoleClass
#define | FOLKS_TYPE_ROLE_FIELD_DETAILS
struct | FolksRoleFieldDetails
struct | FolksRoleFieldDetailsClass
| FolksRoleDetails
struct | FolksRoleDetailsIface

## Description

This represents the role a FolksPersona or FolksIndividual has in a single given organisation, such as a company.

## Functions

### folks_role_is_empty ()

    gboolean
    folks_role_is_empty (FolksRole *self);

Whether none of the components is set.

#### Parameters

self | the FolksRole instance |

#### Returns

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

Since: 0.6.7

### folks_role_to_string ()

    gchar *
    folks_role_to_string (FolksRole *self);

Formatted version of this role.

#### Parameters

self | the FolksRole instance |

Since: 0.4.0

### folks_role_new ()

    FolksRole *
    folks_role_new (const gchar *title,
                    const gchar *organisation_name,
                    const gchar *uid);

Default constructor.

#### Parameters

title | . title of the position . | [in][allow-none]
organisation_name | . organisation where the role is hold . | [in][allow-none]
uid | . a Unique ID associated to this Role . | [in][allow-none]

#### Returns

a new Role

Since: 0.4.0

### folks_role_get_organisation_name ()

    const gchar *
    folks_role_get_organisation_name (FolksRole *self);

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

The name of the organisation in which the role is held.

#### Parameters

self | the FolksRole instance to query |

#### Returns

the value of the "organisation-name" property

### folks_role_set_organisation_name ()

    void
    folks_role_set_organisation_name (FolksRole *self,
                                      const gchar *value);

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

The name of the organisation in which the role is held.

#### Parameters

self | the FolksRole instance to modify |
value | the new value of the "organisation-name" property |

### folks_role_get_title ()

    const gchar *
    folks_role_get_title (FolksRole *self);

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

The title of the position held.

For example: “Director, Ministry of Silly Walks”

#### Parameters

self | the FolksRole instance to query |

#### Returns

the value of the "title" property

### folks_role_set_title ()

    void
    folks_role_set_title (FolksRole *self,
                          const gchar *value);

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

The title of the position held.

For example: “Director, Ministry of Silly Walks”

#### Parameters

self | the FolksRole instance to modify |
value | the new value of the "title" property |

### folks_role_get_role ()

    const gchar *
    folks_role_get_role (FolksRole *self);

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

The role of the position.

For example: “Programmer”

#### Parameters

self | the FolksRole instance to query |

#### Returns

the value of the "role" property

Since: 0.6.0

### folks_role_set_role ()

    void
    folks_role_set_role (FolksRole *self,
                         const gchar *value);

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

The role of the position.

For example: “Programmer”

#### Parameters

self | the FolksRole instance to modify |
value | the new value of the "role" property |

Since: 0.6.0

### folks_role_get_uid ()

    const gchar *
    folks_role_get_uid (FolksRole *self);

`folks_role_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 that distinguishes this role.

#### Parameters

self | the FolksRole instance to query |

#### Returns

the value of the "uid" property

### folks_role_set_uid ()

    void
    folks_role_set_uid (FolksRole *self,
                        const gchar *value);

`folks_role_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 that distinguishes this role.

#### Parameters

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

### folks_role_equal ()

    gboolean
    folks_role_equal (FolksRole *a,
                      FolksRole *b);

Compare if two roles are equal. Roles are equal if their titles and organisation names are equal.

#### Parameters

a | . a role to compare . | [in]
b | . another role to compare . | [in]

#### Returns

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

### folks_role_hash ()

    guint
    folks_role_hash (FolksRole *r);

Hash function for the class. Suitable for use as a hash table key.

#### Parameters

r | . a role to hash . | [in]

#### Returns

hash value for the role instance

### folks_role_field_details_new ()

    FolksRoleFieldDetails *
    folks_role_field_details_new (FolksRole *value,
                                  GeeMultiMap *parameters);

Create a new RoleFieldDetails.

#### Parameters

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

#### Returns

a new RoleFieldDetails

Since: 0.6.0

### folks_role_details_change_roles ()

    void
    folks_role_details_change_roles (FolksRoleDetails *self,
                                     GeeSet *roles,
                                     GAsyncReadyCallback _callback_,
                                     gpointer _user_data_);

Change the contact's roles.

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

FolksPropertyError will be returned in `error`

if setting the roles failed

See also: `folks_role_details_change_roles_finish()`

#### Parameters

self | the FolksRoleDetails instance |
roles | . the set of roles . | [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_role_details_change_roles_finish ()

    void
    folks_role_details_change_roles_finish
                                   (FolksRoleDetails *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Change the contact's roles.

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

FolksPropertyError will be returned in `error`

if setting the roles failed

See also: `folks_role_details_change_roles()`

#### Parameters

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

Since: 0.6.2

### folks_role_details_get_roles ()

    GeeSet *
    folks_role_details_get_roles (FolksRoleDetails *self);

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

The roles of the contact.

#### Parameters

self | the FolksRoleDetails instance to query |

#### Returns

the value of the "roles" property

Since: 0.6.0

### folks_role_details_set_roles ()

    void
    folks_role_details_set_roles (FolksRoleDetails *self,
                                  GeeSet *value);

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

The roles of the contact.

#### Parameters

self | the FolksRoleDetails instance to modify |
value | the new value of the "roles" property |

Since: 0.6.0

## Types and Values

### FOLKS_TYPE_ROLE

    #define FOLKS_TYPE_ROLE (folks_role_get_type ())

The type for FolksRole.

### struct FolksRole

    struct FolksRole {
    	GObject parent_instance;
    	FolksRolePrivate * priv;
    };

Role a contact has in an organisation.

This represents the role a FolksPersona or FolksIndividual has in a single given organisation, such as a company.

Since: 0.4.0

### struct FolksRoleClass

    struct FolksRoleClass {
    	GObjectClass parent_class;
    };

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

#### Members

### FOLKS_TYPE_ROLE_FIELD_DETAILS

    #define FOLKS_TYPE_ROLE_FIELD_DETAILS (folks_role_field_details_get_type ())

The type for FolksRoleFieldDetails.

### struct FolksRoleFieldDetails

    struct FolksRoleFieldDetails {
    	FolksAbstractFieldDetails parent_instance;
    	FolksRoleFieldDetailsPrivate * priv;
    };

Object representing details of a contact in an organisation which can have some parameters associated with it.

See FolksAbstractFieldDetails.

Since: 0.6.0

### struct FolksRoleFieldDetailsClass

    struct FolksRoleFieldDetailsClass {
    	FolksAbstractFieldDetailsClass parent_class;
    };

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

#### Members

### FolksRoleDetails

    typedef struct _FolksRoleDetails FolksRoleDetails;

This interfaces represents the list of roles a FolksPersona and FolksIndividual might have.

Since: 0.4.0

### struct FolksRoleDetailsIface

    struct FolksRoleDetailsIface {
    	GTypeInterface parent_iface;
    	void (*change_roles) (FolksRoleDetails* self, GeeSet* roles, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	void (*change_roles_finish) (FolksRoleDetails* self, GAsyncResult* _res_, GError** error);
    	GeeSet* (*get_roles) (FolksRoleDetails* self);
    	void (*set_roles) (FolksRoleDetails* self, GeeSet* value);
    };

Interface for creating FolksRoleDetails implementations.

#### Members

GTypeInterface `parent_iface`; | the parent interface structure |
`change_roles` () | virtual method called by `folks_role_details_change_roles()` |
`change_roles_finish` () | asynchronous finish function for `change_roles`, called by `folks_role_details_change_roles()` |
`get_roles` () | getter method for the abstract property "roles" |
`set_roles` () | setter method for the abstract property "roles" |