GDataDocumentsQuery: GData Reference Manual

## GDataDocumentsQuery GDataDocumentsQuery — GData Documents query object |

## Stability Level

Stable, unless otherwise indicated

## Functions

GDataDocumentsQuery * | gdata_documents_query_new ()
GDataDocumentsQuery * | gdata_documents_query_new_with_limits ()
gboolean | gdata_documents_query_show_deleted ()
void | gdata_documents_query_set_show_deleted ()
gboolean | gdata_documents_query_show_folders ()
void | gdata_documents_query_set_show_folders ()
const gchar * | gdata_documents_query_get_folder_id ()
void | gdata_documents_query_set_folder_id ()
const gchar * | gdata_documents_query_get_title ()
gboolean | gdata_documents_query_get_exact_title ()
void | gdata_documents_query_set_title ()
GList * | gdata_documents_query_get_collaborator_addresses ()
void | gdata_documents_query_add_collaborator ()
GList * | gdata_documents_query_get_reader_addresses ()
void | gdata_documents_query_add_reader ()

## Properties

gboolean | exact-title | Read / Write
char * | folder-id | Read / Write
gboolean | show-deleted | Read / Write
gboolean | show-folders | Read / Write
char * | title | Read / Write

## Types and Values

| GDataDocumentsQuery
| GDataDocumentsQueryClass

## Object Hierarchy

        GObject
        ╰── GDataQuery
            ╰── GDataDocumentsQuery

## Includes

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

## Description

GDataDocumentsQuery represents a collection of query parameters specific to the Google Documents service, which go above and beyond those catered for by GDataQuery.

For more information on the custom GData query parameters supported by GDataDocumentsQuery, see the online documentation.

Example 29. Querying for Documents

    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
    GDataDocumentsService *service;
    GDataDocumentsQuery *query;
    GDataFeed *feed;
    GTimeVal current_time;
    GList *i;
    GError *error = NULL;

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

    /* Create the query to use. We're going to query for the last 10 documents modified by example@gmail.com in the past week, including
     * deleted documents. */
    query = gdata_documents_query_new_with_limits (NULL, 0, 10);

    gdata_documents_query_add_collaborator (query, "example@gmail.com");
    gdata_documents_query_set_show_deleted (query, TRUE);

    g_get_current_time (&current_time);
    gdata_query_set_updated_min (GDATA_QUERY (query), current_time.tv_sec - 7 * 24 * 60 * 60);
    gdata_query_set_updated_max (GDATA_QUERY (query), current_time.tv_sec);

    /* Execute the query */
    feed = gdata_documents_service_query_documents (service, query, NULL, NULL, NULL, &error);

    g_object_unref (query);
    g_object_unref (service);

    if (error != NULL) {
    	g_error ("Error querying for documents: %s", error->message);
    	g_error_free (error);
    	return;
    }

    /* Iterate through the returned documents and do something with them */
    for (i = gdata_feed_get_entries (feed); i != NULL; i = i->next) {
    	GDataDocumentsDocument *document = GDATA_DOCUMENTS_DOCUMENT (i->data);

    	/* Do something with the document here, such as insert it into a UI */
    }

    g_object_unref (feed);

## Functions

### gdata_documents_query_new ()

    GDataDocumentsQuery *
    gdata_documents_query_new (const gchar *q);

Creates a new GDataDocumentsQuery with its “q” property set to `q` .

#### Parameters

q | a query string, or `NULL`. | [allow-none]

#### Returns

a new GDataDocumentsQuery

Since: 0.4.0

### gdata_documents_query_new_with_limits ()

    GDataDocumentsQuery *
    gdata_documents_query_new_with_limits (const gchar *q,
                                           guint start_index,
                                           guint max_results);

Creates a new GDataDocumentsQuery with its “q” property set to `q` , and the limits `start_index` and `max_results` applied.

#### Parameters

q | a query string, or `NULL`. | [allow-none]
start_index | a one-based start index for the results, or `0` |
max_results | the maximum number of results to return, or `0` |

#### Returns

a new GDataDocumentsQuery

Since: 0.4.0

### gdata_documents_query_show_deleted ()

    gboolean
    gdata_documents_query_show_deleted (GDataDocumentsQuery *self);

Gets the “show_deleted” property.

#### Parameters

self | a GDataDocumentsQuery |

#### Returns

`TRUE` if the request should return deleted entries, `FALSE` otherwise

Since: 0.4.0

### gdata_documents_query_set_show_deleted ()

    void
    gdata_documents_query_set_show_deleted
                                   (GDataDocumentsQuery *self,
                                    gboolean show_deleted);

Sets the “show_deleted” property to `show_deleted` .

#### Parameters

self | a GDataDocumentsQuery |
show_deleted | `TRUE` if the request should return deleted entries, `FALSE` otherwise |

Since: 0.4.0

### gdata_documents_query_show_folders ()

    gboolean
    gdata_documents_query_show_folders (GDataDocumentsQuery *self);

Gets the “show-folders” property.

#### Parameters

self | a GDataDocumentsQuery |

#### Returns

`TRUE` if the request should return folders, `FALSE` otherwise

Since: 0.4.0

### gdata_documents_query_set_show_folders ()

    void
    gdata_documents_query_set_show_folders
                                   (GDataDocumentsQuery *self,
                                    gboolean show_folders);

Sets the “show-folders” property to show_folders.

#### Parameters

self | a GDataDocumentsQuery |
show_folders | `TRUE` if the request should return folders, `FALSE` otherwise |

Since: 0.4.0

### gdata_documents_query_get_folder_id ()

    const gchar *
    gdata_documents_query_get_folder_id (GDataDocumentsQuery *self);

Gets the “folder-id” property.

#### Parameters

self | a GDataDocumentsQuery |

#### Returns

the ID of the folder to be queried, or `NULL`

Since: 0.4.0

### gdata_documents_query_set_folder_id ()

    void
    gdata_documents_query_set_folder_id (GDataDocumentsQuery *self,
                                         const gchar *folder_id);

Sets the “folder-id” property to `folder_id` .

Set `folder_id` to `NULL` to unset the property in the query URI.

#### Parameters

self | a GDataDocumentsQuery |
folder_id | the ID of the folder to be queried, or `NULL`. | [allow-none]

Since: 0.4.0

### gdata_documents_query_get_title ()

    const gchar *
    gdata_documents_query_get_title (GDataDocumentsQuery *self);

Gets the “title” property.

#### Parameters

self | a GDataDocumentsQuery |

#### Returns

the title (or title fragment) being queried for, or `NULL`

Since: 0.4.0

### gdata_documents_query_get_exact_title ()

    gboolean
    gdata_documents_query_get_exact_title (GDataDocumentsQuery *self);

Gets the “exact-title” property.

#### Parameters

self | a GDataDocumentsQuery |

#### Returns

`TRUE` if the query matches the exact title of documents with “title”, `FALSE` otherwise

Since: 0.4.0

### gdata_documents_query_set_title ()

    void
    gdata_documents_query_set_title (GDataDocumentsQuery *self,
                                     const gchar *title,
                                     gboolean exact_title);

Sets the “title” property to `title` .

Set `title` to `NULL` to unset the property in the query URI.

#### Parameters

self | a GDataDocumentsQuery |
title | the title (or title fragment) to query for, or `NULL`. | [allow-none]
exact_title | `TRUE` if the query should match the exact `title` , `FALSE` otherwise |

Since: 0.4.0

### gdata_documents_query_get_collaborator_addresses ()

    GList *
    gdata_documents_query_get_collaborator_addresses
                                   (GDataDocumentsQuery *self);

Gets a list of GDataGDEmailAddresses of the document collaborators whose documents will be queried.

#### Parameters

self | a GDataDocumentsQuery |

#### Returns

a list of GDataGDEmailAddresses of the collaborators concerned by the query, or `NULL`.

[element-type GData.GDEmailAddress][transfer none]

Since: 0.4.0

### gdata_documents_query_add_collaborator ()

    void
    gdata_documents_query_add_collaborator
                                   (GDataDocumentsQuery *self,
                                    const gchar *email_address);

Add `email_address` as a GDataGDEmailAddress to the list of collaborators whose edited documents will be queried.

#### Parameters

self | a GDataDocumentsQuery |
email_address | the e-mail address of the collaborator to add |

Since: 0.4.0

### gdata_documents_query_get_reader_addresses ()

    GList *
    gdata_documents_query_get_reader_addresses
                                   (GDataDocumentsQuery *self);

Gets a list of GDataGDEmailAddresses of the document readers whose documents will be queried.

#### Parameters

self | a GDataDocumentsQuery |

#### Returns

a list of GDataGDEmailAddresses of the readers concerned by the query, or `NULL`.

[element-type GData.GDEmailAddress][transfer none]

Since: 0.4.0

### gdata_documents_query_add_reader ()

    void
    gdata_documents_query_add_reader (GDataDocumentsQuery *self,
                                      const gchar *email_address);

Add `email_address` as a GDataGDEmailAddress to the list of readers, the documents readable by whom will be queried.

#### Parameters

self | a GDataDocumentsQuery |
email_address | the e-mail address of the reader to add |

Since: 0.4.0

## Types and Values

### GDataDocumentsQuery

    typedef struct _GDataDocumentsQuery GDataDocumentsQuery;

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

Since: 0.4.0

### GDataDocumentsQueryClass

    typedef struct {
    } GDataDocumentsQueryClass;

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

Since: 0.4.0

## Property Details

### The `“exact-title”` property

      “exact-title”              gboolean

Specifies whether the query should search for an exact title match for the “title” parameter.

Owner: GDataDocumentsQuery

Flags: Read / Write

Default value: FALSE

Since: 0.4.0

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

      “folder-id”                char *

Specifies the ID of the folder in which to search.

Owner: GDataDocumentsQuery

Flags: Read / Write

Default value: NULL

Since: 0.4.0

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

      “show-deleted”             gboolean

A shortcut to request all documents that have been deleted.

Owner: GDataDocumentsQuery

Flags: Read / Write

Default value: FALSE

Since: 0.4.0

### The `“show-folders”` property

      “show-folders”             gboolean

Specifies if the request also returns folders.

Owner: GDataDocumentsQuery

Flags: Read / Write

Default value: FALSE

Since: 0.4.0

### The `“title”` property

      “title”                    char *

A title (or title fragment) to be searched for. If “exact-title” is `TRUE`, an exact title match will be searched for, otherwise substring matches will also be returned.

Owner: GDataDocumentsQuery

Flags: Read / Write

Default value: NULL

Since: 0.4.0