GDataAccessRule: GData Reference Manual

## GDataAccessRule GDataAccessRule — GData access rule object |

## Stability Level

Stable, unless otherwise indicated

## Functions

GDataAccessRule * | gdata_access_rule_new ()
const gchar * | gdata_access_rule_get_role ()
void | gdata_access_rule_set_role ()
void | gdata_access_rule_get_scope ()
void | gdata_access_rule_set_scope ()
gint64 | gdata_access_rule_get_edited ()
const gchar * | gdata_access_rule_get_key ()

## Properties

gint64 | edited | Read
gchar * | key | Read
gchar * | role | Read / Write
gchar * | scope-type | Read / Write
gchar * | scope-value | Read / Write

## Types and Values

#define | GDATA_ACCESS_SCOPE_USER
#define | GDATA_ACCESS_SCOPE_DOMAIN
#define | GDATA_ACCESS_SCOPE_DEFAULT
#define | GDATA_ACCESS_ROLE_NONE
| GDataAccessRule
| GDataAccessRuleClass

## Object Hierarchy

        GObject
        ╰── GDataParsable
            ╰── GDataEntry
                ╰── GDataAccessRule
                    ├── GDataCalendarAccessRule
                    ╰── GDataDocumentsAccessRule

## Includes

    #include <gdata/gdata-access-rule.h>

## Description

GDataAccessRule is a subclass of GDataEntry to represent a generic access rule from an access control list (ACL). It is returned by the ACL methods implemented in the GDataAccessHandler interface.

Access rules should be inserted to the `GDATA_LINK_ACCESS_CONTROL_LIST` URI of the feed or entry they should be applied to. This will return a `GDATA_SERVICE_ERROR_CONFLICT` error if a rule already exists on that feed or entry for that scope type and value.

Example 4. Adding a Rule to the Access Control List for an Entry

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    GDataAuthorizationDomain *domain;
    GDataService *service;
    GDataEntry *entry;
    GDataFeed *acl_feed;
    GDataAccessRule *rule, *new_rule;
    GError *error = NULL;

    domain = gdata_documents_service_get_primary_authorization_domain ();

    /* Retrieve a GDataEntry which will have a new rule inserted into its ACL. */
    service = build_my_service ();
    entry = get_the_entry (service);

    /* Create and insert a new access rule for example@gmail.com which grants them _no_ permissions on the entry.
     * In a real application, the GDataEntry subclass would define its own access roles which are more useful. For example,
     * GDataDocumentsEntry defines access roles for users who can read (but not write) a Google Document, and users who
     * can also write to the document. */
    rule = gdata_access_rule_new (NULL);
    gdata_access_rule_set_role (rule, GDATA_ACCESS_ROLE_NONE); /* or, for example, GDATA_DOCUMENTS_ACCESS_ROLE_READER */
    gdata_access_rule_set_scope (rule, GDATA_ACCESS_SCOPE_USER, "example@gmail.com"); /* e-mail address of the user the ACL applies to */

    acl_link = gdata_entry_look_up_link (entry, GDATA_LINK_ACCESS_CONTROL_LIST);
    new_rule = GDATA_ACCESS_RULE (gdata_service_insert_entry (GDATA_SERVICE (service), domain, gdata_link_get_uri (acl_link),
                                                              GDATA_ENTRY (rule), NULL, &error));

    g_object_unref (rule);
    g_object_unref (entry);
    g_object_unref (service);

    if (error != NULL) {
    g_error ("Error inserting access rule: %s", error->message);
    g_error_free (error);
    return;
    }

    /* Potentially do something with the new_rule here, such as store its ID for later use. */

    g_object_unref (new_rule);

## Functions

### gdata_access_rule_new ()

    GDataAccessRule *
    gdata_access_rule_new (const gchar *id);

Creates a new GDataAccessRule with the given ID and default properties.

#### Parameters

id | the access rule's ID, or `NULL` |

#### Returns

a new GDataAccessRule; unref with `g_object_unref()`

Since: 0.3.0

### gdata_access_rule_get_role ()

    const gchar *
    gdata_access_rule_get_role (GDataAccessRule *self);

Gets the “role” property.

#### Parameters

self | a GDataAccessRule |

#### Returns

the access rule's role, or `NULL`

Since: 0.3.0

### gdata_access_rule_set_role ()

    void
    gdata_access_rule_set_role (GDataAccessRule *self,
                                const gchar *role);

Sets the “role” property to `role` .

Set `role` to `NULL` to unset the property in the access rule.

#### Parameters

self | a GDataAccessRule |
role | a new role, or `NULL` |

Since: 0.3.0

### gdata_access_rule_get_scope ()

    void
    gdata_access_rule_get_scope (GDataAccessRule *self,
                                 const gchar **type,
                                 const gchar **value);

Gets the “scope-type” and “scope-value” properties.

#### Parameters

self | a GDataAccessRule |
type | return location for the scope type, or `NULL`. | [out callee-allocates][transfer none][allow-none]
value | return location for the scope value, or `NULL`. | [out callee-allocates][transfer none][allow-none]

Since: 0.3.0

### gdata_access_rule_set_scope ()

    void
    gdata_access_rule_set_scope (GDataAccessRule *self,
                                 const gchar *type,
                                 const gchar *value);

Sets the “scope-type” property to `type` and the “scope-value” property to `value` .

Set `scope_value` to `NULL` to unset the “scope-value” property in the access rule. `type` cannot be `NULL`. `scope_value` must be `NULL` if `type` is `default`, and non-`NULL` otherwise.

See the

online documentation for more information.

#### Parameters

self | a GDataAccessRule |
type | a new scope type |
value | a new scope value, or `NULL`. | [allow-none]

Since: 0.3.0

### gdata_access_rule_get_edited ()

    gint64
    gdata_access_rule_get_edited (GDataAccessRule *self);

Gets the “edited” property. If the property is unset, `-1` will be returned.

#### Parameters

self | a GDataAccessRule |

#### Returns

the UNIX timestamp for the time the access rule was last edited, or `-1`

Since: 0.7.0

### gdata_access_rule_get_key ()

    const gchar *
    gdata_access_rule_get_key (GDataAccessRule *self);

Gets the “key” property.

#### Parameters

self | a GDataAccessRule |

#### Returns

the access rule's authorisation key, or `NULL`

Since: 0.16.0

## Types and Values

### GDATA_ACCESS_SCOPE_USER

    #define GDATA_ACCESS_SCOPE_USER "user"

The GDataAccessRule applies to a single individual, whose e-mail address is given in “scope-value”.

Since: 0.7.0

### GDATA_ACCESS_SCOPE_DOMAIN

    #define GDATA_ACCESS_SCOPE_DOMAIN "domain"

The GDataAccessRule applies to all users in a Google Apps For Your Domain domain, given in “scope-value”.

Since: 0.7.0

### GDATA_ACCESS_SCOPE_DEFAULT

    #define GDATA_ACCESS_SCOPE_DEFAULT "default"

The GDataAccessRule applies to all users.

Since: 0.7.0

### GDATA_ACCESS_ROLE_NONE

    #define GDATA_ACCESS_ROLE_NONE "none"

The users specified by the GDataAccessRule have no rights.

Since: 0.7.0

### GDataAccessRule

    typedef struct _GDataAccessRule GDataAccessRule;

All the fields in the GDataAccessRule structure are private and should never be accessed directly.

Since: 0.3.0

### GDataAccessRuleClass

    typedef struct {
    } GDataAccessRuleClass;

All the fields in the GDataAccessRuleClass structure are private and should never be accessed directly.

Since: 0.3.0

## Property Details

### The `“edited”` property

      “edited”                   gint64

The last time the access rule was edited. If the rule has not been edited yet, the content indicates the time it was created.

For more information, see the Atom Publishing Protocol specification.

Flags: Read

Allowed values: >= -1

Default value: -1

Since: 0.7.0

### The `“key”` property

      “key”                      gchar *

An optional authorisation key required to access this item with the given scope. If set, this restricts access to those principals who have a copy of the key. The key is generated server-side and cannot be modified by the client. If no authorisation key is set (and hence none is needed for access to the item), this will be `NULL`.

Flags: Read

Default value: NULL

Since: 0.16.0

### The `“role”` property

      “role”                     gchar *

The role of the person concerned by this ACL. By default, this can only be `GDATA_ACCESS_ROLE_NONE`. Services may extend it with their own namespaced roles.

Flags: Read / Write

Default value: "none"

Since: 0.3.0

### The `“scope-type”` property

      “scope-type”               gchar *

Specifies to whom this access rule applies. For example, `GDATA_ACCESS_SCOPE_USER` or `GDATA_ACCESS_SCOPE_DEFAULT`.

Flags: Read / Write

Default value: "default"

Since: 0.3.0

### The `“scope-value”` property

      “scope-value”              gchar *

A value representing the user who is represented by the access rule, such as an e-mail address for users, or a domain name for domains.

This must be `NULL` if and only if “scope-type” is `GDATA_ACCESS_SCOPE_DEFAULT`.

Flags: Read / Write

Default value: NULL

Since: 0.3.0