GDataAccessRule

## GDataAccessRule GDataAccessRule — GData access rule object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

    #define             GDATA_ACCESS_SCOPE_USER
    #define             GDATA_ACCESS_SCOPE_DOMAIN
    #define             GDATA_ACCESS_SCOPE_DEFAULT
    #define             GDATA_ACCESS_ROLE_NONE
                        GDataAccessRule;
                        GDataAccessRuleClass;
    GDataAccessRule *   gdata_access_rule_new               (const gchar *id);
    const gchar *       gdata_access_rule_get_role          (GDataAccessRule *self);
    void                gdata_access_rule_set_role          (GDataAccessRule *self,
                                                             const gchar *role);
    void                gdata_access_rule_get_scope         (GDataAccessRule *self,
                                                             const gchar **type,
                                                             const gchar **value);
    void                gdata_access_rule_set_scope         (GDataAccessRule *self,
                                                             const gchar *type,
                                                             const gchar *value);
    gint64              gdata_access_rule_get_edited        (GDataAccessRule *self);

## Object Hierarchy

      GObject
       +----GDataParsable
             +----GDataEntry
                   +----GDataAccessRule

## Properties

      "edited"                   gint64                : Read
      "role"                     gchar*                : Read / Write
      "scope-type"               gchar*                : Read / Write
      "scope-value"              gchar*                : Read / Write

## 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
    GDataService *service;
    GDataEntry *entry;
    GDataFeed *acl_feed;
    GDataAccessRule *rule, *new_rule;
    GError *error = NULL;

    /* 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), gdata_link_get_uri (acl_link), GDATA_ENTRY (rule),
                                                              NULL, &error));
    g_object_unref (acl_link);

    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);

## Details

### 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

### gdata_access_rule_new ()

    GDataAccessRule *   gdata_access_rule_new               (const gchar *id);

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

`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.

`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.

`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.

`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.

`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.

`self` : | a GDataAccessRule
Returns : | the UNIX timestamp for the time the access rule was last edited, or `-1`

Since 0.7.0

## Property Details

### The `"edited"` property

      "edited"                   gint64                : Read

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.

Allowed values: >= -1

Default value: -1

Since 0.7.0

### The `"role"` property

      "role"                     gchar*                : Read / Write

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.

Default value: "none"

Since 0.3.0

### The `"scope-type"` property

      "scope-type"               gchar*                : Read / Write

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

Default value: "default"

Since 0.3.0

### The `"scope-value"` property

      "scope-value"              gchar*                : Read / Write

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`.

Default value: NULL

Since 0.3.0