Mongo GridFS Streaming API

Ths submodule provides stream-based access to GridFS files. More...

Collaboration diagram for Mongo GridFS Streaming API:

Functions
mongo_sync_gridfs_stream *	mongo_sync_gridfs_stream_find (mongo_sync_gridfs *gfs, const bson *query)
	Create a stream reader by finding the file matching a query.
mongo_sync_gridfs_stream *	mongo_sync_gridfs_stream_new (mongo_sync_gridfs *gfs, const bson *metadata)
	Create a new GridFS stream writer.
gint64	mongo_sync_gridfs_stream_read (mongo_sync_gridfs_stream *stream, guint8 *buffer, gint64 size)
	Read an arbitrary number of bytes from a GridFS stream.
gboolean	mongo_sync_gridfs_stream_write (mongo_sync_gridfs_stream *stream, const guint8 *buffer, gint64 size)
	Write an arbitrary number of bytes to a GridFS stream.
gboolean	mongo_sync_gridfs_stream_seek (mongo_sync_gridfs_stream *stream, gint64 pos, gint whence)
	Seek to an arbitrary position in a GridFS stream.
gboolean	mongo_sync_gridfs_stream_close (mongo_sync_gridfs_stream *stream)
	Close a GridFS stream.

Detailed Description

Ths submodule provides stream-based access to GridFS files.

Stream based access has the advantage of allowing arbitrary reads and multi-part writes, at the cost of slightly higher memory usage and lower performance speed.

It's best used when one needs only part of a file (and not neccessarily a full chunk, or the parts cross chunk boundaries), or when uploading a file from a source that cannot be fully stored in a memory buffer, and cannot be mmapped. Such as a network connection.

Function Documentation

gboolean mongo_sync_gridfs_stream_close

(

mongo_sync_gridfs_stream *

stream

)

Close a GridFS stream.

Closes the GridFS stream, by writing out the buffered data, and the metadata if it's a write stream, and freeing up all resources in all cases.

Parameters

stream

is the GridFS stream to close and free.

Returns

TRUE on success, FALSE otherwise.

mongo_sync_gridfs_stream* mongo_sync_gridfs_stream_find	(	mongo_sync_gridfs *	gfs,
		const bson *	query
	)

Create a stream reader by finding the file matching a query.

Parameters

gfs	is the GridFS to search on.
query	is the query based on which the file should be searched.

Returns

A newly allocated read-only stream object, or NULL on error.

Note

It is the responsiblity of the caller to free the stream once it is no longer needed.

mongo_sync_gridfs_stream* mongo_sync_gridfs_stream_new	(	mongo_sync_gridfs *	gfs,
		const bson *	metadata
	)

Create a new GridFS stream writer.

Parameters

gfs	is the GridFS to create a file on.
metadata	is the optional extra file metadata to use.

Returns

A newly allocated write-only stream object, or NULL on error.

Note

It is the responsiblity of the caller to free the stream once it is no longer needed.

gint64 mongo_sync_gridfs_stream_read	(	mongo_sync_gridfs_stream *	stream,
		guint8 *	buffer,
		gint64	size
	)

Read an arbitrary number of bytes from a GridFS stream.

Parameters

stream	is the read-only stream to read from.
buffer	is the buffer to store the read data in.
size	is the maximum number of bytes to read.

Returns

The number of bytes read, or -1 on error.

Note

The buffer parameter must have enough space allocated to hold at most size bytes.

gboolean mongo_sync_gridfs_stream_seek	(	mongo_sync_gridfs_stream *	stream,
		gint64	pos,
		gint	whence
	)

Seek to an arbitrary position in a GridFS stream.

Parameters

stream	is the read-only stream to seek in.
pos	is the position to seek to.
whence	is used to determine how to seek. Possible values are SEEK_SET which means seek to the given position, SEEK_CUR meaning seek to the current position plus pos and SEEK_END which will seek from the end of the file.

Returns

TRUE on success, FALSE otherwise.

gboolean mongo_sync_gridfs_stream_write	(	mongo_sync_gridfs_stream *	stream,
		const guint8 *	buffer,
		gint64	size
	)

Write an arbitrary number of bytes to a GridFS stream.

Parameters

stream	is the write-only stream to write to.
buffer	is the data to write.
size	is the amount of data to write.

Returns

TRUE on success, FALSE otherwise.