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 assign `iter->parent.backend` to your `git_refdb_backend`.
  34  */
  35 struct git_reference_iterator {
  36         git_refdb *db;
  37
  38         /**
  39          * Return the current reference and advance the iterator.
  40          */
  41         int (*next)(
  42                 git_reference **ref,
  43                 git_reference_iterator *iter);
  44
  45         /**
  46          * Return the name of the current reference and advance the iterator
  47          */
  48         int (*next_name)(
  49                 const char **ref_name,
  50                 git_reference_iterator *iter);
  51
  52         /**
  53          * Free the iterator
  54          */
  55         void (*free)(
  56                 git_reference_iterator *iter);
  57 };
  58
  59 /** An instance for a custom backend */
  60 struct git_refdb_backend {
  61         unsigned int version;
  62
  63         /**
  64          * Queries the refdb backend to determine if the given ref_name
  65          * exists.  A refdb implementation must provide this function.
  66          */
  67         int (*exists)(
  68                 int *exists,
  69                 git_refdb_backend *backend,
  70                 const char *ref_name);
  71
  72         /**
  73          * Queries the refdb backend for a given reference.  A refdb
  74          * implementation must provide this function.
  75          */
  76         int (*lookup)(
  77                 git_reference **out,
  78                 git_refdb_backend *backend,
  79                 const char *ref_name);
  80
  81         /**
  82          * Allocate an iterator object for the backend.
  83          *
  84          * A refdb implementation must provide this function.
  85          */
  86         int (*iterator)(
  87                 git_reference_iterator **iter,
  88                 struct git_refdb_backend *backend,
  89                 const char *glob);
  90
  91         /*
  92          * Writes the given reference to the refdb.  A refdb implementation
  93          * must provide this function.
  94          */
  95         int (*write)(git_refdb_backend *backend,
  96                      const git_reference *ref, int force,
  97                      const git_signature *who, const char *message,
  98                      const git_oid *old, const char *old_target);
  99
 100         int (*rename)(
 101                 git_reference **out, git_refdb_backend *backend,
 102                 const char *old_name, const char *new_name, int force,
 103                 const git_signature *who, const char *message);
 104
 105         /**
 106          * Deletes the given reference (and if necessary its reflog)
 107          * from the refdb.  A refdb implementation must provide this
 108          * function.
 109          */
 110         int (*del)(git_refdb_backend *backend, const char *ref_name, const git_oid *old_id, const char *old_target);
 111
 112         /**
 113          * Suggests that the given refdb compress or optimize its references.
 114          * This mechanism is implementation specific.  (For on-disk reference
 115          * databases, this may pack all loose references.)    A refdb
 116          * implementation may provide this function; if it is not provided,
 117          * nothing will be done.
 118          */
 119         int (*compress)(git_refdb_backend *backend);
 120
 121         /**
 122          * Query whether a particular reference has a log (may be empty)
 123          */
 124         int (*has_log)(git_refdb_backend *backend, const char *refname);
 125
 126         /**
 127          * Make sure a particular reference will have a reflog which
 128          * will be appended to on writes.
 129          */
 130         int (*ensure_log)(git_refdb_backend *backend, const char *refname);
 131
 132         /**
 133          * Frees any resources held by the refdb.  A refdb implementation may
 134          * provide this function; if it is not provided, nothing will be done.
 135          */
 136         void (*free)(git_refdb_backend *backend);
 137
 138         /**
 139          * Read the reflog for the given reference name.
 140          */
 141         int (*reflog_read)(git_reflog **out, git_refdb_backend *backend, const char *name);
 142
 143         /**
 144          * Write a reflog to disk.
 145          */
 146         int (*reflog_write)(git_refdb_backend *backend, git_reflog *reflog);
 147
 148         /**
 149          * Rename a reflog
 150          */
 151         int (*reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name);
 152
 153         /**
 154          * Remove a reflog.
 155          */
 156         int (*reflog_delete)(git_refdb_backend *backend, const char *name);
 157
 158         /**
 159          * Lock a reference. The opaque parameter will be passed to the unlock function
 160          */
 161         int (*lock)(void **payload_out, git_refdb_backend *backend, const char *refname);
 162
 163         /**
 164          * Unlock a reference. Only one of target or symbolic_target
 165          * will be set. success indicates whether to update the
 166          * reference or discard the lock (if it's false)
 167          */
 168         int (*unlock)(git_refdb_backend *backend, void *payload, int success, int update_reflog,
 169                       const git_reference *ref, const git_signature *sig, const char *message);
 170 };
 171
 172 #define GIT_REFDB_BACKEND_VERSION 1
 173 #define GIT_REFDB_BACKEND_INIT {GIT_REFDB_BACKEND_VERSION}
 174
 175 /**
 176  * Initializes a `git_refdb_backend` with default values. Equivalent to
 177  * creating an instance with GIT_REFDB_BACKEND_INIT.
 178  *
 179  * @param backend the `git_refdb_backend` struct to initialize
 180  * @param version Version of struct; pass `GIT_REFDB_BACKEND_VERSION`
 181  * @return Zero on success; -1 on failure.
 182  */
 183 GIT_EXTERN(int) git_refdb_init_backend(
 184         git_refdb_backend *backend,
 185         unsigned int version);
 186
 187 /**
 188  * Constructors for default filesystem-based refdb backend
 189  *
 190  * Under normal usage, this is called for you when the repository is
 191  * opened / created, but you can use this to explicitly construct a
 192  * filesystem refdb backend for a repository.
 193  *
 194  * @param backend_out Output pointer to the git_refdb_backend object
 195  * @param repo Git repository to access
 196  * @return 0 on success, <0 error code on failure
 197  */
 198 GIT_EXTERN(int) git_refdb_backend_fs(
 199         git_refdb_backend **backend_out,
 200         git_repository *repo);
 201
 202 /**
 203  * Sets the custom backend to an existing reference DB
 204  *
 205  * The `git_refdb` will take ownership of the `git_refdb_backend` so you
 206  * should NOT free it after calling this function.
 207  *
 208  * @param refdb database to add the backend to
 209  * @param backend pointer to a git_refdb_backend instance
 210  * @return 0 on success; error code otherwise
 211  */
 212 GIT_EXTERN(int) git_refdb_set_backend(
 213         git_refdb *refdb,
 214         git_refdb_backend *backend);
 215
 216 GIT_END_DECL
 217
 218 #endif