GData Reference Manual: 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, GDataDocumentsDrawing, GDataDocumentsEntry, GDataDocumentsFolder, GDataDocumentsPdf, 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.

For an example of inserting an access rule into an ACL, see the documentation for GDataAccessRule.

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