]>
Commit | Line | Data |
---|---|---|
f5918330 VM |
1 | /* |
2 | * This file is free software; you can redistribute it and/or modify | |
3 | * it under the terms of the GNU General Public License, version 2, | |
4 | * as published by the Free Software Foundation. | |
5 | * | |
6 | * In addition to the permissions in the GNU General Public License, | |
7 | * the authors give you unlimited permission to link the compiled | |
8 | * version of this file into combinations with other programs, | |
9 | * and to distribute those combinations without any restriction | |
10 | * coming from the use of this file. (The General Public License | |
11 | * restrictions do apply in other respects; for example, they cover | |
12 | * modification of the file, and distribution when not linked into | |
13 | * a combined executable.) | |
14 | * | |
15 | * This file is distributed in the hope that it will be useful, but | |
16 | * WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
18 | * General Public License for more details. | |
19 | * | |
20 | * You should have received a copy of the GNU General Public License | |
21 | * along with this program; see the file COPYING. If not, write to | |
22 | * the Free Software Foundation, 51 Franklin Street, Fifth Floor, | |
23 | * Boston, MA 02110-1301, USA. | |
24 | */ | |
d12299fe VM |
25 | #ifndef INCLUDE_git_object_h__ |
26 | #define INCLUDE_git_object_h__ | |
27 | ||
28 | #include "common.h" | |
29 | #include "types.h" | |
30 | #include "oid.h" | |
31 | ||
32 | /** | |
f5918330 | 33 | * @file git2/object.h |
d12299fe VM |
34 | * @brief Git revision object management routines |
35 | * @defgroup git_object Git revision object management routines | |
36 | * @ingroup Git | |
37 | * @{ | |
38 | */ | |
39 | GIT_BEGIN_DECL | |
40 | ||
5de079b8 VM |
41 | /** |
42 | * Lookup a reference to one of the objects in a repostory. | |
43 | * | |
44 | * The generated reference is owned by the repository and | |
72a3fe42 VM |
45 | * should be closed with the `git_object_close` method |
46 | * instead of free'd manually. | |
5de079b8 VM |
47 | * |
48 | * The 'type' parameter must match the type of the object | |
49 | * in the odb; the method will fail otherwise. | |
50 | * The special value 'GIT_OBJ_ANY' may be passed to let | |
51 | * the method guess the object's type. | |
52 | * | |
53 | * @param object pointer to the looked-up object | |
54 | * @param repo the repository to look up the object | |
55 | * @param id the unique identifier for the object | |
56 | * @param type the type of the object | |
57 | * @return a reference to the object | |
58 | */ | |
59 | GIT_EXTERN(int) git_object_lookup(git_object **object, git_repository *repo, const git_oid *id, git_otype type); | |
60 | ||
d12299fe VM |
61 | /** |
62 | * Get the id (SHA1) of a repository object | |
63 | * | |
d12299fe VM |
64 | * @param obj the repository object |
65 | * @return the SHA1 id | |
66 | */ | |
17cdf252 | 67 | GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj); |
d12299fe VM |
68 | |
69 | /** | |
70 | * Get the object type of an object | |
71 | * | |
72 | * @param obj the repository object | |
73 | * @return the object's type | |
74 | */ | |
17cdf252 | 75 | GIT_EXTERN(git_otype) git_object_type(const git_object *obj); |
d12299fe VM |
76 | |
77 | /** | |
78 | * Get the repository that owns this object | |
79 | * | |
ef5ffed3 VM |
80 | * Freeing or calling `git_repository_close` on the |
81 | * returned pointer will invalidate the actual object. | |
82 | * | |
83 | * Any other operation may be run on the repository without | |
84 | * affecting the object. | |
85 | * | |
d12299fe VM |
86 | * @param obj the object |
87 | * @return the repository who owns this object | |
88 | */ | |
17cdf252 | 89 | GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj); |
d12299fe VM |
90 | |
91 | /** | |
48c27f86 | 92 | * Close an open object |
d12299fe | 93 | * |
48c27f86 | 94 | * This method instructs the library to close an existing |
6b2a1941 VM |
95 | * object; note that git_objects are owned and cached by the repository |
96 | * so the object may or may not be freed after this library call, | |
97 | * depending on how agressive is the caching mechanism used | |
98 | * by the repository. | |
d12299fe | 99 | * |
48c27f86 | 100 | * IMPORTANT: |
72a3fe42 VM |
101 | * It *is* necessary to call this method when you stop using |
102 | * an object. Failure to do so will cause a memory leak. | |
48c27f86 VM |
103 | * |
104 | * @param object the object to close | |
d12299fe | 105 | */ |
48c27f86 | 106 | GIT_EXTERN(void) git_object_close(git_object *object); |
d12299fe VM |
107 | |
108 | /** | |
109 | * Convert an object type to it's string representation. | |
110 | * | |
111 | * The result is a pointer to a string in static memory and | |
112 | * should not be free()'ed. | |
113 | * | |
114 | * @param type object type to convert. | |
115 | * @return the corresponding string representation. | |
116 | */ | |
117 | GIT_EXTERN(const char *) git_object_type2string(git_otype type); | |
118 | ||
119 | /** | |
120 | * Convert a string object type representation to it's git_otype. | |
121 | * | |
122 | * @param str the string to convert. | |
123 | * @return the corresponding git_otype. | |
124 | */ | |
125 | GIT_EXTERN(git_otype) git_object_string2type(const char *str); | |
126 | ||
127 | /** | |
128 | * Determine if the given git_otype is a valid loose object type. | |
129 | * | |
130 | * @param type object type to test. | |
131 | * @return true if the type represents a valid loose object type, | |
132 | * false otherwise. | |
133 | */ | |
134 | GIT_EXTERN(int) git_object_typeisloose(git_otype type); | |
135 | ||
e52ed7a5 VM |
136 | /** |
137 | * Get the size in bytes for the structure which | |
138 | * acts as an in-memory representation of any given | |
139 | * object type. | |
140 | * | |
141 | * For all the core types, this would the equivalent | |
142 | * of calling `sizeof(git_commit)` if the core types | |
143 | * were not opaque on the external API. | |
144 | * | |
145 | * @param type object type to get its size | |
146 | * @return size in bytes of the object | |
147 | */ | |
148 | GIT_EXTERN(size_t) git_object__size(git_otype type); | |
149 | ||
d12299fe VM |
150 | /** @} */ |
151 | GIT_END_DECL | |
152 | ||
153 | #endif |