GDataDocumentsEntry: GData Reference Manual

## GDataDocumentsEntry GDataDocumentsEntry — GData document object abstract class |

## Stability Level

Stable, unless otherwise indicated

## Functions

gchar * | gdata_documents_entry_get_path ()
const gchar * | gdata_documents_entry_get_resource_id ()
const gchar * | gdata_documents_entry_get_document_id ()
gint64 | gdata_documents_entry_get_edited ()
GDataAuthor * | gdata_documents_entry_get_last_modified_by ()
gint64 | gdata_documents_entry_get_last_viewed ()
goffset | gdata_documents_entry_get_quota_used ()
goffset | gdata_documents_entry_get_file_size ()
gboolean | gdata_documents_entry_writers_can_invite ()
void | gdata_documents_entry_set_writers_can_invite ()
gboolean | gdata_documents_entry_is_deleted ()
GList * | gdata_documents_entry_get_document_properties ()
gboolean | gdata_documents_entry_add_documents_property ()
gboolean | gdata_documents_entry_remove_documents_property ()
gint64 | gdata_documents_entry_get_shared_with_me_date ()
gboolean | gdata_documents_entry_can_edit ()

## Properties

gboolean | can-edit | Read
char * | document-id | Read
gint64 | edited | Read
gint64 | file-size | Read
gboolean | is-deleted | Read / Write
GDataAuthor * | last-modified-by | Read
gint64 | last-viewed | Read
gint64 | quota-used | Read
char * | resource-id | Read
gint64 | shared-with-me-date | Read
gboolean | writers-can-invite | Read / Write

## Types and Values

#define | GDATA_DOCUMENTS_ACCESS_ROLE_OWNER
#define | GDATA_DOCUMENTS_ACCESS_ROLE_WRITER
#define | GDATA_DOCUMENTS_ACCESS_ROLE_READER
| GDataDocumentsEntry
| GDataDocumentsEntryClass

## Object Hierarchy

        GObject
        ╰── GDataParsable
            ╰── GDataEntry
                ╰── GDataDocumentsEntry
                    ├── GDataDocumentsDocument
                    ╰── GDataDocumentsFolder

## Implemented Interfaces

GDataDocumentsEntry implements GDataAccessHandler.

## Includes

    #include <gdata/services/documents/gdata-documents-entry.h>

## Description

GDataDocumentsEntry is a subclass of GDataEntry to represent a Google Drive entry, which is then further subclassed to give specific document types.

GDataDocumentsEntry implements GDataAccessHandler, meaning the access rules to it can be modified using that interface. As well as the access roles defined for the base GDataAccessRule (e.g. `GDATA_ACCESS_ROLE_NONE`), GDataDocumentsEntry has its own, such as `GDATA_DOCUMENTS_ACCESS_ROLE_OWNER` and `GDATA_DOCUMENTS_ACCESS_ROLE_READER`.

Documents can (confusingly) be referenced by three different types of IDs: their entry ID, their resource ID and their document ID (untyped resource ID). Each is a substring of the previous ones (i.e. the entry ID contains the resource ID, which in turn contains the document ID). The resource ID and document ID should almost always be considered as internal, and thus entry IDs (“id”) should normally be used to uniquely identify documents. For more information, see “resource-id”.

For more details of Google Drive's GData API, see the

online documentation.

Example 31. Moving an Entry Between Folders

    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
    39
    40
    41
    42
    43
    44
    45
    46
    GDataDocumentsService *service;
    GDataDocumentsEntry *entry, *intermediate_entry, *updated_entry;
    GDataDocumentsFolder *old_folder, *new_folder;
    GError *error = NULL;

    /* Create a service */
    service = create_documents_service ();

    /* Get the entry, the folder it's being moved out of, and the folder it's being moved into. The entry can either be a document or
     * another folder, allowing hierarchies of folders to be constructed. */
    entry = query_user_for_entry (service);
    old_folder = query_user_for_old_folder (service);
    new_folder = query_user_for_new_folder (service);

    /* Add the entry to the new folder */
    intermediate_entry = gdata_documents_service_add_entry_to_folder (service, entry, new_folder, NULL, &error);

    g_object_unref (entry);
    g_object_unref (new_folder);

    if (error != NULL) {
    	g_error ("Error adding entry to new folder: %s", error->message);
    	g_error_free (error);
    	g_object_unref (old_folder);
    	g_object_unref (service);
    	return;
    }

    /* Remove the entry from the old folder */
    updated_entry = gdata_documents_service_remove_entry_from_folder (service, intermediate_entry, old_folder, NULL, &error);

    g_object_unref (intermediate_entry);
    g_object_unref (old_folder);
    g_object_unref (service);

    if (error != NULL) {
    	/* Note that you might want to attempt to remove the intermediate_entry from the new_folder in this error case, so that
    	 * the operation is aborted cleanly. */
    	g_error ("Error removing entry from previous folder: %s", error->message);
    	g_error_free (error);
    	return;
    }

    /* Do something with the updated entry */

    g_object_unref (updated_entry);

## Functions

### gdata_documents_entry_get_path ()

    gchar *
    gdata_documents_entry_get_path (GDataDocumentsEntry *self);

Builds a path for the GDataDocumentsEntry, starting from a root node and traversing the folders containing the document, then ending with the document's ID.

An example path would be: `/folder_id1/folder_id2/document_id`.

Note: the path is based on the entry/document IDs of the folders (“id”) and document (“document-id”), and not the entries' human-readable names (“title”).

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

the folder hierarchy path containing the document, or `NULL`; free with `g_free()`

Since: 0.4.0

### gdata_documents_entry_get_resource_id ()

    const gchar *
    gdata_documents_entry_get_resource_id (GDataDocumentsEntry *self);

Gets the “resource-id” property.

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

the document's resource ID

Since: 0.11.0

### gdata_documents_entry_get_document_id ()

    const gchar *
    gdata_documents_entry_get_document_id (GDataDocumentsEntry *self);

`gdata_documents_entry_get_document_id` has been deprecated since version 0.11.0 and should not be used in newly-written code.

Use `gdata_documents_entry_get_resource_id()` instead. See “document-id”.

Gets the “document-id” property. The

online GData Documentation

refers to these as “untyped resource IDs”.

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

the document's document ID

Since: 0.4.0

### gdata_documents_entry_get_edited ()

    gint64
    gdata_documents_entry_get_edited (GDataDocumentsEntry *self);

`gdata_documents_entry_get_edited` has been deprecated since version 0.17.0 and should not be used in newly-written code.

Use `gdata_entry_get_updated()` instead. See “edited”.

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

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

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

Since: 0.4.0

### gdata_documents_entry_get_last_modified_by ()

    GDataAuthor *
    gdata_documents_entry_get_last_modified_by
                                   (GDataDocumentsEntry *self);

Gets the “last-modified-by” property.

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

the author who last modified the document.

[transfer none]

Since: 0.4.0

### gdata_documents_entry_get_last_viewed ()

    gint64
    gdata_documents_entry_get_last_viewed (GDataDocumentsEntry *self);

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

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

the UNIX timestamp for the time the document was last viewed, or `-1`

Since: 0.4.0

### gdata_documents_entry_get_quota_used ()

    goffset
    gdata_documents_entry_get_quota_used (GDataDocumentsEntry *self);

Gets the “quota-used” property.

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

the number of quota bytes used by the document

Since: 0.13.0

### gdata_documents_entry_get_file_size ()

    goffset
    gdata_documents_entry_get_file_size (GDataDocumentsEntry *self);

Gets the “file-size” property.

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

the size of the document in bytes

Since: 0.17.7

### gdata_documents_entry_writers_can_invite ()

    gboolean
    gdata_documents_entry_writers_can_invite
                                   (GDataDocumentsEntry *self);

Gets the “writers-can-invite” property.

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

`TRUE` if writers can invite other people to edit the document, `FALSE` otherwise

Since: 0.4.0

### gdata_documents_entry_set_writers_can_invite ()

    void
    gdata_documents_entry_set_writers_can_invite
                                   (GDataDocumentsEntry *self,
                                    gboolean writers_can_invite);

Sets the “writers-can-invite” property to `writers_can_invite` .

#### Parameters

self | a GDataDocumentsEntry |
writers_can_invite | `TRUE` if writers can invite other people to edit the document, `FALSE` otherwise |

Since: 0.4.0

### gdata_documents_entry_is_deleted ()

    gboolean
    gdata_documents_entry_is_deleted (GDataDocumentsEntry *self);

Gets the “is-deleted” property.

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

`TRUE` if the document has been deleted, `FALSE` otherwise

Since: 0.5.0

### gdata_documents_entry_get_document_properties ()

    GList *
    gdata_documents_entry_get_document_properties
                                   (GDataDocumentsEntry *self);

Gets a list of the GDataDocumentsPropertys for this entry.

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

a GList of pointers to GDataDocumentsPropertys.

[transfer none][element-type GDataDocumentsProperty]

Since: 0.17.11

### gdata_documents_entry_add_documents_property ()

    gboolean
    gdata_documents_entry_add_documents_property
                                   (GDataDocumentsEntry *self,
                                    GDataDocumentsProperty *property);

Inserts/updates `property` on "properties" list in `self` . Since, a GDataDocumentsProperty is uniquely identified by “key” and “visibility”, if no such property exists in the "properties" list, then a `property` will be appended to the list after incrementing the reference count.

In case that there already exists a `property` in "properties", the GDataDocumentsProperty inside the list will be updated to `property` . Note that “value” has no role in determining the uniqueness of a GDataDocumentsProperty.

The changes made by this function will be local only and you need to explicitly update `self` by calling `gdata_service_update_entry()`.

#### Parameters

self | a GDataDocumentsEntry |
property | a GDataDocumentsProperty |

#### Returns

`TRUE` if the `property` doesn't exist in the "properties" list, or that “value” of `property` has been set to `NULL` by a call to `gdata_documents_entry_remove_documents_property()`. `FALSE` if `property` exists in "properties" list, or in the case that `self` or `property` aren't of proper types.

Since: 0.17.11

### gdata_documents_entry_remove_documents_property ()

    gboolean
    gdata_documents_entry_remove_documents_property
                                   (GDataDocumentsEntry *self,
                                    GDataDocumentsProperty *property);

The property specified by `property` will be removed from the "properties" list on `self` .

Only “key” and “visibility” will be used to find `property` in "properties" list. “value” has no role in determining the uniqueness of a GDataDocumentsProperty.

The changes made by this function will be local only and you need to explicitly update `self` by calling `gdata_service_update_entry()`.

#### Parameters

self | a GDataDocumentsEntry |
property | a GDataDocumentsProperty |

#### Returns

`TRUE` if `property` has been successfully removed from "properties" list on `self` , `FALSE` otherwise.

Since: 0.17.11

### gdata_documents_entry_get_shared_with_me_date ()

    gint64
    gdata_documents_entry_get_shared_with_me_date
                                   (GDataDocumentsEntry *self);

Gets the “shared-with-me-date” property. If the property is unset, `-1` will be returned.

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

the UNIX timestamp for the time at which this file was shared with the user, or `-1`

Since: 0.18.0

### gdata_documents_entry_can_edit ()

    gboolean
    gdata_documents_entry_can_edit (GDataDocumentsEntry *self);

Gets the “can-edit” property.

#### Parameters

self | a GDataDocumentsEntry |

#### Returns

`TRUE` if the current user can edit this file, `FALSE` otherwise

Since: 0.18.0

## Types and Values

### GDATA_DOCUMENTS_ACCESS_ROLE_OWNER

    #define GDATA_DOCUMENTS_ACCESS_ROLE_OWNER "owner"

The users specified by the GDataAccessRule have full owner access to the document. This allows them to modify the access rules and delete the document, amongst other things.

Since: 0.7.0

### GDATA_DOCUMENTS_ACCESS_ROLE_WRITER

    #define GDATA_DOCUMENTS_ACCESS_ROLE_WRITER "writer"

The users specified by the GDataAccessRule have write access to the document. They cannot modify the access rules or delete the document.

Since: 0.7.0

### GDATA_DOCUMENTS_ACCESS_ROLE_READER

    #define GDATA_DOCUMENTS_ACCESS_ROLE_READER "reader"

The users specified by the GDataAccessRule have read-only access to the document.

Since: 0.7.0

### GDataDocumentsEntry

    typedef struct _GDataDocumentsEntry GDataDocumentsEntry;

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

Since: 0.4.0

### GDataDocumentsEntryClass

    typedef struct {
    } GDataDocumentsEntryClass;

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

Since: 0.4.0

## Property Details

### The `“can-edit”` property

      “can-edit”                 gboolean

Indicates whether the current user can edit this file.

Owner: GDataDocumentsEntry

Flags: Read

Default value: FALSE

Since: 0.18.0

### The `“document-id”` property

      “document-id”              char *

The document ID of the document, which is different from its entry ID (GDataEntry:id). The

online GData Documentation refers to these as “untyped resource IDs”.

`GDataDocumentsEntry:document-id` has been deprecated since version 0.11.0 and should not be used in newly-written code.

This a substring of the “resource-id”, which is more general and should be used instead.

Owner: GDataDocumentsEntry

Flags: Read

Default value: NULL

Since: 0.4.0

### The `“edited”` property

      “edited”                   gint64

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

`GDataDocumentsEntry:edited` has been deprecated since version 0.17.0 and should not be used in newly-written code.

This is identical to “updated”.

Owner: GDataDocumentsEntry

Flags: Read

Allowed values: >= -1

Default value: -1

Since: 0.4.0

### The `“file-size”` property

      “file-size”                gint64

The size of the document. This is only set for non-document files. Standard formats, such as GDataDocumentsText, GDataDocumentsSpreadsheet and GDataDocumentsFolder are not binary data and so have no size. Measured in bytes.

Owner: GDataDocumentsEntry

Flags: Read

Allowed values: >= 0

Default value: 0

Since: 0.17.7

### The `“is-deleted”` property

      “is-deleted”               gboolean

Indicates whether the document entry has been deleted (moved to the trash). Deleted documents will only appear in query results if the “show-deleted” property is `TRUE`.

Owner: GDataDocumentsEntry

Flags: Read / Write

Default value: FALSE

Since: 0.5.0

### The `“last-modified-by”` property

      “last-modified-by”         GDataAuthor *

Indicates the author of the last modification.

Owner: GDataDocumentsEntry

Flags: Read

Since: 0.4.0

### The `“last-viewed”` property

      “last-viewed”              gint64

The last time the document was viewed.

Owner: GDataDocumentsEntry

Flags: Read

Allowed values: >= -1

Default value: -1

Since: 0.4.0

### The `“quota-used”` property

      “quota-used”               gint64

The amount of user quota the document is occupying. Currently, only arbitrary files consume file space quota (whereas standard document formats, such as GDataDocumentsText, GDataDocumentsSpreadsheet and GDataDocumentsFolder don't). Measured in bytes.

This property will be `0` for documents which aren't consuming any quota.

Owner: GDataDocumentsEntry

Flags: Read

Allowed values: >= 0

Default value: 0

Since: 0.13.0

### The `“resource-id”` property

      “resource-id”              char *

The resource ID of the document. This should not normally need to be used in client code, and is mostly for internal use. To uniquely identify a given document or folder, use its “id”.

Resource IDs have the form: ``document|drawing|pdf|spreadsheet|presentation|folder`:`untyped resource ID``; whereas entry IDs have the form: `https://docs.google.com/feeds/id/`resource ID`` in version 3 of the API.

For more information, see the

Google Documents API reference.

Owner: GDataDocumentsEntry

Flags: Read

Default value: NULL

Since: 0.11.0

### The `“shared-with-me-date”` property

      “shared-with-me-date”      gint64

The UNIX timestamp for the time at which this file was shared with the user.

Owner: GDataDocumentsEntry

Flags: Read

Allowed values: >= -1

Default value: -1

Since: 0.18.0

### The `“writers-can-invite”` property

      “writers-can-invite”       gboolean

Indicates whether the document entry writers can invite others to edit the document.

Owner: GDataDocumentsEntry

Flags: Read / Write

Default value: FALSE

Since: 0.4.0