Uploader for using Google media upload protocols. More...

#include "client/service/media_uploader.h"

Public Types
typedef ResultCallback2 < util::Status, const StringPiece &, string * >	UrlPreparer
	Callback function used to resolve URI templated variables in a URI.
Public Member Functions
	MediaUploader (const MediaUploadSpec *spec, const StringPiece &base_url, const StringPiece &non_media_upload_path)
	Standard constructor.
virtual	~MediaUploader ()
	Standard destructor.
bool	is_ready () const
	Find out if BuildRequest was called and returned successfully so that the uploader is ready to Upload().
void	set_multipart_boundary (const string &boundary)
	Set custom multipart oundary separator.
const string &	multipart_boundary () const
	Returns the separator string used to denote the multipart boundary.
void	set_metadata (const SerializableJson &from_json)
	Set the metadata using a Json object or pre-encoded string.
void	set_metadata (const string &content_type, const string &from_text)
	Set the metadata using a Json object or pre-encoded string.
void	set_media_content_reader (const string &content_type, DataReader *media)
	Set the media content payload byte stream.
const string &	base_url () const
	Returns the base_url bound in teh constructor.
const string &	non_media_upload_path () const
	Returns the non_media_upload_path bound in the constructor.
util::Status	Upload (HttpRequest *http_request)
	Synchronously perform the upload protocol using the given request.
util::Status	BuildRequest (HttpRequest request, UrlPreparer url_preparer)
	prepares the uploader and builds the HttpRequest.

Detailed Description

Uploader for using Google media upload protocols.

In practice the methods generated by the code generator provide a factory that creates one of these and you just populated it. The upload happens when the method (acting as the factory) executes.

    scoped_ptr<drive_api::File> file(drive_api::File::New());
    file->set_title(StrCat("Uploaded from ", path));

    const DriveService::FilesResource& ops = app_->service()->get_files();
    scoped_ptr<FilesResource_InsertMethod> insert(
        ops.NewInsertMethod(app_->credential()));
    client::MediaUploader* uploader = insert->media_uploader();
    uploader->set_metadata(*file);
    uploader->set_media_content(mime_type.as_string(), file_content);
    insert->Execute();

If using this yourself then instead of the insert->Execute you would call uploader->upload, passing in the http_request to upload and http_response. You can explicitly form the request yourself, or call BuildRequest to initialize a standard one.

The media uploader is not reusable at this time.

TODO(ewiseblatt): Only a synchronous Upload is provided at this time but eventually this will support asynchronous uploads. Even so, the underlying HttpRequest and its HttpResponse attribute are threadsafe and support condition variables so you can Upload in a thread and synchronize on the response in another.

TODO(ewiseblatt): The interface does not yet support -- streaming content -- resumable uploads -- auto protocol selection To add auto selection I'll probably configure it with a vector of specs to choose from.

Member Typedef Documentation

typedef ResultCallback2< util::Status, const StringPiece&, string*> UrlPreparer

Callback function used to resolve URI templated variables in a URI.

Parameters:

[in]	StringPiece	is the URI to resolve.
[out]	The	resolved URL

Returns:: success if all the URI parameters could be resolved, failure if somec could not. resolved url

Constructor & Destructor Documentation

MediaUploader	(	const MediaUploadSpec *	spec,
		const StringPiece &	base_url,
		const StringPiece &	non_media_upload_path
	)		`[explicit]`

Standard constructor.

Parameters:

[in]	spec	Should remain valid over the lifetime of the instance.
[in]	base_url	The url that the spec paths are relative to.
[in]	non_media_upload_path	The path to send metadata to when there is no media content (i.e. the non-media upload case).

TODO(ewiseblatt): In the future this will also be used if multipart is not supported.

virtual ~MediaUploader ( ) [virtual]

Standard destructor.

Member Function Documentation

const string& base_url ( ) const [inline]

Returns the base_url bound in teh constructor.

util::Status BuildRequest	(	HttpRequest *	request,
		UrlPreparer *	url_preparer
	)

prepares the uploader and builds the HttpRequest.

This fills out the request body and any critical headers that the underlying protocol uses. Any metadata and content attributes for the uploader must be set before calling this method.

This method also determines the final protocol and url endpoint to use. The url_preparer is used to resolve variables in templated urls and add any other query parameters. It is only called once so can be a single use callback. It can be left NULL to not modify the protocol url, but should only do so if there are known to be no templated parameters in the urls or extra query parameters needed in the upload request.

Parameters:

[in,out]	request	The request to build.
[in]	url_preparer	The Callback for resolving template variables in the upload url if it was specified using URI Templating..

bool is_ready ( ) const [inline]

Find out if BuildRequest was called and returned successfully so that the uploader is ready to Upload().

Returns:: true if can perform media upload, false if not yet ready.

const string& multipart_boundary ( ) const [inline]

Returns the separator string used to denote the multipart boundary.

const string& non_media_upload_path ( ) const [inline]

Returns the non_media_upload_path bound in the constructor.

void set_media_content_reader	(	const string &	content_type,
		DataReader *	media
	)

Set the media content payload byte stream.

Parameters:

[in]	content_type	The media payload content type.
[in]	media	Takes ownership of the mdeia payload byte stream.

If the reader is known to be empty then no content will be uploaded allowing the uploader to just send the metadata (if any).

void set_metadata ( const SerializableJson & from_json )

Set the metadata using a Json object or pre-encoded string.

Parameters:

[in] from_json If this is empty then no metadata will be added (i.e. just a media upload). Otherwise this is a JSON-encoded metadata payload.

void set_metadata	(	const string &	content_type,
		const string &	from_text
	)

Set the metadata using a Json object or pre-encoded string.

Parameters:

[in]	content_type	The content type of the metadata payload.
[in]	from_text	The content_type encoded metadata payload.

void set_multipart_boundary ( const string & boundary ) [inline]

Set custom multipart oundary separator.

Overrides the boundary used for multipart separators should this instance ever create a multipart content_type.

If the boundary is empty then it will be automatically determined from the content. Since the content reader may not be resettable, relying on auto-boundaries might make the request unsendable if the content payload cannot be reset between discovering the boundary and sending the message.

util::Status Upload ( HttpRequest * http_request )

Synchronously perform the upload protocol using the given request.

This method requires BuildRequest was called to fill out the request. If authorization is needed, the credentials should be set on the request.

Parameters:

[in,out] http_request The request used to perform the upload.

Returns:: The overall status of the upload. Error detail can be retrieved from the http_request->status().

The documentation for this class was generated from the following file:

googleapis/client/service/media_uploader.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation