1 /*
2  * Copyright (C) the libgit2 contributors. All rights reserved.
3  *
4  * This file is part of libgit2, distributed under the GNU GPL v2 with
5  * a Linking Exception. For full terms see the included COPYING file.
6  */
7 module libgit2_d.odb;
8 
9 
10 private static import libgit2_d.indexer;
11 private static import libgit2_d.oid;
12 private static import libgit2_d.types;
13 
14 /**
15  * @file git2/odb.h
16  * @brief Git object database routines
17  * @defgroup git_odb Git object database routines
18  * @ingroup Git
19  * @{
20  */
21 extern (C):
22 nothrow @nogc:
23 public:
24 
25 /**
26  * Function type for callbacks from git_odb_foreach.
27  */
28 alias git_odb_foreach_cb = int function(const (libgit2_d.oid.git_oid)* id, void* payload);
29 
30 /**
31  * Create a new object database with no backends.
32  *
33  * Before the ODB can be used for read/writing, a custom database
34  * backend must be manually added using `git_odb_add_backend()`
35  *
36  * Params:
37  *      out_ = location to store the database pointer, if opened. Set to null if the open failed.
38  *
39  * Returns: 0 or an error code
40  */
41 //GIT_EXTERN
42 int git_odb_new(libgit2_d.types.git_odb** out_);
43 
44 /**
45  * Create a new object database and automatically add
46  * the two default backends:
47  *
48  *	- git_odb_backend_loose: read and write loose object files
49  *		from disk, assuming `objects_dir` as the Objects folder
50  *
51  *	- git_odb_backend_pack: read objects from packfiles,
52  *		assuming `objects_dir` as the Objects folder which
53  *		contains a 'pack/' folder with the corresponding data
54  *
55  * Params:
56  *      out_ = location to store the database pointer, if opened. Set to null if the open failed.
57  *      objects_dir = path of the backends' "objects" directory.
58  *
59  * Returns: 0 or an error code
60  */
61 //GIT_EXTERN
62 int git_odb_open(libgit2_d.types.git_odb** out_, const (char)* objects_dir);
63 
64 /**
65  * Add an on-disk alternate to an existing Object DB.
66  *
67  * Note that the added path must point to an `objects`, not
68  * to a full repository, to use it as an alternate store.
69  *
70  * Alternate backends are always checked for objects *after*
71  * all the main backends have been exhausted.
72  *
73  * Writing is disabled on alternate backends.
74  *
75  * Params:
76  *      odb = database to add the backend to
77  *      path = path to the objects folder for the alternate
78  *
79  * Returns: 0 on success; error code otherwise
80  */
81 //GIT_EXTERN
82 int git_odb_add_disk_alternate(libgit2_d.types.git_odb* odb, const (char)* path);
83 
84 /**
85  * Close an open object database.
86  *
87  * Params:
88  *      db = database pointer to close. If null no action is taken.
89  */
90 //GIT_EXTERN
91 void git_odb_free(libgit2_d.types.git_odb* db);
92 
93 /**
94  * Read an object from the database.
95  *
96  * This method queries all available ODB backends
97  * trying to read the given OID.
98  *
99  * The returned object is reference counted and
100  * internally cached, so it should be closed
101  * by the user once it's no longer in use.
102  *
103  * Params:
104  *      out_ = pointer where to store the read object
105  *      db = database to search for the object in.
106  *      id = identity of the object to read.
107  *
108  * @return
109  * - 0 if the object was read;
110  * - git_error_code.GIT_ENOTFOUND if the object is not in the database.
111  */
112 //GIT_EXTERN
113 int git_odb_read(libgit2_d.types.git_odb_object** out_, libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* id);
114 
115 /**
116  * Read an object from the database, given a prefix
117  * of its identifier.
118  *
119  * This method queries all available ODB backends
120  * trying to match the 'len' first hexadecimal
121  * characters of the 'short_id'.
122  * The remaining (GIT_OID_HEXSZ-len)*4 bits of
123  * 'short_id' must be 0s.
124  * 'len' must be at least GIT_OID_MINPREFIXLEN,
125  * and the prefix must be long enough to identify
126  * a unique object in all the backends; the
127  * method will fail otherwise.
128  *
129  * The returned object is reference counted and
130  * internally cached, so it should be closed
131  * by the user once it's no longer in use.
132  *
133  * Params:
134  *      out_ = pointer where to store the read object
135  *      db = database to search for the object in.
136  *      short_id = a prefix of the id of the object to read.
137  *      len = the length of the prefix
138  *
139  * @return
140  * - 0 if the object was read;
141  * - git_error_code.GIT_ENOTFOUND if the object is not in the database.
142  * - git_error_code.GIT_EAMBIGUOUS if the prefix is ambiguous (several objects match the
143  * prefix)
144  */
145 //GIT_EXTERN
146 int git_odb_read_prefix(libgit2_d.types.git_odb_object** out_, libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* short_id, size_t len);
147 
148 /**
149  * Read the header of an object from the database, without
150  * reading its full contents.
151  *
152  * The header includes the length and the type of an object.
153  *
154  * Note that most backends do not support reading only the header
155  * of an object, so the whole object will be read and then the
156  * header will be returned.
157  *
158  * Params:
159  *      len_out = pointer where to store the length
160  *      type_out = pointer where to store the type
161  *      db = database to search for the object in.
162  *      id = identity of the object to read.
163  *
164  * @return
165  * - 0 if the object was read;
166  * - git_error_code.GIT_ENOTFOUND if the object is not in the database.
167  */
168 //GIT_EXTERN
169 int git_odb_read_header(size_t* len_out, libgit2_d.types.git_object_t* type_out, libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* id);
170 
171 /**
172  * Determine if the given object can be found in the object database.
173  *
174  * Params:
175  *      db = database to be searched for the given object.
176  *      id = the object to search for.
177  *
178  * @return
179  * - 1, if the object was found
180  * - 0, otherwise
181  */
182 //GIT_EXTERN
183 int git_odb_exists(libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* id);
184 
185 /**
186  * Determine if an object can be found in the object database by an
187  * abbreviated object ID.
188  *
189  * Params:
190  *      out_ = The full OID of the found object if just one is found.
191  *      db = The database to be searched for the given object.
192  *      short_id = A prefix of the id of the object to read.
193  *      len = The length of the prefix.
194  *
195  * Returns: 0 if found, git_error_code.GIT_ENOTFOUND if not found, git_error_code.GIT_EAMBIGUOUS if multiple matches were found, other value < 0 if there was a read error.
196  */
197 //GIT_EXTERN
198 int git_odb_exists_prefix(libgit2_d.oid.git_oid* out_, libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* short_id, size_t len);
199 
200 /**
201  * The information about object IDs to query in `git_odb_expand_ids`,
202  * which will be populated upon return.
203  */
204 struct git_odb_expand_id
205 {
206 	/**
207 	 * The object ID to expand
208 	 */
209 	libgit2_d.oid.git_oid id;
210 
211 	/**
212 	 * The length of the object ID (in nibbles, or packets of 4 bits; the
213 	 * number of hex characters)
214 	 * */
215 	ushort length;
216 
217 	/**
218 	 * The (optional) type of the object to search for; leave as `0` or set
219 	 * to `git_object_t.GIT_OBJECT_ANY` to query for any object matching the ID.
220 	 */
221 	libgit2_d.types.git_object_t type = cast(libgit2_d.types.git_object_t)(0);
222 }
223 
224 /**
225  * Determine if one or more objects can be found in the object database
226  * by their abbreviated object ID and type.  The given array will be
227  * updated in place:  for each abbreviated ID that is unique in the
228  * database, and of the given type (if specified), the full object ID,
229  * object ID length (`GIT_OID_HEXSZ`) and type will be written back to
230  * the array.  For IDs that are not found (or are ambiguous), the
231  * array entry will be zeroed.
232  *
233  * Note that since this function operates on multiple objects, the
234  * underlying database will not be asked to be reloaded if an object is
235  * not found (which is unlike other object database operations.)
236  *
237  * Params:
238  *      db = The database to be searched for the given objects.
239  *      ids = An array of short object IDs to search for
240  *      count = The length of the `ids` array
241  *
242  * Returns: 0 on success or an error code on failure
243  */
244 //GIT_EXTERN
245 int git_odb_expand_ids(libgit2_d.types.git_odb* db, .git_odb_expand_id* ids, size_t count);
246 
247 /**
248  * Refresh the object database to load newly added files.
249  *
250  * If the object databases have changed on disk while the library
251  * is running, this function will force a reload of the underlying
252  * indexes.
253  *
254  * Use this function when you're confident that an external
255  * application has tampered with the ODB.
256  *
257  * NOTE that it is not necessary to call this function at all. The
258  * library will automatically attempt to refresh the ODB
259  * when a lookup fails, to see if the looked up object exists
260  * on disk but hasn't been loaded yet.
261  *
262  * Params:
263  *      db = database to refresh
264  *
265  * Returns: 0 on success, error code otherwise
266  */
267 //GIT_EXTERN
268 int git_odb_refresh(libgit2_d.types.git_odb* db);
269 
270 /**
271  * List all objects available in the database
272  *
273  * The callback will be called for each object available in the
274  * database. Note that the objects are likely to be returned in the index
275  * order, which would make accessing the objects in that order inefficient.
276  * Return a non-zero value from the callback to stop looping.
277  *
278  * Params:
279  *      db = database to use
280  *      cb = the callback to call for each object
281  *      payload = data to pass to the callback
282  *
283  * Returns: 0 on success, non-zero callback return value, or error code
284  */
285 //GIT_EXTERN
286 int git_odb_foreach(libgit2_d.types.git_odb* db, .git_odb_foreach_cb cb, void* payload);
287 
288 /**
289  * Write an object directly into the ODB
290  *
291  * This method writes a full object straight into the ODB.
292  * For most cases, it is preferred to write objects through a write
293  * stream, which is both faster and less memory intensive, specially
294  * for big objects.
295  *
296  * This method is provided for compatibility with custom backends
297  * which are not able to support streaming writes
298  *
299  * Params:
300  *      out_ = pointer to store the OID result of the write
301  *      odb = object database where to store the object
302  *      data = buffer with the data to store
303  *      len = size of the buffer
304  *      type = type of the data to store
305  *
306  * Returns: 0 or an error code
307  */
308 //GIT_EXTERN
309 int git_odb_write(libgit2_d.oid.git_oid* out_, libgit2_d.types.git_odb* odb, const (void)* data, size_t len, libgit2_d.types.git_object_t type);
310 
311 /**
312  * Open a stream to write an object into the ODB
313  *
314  * The type and final length of the object must be specified
315  * when opening the stream.
316  *
317  * The returned stream will be of type `git_odb_stream_t.GIT_STREAM_WRONLY`, and it
318  * won't be effective until `git_odb_stream_finalize_write` is called
319  * and returns without an error
320  *
321  * The stream must always be freed when done with `git_odb_stream_free` or
322  * will leak memory.
323  *
324  * @see git_odb_stream
325  *
326  * Params:
327  *      out_ = pointer where to store the stream
328  *      db = object database where the stream will write
329  *      size = final size of the object that will be written
330  *      type = type of the object that will be written
331  *
332  * Returns: 0 if the stream was created; error code otherwise
333  */
334 //GIT_EXTERN
335 int git_odb_open_wstream(libgit2_d.types.git_odb_stream** out_, libgit2_d.types.git_odb* db, libgit2_d.types.git_object_size_t size, libgit2_d.types.git_object_t type);
336 
337 /**
338  * Write to an odb stream
339  *
340  * This method will fail if the total number of received bytes exceeds the
341  * size declared with `git_odb_open_wstream()`
342  *
343  * Params:
344  *      stream = the stream
345  *      buffer = the data to write
346  *      len = the buffer's length
347  *
348  * Returns: 0 if the write succeeded; error code otherwise
349  */
350 //GIT_EXTERN
351 int git_odb_stream_write(libgit2_d.types.git_odb_stream* stream, const (char)* buffer, size_t len);
352 
353 /**
354  * Finish writing to an odb stream
355  *
356  * The object will take its final name and will be available to the
357  * odb.
358  *
359  * This method will fail if the total number of received bytes
360  * differs from the size declared with `git_odb_open_wstream()`
361  *
362  * Params:
363  *      out_ = pointer to store the resulting object's id
364  *      stream = the stream
365  *
366  * Returns: 0 on success; an error code otherwise
367  */
368 //GIT_EXTERN
369 int git_odb_stream_finalize_write(libgit2_d.oid.git_oid* out_, libgit2_d.types.git_odb_stream* stream);
370 
371 /**
372  * Read from an odb stream
373  *
374  * Most backends don't implement streaming reads
375  */
376 //GIT_EXTERN
377 int git_odb_stream_read(libgit2_d.types.git_odb_stream* stream, char* buffer, size_t len);
378 
379 /**
380  * Free an odb stream
381  *
382  * Params:
383  *      stream = the stream to free
384  */
385 //GIT_EXTERN
386 void git_odb_stream_free(libgit2_d.types.git_odb_stream* stream);
387 
388 /**
389  * Open a stream to read an object from the ODB
390  *
391  * Note that most backends do *not* support streaming reads
392  * because they store their objects as compressed/delta'ed blobs.
393  *
394  * It's recommended to use `git_odb_read` instead, which is
395  * assured to work on all backends.
396  *
397  * The returned stream will be of type `git_odb_stream_t.GIT_STREAM_RDONLY` and
398  * will have the following methods:
399  *
400  *		- stream->read: read `n` bytes from the stream
401  *		- stream->free: free the stream
402  *
403  * The stream must always be free'd or will leak memory.
404  *
405  * @see git_odb_stream
406  *
407  * Params:
408  *      out_ = pointer where to store the stream
409  *      len = pointer where to store the length of the object
410  *      type = pointer where to store the type of the object
411  *      db = object database where the stream will read from
412  *      oid = oid of the object the stream will read from
413  *
414  * Returns: 0 if the stream was created; error code otherwise
415  */
416 //GIT_EXTERN
417 int git_odb_open_rstream(libgit2_d.types.git_odb_stream** out_, size_t* len, libgit2_d.types.git_object_t* type, libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* oid);
418 
419 /**
420  * Open a stream for writing a pack file to the ODB.
421  *
422  * If the ODB layer understands pack files, then the given
423  * packfile will likely be streamed directly to disk (and a
424  * corresponding index created).  If the ODB layer does not
425  * understand pack files, the objects will be stored in whatever
426  * format the ODB layer uses.
427  *
428  * @see git_odb_writepack
429  *
430  * Params:
431  *      out_ = pointer to the writepack functions
432  *      db = object database where the stream will read from
433  *      progress_cb = function to call with progress information. Be aware that this is called inline with network and indexing operations, so performance may be affected.
434  *      progress_payload = payload for the progress callback
435  */
436 //GIT_EXTERN
437 int git_odb_write_pack(libgit2_d.types.git_odb_writepack** out_, libgit2_d.types.git_odb* db, libgit2_d.indexer.git_indexer_progress_cb progress_cb, void* progress_payload);
438 
439 /**
440  * Determine the object-ID (sha1 hash) of a data buffer
441  *
442  * The resulting SHA-1 OID will be the identifier for the data
443  * buffer as if the data buffer it were to written to the ODB.
444  *
445  * Params:
446  *      out_ = the resulting object-ID.
447  *      data = data to hash
448  *      len = size of the data
449  *      type = of the data to hash
450  *
451  * Returns: 0 or an error code
452  */
453 //GIT_EXTERN
454 int git_odb_hash(libgit2_d.oid.git_oid* out_, const (void)* data, size_t len, libgit2_d.types.git_object_t type);
455 
456 /**
457  * Read a file from disk and fill a git_oid with the object id
458  * that the file would have if it were written to the Object
459  * Database as an object of the given type (w/o applying filters).
460  * Similar functionality to git.git's `git hash-object` without
461  * the `-w` flag, however, with the --no-filters flag.
462  * If you need filters, see git_repository_hashfile.
463  *
464  * Params:
465  *      out_ = oid structure the result is written into.
466  *      path = file to read and determine object id for
467  *      type = the type of the object that will be hashed
468  *
469  * Returns: 0 or an error code
470  */
471 //GIT_EXTERN
472 int git_odb_hashfile(libgit2_d.oid.git_oid* out_, const (char)* path, libgit2_d.types.git_object_t type);
473 
474 /**
475  * Create a copy of an odb_object
476  *
477  * The returned copy must be manually freed with `git_odb_object_free`.
478  * Note that because of an implementation detail, the returned copy will be
479  * the same pointer as `source`: the object is internally refcounted, so the
480  * copy still needs to be freed twice.
481  *
482  * Params:
483  *      dest = pointer where to store the copy
484  *      source = object to copy
485  *
486  * Returns: 0 or an error code
487  */
488 //GIT_EXTERN
489 int git_odb_object_dup(libgit2_d.types.git_odb_object** dest, libgit2_d.types.git_odb_object* source);
490 
491 /**
492  * Close an ODB object
493  *
494  * This method must always be called once a `git_odb_object` is no
495  * longer needed, otherwise memory will leak.
496  *
497  * Params:
498  *      object = object to close
499  */
500 //GIT_EXTERN
501 void git_odb_object_free(libgit2_d.types.git_odb_object* object);
502 
503 /**
504  * Return the OID of an ODB object
505  *
506  * This is the OID from which the object was read from
507  *
508  * Params:
509  *      object = the object
510  *
511  * Returns: a pointer to the OID
512  */
513 //GIT_EXTERN
514 const (libgit2_d.oid.git_oid)* git_odb_object_id(libgit2_d.types.git_odb_object* object);
515 
516 /**
517  * Return the data of an ODB object
518  *
519  * This is the uncompressed, raw data as read from the ODB,
520  * without the leading header.
521  *
522  * This pointer is owned by the object and shall not be free'd.
523  *
524  * Params:
525  *      object = the object
526  *
527  * Returns: a pointer to the data
528  */
529 //GIT_EXTERN
530 const (void)* git_odb_object_data(libgit2_d.types.git_odb_object* object);
531 
532 /**
533  * Return the size of an ODB object
534  *
535  * This is the real size of the `data` buffer, not the
536  * actual size of the object.
537  *
538  * Params:
539  *      object = the object
540  *
541  * Returns: the size
542  */
543 //GIT_EXTERN
544 size_t git_odb_object_size(libgit2_d.types.git_odb_object* object);
545 
546 /**
547  * Return the type of an ODB object
548  *
549  * Params:
550  *      object = the object
551  *
552  * Returns: the type
553  */
554 //GIT_EXTERN
555 libgit2_d.types.git_object_t git_odb_object_type(libgit2_d.types.git_odb_object* object);
556 
557 /**
558  * Add a custom backend to an existing Object DB
559  *
560  * The backends are checked in relative ordering, based on the
561  * value of the `priority` parameter.
562  *
563  * Read <sys/odb_backend.h> for more information.
564  *
565  * Params:
566  *      odb = database to add the backend to
567  *      backend = pointer to a git_odb_backend instance
568  *      priority = Value for ordering the backends queue
569  *
570  * Returns: 0 on success; error code otherwise
571  */
572 //GIT_EXTERN
573 int git_odb_add_backend(libgit2_d.types.git_odb* odb, libgit2_d.types.git_odb_backend* backend, int priority);
574 
575 /**
576  * Add a custom backend to an existing Object DB; this
577  * backend will work as an alternate.
578  *
579  * Alternate backends are always checked for objects *after*
580  * all the main backends have been exhausted.
581  *
582  * The backends are checked in relative ordering, based on the
583  * value of the `priority` parameter.
584  *
585  * Writing is disabled on alternate backends.
586  *
587  * Read <sys/odb_backend.h> for more information.
588  *
589  * Params:
590  *      odb = database to add the backend to
591  *      backend = pointer to a git_odb_backend instance
592  *      priority = Value for ordering the backends queue
593  *
594  * Returns: 0 on success; error code otherwise
595  */
596 //GIT_EXTERN
597 int git_odb_add_alternate(libgit2_d.types.git_odb* odb, libgit2_d.types.git_odb_backend* backend, int priority);
598 
599 /**
600  * Get the number of ODB backend objects
601  *
602  * Params:
603  *      odb = object database
604  *
605  * Returns: number of backends in the ODB
606  */
607 //GIT_EXTERN
608 size_t git_odb_num_backends(libgit2_d.types.git_odb* odb);
609 
610 /**
611  * Lookup an ODB backend object by index
612  *
613  * Params:
614  *      out_ = output pointer to ODB backend at pos
615  *      odb = object database
616  *      pos = index into object database backend list
617  *
618  * Returns: 0 on success; git_error_code.GIT_ENOTFOUND if pos is invalid; other errors < 0
619  */
620 //GIT_EXTERN
621 int git_odb_get_backend(libgit2_d.types.git_odb_backend** out_, libgit2_d.types.git_odb* odb, size_t pos);
622 
623 /** @} */