1 files changed, 134 insertions, 0 deletions
diff --git a/src/sync-gridfs-chunk.h b/src/sync-gridfs-chunk.h
new file mode 100644
index 0000000..e567328
--- /dev/null
+++ b/src/sync-gridfs-chunk.h
@@ -0,0 +1,134 @@
+/* sync-gridfs-chunk.h - libmong-client GridFS chunk API
+ * Copyright 2011, 2012 Gergely Nagy <algernon@balabit.hu>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** @file src/sync-gridfs-chunk.h
+ * MongoDB GridFS Chunk API.
+ *
+ * @addtogroup mongo_sync_gridfs_api
+ * @{
+ */
+
+#ifndef LIBMONGO_SYNC_GRIDFS_CHUNK_H
+#define LIBMONGO_SYNC_GRIDFS_CHUNK_H 1
+
+#include <sync-gridfs.h>
+#include <glib.h>
+
+G_BEGIN_DECLS
+
+/** @defgroup mongo_sync_gridfs_chunk_api Mongo GridFS Chunk API
+ *
+ * This submodule provides chunk-based access to GridFS
+ * files. Chunk-based access has the advantage of being reasonably
+ * lightweight and fast, and the disadvantage of making it harder to
+ * do arbitrary reads or multi-part writes.
+ *
+ * It's best used when the whole file needs to be retrieved, or when
+ * uploading files that either fit in a buffer, or can be mmapped.
+ *
+ * @addtogroup mongo_sync_gridfs_chunk_api
+ * @{
+ */
+
+/** Opaque GridFS chunked file object. */
+typedef struct _mongo_sync_gridfs_chunked_file mongo_sync_gridfs_chunked_file;
+
+/** Find a file on GridFS.
+ *
+ * Finds a file on GridFS, based on a custom query.
+ *
+ * @param gfs is the GridFS to find the file in.
+ * @param query is the custom query based on which the file shall be
+ * sought.
+ *
+ * @returns A newly allocated chunked file object, or NULL on
+ * error. It is the responsibility of the caller to free the returned
+ * object once it is no longer needed.
+ */
+mongo_sync_gridfs_chunked_file *mongo_sync_gridfs_chunked_find (mongo_sync_gridfs *gfs,
+                                                                const bson *query);
+
+/** Upload a file to GridFS from a buffer.
+ *
+ * Create a new file on GridFS from a buffer, using custom meta-data.
+ *
+ * @param gfs is the GridFS to create the file on.
+ * @param metadata is the (optional) file metadata.
+ * @param data is the data to store on GridFS.
+ * @param size is the size of the data.
+ *
+ * @returns A newly allocated file object, or NULL on error. It is the
+ * responsibility of the caller to free the returned object once it is
+ * no longer needed.
+ *
+ * @note The metadata MUST NOT contain any of the required GridFS
+ * metadata fields (_id, length, chunkSize, uploadDate, md5),
+ * otherwise a conflict will occurr, against which the function does
+ * not guard by design.
+ */
+mongo_sync_gridfs_chunked_file *mongo_sync_gridfs_chunked_file_new_from_buffer (mongo_sync_gridfs *gfs,
+                                                                                const bson *metadata,
+                                                                                const guint8 *data,
+                                                                                gint64 size);
+/** Free a GridFS chunked file object.
+ *
+ * @param gfile is the file object to free.
+ */
+void mongo_sync_gridfs_chunked_file_free (mongo_sync_gridfs_chunked_file *gfile);
+
+/* Data access */
+
+/** Create a cursor for a GridFS chunked file.
+ *
+ * The cursor can be used (via
+ * mongo_sync_gridfs_file_cursor_get_chunk()) to retrieve a GridFS
+ * file chunk by chunk.
+ *
+ * @param gfile is the GridFS chunked file to work with.
+ * @param start is the starting chunk.
+ * @param num is the total number of chunks to make a cursor for.
+ *
+ * @returns A newly allocated cursor object, or NULL on error. It is
+ * the responsibility of the caller to free the cursor once it is no
+ * longer needed.
+ */
+mongo_sync_cursor *mongo_sync_gridfs_chunked_file_cursor_new (mongo_sync_gridfs_chunked_file *gfile,
+                                                              gint start, gint num);
+
+/** Get the data of a GridFS file chunk, via a cursor.
+ *
+ * Once we have a cursor, it can be iterated over with
+ * mongo_sync_cursor_next(), and its data can be conveniently accessed
+ * with this function.
+ *
+ * @param cursor is the cursor object to work with.
+ * @param size is a pointer to a variable where the chunk's actual
+ * size can be stored.
+ *
+ * @returns A pointer to newly allocated memory that holds the current
+ * chunk's data, or NULL on error. It is the responsibility of the
+ * caller to free this once it is no longer needed.
+ */
+guint8 *mongo_sync_gridfs_chunked_file_cursor_get_chunk (mongo_sync_cursor *cursor,
+                                                         gint32 *size);
+
+/** @} */
+
+G_END_DECLS
+
+/** @} */
+
+#endif