]>
Commit | Line | Data |
---|---|---|
83cc70d9 RB |
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 | #ifndef INCLUDE_sys_git_odb_backend_h__ | |
8 | #define INCLUDE_sys_git_odb_backend_h__ | |
9 | ||
10 | #include "git2/common.h" | |
11 | #include "git2/types.h" | |
12 | #include "git2/oid.h" | |
13 | #include "git2/odb.h" | |
14 | ||
15 | /** | |
16 | * @file git2/sys/backend.h | |
17 | * @brief Git custom backend implementors functions | |
18 | * @defgroup git_backend Git custom backend APIs | |
19 | * @ingroup Git | |
20 | * @{ | |
21 | */ | |
22 | GIT_BEGIN_DECL | |
23 | ||
24 | /** | |
25 | * An instance for a custom backend | |
26 | */ | |
27 | struct git_odb_backend { | |
28 | unsigned int version; | |
29 | git_odb *odb; | |
30 | ||
31 | /* read and read_prefix each return to libgit2 a buffer which | |
32 | * will be freed later. The buffer should be allocated using | |
22a2d3d5 UG |
33 | * the function git_odb_backend_data_alloc to ensure that libgit2 |
34 | * can safely free it later. */ | |
ac3d33df JK |
35 | int GIT_CALLBACK(read)( |
36 | void **, size_t *, git_object_t *, git_odb_backend *, const git_oid *); | |
83cc70d9 | 37 | |
f5753999 RB |
38 | /* To find a unique object given a prefix of its oid. The oid given |
39 | * must be so that the remaining (GIT_OID_HEXSZ - len)*4 bits are 0s. | |
83cc70d9 | 40 | */ |
ac3d33df JK |
41 | int GIT_CALLBACK(read_prefix)( |
42 | git_oid *, void **, size_t *, git_object_t *, | |
83cc70d9 RB |
43 | git_odb_backend *, const git_oid *, size_t); |
44 | ||
ac3d33df JK |
45 | int GIT_CALLBACK(read_header)( |
46 | size_t *, git_object_t *, git_odb_backend *, const git_oid *); | |
83cc70d9 | 47 | |
7a3764be CMN |
48 | /** |
49 | * Write an object into the backend. The id of the object has | |
50 | * already been calculated and is passed in. | |
51 | */ | |
ac3d33df JK |
52 | int GIT_CALLBACK(write)( |
53 | git_odb_backend *, const git_oid *, const void *, size_t, git_object_t); | |
83cc70d9 | 54 | |
ac3d33df | 55 | int GIT_CALLBACK(writestream)( |
22a2d3d5 | 56 | git_odb_stream **, git_odb_backend *, git_object_size_t, git_object_t); |
83cc70d9 | 57 | |
ac3d33df JK |
58 | int GIT_CALLBACK(readstream)( |
59 | git_odb_stream **, size_t *, git_object_t *, | |
eae0bfdc | 60 | git_odb_backend *, const git_oid *); |
83cc70d9 | 61 | |
ac3d33df | 62 | int GIT_CALLBACK(exists)( |
83cc70d9 RB |
63 | git_odb_backend *, const git_oid *); |
64 | ||
ac3d33df | 65 | int GIT_CALLBACK(exists_prefix)( |
f5753999 RB |
66 | git_oid *, git_odb_backend *, const git_oid *, size_t); |
67 | ||
b1a6c316 | 68 | /** |
69 | * If the backend implements a refreshing mechanism, it should be exposed | |
70 | * through this endpoint. Each call to `git_odb_refresh()` will invoke it. | |
71 | * | |
72 | * However, the backend implementation should try to stay up-to-date as much | |
73 | * as possible by itself as libgit2 will not automatically invoke | |
74 | * `git_odb_refresh()`. For instance, a potential strategy for the backend | |
75 | * implementation to achieve this could be to internally invoke this | |
76 | * endpoint on failed lookups (ie. `exists()`, `read()`, `read_header()`). | |
77 | */ | |
ac3d33df | 78 | int GIT_CALLBACK(refresh)(git_odb_backend *); |
83cc70d9 | 79 | |
ac3d33df | 80 | int GIT_CALLBACK(foreach)( |
83cc70d9 RB |
81 | git_odb_backend *, git_odb_foreach_cb cb, void *payload); |
82 | ||
ac3d33df | 83 | int GIT_CALLBACK(writepack)( |
0b33fca0 | 84 | git_odb_writepack **, git_odb_backend *, git_odb *odb, |
22a2d3d5 | 85 | git_indexer_progress_cb progress_cb, void *progress_payload); |
83cc70d9 | 86 | |
c25aa7cd PP |
87 | /** |
88 | * If the backend supports pack files, this will create a | |
89 | * `multi-pack-index` file which will contain an index of all objects | |
90 | * across all the `.pack` files. | |
91 | */ | |
92 | int GIT_CALLBACK(writemidx)(git_odb_backend *); | |
93 | ||
8f09a98e ET |
94 | /** |
95 | * "Freshens" an already existing object, updating its last-used | |
96 | * time. This occurs when `git_odb_write` was called, but the | |
97 | * object already existed (and will not be re-written). The | |
98 | * underlying implementation may want to update last-used timestamps. | |
99 | * | |
100 | * If callers implement this, they should return `0` if the object | |
101 | * exists and was freshened, and non-zero otherwise. | |
102 | */ | |
ac3d33df | 103 | int GIT_CALLBACK(freshen)(git_odb_backend *, const git_oid *); |
8f09a98e | 104 | |
d3b29fb9 AS |
105 | /** |
106 | * Frees any resources held by the odb (including the `git_odb_backend` | |
107 | * itself). An odb backend implementation must provide this function. | |
108 | */ | |
ac3d33df | 109 | void GIT_CALLBACK(free)(git_odb_backend *); |
83cc70d9 RB |
110 | }; |
111 | ||
112 | #define GIT_ODB_BACKEND_VERSION 1 | |
113 | #define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION} | |
114 | ||
b9f81997 MB |
115 | /** |
116 | * Initializes a `git_odb_backend` with default values. Equivalent to | |
117 | * creating an instance with GIT_ODB_BACKEND_INIT. | |
118 | * | |
41808d04 | 119 | * @param backend the `git_odb_backend` struct to initialize. |
bc91347b | 120 | * @param version Version the struct; pass `GIT_ODB_BACKEND_VERSION` |
b9f81997 MB |
121 | * @return Zero on success; -1 on failure. |
122 | */ | |
123 | GIT_EXTERN(int) git_odb_init_backend( | |
bc91347b RB |
124 | git_odb_backend *backend, |
125 | unsigned int version); | |
b9f81997 | 126 | |
22a2d3d5 UG |
127 | /** |
128 | * Allocate data for an ODB object. Custom ODB backends may use this | |
129 | * to provide data back to the ODB from their read function. This | |
130 | * memory should not be freed once it is returned to libgit2. If a | |
131 | * custom ODB uses this function but encounters an error and does not | |
132 | * return this data to libgit2, then they should use the corresponding | |
133 | * git_odb_backend_data_free function. | |
134 | * | |
135 | * @param backend the ODB backend that is allocating this memory | |
136 | * @param len the number of bytes to allocate | |
137 | * @return the allocated buffer on success or NULL if out of memory | |
138 | */ | |
139 | GIT_EXTERN(void *) git_odb_backend_data_alloc(git_odb_backend *backend, size_t len); | |
140 | ||
141 | /** | |
142 | * Frees custom allocated ODB data. This should only be called when | |
143 | * memory allocated using git_odb_backend_data_alloc is not returned | |
144 | * to libgit2 because the backend encountered an error in the read | |
145 | * function after allocation and did not return this data to libgit2. | |
146 | * | |
147 | * @param backend the ODB backend that is freeing this memory | |
148 | * @param data the buffer to free | |
149 | */ | |
150 | GIT_EXTERN(void) git_odb_backend_data_free(git_odb_backend *backend, void *data); | |
151 | ||
152 | ||
153 | /* | |
154 | * Users can avoid deprecated functions by defining `GIT_DEPRECATE_HARD`. | |
155 | */ | |
156 | #ifndef GIT_DEPRECATE_HARD | |
157 | ||
158 | /** | |
159 | * Allocate memory for an ODB object from a custom backend. This is | |
160 | * an alias of `git_odb_backend_data_alloc` and is preserved for | |
161 | * backward compatibility. | |
162 | * | |
163 | * This function is deprecated, but there is no plan to remove this | |
164 | * function at this time. | |
165 | * | |
166 | * @deprecated git_odb_backend_data_alloc | |
167 | * @see git_odb_backend_data_alloc | |
168 | */ | |
83cc70d9 RB |
169 | GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len); |
170 | ||
22a2d3d5 UG |
171 | #endif |
172 | ||
83cc70d9 RB |
173 | GIT_END_DECL |
174 | ||
175 | #endif |