gridfs.h File Reference

GridFS Declarations. More...

#include "mongo.h"
#include "bson.h"
#include "platform_hacks.h"
#include <stdio.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
int	gridfs_init (mongo_connection *client, const char *dbname, const char *prefix, gridfs *gfs)
	Initializes a GridFS object.
void	gridfs_destroy (gridfs *gfs)
	Destroys a GridFS object.
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.
void	gridfile_write_buffer (gridfile *gfile, const char *data, gridfs_offset length)
	Write to a GridFS file incrementally.
bson	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.
bson	gridfs_store_buffer (gridfs *gfs, const char *data, gridfs_offset length, const char *remotename, const char *contenttype)
	Store a buffer as a GridFS file.
bson	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.
void	gridfs_remove_filename (gridfs *gfs, const char *filename)
	Removes the files referenced by filename from the db.
int	gridfs_find_query (gridfs *gfs, bson *query, gridfile *gfile)
	Find the first query within the GridFS and return it as a GridFile.
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.
int	gridfile_init (gridfs *gfs, bson *meta, gridfile *gfile)
	Initializes a GridFile containing the GridFS and file bson.
void	gridfile_destroy (gridfile *gfile)
	Destroys the GridFile.
int	gridfile_exists (gridfile *gfile)
	Returns whether or not the GridFile exists.
const char *	gridfile_get_filename (gridfile *gfile)
	Returns the filename of GridFile.
int	gridfile_get_chunksize (gridfile *gfile)
	Returns the size of the chunks of the GridFile.
gridfs_offset	gridfile_get_contentlength (gridfile *gfile)
	Returns the length of GridFile's data.
const char *	gridfile_get_contenttype (gridfile *gfile)
	Returns the MIME type of the GridFile.
bson_date_t	gridfile_get_uploaddate (gridfile *gfile)
	Returns the upload date of GridFile.
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.
bson	gridfile_get_metadata (gridfile *gfile)
	Returns the metadata of GridFile.
int	gridfile_get_numchunks (gridfile *gfile)
	Returns the number of chunks in the GridFile.
bson	gridfile_get_chunk (gridfile *gfile, int n)
	Returns chunk n of GridFile.
mongo_cursor *	gridfile_get_chunks (gridfile *gfile, int start, int size)
	Returns a mongo_cursor of *size* chunks starting with chunk *start*.
gridfs_offset	gridfile_write_file (gridfile *gfile, FILE *stream)
	Writes the GridFile to a stream.
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.
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

void gridfile_destroy

(

gridfile *

gfile

)

Destroys the GridFile.

Parameters:

oGridFIle

- the GridFile being destroyed

int 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)

bson gridfile_get_chunk	(	gridfile *	gfile,
		int	n
	)

Returns chunk n of GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the nth chunk of the Gridfile

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)

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

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

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)

const char* gridfile_get_filename

(

gridfile *

gfile

)

Returns the filename of GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the filename of the Gridfile

const char* gridfile_get_md5

(

gridfile *

gfile

)

Returns the MD5 of GridFile.

Parameters:

gfile

- the working GridFile

Returns:

- the MD5 of the Gridfile

bson gridfile_get_metadata

(

gridfile *

gfile

)

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)

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

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

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:

1 if successful, 0 otherwise

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

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

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.

Returns:

- 1 if successful, 0 otherwise

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

bson 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:

- the file object if successful; otherwise 0.

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.

Returns:

- 1 if successful, 0 otherwise

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:

1 if successful, 0 otherwise

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

Find the first query within the GridFS and return it 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:

1 if successful, 0 otherwise

int gridfs_init	(	mongo_connection *	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:

- 1 if successful, 0 otherwise

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

bson 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:

- the file object

bson 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:

- the file object