The raw data management module is responsible for access to and manipulation of raw data. More...

Classes
class	DataReader
	Interface for reading from an asynchronous binary data stream. More...
class	DataWriter
	Interface for writing into synchronous binary data stream. More...
Functions
DataReader *	NewManagedInvalidDataReader (util::Status status, Closure *deleter)
	Returns a data reader that is always in an error state.
DataReader *	NewUnmanagedInvalidDataReader (util::Status status)
	Returns an unmanaged invalid data reader.
DataReader *	NewManagedInMemoryDataReader (const StringPiece &data, Closure *deleter)
	Reads from a contiguous byte array.
DataReader *	NewUnmanagedInMemoryDataReader (const StringPiece &data)
	Creates an unmanaged InMenoryDataReaderThis is shorthand for NewManagedInMemoryDataReader(data, NULL)
DataReader *	NewManagedInMemoryDataReader (string *data)
	Returns a managed reader that consumes a dynanic input string.
DataReader *	NewManagedInMemoryDataReader (const string &data)
	Creates a managed InMemoryDataReader from an existing string.
DataReader *	NewManagedBufferedDataReader (DataReader *reader, int64 buffer_bytes)
	Returns an InMemoryDataReader that returns the content from another data reader.
DataReader *	NewUnmanagedBufferedDataReader (DataReader *reader, int64 buffer_bytes)
	Similar to NewUManagedBufferdDataReader but the caller retains ownership of the original reader.
DataReader *	NewManagedBufferedDataReader (DataReader reader, int64 buffer_bytes, Closure deleter)
	A general form of a managed BufferedDataReader.
DataReader *	NewUnmanagedCompositeDataReader (const vector< DataReader * > &readers)
	Returns an unmanaged composite DataReader that reads directly from one or more other data readers.
DataReader *	NewManagedCompositeDataReader (const vector< DataReader * > &readers, Closure *deleter)
	Returns a managed composite DataReader that reads directly from one or more other data readers.
Closure *	NewCompositeReaderListAndContainerDeleter (vector< DataReader * > *readers)
	Creates a managed closure that deletes an entire vector of readers when run.
DataReader *	NewManagedFileDataReader (const StringPiece &path, Closure *deleter)
	Creates a managed DataReader that reads its byte stream from a file on disk.
DataReader *	NewUnmanagedFileDataReader (const StringPiece &path)
	Creates an unmanaged DataReader that reads its byte stream from a file on disk.
DataReader *	NewManagedIstreamDataReader (std::istream stream, Closure deleter)
	Creates a managed reader that reads its byte stream from a generic C++ std::istream of unknown length.
DataReader *	NewManagedIstreamDataReaderWithLength (std::istream stream, int64 length, Closure deleter)
	Creates a managed reader that reads its byte stream from a generic C++ std::istream of unknown length.
DataReader *	NewUnmanagedIstreamDataReader (std::istream *stream)
	Creates an unmanaged reader that reads its byte stream from a generic C++ std::istream of unknown length.
DataReader *	NewUnmanagedIstreamDataReaderWithLength (std::istream *stream, int64 length)
	Creates an unmanaged reader that reads its byte stream from a generic C++ std::istream of a known length.
DataWriter *	NewFileDataWriter (const StringPiece &path)
	Creates a data writer that rewrites the file at the given path.
DataWriter *	NewFileDataWriter (const StringPiece &path, const FileOpenOptions &options)
	Creates a data writer that rewrites the file at the given path with control over how the file is created.
DataWriter *	NewStringDataWriter (string *s)
	Creates a data writer that rewrites the given string.
DataWriter *	NewStringDataWriter ()
	Creates an in-memory data writer that encapsulates the memory it uses.

Detailed Description

The raw data management module is responsible for access to and manipulation of raw data.

It provides abstractions and mechanisms for supplying data for messaging payloads, and for getting the data out of those payloads. As a rule of thumb it provides data support without being tied to the HTTP Transport Layer or involving any inter-process messaging. The concepts it defines are used throughout the Google APIs Client Libraries for C++ to help facilitate passing data through the various components and subsystems.

Function Documentation

Closure* googleapis::client::NewCompositeReaderListAndContainerDeleter ( vector< DataReader * > * readers )

Creates a managed closure that deletes an entire vector of readers when run.

This is a convienence function for creating a closure to pass to NewManagedCompositeDataReader.

Parameters:

[in] readers Takes ownership of the vector and its contents are passed so the vector should hae been allocated with the new operator.

DataWriter* googleapis::client::NewFileDataWriter ( const StringPiece & path )

Creates a data writer that rewrites the file at the given path.

Parameters:

[in] path The caller will own the file at the given path.

DataWriter* googleapis::client::NewFileDataWriter	(	const StringPiece &	path,
		const FileOpenOptions &	options
	)

Creates a data writer that rewrites the file at the given path with control over how the file is created.

Parameters:

[in]	path	The caller will own the file at the given path.
[in]	options	The options can be used to override the permissions to given the created file.

DataReader* googleapis::client::NewManagedBufferedDataReader	(	DataReader *	reader,
		int64	buffer_bytes
	)

Returns an InMemoryDataReader that returns the content from another data reader.

This reader is only intended to make unreliable readers reliable when you need to reset them. It is high overhead since you are creating an in-memory copy of the data, which defeats the whole point of having a reader and will cost twice the storage.

Parameters:

[in]	reader	Ownership of the wrapped reader will be passed the new instance to manage.
[in]	buffer_bytes	The total number of bytes to expect, or -1 if unknown.

DataReader* googleapis::client::NewManagedBufferedDataReader	(	DataReader *	reader,
		int64	buffer_bytes,
		Closure *	deleter
	)

A general form of a managed BufferedDataReader.

Parameters:

[in]	reader	The caller maintains ownership of this reader, however the caller may have passed ownership to the deleter.
[in]	buffer_bytes	The number of bytes to expect in the reader, or -1 if not known.
[in]	deleter	The management closure to call when this instance is destroyed.

DataReader* googleapis::client::NewManagedCompositeDataReader	(	const vector< DataReader * > &	readers,
		Closure *	deleter
	)

Returns a managed composite DataReader that reads directly from one or more other data readers.

The composite readers are not buffered at all by this reader so little additional overhead is added. The component readers within this may come from different types of sources or might just have different fragments of memory.

Parameters:

[in]	readers	The list of readers taht define the byte sequence returned by this reader. The caller retains ownership of each of these readers though may pass their ownership to the deleter.
[in]	deleter	The management closure to be called when the composite reader is destroyed.

DataReader* googleapis::client::NewManagedFileDataReader	(	const StringPiece &	path,
		Closure *	deleter
	)

Creates a managed DataReader that reads its byte stream from a file on disk.

If the path does not exist, or cannot be read for some other reason then this will return a reader in the error state. Check its status() to get more details on the error.

The caller should ensure the file remains valid and unchanged over the lifetime of the reader. Changing the file contents will corrupt the reader.

Parameters:

[in]	path	The path to the file to read from.
[in]	deleter	If non-NULL this closure will be called when the reader is destroyed. The reader itself will no longer be valid when the closure is called.

DataReader* googleapis::client::NewManagedInMemoryDataReader	(	const StringPiece &	data,
		Closure *	deleter
	)

Reads from a contiguous byte array.

Managed InMemoryDataReader instances are very low overhead if the memory already exists. However, the owner must ensure that the referenced data remains valid and unchanged over the lifetime of the reader. Modifying the data will corrupt the reader.

Unmanaged instances can pass memory ownership into the instance itself and have the instance encapsulate it by being the only remaining direct reference. This reduces the chance for the data to get corrupted and guarantees that the data will remain vaid for as long, and only as long, as the reader remains.

For brevity only StringPiece variations are provided. If you have an ordinary char*, you can turn it into a StringPiece by passing StringPiece(ptr, len) presuming that you know the length. If you do not know the length then you cannot use the InMemoryDataReader anyway.

If your char* is part of a larger object which you only need to support the reader, you can have the reader manage it by passing a DeletePointerClosure as the reader's managing closure.

   char* data = obj->data()
   int64 len = obj->data_len()
   NewManagedInMemoryDataReader(StringPiece(data, len),
                                DeletePointerClosure(obj))

Parameters:

[in]	data	The data used by the reader must remain valid and unchanged over the lifetime of the readaer.
[in]	deleter	If non-NULL then this will be a managed reader calling the deletre when this object is destroyed. See the base DataReader class for more information about managed readers.

DataReader* googleapis::client::NewManagedInMemoryDataReader ( string * data )

Returns a managed reader that consumes a dynanic input string.

This is a convienence function to create a managed reader from a string pinter.

Parameters:

[in] data Takes ownership of the string

See also:: NewManagedInMemoryDataReader

DataReader* googleapis::client::NewManagedInMemoryDataReader ( const string & data ) [inline]

Creates a managed InMemoryDataReader from an existing string.

This function will create a copy of the string then manage the copy.

See also:: NewManagedInMemoryDataReader

DataReader* googleapis::client::NewManagedInvalidDataReader	(	util::Status	status,
		Closure *	deleter
	)

Returns a data reader that is always in an error state.

Parameters:

[in]	status	The permanent status() to give the reader, expaining why any access to it will fail.
[in]	deleter	If non-NULL this reader will be a "managed" reader and run teh deleter in its destructor.

This reader is meant to be returned by factory methdos that fail. It is a placeholder value so that DataReaders are never NULL.

DataReader* googleapis::client::NewManagedIstreamDataReader	(	std::istream *	stream,
		Closure *	deleter
	)

Creates a managed reader that reads its byte stream from a generic C++ std::istream of unknown length.

If you know how many bytes are in the stream then you should use NewManagedIstreamDataReaderWithLength

Parameters:

[in]	stream	The caller retains ownership of the stream to read from, though the caller may pass ownership to the deleter. The caller must insure it remains valid over the lifetime of the reader, and should not read from it outside the returned reader.
[in]	deleter	The managing closure is called when the reaer is destroyed. The reader will not be valid when the deleter is called.

See also:: NewDeleterClosure; NewManagedFileDataReader

DataReader* googleapis::client::NewManagedIstreamDataReaderWithLength	(	std::istream *	stream,
		int64	length,
		Closure *	deleter
	)

Creates a managed reader that reads its byte stream from a generic C++ std::istream of unknown length.

Parameters:

[in]	stream	The caller retains ownership of the stream to read from, though the caller may pass ownership to the deleter. The caller must insure it remains valid over the lifetime of the reader, and should not read from it outside the returned reader.
[in]	length	The length if known, or -1 can be used if unknown. A length of 0 indicates and empty stream.
[in]	deleter	The managing closure is called when the reaer is destroyed. The reader will not be valid when the deleter is called.

See also:: NewDeleterClosure; NewMmanagedFileDataReader

DataWriter* googleapis::client::NewStringDataWriter ( string * s )

Creates a data writer that rewrites the given string.

Parameters:

[in] s A pointer to a string owned by the caller. This string will remain valid after the writer is destroyed. Use s->data() rather than s->c_str() if you need to access the raw bytes in the string since the writer may be given binary data.

DataWriter* googleapis::client::NewStringDataWriter ( )

Creates an in-memory data writer that encapsulates the memory it uses.

DataReader* googleapis::client::NewUnmanagedBufferedDataReader	(	DataReader *	reader,
		int64	buffer_bytes
	)

Similar to NewUManagedBufferdDataReader but the caller retains ownership of the original reader.

Parameters:

[in]	reader	The caller keeps ownership of the reader being wrapped.
[in]	buffer_bytes	The total number of bytes to expect, or -1 if unknown.

See also:: NewManagedBufferedDataReader

DataReader* googleapis::client::NewUnmanagedCompositeDataReader ( const vector< DataReader * > & readers )

Returns an unmanaged composite DataReader that reads directly from one or more other data readers.

The composite readers are not buffered at all by this reader so little additional overhead is added. The component readers within this may come from different types of sources or might just have different fragments of memory.

Parameters:

[in] readers The list of readers taht define the byte sequence returned by this reader. The caller retains ownership of each of these and must guarantee they are kept valid and otherwise unused over the lifetime of this instance. if data is read from any of these outside the composite reader then the compsite reader will be corrupted.

DataReader* googleapis::client::NewUnmanagedFileDataReader ( const StringPiece & path )

Creates an unmanaged DataReader that reads its byte stream from a file on disk.

If the path does not exist, or cannot be read for some other reason then this will return a reader in the error state. Check its status() to get more details on the error.

The caller should ensure the file remains valid and unchanged over the lifetime of the reader. Changing the file contents will corrupt the reader.

Parameters:

[in] path The path to the file to read from.

DataReader* googleapis::client::NewUnmanagedInMemoryDataReader ( const StringPiece & data )

Creates an unmanaged InMenoryDataReaderThis is shorthand for NewManagedInMemoryDataReader(data, NULL)

See also:: NewManagedInMemoryDataReader

DataReader* googleapis::client::NewUnmanagedInvalidDataReader ( util::Status status ) [inline]

Returns an unmanaged invalid data reader.

Parameters:

[in] status The permanent status() to give the reader.

See also:: NewManagedInvalidDataReader

DataReader* googleapis::client::NewUnmanagedIstreamDataReader ( std::istream * stream )

Creates an unmanaged reader that reads its byte stream from a generic C++ std::istream of unknown length.

This is similar to NewManagedIstreamDataReader, but with a NULL deleter.

See also:: NewManagedIStreamDataReader; NewUnmanagedFileDataReader

DataReader* googleapis::client::NewUnmanagedIstreamDataReaderWithLength	(	std::istream *	stream,
		int64	length
	)

Creates an unmanaged reader that reads its byte stream from a generic C++ std::istream of a known length.

This is similar to NewManagedIstreamDataReaderWithLength, but with a NULL deleter.

See also:: NewManagedIStreamDataReaderWIthLength; NewUnmanagedFileDataReader

Classes

Functions

Detailed Description

Function Documentation