include/git2/object.h

   1 /*
   2  * Copyright (C) 2009-2012 the libgit2 contributors
   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_git_object_h__
   8 #define INCLUDE_git_object_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "oid.h"
  13
  14 /**
  15  * @file git2/object.h
  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
  23 /**
  24  * Lookup a reference to one of the objects in a repository.
  25  *
  26  * The generated reference is owned by the repository and
  27  * should be closed with the `git_object_free` method
  28  * instead of free'd manually.
  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  */
  41 GIT_EXTERN(int) git_object_lookup(
  42                 git_object **object,
  43                 git_repository *repo,
  44                 const git_oid *id,
  45                 git_otype type);
  46
  47 /**
  48  * Lookup a reference to one of the objects in a repository,
  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'.
  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.
  57  *
  58  * The generated reference is owned by the repository and
  59  * should be closed with the `git_object_free` method
  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  *
  67  * @param object_out pointer where to store the looked-up object
  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
  72  * @return 0 or an error code
  73  */
  74 GIT_EXTERN(int) git_object_lookup_prefix(
  75                 git_object **object_out,
  76                 git_repository *repo,
  77                 const git_oid *id,
  78                 size_t len,
  79                 git_otype type);
  80
  81 /**
  82  * Get the id (SHA1) of a repository object
  83  *
  84  * @param obj the repository object
  85  * @return the SHA1 id
  86  */
  87 GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj);
  88
  89 /**
  90  * Get the object type of an object
  91  *
  92  * @param obj the repository object
  93  * @return the object's type
  94  */
  95 GIT_EXTERN(git_otype) git_object_type(const git_object *obj);
  96
  97 /**
  98  * Get the repository that owns this object
  99  *
 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  *
 106  * @param obj the object
 107  * @return the repository who owns this object
 108  */
 109 GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj);
 110
 111 /**
 112  * Close an open object
 113  *
 114  * This method instructs the library to close an existing
 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,
 117  * depending on how aggressive is the caching mechanism used
 118  * by the repository.
 119  *
 120  * IMPORTANT:
 121  * It *is* necessary to call this method when you stop using
 122  * an object. Failure to do so will cause a memory leak.
 123  *
 124  * @param object the object to close
 125  */
 126 GIT_EXTERN(void) git_object_free(git_object *object);
 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
 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
 170 /**
 171  * Recursively peel an object until an object of the specified type is met.
 172  *
 173  * The retrieved `peeled` object is owned by the repository and should be
 174  * closed with the `git_object_free` method.
 175  *
 176  * If you pass `GIT_OBJ_ANY` as the target type, then the object will be
 177  * peeled until the type changes (e.g. a tag will be chased until the
 178  * referenced object is no longer a tag).
 179  *
 180  * @param peeled Pointer to the peeled git_object
 181  * @param object The object to be processed
 182  * @param target_type The type of the requested object
 183  * @return 0 or an error code
 184  */
 185 GIT_EXTERN(int) git_object_peel(
 186                 git_object **peeled,
 187                 git_object *object,
 188                 git_otype target_type);
 189
 190 /** @} */
 191 GIT_END_DECL
 192
 193 #endif