GDataAccessHandler

## GDataAccessHandler GDataAccessHandler — GData access handler interface |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataAccessHandler;
                        GDataAccessHandlerIface;
    GDataFeed *         gdata_access_handler_get_rules      (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    GDataAccessRule *   gdata_access_handler_insert_rule    (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GDataAccessRule *rule,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GDataAccessRule *   gdata_access_handler_update_rule    (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GDataAccessRule *rule,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            gdata_access_handler_delete_rule    (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GDataAccessRule *rule,
                                                             GCancellable *cancellable,
                                                             GError **error);

## Object Hierarchy

      GInterface
       +----GDataAccessHandler

## Prerequisites

GDataAccessHandler requires GDataEntry.

## Known Implementations

GDataAccessHandler is implemented by GDataCalendarCalendar, GDataDocumentsEntry, GDataDocumentsFolder, GDataDocumentsPresentation, GDataDocumentsSpreadsheet and GDataDocumentsText.

## Description

GDataAccessHandler is an interface which can be implemented by GDataEntrys which can have their permissions controlled by an access control list (ACL). It has a set of methods which allow the GDataAccessRules for the access handler/entry to be retrieved, added, modified and deleted, with immediate effect.

When implementing the interface, classes must implement an `is_owner_rule` function.

## Details

### GDataAccessHandler

    typedef struct _GDataAccessHandler GDataAccessHandler;

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

Since 0.3.0

### GDataAccessHandlerIface

    typedef struct {
    	GTypeInterface parent;

    	gboolean (*is_owner_rule) (GDataAccessRule *rule);
    } GDataAccessHandlerIface;

The class structure for the GDataAccessHandler interface.

GTypeInterface `parent`; | the parent type
`is_owner_rule` () | a function to return whether the given GDataAccessRule has the role of an owner (of a GDataAccessHandler).

Since 0.3.0

### gdata_access_handler_get_rules ()

    GDataFeed *         gdata_access_handler_get_rules      (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);

Retrieves a GDataFeed containing all the access rules which apply to the given GDataAccessHandler. Only the owner of a GDataAccessHandler may view its rule feed.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned.

A `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` will be returned if the server indicates there is a problem with the query.

For each rule in the response feed, `progress_callback` will be called in the main thread. If there was an error parsing the XML response, a GDataParserError will be returned.

`self` : | a GDataAccessHandler
`service` : | a GDataService
`cancellable` : | optional GCancellable object, or `NULL`
`progress_callback` : | a GDataQueryProgressCallback to call when a rule is loaded, or `NULL`. [scope call]
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`error` : | a GError, or `NULL`
Returns : | a GDataFeed of access control rules, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.3.0

### gdata_access_handler_insert_rule ()

    GDataAccessRule *   gdata_access_handler_insert_rule    (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GDataAccessRule *rule,
                                                             GCancellable *cancellable,
                                                             GError **error);

Inserts `rule` in the access control list of the GDataAccessHandler.

The service will return an updated version of the rule, which is the return value of this function on success.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned.

If the rule is marked as already having been inserted a `GDATA_SERVICE_ERROR_ENTRY_ALREADY_INSERTED` error will be returned immediately (there will be no network requests).

If there is an error inserting the rule, a `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` error will be returned.

`self` : | a GDataAccessHandler
`service` : | a GDataService
`rule` : | the GDataAccessRule to insert
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataAccessRule, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.3.0

### gdata_access_handler_update_rule ()

    GDataAccessRule *   gdata_access_handler_update_rule    (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GDataAccessRule *rule,
                                                             GCancellable *cancellable,
                                                             GError **error);

Updates `rule` in the access control list of the GDataAccessHandler.

The service will return an updated version of the rule, which is the return value of this function on success.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned.

If there is an error updating the rule, a `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` error will be returned.

`self` : | a GDataAccessHandler
`service` : | a GDataService
`rule` : | the GDataAccessRule to update
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataAccessRule, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.3.0

### gdata_access_handler_delete_rule ()

    gboolean            gdata_access_handler_delete_rule    (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GDataAccessRule *rule,
                                                             GCancellable *cancellable,
                                                             GError **error);

Deletes `rule` from the access control list of the GDataAccessHandler.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned.

If there is an error deleting the rule, a `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` error will be returned, unless the `rule` was the owner's rule; in which case, `GDATA_SERVICE_ERROR_FORBIDDEN` will be returned without any network activity.

`self` : | a GDataAccessHandler
`service` : | a GDataService
`rule` : | the GDataAccessRule to delete
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

Since 0.3.0