GDataDocumentsUploadQuery

## GDataDocumentsUploadQuery GDataDocumentsUploadQuery — GData Documents upload query object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataDocumentsUploadQuery;
                        GDataDocumentsUploadQueryClass;
    GDataDocumentsUploadQuery * gdata_documents_upload_query_new
                                                            (void);
    gchar *             gdata_documents_upload_query_build_uri
                                                            (GDataDocumentsUploadQuery *self);
    GDataDocumentsFolder * gdata_documents_upload_query_get_folder
                                                            (GDataDocumentsUploadQuery *self);
    void                gdata_documents_upload_query_set_folder
                                                            (GDataDocumentsUploadQuery *self,
                                                             GDataDocumentsFolder *folder);
    gboolean            gdata_documents_upload_query_get_convert
                                                            (GDataDocumentsUploadQuery *self);
    void                gdata_documents_upload_query_set_convert
                                                            (GDataDocumentsUploadQuery *self,
                                                             gboolean convert);

## Object Hierarchy

      GObject
       +----GDataDocumentsUploadQuery

## Properties

      "convert"                  gboolean              : Read / Write
      "folder"                   GDataDocumentsFolder*  : Read / Write

## Description

GDataDocumentsUploadQuery is a collection of parameters for document uploads to Google Documents, allowing various options to be set when uploading a document for the first time. For example, the destination folder for the uploaded document may be specified; or whether to automatically convert the document to a common format.

GDataDocumentsUploadQuery is designed as an object (rather than a fixed struct or set of function arguments) to allow for easy additions of new Google Documents features in the future.

Example 31. Uploading an Arbitrary File from Disk

    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
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    GDataDocumentsService *service;
    GDataDocumentsDocument *document, *uploaded_document;
    GFile *arbitrary_file;
    GFileInfo *file_info;
    const gchar *slug, *content_type;
    goffset file_size;
    GDataDocumentsUploadQuery *upload_query;
    GFileInputStream *file_stream;
    GDataUploadStream *upload_stream;
    GError *error = NULL;

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

    /* Get the file to upload. */
    arbitrary_file = g_file_new_for_path ("arbitrary-file.bin");

    /* Get the file's display name, content type and size. */
    file_info = g_file_query_info (arbitrary_file, G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME "," G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE ","
                                   G_FILE_ATTRIBUTE_STANDARD_SIZE, G_FILE_QUERY_INFO_NONE, NULL, &error);

    if (error != NULL) {
        g_error ("Error getting arbitrary file information: %s", error->message);
        g_error_free (error);
        g_object_unref (arbitrary_file);
        g_object_unref (service);
        return;
    }

    slug = g_file_info_get_display_name (file_info);
    content_type = g_file_info_get_content_type (file_info);
    file_size = g_file_info_get_size (file_info);

    /* Get an input stream for the file. */
    file_stream = g_file_read (arbitrary_file, NULL, &error);

    g_object_unref (arbitrary_file);

    if (error != NULL) {
        g_error ("Error getting arbitrary file stream: %s", error->message);
        g_error_free (error);
        g_object_unref (file_info);
        g_object_unref (service);
        return;
    }

    /* Create the file metadata to upload. */
    document = gdata_documents_document_new (NULL);
    gdata_entry_set_title (GDATA_ENTRY (document), "Title for My Arbitrary File");

    /* Build the upload query and set the upload to not be converted to a standard format. */
    upload_query = gdata_documents_upload_query_new ();
    gdata_documents_upload_query_set_convert (upload_query, FALSE);

    /* Get an upload stream for the file. */
    upload_stream = gdata_documents_service_upload_document_resumable (service, document, slug, content_type, file_size, upload_query, NULL, &error);

    g_object_unref (upload_query);
    g_object_unref (document);
    g_object_unref (file_info);

    if (error != NULL) {
        g_error ("Error getting upload stream: %s", error->message);
        g_error_free (error);
        g_object_unref (file_stream);
        g_object_unref (service);
        return;
    }

    /* Upload the document. This is a blocking operation, and should normally be done asynchronously. */
    g_output_stream_splice (G_OUTPUT_STREAM (upload_stream), G_INPUT_STREAM (file_stream),
                            G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE | G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET, NULL, &error);

    g_object_unref (file_stream);

    if (error != NULL) {
        g_error ("Error splicing streams: %s", error->message);
        g_error_free (error);
        g_object_unref (upload_stream);
        g_object_unref (service);
        return;
    }

    /* Finish off the upload by parsing the returned updated document metadata entry. */
    uploaded_document = gdata_documents_service_finish_upload (service, upload_stream, &error);

    g_object_unref (upload_stream);
    g_object_unref (service);

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

    /* Do something with the uploaded document. */

    g_object_unref (uploaded_document);

## Details

### GDataDocumentsUploadQuery

    typedef struct _GDataDocumentsUploadQuery GDataDocumentsUploadQuery;

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

Since 0.13.0

### GDataDocumentsUploadQueryClass

    typedef struct {
    } GDataDocumentsUploadQueryClass;

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

Since 0.13.0

### gdata_documents_upload_query_new ()

    GDataDocumentsUploadQuery * gdata_documents_upload_query_new
                                                            (void);

Constructs a new empty GDataDocumentsUploadQuery.

Returns : | a new GDataDocumentsUploadQuery; unref with `g_object_unref()`. [transfer full]

Since 0.13.0

### gdata_documents_upload_query_build_uri ()

    gchar *             gdata_documents_upload_query_build_uri
                                                            (GDataDocumentsUploadQuery *self);

Builds an upload URI suitable for passing to `gdata_upload_stream_new_resumable()` in order to upload a document to Google Documents as described in the online documentation.

`self` : | a GDataDocumentsUploadQuery
Returns : | a complete upload URI; free with `g_free()`. [transfer full]

Since 0.13.0

### gdata_documents_upload_query_get_folder ()

    GDataDocumentsFolder * gdata_documents_upload_query_get_folder
                                                            (GDataDocumentsUploadQuery *self);

Gets "folder".

`self` : | a GDataDocumentsUploadQuery
Returns : | the folder to upload into, or `NULL`. [allow-none][transfer none]

Since 0.13.0

### gdata_documents_upload_query_set_folder ()

    void                gdata_documents_upload_query_set_folder
                                                            (GDataDocumentsUploadQuery *self,
                                                             GDataDocumentsFolder *folder);

Sets "folder" to `folder`.

`self` : | a GDataDocumentsUploadQuery
`folder` : | a new folder to upload into, or `NULL`. [allow-none][transfer none]

Since 0.13.0

### gdata_documents_upload_query_get_convert ()

    gboolean            gdata_documents_upload_query_get_convert
                                                            (GDataDocumentsUploadQuery *self);

Gets "convert".

`self` : | a GDataDocumentsUploadQuery
Returns : | `TRUE` to convert documents to common formats, `FALSE` to upload them unmodified

Since 0.13.0

### gdata_documents_upload_query_set_convert ()

    void                gdata_documents_upload_query_set_convert
                                                            (GDataDocumentsUploadQuery *self,
                                                             gboolean convert);

Sets "convert" to `convert`.

`self` : | a GDataDocumentsUploadQuery
`convert` : | `TRUE` to convert documents to common formats, `FALSE` to upload them unmodified

Since 0.13.0

## Property Details

### The `"convert"` property

      "convert"                  gboolean              : Read / Write

`TRUE` to automatically convert the uploaded document into a standard format (such as a text document, spreadsheet, presentation, etc.). `FALSE` to upload the document without converting it; this allows for arbitrary files to be uploaded to Google Documents.

For more information, see the online documentation.

Note that uploading with this property set to `FALSE` will only have an effect when using `gdata_documents_service_update_document_resumable()` and not `gdata_documents_service_update_document()`. Additionally, the GDataDocumentsDocument passed to `gdata_documents_service_update_document_resumable()` must be a GDataDocumentsDocument if this property is `FALSE`, and a subclass of it otherwise.

Default value: TRUE

Since 0.13.0

### The `"folder"` property

      "folder"                   GDataDocumentsFolder*  : Read / Write

Folder to upload the document into. If this is `NULL`, the document will be uploaded into the root folder.

Since 0.13.0