MongoDBCDriver  0.7.1
Classes | Typedefs | Enumerations | Functions
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 gridfsgridfs_create (void)
MONGO_EXPORT void gridfs_dispose (gridfs *gfs)
MONGO_EXPORT gridfilegridfile_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_cursorgridfile_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:
gfsa 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.