src/git/odb.h

   1 #ifndef INCLUDE_git_odb_h__
   2 #define INCLUDE_git_odb_h__
   3
   4 #include "common.h"
   5 #include "oid.h"
   6 #include <stdlib.h>
   7
   8 /**
   9  * @file git/odb.h
  10  * @brief Git object database routines
  11  * @defgroup git_odb Git object database routines
  12  * @ingroup Git
  13  * @{
  14  */
  15 GIT_BEGIN_DECL
  16
  17 /** An open object database handle. */
  18 typedef struct git_odb git_odb;
  19
  20 /**
  21  * Open an object database for read/write access.
  22  * @param out location to store the database pointer, if opened.
  23  *            Set to NULL if the open failed.
  24  * @param objects_dir path of the database's "objects" directory.
  25  * @return GIT_SUCCESS if the database opened; otherwise an error
  26  *         code describing why the open was not possible.
  27  */
  28 GIT_EXTERN(int) git_odb_open(git_odb **out, const char *objects_dir);
  29
  30 /**
  31  * Close an open object database.
  32  * @param db database pointer to close.  If NULL no action is taken.
  33  */
  34 GIT_EXTERN(void) git_odb_close(git_odb *db);
  35
  36 /** Basic type (loose or packed) of any Git object. */
  37 typedef enum {
  38         GIT_OBJ_BAD = -1,       /**< Object is invalid. */
  39         GIT_OBJ__EXT1 = 0,      /**< Reserved for future use. */
  40         GIT_OBJ_COMMIT = 1,     /**< A commit object. */
  41         GIT_OBJ_TREE = 2,       /**< A tree (directory listing) object. */
  42         GIT_OBJ_BLOB = 3,       /**< A file revision object. */
  43         GIT_OBJ_TAG = 4,        /**< An annotated tag object. */
  44         GIT_OBJ__EXT2 = 5,      /**< Reserved for future use. */
  45         GIT_OBJ_OFS_DELTA = 6,  /**< A delta, base is given by an offset. */
  46         GIT_OBJ_REF_DELTA = 7,  /**< A delta, base is given by object id. */
  47 } git_otype;
  48
  49 /** An object read from the database. */
  50 typedef struct {
  51         void *data;          /**< Raw, decompressed object data. */
  52         size_t len;          /**< Total number of bytes in data. */
  53         git_otype type;      /**< Type of this object. */
  54 } git_obj;
  55
  56 /**
  57  * Read an object from the database.
  58  *
  59  * If GIT_ENOTFOUND then out->data is set to NULL.
  60  *
  61  * @param out object descriptor to populate upon reading.
  62  * @param db database to search for the object in.
  63  * @param id identity of the object to read.
  64  * @return
  65  * - GIT_SUCCESS if the object was read;
  66  * - GIT_ENOTFOUND if the object is not in the database.
  67  */
  68 GIT_EXTERN(int) git_odb_read(git_obj *out, git_odb *db, const git_oid *id);
  69
  70 /**
  71  * Read an object from the database using only pack files.
  72  *
  73  * If GIT_ENOTFOUND then out->data is set to NULL.
  74  *
  75  * @param out object descriptor to populate upon reading.
  76  * @param db database to search for the object in.
  77  * @param id identity of the object to read.
  78  * @return
  79  * - GIT_SUCCESS if the object was read.
  80  * - GIT_ENOTFOUND if the object is not in the database.
  81  */
  82 GIT_EXTERN(int) git_odb__read_packed(git_obj *out, git_odb *db, const git_oid *id);
  83
  84 /**
  85  * Read an object from the database using only loose object files.
  86  *
  87  * If GIT_ENOTFOUND then out->data is set to NULL.
  88  *
  89  * @param out object descriptor to populate upon reading.
  90  * @param db database to search for the object in.
  91  * @param id identity of the object to read.
  92  * @return
  93  * - GIT_SUCCESS if the object was read.
  94  * - GIT_ENOTFOUND if the object is not in the database.
  95  */
  96 GIT_EXTERN(int) git_odb__read_loose(git_obj *out, git_odb *db, const git_oid *id);
  97
  98 /**
  99  * Write an object to the database.
 100  *
 101  * @param id identity of the object written.
 102  * @param db database to which the object should be written.
 103  * @param obj object descriptor for the object to write.
 104  * @return
 105  * - GIT_SUCCESS if the object was written;
 106  * - GIT_ERROR otherwise.
 107  */
 108 GIT_EXTERN(int) git_odb_write(git_oid *id, git_odb *db, git_obj *obj);
 109
 110 /**
 111  * Release all memory used by the obj structure.
 112  *
 113  * As a result of this call, obj->data will be set to NULL.
 114  *
 115  * If obj->data is already NULL, nothing happens.
 116  *
 117  * @param obj object descriptor to free.
 118  */
 119 GIT_INLINE(void) git_obj_close(git_obj *obj)
 120 {
 121         free(obj->data);
 122         obj->data = NULL;
 123 }
 124
 125 /**
 126  * Convert an object type to it's string representation.
 127  *
 128  * The result is a pointer to a string in static memory and
 129  * should not be free()'ed.
 130  *
 131  * @param type object type to convert.
 132  * @return the corresponding string representation.
 133  */
 134 GIT_EXTERN(const char *) git_obj_type_to_string(git_otype type);
 135
 136 /**
 137  * Convert a string object type representation to it's git_otype.
 138  *
 139  * @param str the string to convert.
 140  * @return the corresponding git_otype.
 141  */
 142 GIT_EXTERN(git_otype) git_obj_string_to_type(const char *str);
 143
 144 /**
 145  * Determine if the given git_otype is a valid loose object type.
 146  *
 147  * @param type object type to test.
 148  * @return true if the type represents a valid loose object type,
 149  * false otherwise.
 150  */
 151 GIT_EXTERN(int) git_obj__loose_object_type(git_otype type);
 152
 153 /**
 154  * Determine the object-ID (sha1 hash) of the given git_obj.
 155  *
 156  * The input obj must be a valid loose object type and the data
 157  * pointer must not be NULL, unless the len field is also zero.
 158  *
 159  * @param id the resulting object-ID.
 160  * @param obj the object whose hash is to be determined.
 161  * @return
 162  * - GIT_SUCCESS if the object-ID was correctly determined.
 163  * - GIT_ERROR if the given object is malformed.
 164  */
 165 GIT_EXTERN(int) git_obj_hash(git_oid *id, git_obj *obj);
 166
 167 /**
 168  * Determine if the given object can be found in the object database.
 169  *
 170  * @param db database to be searched for the given object.
 171  * @param id the object to search for.
 172  * @return
 173  * - true, if the object was found
 174  * - false, otherwise
 175  */
 176 GIT_EXTERN(int) git_odb_exists(git_odb *db, const git_oid *id);
 177
 178 /** @} */
 179 GIT_END_DECL
 180 #endif