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
  24 /**
  25  * Every backend's iterator must have a pointer to itself as the first
  26  * element, so the API can talk to it. You'd define your iterator as
  27  *
  28  *     struct my_iterator {
  29  *             git_reference_iterator parent;
  30  *             ...
  31  *     }
  32  *
  33  * and assing `iter->parent.backend` to your `git_refdb_backend`.
  34  */
  35 struct git_reference_iterator {
  36         git_refdb_backend *backend;
  37 };
  38
  39 /** An instance for a custom backend */
  40 struct git_refdb_backend {
  41     unsigned int version;
  42
  43         /**
  44          * Queries the refdb backend to determine if the given ref_name
  45          * exists.  A refdb implementation must provide this function.
  46          */
  47         int (*exists)(
  48                 int *exists,
  49                 git_refdb_backend *backend,
  50                 const char *ref_name);
  51
  52         /**
  53          * Queries the refdb backend for a given reference.  A refdb
  54          * implementation must provide this function.
  55          */
  56         int (*lookup)(
  57                 git_reference **out,
  58                 git_refdb_backend *backend,
  59                 const char *ref_name);
  60
  61         /**
  62          * Enumerates each reference in the refdb.  A refdb implementation must
  63          * provide this function.
  64          */
  65         int (*foreach)(
  66                 git_refdb_backend *backend,
  67                 unsigned int list_flags,
  68                 git_reference_foreach_cb callback,
  69                 void *payload);
  70
  71         /**
  72          * Enumerates each reference in the refdb that matches the given
  73          * glob string.  A refdb implementation may provide this function;
  74          * if it is not provided, foreach will be used and the results filtered
  75          * against the glob.
  76          */
  77         int (*foreach_glob)(
  78                 git_refdb_backend *backend,
  79                 const char *glob,
  80                 unsigned int list_flags,
  81                 git_reference_foreach_cb callback,
  82                 void *payload);
  83
  84         /**
  85          * Allocate an iterator object for the backend
  86          */
  87         int (*iterator)(
  88                 git_reference_iterator **iter,
  89                 struct git_refdb_backend *backend);
  90
  91         /**
  92          * Return the current value and advance the iterator.
  93          */
  94         int (*next)(
  95                 const char **name,
  96                 git_reference_iterator *iter);
  97
  98         /**
  99          * Free the iterator
 100          */
 101         void (*iterator_free)(
 102                 git_reference_iterator *iter);
 103         /*
 104          * Writes the given reference to the refdb.  A refdb implementation
 105          * must provide this function.
 106          */
 107         int (*write)(git_refdb_backend *backend, const git_reference *ref);
 108
 109         /**
 110          * Deletes the given reference from the refdb.  A refdb implementation
 111          * must provide this function.
 112          */
 113         int (*delete)(git_refdb_backend *backend, const git_reference *ref);
 114
 115         /**
 116          * Suggests that the given refdb compress or optimize its references.
 117          * This mechanism is implementation specific.  (For on-disk reference
 118          * databases, this may pack all loose references.)    A refdb
 119          * implementation may provide this function; if it is not provided,
 120          * nothing will be done.
 121          */
 122         int (*compress)(git_refdb_backend *backend);
 123
 124         /**
 125          * Frees any resources held by the refdb.  A refdb implementation may
 126          * provide this function; if it is not provided, nothing will be done.
 127          */
 128         void (*free)(git_refdb_backend *backend);
 129 };
 130
 131 #define GIT_ODB_BACKEND_VERSION 1
 132 #define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION}
 133
 134 /**
 135  * Constructors for default filesystem-based refdb backend
 136  *
 137  * Under normal usage, this is called for you when the repository is
 138  * opened / created, but you can use this to explicitly construct a
 139  * filesystem refdb backend for a repository.
 140  *
 141  * @param backend_out Output pointer to the git_refdb_backend object
 142  * @param repo Git repository to access
 143  * @return 0 on success, <0 error code on failure
 144  */
 145 GIT_EXTERN(int) git_refdb_backend_fs(
 146         git_refdb_backend **backend_out,
 147         git_repository *repo);
 148
 149 /**
 150  * Sets the custom backend to an existing reference DB
 151  *
 152  * The `git_refdb` will take ownership of the `git_refdb_backend` so you
 153  * should NOT free it after calling this function.
 154  *
 155  * @param refdb database to add the backend to
 156  * @param backend pointer to a git_refdb_backend instance
 157  * @return 0 on success; error code otherwise
 158  */
 159 GIT_EXTERN(int) git_refdb_set_backend(
 160         git_refdb *refdb,
 161         git_refdb_backend *backend);
 162
 163 GIT_END_DECL
 164
 165 #endif