GDataAccessHandler

## GDataAccessHandler GDataAccessHandler — GData access handler interface |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

    #define             GDATA_LINK_ACCESS_CONTROL_LIST
                        GDataAccessHandler;
                        GDataAccessHandlerIface;
    GDataFeed *         gdata_access_handler_get_rules      (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    void                gdata_access_handler_get_rules_async
                                                            (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GDestroyNotify destroy_progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

## Object Hierarchy

      GInterface
       +----GDataAccessHandler

## Prerequisites

GDataAccessHandler requires GDataEntry.

## Known Implementations

GDataAccessHandler is implemented by GDataCalendarCalendar, GDataDocumentsDocument, 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. It's optional to implement a `get_authorization_domain` function, but if it's not implemented, any operations on the access handler's GDataAccessRules will be performed unauthorized (i.e. as if by a non-logged-in user). This will not usually work.

## Details

### GDATA_LINK_ACCESS_CONTROL_LIST

    #define GDATA_LINK_ACCESS_CONTROL_LIST "http://schemas.google.com/acl/2007#accessControlList"

The relation type URI of the access control list location for this resource.

For more information, see the ACL specification.

Since 0.7.0

### 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);
    	GDataAuthorizationDomain *(*get_authorization_domain) (GDataAccessHandler *self);
    } 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).
`get_authorization_domain` () | a function to return the GDataAuthorizationDomain to be used for all operations on the access rules belonging to this access handler; not implementing this function is equivalent to returning `NULL` from it, which signifies that operations on the access rules don't require authorization; new in version 0.9.0. [allow-none]

Since 0.9.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`. [allow-none]
`progress_callback` : | a GDataQueryProgressCallback to call when a rule is loaded, or `NULL`. [allow-none][scope call][closure progress_user_data]
`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_get_rules_async ()

    void                gdata_access_handler_get_rules_async
                                                            (GDataAccessHandler *self,
                                                             GDataService *service,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GDestroyNotify destroy_progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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. `self` and `service` are both reffed when this function is called, so can safely be unreffed after this function returns.

For more details, see `gdata_access_handler_get_rules()`, which is the synchronous version of this function, and `gdata_service_query_async()`, which is the base asynchronous query function.

When the operation is finished, `callback` will be called. You can then call `gdata_service_query_finish()` to get the results of the operation.

`self` : | a GDataAccessHandler
`service` : | a GDataService
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`progress_callback` : | a GDataQueryProgressCallback to call when a rule is loaded, or `NULL`. [allow-none][closure progress_user_data]
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`destroy_progress_user_data` : | the function to call when `progress_callback` will not be called any more, or `NULL`. This function will be called with `progress_user_data` as a parameter and can be used to free any memory allocated for it. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the query is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.9.1