]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
5e0de328 | 2 | * Copyright (C) 2009-2012 the libgit2 contributors |
f5918330 | 3 | * |
bb742ede VM |
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. | |
f5918330 | 6 | */ |
d12299fe VM |
7 | #ifndef INCLUDE_git_object_h__ |
8 | #define INCLUDE_git_object_h__ | |
9 | ||
10 | #include "common.h" | |
11 | #include "types.h" | |
12 | #include "oid.h" | |
13 | ||
14 | /** | |
f5918330 | 15 | * @file git2/object.h |
d12299fe VM |
16 | * @brief Git revision object management routines |
17 | * @defgroup git_object Git revision object management routines | |
18 | * @ingroup Git | |
19 | * @{ | |
20 | */ | |
21 | GIT_BEGIN_DECL | |
22 | ||
5de079b8 | 23 | /** |
d73c94b2 | 24 | * Lookup a reference to one of the objects in a repository. |
5de079b8 VM |
25 | * |
26 | * The generated reference is owned by the repository and | |
45e79e37 | 27 | * should be closed with the `git_object_free` method |
72a3fe42 | 28 | * instead of free'd manually. |
5de079b8 VM |
29 | * |
30 | * The 'type' parameter must match the type of the object | |
31 | * in the odb; the method will fail otherwise. | |
32 | * The special value 'GIT_OBJ_ANY' may be passed to let | |
33 | * the method guess the object's type. | |
34 | * | |
35 | * @param object pointer to the looked-up object | |
36 | * @param repo the repository to look up the object | |
37 | * @param id the unique identifier for the object | |
38 | * @param type the type of the object | |
39 | * @return a reference to the object | |
40 | */ | |
d0323a5f VM |
41 | GIT_EXTERN(int) git_object_lookup( |
42 | git_object **object, | |
43 | git_repository *repo, | |
44 | const git_oid *id, | |
45 | git_otype type); | |
5de079b8 | 46 | |
dd453c4d | 47 | /** |
d73c94b2 | 48 | * Lookup a reference to one of the objects in a repository, |
dd453c4d MP |
49 | * given a prefix of its identifier (short id). |
50 | * | |
51 | * The object obtained will be so that its identifier | |
52 | * matches the first 'len' hexadecimal characters | |
53 | * (packets of 4 bits) of the given 'id'. | |
ac2b94ad MP |
54 | * 'len' must be at least GIT_OID_MINPREFIXLEN, and |
55 | * long enough to identify a unique object matching | |
56 | * the prefix; otherwise the method will fail. | |
dd453c4d MP |
57 | * |
58 | * The generated reference is owned by the repository and | |
45e79e37 | 59 | * should be closed with the `git_object_free` method |
dd453c4d MP |
60 | * instead of free'd manually. |
61 | * | |
62 | * The 'type' parameter must match the type of the object | |
63 | * in the odb; the method will fail otherwise. | |
64 | * The special value 'GIT_OBJ_ANY' may be passed to let | |
65 | * the method guess the object's type. | |
66 | * | |
d144c569 | 67 | * @param object_out pointer where to store the looked-up object |
dd453c4d MP |
68 | * @param repo the repository to look up the object |
69 | * @param id a short identifier for the object | |
70 | * @param len the length of the short identifier | |
71 | * @param type the type of the object | |
e172cf08 | 72 | * @return 0 or an error code |
dd453c4d | 73 | */ |
d0323a5f VM |
74 | GIT_EXTERN(int) git_object_lookup_prefix( |
75 | git_object **object_out, | |
76 | git_repository *repo, | |
77 | const git_oid *id, | |
b8457baa | 78 | size_t len, |
d0323a5f | 79 | git_otype type); |
dd453c4d | 80 | |
d12299fe VM |
81 | /** |
82 | * Get the id (SHA1) of a repository object | |
83 | * | |
d12299fe VM |
84 | * @param obj the repository object |
85 | * @return the SHA1 id | |
86 | */ | |
17cdf252 | 87 | GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj); |
d12299fe VM |
88 | |
89 | /** | |
90 | * Get the object type of an object | |
91 | * | |
92 | * @param obj the repository object | |
93 | * @return the object's type | |
94 | */ | |
17cdf252 | 95 | GIT_EXTERN(git_otype) git_object_type(const git_object *obj); |
d12299fe VM |
96 | |
97 | /** | |
98 | * Get the repository that owns this object | |
99 | * | |
ef5ffed3 VM |
100 | * Freeing or calling `git_repository_close` on the |
101 | * returned pointer will invalidate the actual object. | |
102 | * | |
103 | * Any other operation may be run on the repository without | |
104 | * affecting the object. | |
105 | * | |
d12299fe VM |
106 | * @param obj the object |
107 | * @return the repository who owns this object | |
108 | */ | |
17cdf252 | 109 | GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj); |
d12299fe VM |
110 | |
111 | /** | |
48c27f86 | 112 | * Close an open object |
d12299fe | 113 | * |
48c27f86 | 114 | * This method instructs the library to close an existing |
6b2a1941 VM |
115 | * object; note that git_objects are owned and cached by the repository |
116 | * so the object may or may not be freed after this library call, | |
d73c94b2 | 117 | * depending on how aggressive is the caching mechanism used |
6b2a1941 | 118 | * by the repository. |
d12299fe | 119 | * |
48c27f86 | 120 | * IMPORTANT: |
72a3fe42 VM |
121 | * It *is* necessary to call this method when you stop using |
122 | * an object. Failure to do so will cause a memory leak. | |
48c27f86 VM |
123 | * |
124 | * @param object the object to close | |
d12299fe | 125 | */ |
45e79e37 | 126 | GIT_EXTERN(void) git_object_free(git_object *object); |
d12299fe VM |
127 | |
128 | /** | |
129 | * Convert an object type to it's string representation. | |
130 | * | |
131 | * The result is a pointer to a string in static memory and | |
132 | * should not be free()'ed. | |
133 | * | |
134 | * @param type object type to convert. | |
135 | * @return the corresponding string representation. | |
136 | */ | |
137 | GIT_EXTERN(const char *) git_object_type2string(git_otype type); | |
138 | ||
139 | /** | |
140 | * Convert a string object type representation to it's git_otype. | |
141 | * | |
142 | * @param str the string to convert. | |
143 | * @return the corresponding git_otype. | |
144 | */ | |
145 | GIT_EXTERN(git_otype) git_object_string2type(const char *str); | |
146 | ||
147 | /** | |
148 | * Determine if the given git_otype is a valid loose object type. | |
149 | * | |
150 | * @param type object type to test. | |
151 | * @return true if the type represents a valid loose object type, | |
152 | * false otherwise. | |
153 | */ | |
154 | GIT_EXTERN(int) git_object_typeisloose(git_otype type); | |
155 | ||
e52ed7a5 VM |
156 | /** |
157 | * Get the size in bytes for the structure which | |
158 | * acts as an in-memory representation of any given | |
159 | * object type. | |
160 | * | |
161 | * For all the core types, this would the equivalent | |
162 | * of calling `sizeof(git_commit)` if the core types | |
163 | * were not opaque on the external API. | |
164 | * | |
165 | * @param type object type to get its size | |
166 | * @return size in bytes of the object | |
167 | */ | |
168 | GIT_EXTERN(size_t) git_object__size(git_otype type); | |
169 | ||
db9be945 | 170 | /** |
171 | * Recursively peel an object until an object of the specified | |
172 | * type is met | |
173 | * | |
174 | * The retrieved `peeled` object is owned by the repository | |
175 | * and should be closed with the `git_object_free` method. | |
176 | * | |
177 | * @param peeled Pointer to the peeled git_object | |
178 | * @param object The object to be processed | |
179 | * @param target_type The type of the requested object | |
180 | * @return 0 or an error code | |
181 | */ | |
182 | GIT_EXTERN(int) git_object_peel( | |
183 | git_object **peeled, | |
184 | git_object *object, | |
185 | git_otype target_type); | |
186 | ||
d12299fe VM |
187 | /** @} */ |
188 | GIT_END_DECL | |
189 | ||
190 | #endif |