gridfs.h File Reference

GridFS declarations. More...

#include "mongo.h"

Go to the source code of this file.

Classes
struct	gridfs
struct	gridfile
Typedefs
typedef uint64_t	gridfs_offset
Enumerations
enum	{ DEFAULT_CHUNK_SIZE = 256 * 1024 }
Functions
MONGO_EXPORT gridfs *	gridfs_create (void)
MONGO_EXPORT void	gridfs_dispose (gridfs *gfs)
MONGO_EXPORT gridfile *	gridfile_create (void)
MONGO_EXPORT void	gridfile_dispose (gridfile *gf)
MONGO_EXPORT void	gridfile_get_descriptor (gridfile *gf, bson *out)
MONGO_EXPORT int	gridfs_init (mongo *client, const char *dbname, const char *prefix, gridfs *gfs)
	Initializes a GridFS object.
MONGO_EXPORT void	gridfs_destroy (gridfs *gfs)
	Destroys a GridFS object.
MONGO_EXPORT void	gridfile_writer_init (gridfile *gfile, gridfs *gfs, const char *remote_name, const char *content_type)
	Initializes a gridfile for writing incrementally with gridfs_write_buffer.
MONGO_EXPORT void	gridfile_write_buffer (gridfile *gfile, const char *data, gridfs_offset length)
	Write to a GridFS file incrementally.
MONGO_EXPORT int	gridfile_writer_done (gridfile *gfile)
	Signal that writing of this gridfile is complete by writing any buffered chunks along with the entry in the files collection.
MONGO_EXPORT int	gridfs_store_buffer (gridfs *gfs, const char *data, gridfs_offset length, const char *remotename, const char *contenttype)
	Store a buffer as a GridFS file.
MONGO_EXPORT int	gridfs_store_file (gridfs *gfs, const char *filename, const char *remotename, const char *contenttype)
	Open the file referenced by filename and store it as a GridFS file.
MONGO_EXPORT void	gridfs_remove_filename (gridfs *gfs, const char *filename)
	Removes the files referenced by filename from the db.
MONGO_EXPORT int	gridfs_find_query (gridfs *gfs, bson *query, gridfile *gfile)
	Find the first file matching the provided query within the GridFS files collection, and return the file as a GridFile.
MONGO_EXPORT int	gridfs_find_filename (gridfs *gfs, const char *filename, gridfile *gfile)
	Find the first file referenced by filename within the GridFS and return it as a GridFile.
MONGO_EXPORT int	gridfile_init (gridfs *gfs, bson *meta, gridfile *gfile)
	Initializes a GridFile containing the GridFS and file bson.
MONGO_EXPORT void	gridfile_destroy (gridfile *gfile)
	Destroys the GridFile.
MONGO_EXPORT bson_bool_t	gridfile_exists (gridfile *gfile)
	Returns whether or not the GridFile exists.
MONGO_EXPORT const char *	gridfile_get_filename (gridfile *gfile)
	Returns the filename of GridFile.
MONGO_EXPORT int	gridfile_get_chunksize (gridfile *gfile)
	Returns the size of the chunks of the GridFile.
MONGO_EXPORT gridfs_offset	gridfile_get_contentlength (gridfile *gfile)
	Returns the length of GridFile's data.
MONGO_EXPORT const char *	gridfile_get_contenttype (gridfile *gfile)
	Returns the MIME type of the GridFile.
MONGO_EXPORT bson_date_t	gridfile_get_uploaddate (gridfile *gfile)
	Returns the upload date of GridFile.
MONGO_EXPORT const char *	gridfile_get_md5 (gridfile *gfile)
	Returns the MD5 of GridFile.
const char *	gridfile_get_field (gridfile *gfile, const char *name)
	Returns the field in GridFile specified by name.
bson_bool_t	gridfile_get_boolean (gridfile *gfile, const char *name)
	Returns a boolean field in GridFile specified by name.
MONGO_EXPORT void	gridfile_get_metadata (gridfile *gfile, bson *out)
	Returns the metadata of GridFile.
MONGO_EXPORT int	gridfile_get_numchunks (gridfile *gfile)
	Returns the number of chunks in the GridFile.
MONGO_EXPORT void	gridfile_get_chunk (gridfile *gfile, int n, bson *out)
	Returns chunk n of GridFile.
MONGO_EXPORT mongo_cursor *	gridfile_get_chunks (gridfile *gfile, int start, int size)
	Returns a mongo_cursor of *size* chunks starting with chunk *start*.
MONGO_EXPORT gridfs_offset	gridfile_write_file (gridfile *gfile, FILE *stream)
	Writes the GridFile to a stream.
MONGO_EXPORT gridfs_offset	gridfile_read (gridfile *gfile, gridfs_offset size, char *buf)
	Reads length bytes from the GridFile to a buffer and updates the position in the file.
MONGO_EXPORT gridfs_offset	gridfile_seek (gridfile *gfile, gridfs_offset offset)
	Updates the position in the file (If the offset goes beyond the contentlength, the position is updated to the end of the file.)

---

Detailed Description

GridFS declarations.

---

Function Documentation

MONGO_EXPORT void gridfile_destroy

(

gridfile *

gfile

)

Destroys the GridFile.

Parameters:

oGridFIle

- the GridFile being destroyed

MONGO_EXPORT bson_bool_t gridfile_exists

(

gridfile *

gfile

)

Returns whether or not the GridFile exists.

Parameters:

gfile

- the GridFile being examined

bson_bool_t gridfile_get_boolean	(	gridfile *	gfile,
		const char *	name
	)

Returns a boolean field in GridFile specified by name.

Parameters:

gfile	- the working GridFile
name	- the name of the field to be returned

Returns:

- the boolean of the field specified (NULL if none exists)

MONGO_EXPORT void gridfile_get_chunk	(	gridfile *	gfile,
		int	n,
		bson *	out
	)

Returns chunk n of GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the nth chunk of the Gridfile

MONGO_EXPORT mongo_cursor* gridfile_get_chunks	(	gridfile *	gfile,
		int	start,
		int	size
	)

Returns a mongo_cursor of *size* chunks starting with chunk *start*.

Parameters:

gfile	- the working GridFile
start	- the first chunk in the cursor
size	- the number of chunks to be returned

Returns:

- mongo_cursor of the chunks (must be destroyed after use)

MONGO_EXPORT int gridfile_get_chunksize

(

gridfile *

gfile

)

Returns the size of the chunks of the GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the size of the chunks of the Gridfile

MONGO_EXPORT gridfs_offset gridfile_get_contentlength

(

gridfile *

gfile

)

Returns the length of GridFile's data.

Parameters:

gfile

- the working GridFile

Returns:

- the length of the Gridfile's data

MONGO_EXPORT const char* gridfile_get_contenttype

(

gridfile *

gfile

)

Returns the MIME type of the GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the MIME type of the Gridfile (NULL if no type specified)

const char* gridfile_get_field	(	gridfile *	gfile,
		const char *	name
	)

Returns the field in GridFile specified by name.

Parameters:

gfile	- the working GridFile
name	- the name of the field to be returned

Returns:

- the data of the field specified (NULL if none exists)

MONGO_EXPORT const char* gridfile_get_filename

(

gridfile *

gfile

)

Returns the filename of GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the filename of the Gridfile

MONGO_EXPORT const char* gridfile_get_md5

(

gridfile *

gfile

)

Returns the MD5 of GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the MD5 of the Gridfile

MONGO_EXPORT void gridfile_get_metadata	(	gridfile *	gfile,
		bson *	out
	)

Returns the metadata of GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the metadata of the Gridfile in a bson object (an empty bson is returned if none exists)

MONGO_EXPORT int gridfile_get_numchunks

(

gridfile *

gfile

)

Returns the number of chunks in the GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the number of chunks in the Gridfile

MONGO_EXPORT bson_date_t gridfile_get_uploaddate

(

gridfile *

gfile

)

Returns the upload date of GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the upload date of the Gridfile

MONGO_EXPORT int gridfile_init	(	gridfs *	gfs,
		bson *	meta,
		gridfile *	gfile
	)

Initializes a GridFile containing the GridFS and file bson.

Parameters:

gfs	- the GridFS where the GridFile is located
meta	- the file object
gfile	- the output GridFile that is being initialized

Returns:

- MONGO_OK or MONGO_ERROR.

MONGO_EXPORT gridfs_offset gridfile_read	(	gridfile *	gfile,
		gridfs_offset	size,
		char *	buf
	)

Reads length bytes from the GridFile to a buffer and updates the position in the file.

(assumes the buffer is large enough) (if size is greater than EOF gridfile_read reads until EOF)

Parameters:

gfile	- the working GridFile
size	- the amount of bytes to be read
buf	- the buffer to read to

Returns:

- the number of bytes read

MONGO_EXPORT gridfs_offset gridfile_seek	(	gridfile *	gfile,
		gridfs_offset	offset
	)

Updates the position in the file (If the offset goes beyond the contentlength, the position is updated to the end of the file.)

Parameters:

gfile	- the working GridFile
offset	- the position to update to

Returns:

- resulting offset location

MONGO_EXPORT void gridfile_write_buffer	(	gridfile *	gfile,
		const char *	data,
		gridfs_offset	length
	)

Write to a GridFS file incrementally.

You can call this function any number of times with a new buffer each time. This allows you to effectively stream to a GridFS file. When finished, be sure to call gridfs_writer_done.

MONGO_EXPORT gridfs_offset gridfile_write_file	(	gridfile *	gfile,
		FILE *	stream
	)

Writes the GridFile to a stream.

Parameters:

gfile	- the working GridFile
stream	- the file stream to write to

MONGO_EXPORT int gridfile_writer_done

(

gridfile *

gfile

)

Signal that writing of this gridfile is complete by writing any buffered chunks along with the entry in the files collection.

Returns:

- MONGO_OK or MONGO_ERROR.

MONGO_EXPORT void gridfile_writer_init	(	gridfile *	gfile,
		gridfs *	gfs,
		const char *	remote_name,
		const char *	content_type
	)

Initializes a gridfile for writing incrementally with gridfs_write_buffer.

Once initialized, you can write any number of buffers with gridfs_write_buffer. When done, you must call gridfs_writer_done to save the file metadata.

MONGO_EXPORT void gridfs_destroy

(

gridfs *

gfs

)

Destroys a GridFS object.

Call this when finished with the object..

Parameters:

gfs

a grid

MONGO_EXPORT int gridfs_find_filename	(	gridfs *	gfs,
		const char *	filename,
		gridfile *	gfile
	)

Find the first file referenced by filename within the GridFS and return it as a GridFile.

Parameters:

gfs	- the working GridFS
filename	- filename of the file to find
gfile	- the output GridFile to be intialized

Returns:

MONGO_OK or MONGO_ERROR.

MONGO_EXPORT int gridfs_find_query	(	gridfs *	gfs,
		bson *	query,
		gridfile *	gfile
	)

Find the first file matching the provided query within the GridFS files collection, and return the file as a GridFile.

Parameters:

gfs	- the working GridFS
query	- a pointer to the bson with the query data
gfile	- the output GridFile to be initialized

Returns:

MONGO_OK if successful, MONGO_ERROR otherwise

MONGO_EXPORT int gridfs_init	(	mongo *	client,
		const char *	dbname,
		const char *	prefix,
		gridfs *	gfs
	)

Initializes a GridFS object.

Parameters:

client	- db connection
dbname	- database name
prefix	- collection prefix, default is fs if NULL or empty
gfs	- the GridFS object to initialize

Returns:

- MONGO_OK or MONGO_ERROR.

MONGO_EXPORT void gridfs_remove_filename	(	gridfs *	gfs,
		const char *	filename
	)

Removes the files referenced by filename from the db.

Parameters:

gfs	- the working GridFS
filename	- the filename of the file/s to be removed

MONGO_EXPORT int gridfs_store_buffer	(	gridfs *	gfs,
		const char *	data,
		gridfs_offset	length,
		const char *	remotename,
		const char *	contenttype
	)

Store a buffer as a GridFS file.

Parameters:

gfs	- the working GridFS
data	- pointer to buffer to store in GridFS
length	- length of the buffer
remotename	- filename for use in the database
contenttype	- optional MIME type for this object

Returns:

- MONGO_OK or MONGO_ERROR.

MONGO_EXPORT int gridfs_store_file	(	gridfs *	gfs,
		const char *	filename,
		const char *	remotename,
		const char *	contenttype
	)

Open the file referenced by filename and store it as a GridFS file.

Parameters:

gfs	- the working GridFS
filename	- local filename relative to the process
remotename	- optional filename for use in the database
contenttype	- optional MIME type for this object

Returns:

- MONGO_OK or MONGO_ERROR.