include/git2/sys/refdb_backend.h

   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_refdb_backend_h__
   8 #define INCLUDE_sys_git_refdb_backend_h__
   9
  10 #include "git2/common.h"
  11 #include "git2/types.h"
  12 #include "git2/oid.h"
  13
  14 /**
  15  * @file git2/refdb_backend.h
  16  * @brief Git custom refs backend functions
  17  * @defgroup git_refdb_backend Git custom refs backend API
  18  * @ingroup Git
  19  * @{
  20  */
  21 GIT_BEGIN_DECL
  22
  23 /** An instance for a custom backend */
  24 struct git_refdb_backend {
  25     unsigned int version;
  26
  27         /**
  28          * Queries the refdb backend to determine if the given ref_name
  29          * exists.  A refdb implementation must provide this function.
  30          */
  31         int (*exists)(
  32                 int *exists,
  33                 git_refdb_backend *backend,
  34                 const char *ref_name);
  35
  36         /**
  37          * Queries the refdb backend for a given reference.  A refdb
  38          * implementation must provide this function.
  39          */
  40         int (*lookup)(
  41                 git_reference **out,
  42                 git_refdb_backend *backend,
  43                 const char *ref_name);
  44
  45         /**
  46          * Enumerates each reference in the refdb.  A refdb implementation must
  47          * provide this function.
  48          */
  49         int (*foreach)(
  50                 git_refdb_backend *backend,
  51                 unsigned int list_flags,
  52                 git_reference_foreach_cb callback,
  53                 void *payload);
  54
  55         /**
  56          * Enumerates each reference in the refdb that matches the given
  57          * glob string.  A refdb implementation may provide this function;
  58          * if it is not provided, foreach will be used and the results filtered
  59          * against the glob.
  60          */
  61         int (*foreach_glob)(
  62                 git_refdb_backend *backend,
  63                 const char *glob,
  64                 unsigned int list_flags,
  65                 git_reference_foreach_cb callback,
  66                 void *payload);
  67
  68         /**
  69          * Writes the given reference to the refdb.  A refdb implementation
  70          * must provide this function.
  71          */
  72         int (*write)(git_refdb_backend *backend, const git_reference *ref);
  73
  74         /**
  75          * Deletes the given reference from the refdb.  A refdb implementation
  76          * must provide this function.
  77          */
  78         int (*delete)(git_refdb_backend *backend, const git_reference *ref);
  79
  80         /**
  81          * Suggests that the given refdb compress or optimize its references.
  82          * This mechanism is implementation specific.  (For on-disk reference
  83          * databases, this may pack all loose references.)    A refdb
  84          * implementation may provide this function; if it is not provided,
  85          * nothing will be done.
  86          */
  87         int (*compress)(git_refdb_backend *backend);
  88
  89         /**
  90          * Frees any resources held by the refdb.  A refdb implementation may
  91          * provide this function; if it is not provided, nothing will be done.
  92          */
  93         void (*free)(git_refdb_backend *backend);
  94 };
  95
  96 #define GIT_ODB_BACKEND_VERSION 1
  97 #define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION}
  98
  99 /**
 100  * Constructors for default filesystem-based refdb backend
 101  *
 102  * Under normal usage, this is called for you when the repository is
 103  * opened / created, but you can use this to explicitly construct a
 104  * filesystem refdb backend for a repository.
 105  *
 106  * @param backend_out Output pointer to the git_refdb_backend object
 107  * @param repo Git repository to access
 108  * @return 0 on success, <0 error code on failure
 109  */
 110 GIT_EXTERN(int) git_refdb_backend_fs(
 111         git_refdb_backend **backend_out,
 112         git_repository *repo);
 113
 114 /**
 115  * Sets the custom backend to an existing reference DB
 116  *
 117  * The `git_refdb` will take ownership of the `git_refdb_backend` so you
 118  * should NOT free it after calling this function.
 119  *
 120  * @param refdb database to add the backend to
 121  * @param backend pointer to a git_refdb_backend instance
 122  * @return 0 on success; error code otherwise
 123  */
 124 GIT_EXTERN(int) git_refdb_set_backend(
 125         git_refdb *refdb,
 126         git_refdb_backend *backend);
 127
 128 GIT_END_DECL
 129
 130 #endif