1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
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
|
