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_config_backend_h__
8 #define INCLUDE_sys_git_config_backend_h__
9 
10 #include "git2/common.h"
11 #include "git2/types.h"
12 #include "git2/config.h"
13 
14 /**
15  * @file git2/sys/config.h
16  * @brief Git config backend routines
17  * @defgroup git_backend Git custom backend APIs
18  * @ingroup Git
19  * @{
20  */
21 GIT_BEGIN_DECL
22 
23 /**
24  * Every iterator must have this struct as its first element, so the
25  * API can talk to it. You'd define your iterator as
26  *
27  *     struct my_iterator {
28  *             git_config_iterator parent;
29  *             ...
30  *     }
31  *
32  * and assign `iter->parent.backend` to your `git_config_backend`.
33  */
34 struct git_config_iterator {
35 	git_config_backend *backend;
36 	unsigned int flags;
37 
38 	/**
39 	 * Return the current entry and advance the iterator. The
40 	 * memory belongs to the library.
41 	 */
42 	int GIT_CALLBACK(next)(git_config_entry **entry, git_config_iterator *iter);
43 
44 	/**
45 	 * Free the iterator
46 	 */
47 	void GIT_CALLBACK(free)(git_config_iterator *iter);
48 };
49 
50 /**
51  * Generic backend that implements the interface to
52  * access a configuration file
53  */
54 struct git_config_backend {
55 	unsigned int version;
56 	/** True if this backend is for a snapshot */
57 	int readonly;
58 	struct git_config *cfg;
59 
60 	/* Open means open the file/database and parse if necessary */
61 	int GIT_CALLBACK(open)(struct git_config_backend *, git_config_level_t level, const git_repository *repo);
62 	int GIT_CALLBACK(get)(struct git_config_backend *, const char *key, git_config_entry **entry);
63 	int GIT_CALLBACK(set)(struct git_config_backend *, const char *key, const char *value);
64 	int GIT_CALLBACK(set_multivar)(git_config_backend *cfg, const char *name, const char *regexp, const char *value);
65 	int GIT_CALLBACK(del)(struct git_config_backend *, const char *key);
66 	int GIT_CALLBACK(del_multivar)(struct git_config_backend *, const char *key, const char *regexp);
67 	int GIT_CALLBACK(iterator)(git_config_iterator **, struct git_config_backend *);
68 	/** Produce a read-only version of this backend */
69 	int GIT_CALLBACK(snapshot)(struct git_config_backend **, struct git_config_backend *);
70 	/**
71 	 * Lock this backend.
72 	 *
73 	 * Prevent any writes to the data store backing this
74 	 * backend. Any updates must not be visible to any other
75 	 * readers.
76 	 */
77 	int GIT_CALLBACK(lock)(struct git_config_backend *);
78 	/**
79 	 * Unlock the data store backing this backend. If success is
80 	 * true, the changes should be committed, otherwise rolled
81 	 * back.
82 	 */
83 	int GIT_CALLBACK(unlock)(struct git_config_backend *, int success);
84 	void GIT_CALLBACK(free)(struct git_config_backend *);
85 };
86 #define GIT_CONFIG_BACKEND_VERSION 1
87 #define GIT_CONFIG_BACKEND_INIT {GIT_CONFIG_BACKEND_VERSION}
88 
89 /**
90  * Initializes a `git_config_backend` with default values. Equivalent to
91  * creating an instance with GIT_CONFIG_BACKEND_INIT.
92  *
93  * @param backend the `git_config_backend` struct to initialize.
94  * @param version Version of struct; pass `GIT_CONFIG_BACKEND_VERSION`
95  * @return Zero on success; -1 on failure.
96  */
97 GIT_EXTERN(int) git_config_init_backend(
98 	git_config_backend *backend,
99 	unsigned int version);
100 
101 /**
102  * Add a generic config file instance to an existing config
103  *
104  * Note that the configuration object will free the file
105  * automatically.
106  *
107  * Further queries on this config object will access each
108  * of the config file instances in order (instances with
109  * a higher priority level will be accessed first).
110  *
111  * @param cfg the configuration to add the file to
112  * @param file the configuration file (backend) to add
113  * @param level the priority level of the backend
114  * @param repo optional repository to allow parsing of
115  *  conditional includes
116  * @param force if a config file already exists for the given
117  *  priority level, replace it
118  * @return 0 on success, GIT_EEXISTS when adding more than one file
119  *  for a given priority level (and force_replace set to 0), or error code
120  */
121 GIT_EXTERN(int) git_config_add_backend(
122 	git_config *cfg,
123 	git_config_backend *file,
124 	git_config_level_t level,
125 	const git_repository *repo,
126 	int force);
127 
128 /** @} */
129 GIT_END_DECL
130 #endif
131