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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
/*
* This file is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License, version 2,
* as published by the Free Software Foundation.
*
* In addition to the permissions in the GNU General Public License,
* the authors give you unlimited permission to link the compiled
* version of this file into combinations with other programs,
* and to distribute those combinations without any restriction
* coming from the use of this file. (The General Public License
* restrictions do apply in other respects; for example, they cover
* modification of the file, and distribution when not linked into
* a combined executable.)
*
* This file is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; see the file COPYING. If not, write to
* the Free Software Foundation, 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
*/
#ifndef INCLUDE_git_odb_h__
#define INCLUDE_git_odb_h__
#include "common.h"
#include "types.h"
#include "oid.h"
#include "odb_backend.h"
/**
* @file git2/odb.h
* @brief Git object database routines
* @defgroup git_odb Git object database routines
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
* Create a new object database with no backends.
*
* Before the ODB can be used for read/writing, a custom database
* backend must be manually added using `git_odb_add_backend()`
*
* @param out location to store the database pointer, if opened.
* Set to NULL if the open failed.
* @return GIT_SUCCESS if the database was created; otherwise an error
* code describing why the open was not possible.
*/
GIT_EXTERN(int) git_odb_new(git_odb **out);
/**
* Create a new object database and automatically add
* the two default backends:
*
* - git_odb_backend_loose: read and write loose object files
* from disk, assuming `objects_dir` as the Objects folder
*
* - git_odb_backend_pack: read objects from packfiles,
* assuming `objects_dir` as the Objects folder which
* contains a 'pack/' folder with the corresponding data
*
* @param out location to store the database pointer, if opened.
* Set to NULL if the open failed.
* @param objects_dir path of the backends' "objects" directory.
* @return GIT_SUCCESS if the database opened; otherwise an error
* code describing why the open was not possible.
*/
GIT_EXTERN(int) git_odb_open(git_odb **out, const char *objects_dir);
/**
* Add a custom backend to an existing Object DB
*
* Read <odb_backends.h> for more information.
*
* @param odb database to add the backend to
* @paramm backend pointer to a git_odb_backend instance
* @return 0 on sucess; error code otherwise
*/
GIT_EXTERN(int) git_odb_add_backend(git_odb *odb, git_odb_backend *backend, int priority);
/**
* Add a custom backend to an existing Object DB; this
* backend will work as an alternate.
*
* Alternate backends are always checked for objects *after*
* all the main backends have been exhausted.
*
* Writing is disabled on alternate backends.
*
* Read <odb_backends.h> for more information.
*
* @param odb database to add the backend to
* @paramm backend pointer to a git_odb_backend instance
* @return 0 on sucess; error code otherwise
*/
GIT_EXTERN(int) git_odb_add_alternate(git_odb *odb, git_odb_backend *backend, int priority);
/**
* Close an open object database.
*
* @param db database pointer to close. If NULL no action is taken.
*/
GIT_EXTERN(void) git_odb_close(git_odb *db);
/**
* Read an object from the database.
*
* This method queries all avaiable ODB backends
* trying to read the given OID.
*
* The returned object is reference counted and
* internally cached, so it should be closed
* by the user once it's no longer in use.
*
* @param out pointer where to store the read object
* @param db database to search for the object in.
* @param id identity of the object to read.
* @return
* - GIT_SUCCESS if the object was read;
* - GIT_ENOTFOUND if the object is not in the database.
*/
GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *id);
/**
* Read the header of an object from the database, without
* reading its full contents.
*
* The header includes the length and the type of an object.
*
* Note that most backends do not support reading only the header
* of an object, so the whole object will be read and then the
* header will be returned.
*
* @param len_p pointer where to store the length
* @param type_p pointer where to store the type
* @param db database to search for the object in.
* @param id identity of the object to read.
* @return
* - GIT_SUCCESS if the object was read;
* - GIT_ENOTFOUND if the object is not in the database.
*/
GIT_EXTERN(int) git_odb_read_header(size_t *len_p, git_otype *type_p, git_odb *db, const git_oid *id);
/**
* Determine if the given object can be found in the object database.
*
* @param db database to be searched for the given object.
* @param id the object to search for.
* @return
* - 1, if the object was found
* - 0, otherwise
*/
GIT_EXTERN(int) git_odb_exists(git_odb *db, const git_oid *id);
/**
* Open a stream to write an object into the ODB
*
* The type and final length of the object must be specified
* when opening the stream.
*
* The returned stream will be of type `GIT_STREAM_WRONLY` and
* will have the following methods:
*
* - stream->write: write `n` bytes into the stream
* - stream->finalize_write: close the stream and store the object in
* the odb
* - stream->free: free the stream
*
* The streaming write won't be effective until `stream->finalize_write`
* is called and returns without an error
*
* The stream must always be free'd or will leak memory.
*
* @see git_odb_stream
*
* @param stream pointer where to store the stream
* @param db object database where the stream will write
* @param size final size of the object that will be written
* @para type type of the object that will be written
* @return 0 if the stream was created; error code otherwise
*/
GIT_EXTERN(int) git_odb_open_wstream(git_odb_stream **stream, git_odb *db, size_t size, git_otype type);
/**
* Open a stream to read an object from the ODB
*
* Note that most backends do *not* support streaming reads
* because they store their objects as compressed/delta'ed blobs.
*
* It's recommended to use `git_odb_read` instead, which is
* assured to work on all backends.
*
* The returned stream will be of type `GIT_STREAM_RDONLY` and
* will have the following methods:
*
* - stream->read: read `n` bytes from the stream
* - stream->free: free the stream
*
* The stream must always be free'd or will leak memory.
*
* @see git_odb_stream
*
* @param stream pointer where to store the stream
* @param db object database where the stream will read from
* @param oid oid of the object the stream will read from
* @return 0 if the stream was created; error code otherwise
*/
GIT_EXTERN(int) git_odb_open_rstream(git_odb_stream **stream, git_odb *db, const git_oid *oid);
/**
* Determine the object-ID (sha1 hash) of a data buffer
*
* The resulting SHA-1 OID will the itentifier for the data
* buffer as if the data buffer it were to written to the ODB.
*
* @param id the resulting object-ID.
* @param data data to hash
* @param len size of the data
* @param type of the data to hash
* @return 0 on success; error code otherwise
*/
GIT_EXTERN(int) git_odb_hash(git_oid *id, const void *data, size_t len, git_otype type);
/**
* Close an ODB object
*
* This method must always be called once a `git_odb_object` is no
* longer needed, otherwise memory will leak.
*
* @param object object to close
*/
GIT_EXTERN(void) git_odb_object_close(git_odb_object *object);
/** @} */
GIT_END_DECL
#endif
|
