« back to all changes in this revision
Viewing changes to include/u1db/u1db.h
- browse files at revision 160.1.2
- compare with another revision
- download diff
- download tarball
- view history from revision 160.1.2
- Committer: John Arbash Meinel
- Date: 2012-01-10 16:05:33 UTC
- mfrom: (66.2.29 sqlite-c-backend) (160.2.1 c-layout)
- mto: This revision was merged to the branch mainline in revision 162.
- Revision ID: john@arbash-meinel.com-20120110160533-gm2rmh30fj9olreo
Merge the actual content from sqlite-c-backend, but get rid of all the conflicting stuff.
- files added:
- include
- include/u1db
- src
added
removed
include/u1db/u1db.h
1
/*
2
* Copyright 2011 Canonical Ltd.
3
*
4
* This program is free software: you can redistribute it and/or modify it
5
* under the terms of the GNU General Public License version 3, as published
6
* by the Free Software Foundation.
7
*
8
* This program is distributed in the hope that it will be useful, but
9
* WITHOUT ANY WARRANTY; without even the implied warranties of
10
* MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
11
* PURPOSE. See the GNU General Public License for more details.
12
*
13
* You should have received a copy of the GNU General Public License along
14
* with this program. If not, see <http://www.gnu.org/licenses/>.
15
*/
16
17
#ifndef _U1DB_H_
18
#define _U1DB_H_
19
20
typedef struct _u1database u1database;
21
22
#define U1DB_OK 0
23
#define U1DB_INVALID_PARAMETER -1
24
// put_doc() was called but the doc_rev stored in the database doesn't match
25
// the one supplied.
26
#define U1DB_INVALID_DOC_REV -2
27
#define U1DB_INVALID_DOC_ID -3
28
29
/**
30
* The basic constructor for a new connection.
31
*/
32
u1database *u1db_open(const char *fname);
33
34
/**
35
* Close an existing connection, freeing memory, etc.
36
* This is generally used as u1db_free(&db);
37
* After freeing the memory, we will set the pointer to NULL.
38
*/
39
void u1db_free(u1database **db);
40
41
/**
42
* Set the machine_id defined for this database.
43
*/
44
int u1db_set_machine_id(u1database *db, const char *machine_id);
45
46
/**
47
* Get the machine_id defined for this database.
48
*/
49
int u1db_get_machine_id(u1database *db, char **machine_id);
50
51
/**
52
* Create a new document.
53
*
54
* @param doc: The JSON string representing the document.
55
* @param n: The number of bytes in doc
56
* @param doc_id: A string identifying the document. If the value supplied is
57
* NULL, then a new doc_id will be generated. Callers are responsible for
58
* then freeing the returned string.
59
* @param doc_rev: The document revision. Callers are responsible for freeing
60
* the information.
61
*/
62
int u1db_create_doc(u1database *db, const char *doc, int n, char **doc_id,
63
char **doc_rev);
64
65
/**
66
* Put new document content for the given document identifier.
67
*
68
* @param doc_id: A string identifying the document. If the value supplied is
69
* NULL, then a new doc_id will be generated. Callers are responsible for
70
* then freeing the returned string.
71
* @param doc_rev: The document revision. This should contain the revision that
72
* is being replaced, and it will be filled in with the new document revision.
73
* The new revision will be malloced(), callers are responsible for
74
* calling free.
75
* @param doc: The JSON string representing the document.
76
* @param n: The number of bytes in doc
77
*/
78
int u1db_put_doc(u1database *db, const char *doc_id, char **doc_rev,
79
const char *doc, int n);
80
81
/**
82
* Get the document defined by the given document id.
83
*
84
* @param doc_id (IN) The document we are looking for
85
* @param doc_rev (OUT) The final document revision. Callers must free the memory
86
* @param doc (OUT) Callers are responsible for freeing the memory
87
* @param n (OUT) Number of bytes for doc
88
* @param has_conflicts (OUT) Are there conflicts present for this document?
89
*/
90
int u1db_get_doc(u1database *db, const char *doc_id, char **doc_rev,
91
char **doc, int *n, int *has_conflicts);
92
93
/**
94
* Mark a document as deleted.
95
*
96
* @param doc_id (IN) The document we want to delete.
97
* @param doc_rev (IN/OUT) The rev of the document we are deleting, must match
98
* the stored value, or the delete will fail. Will be updated
99
* to point at the new document revision (for the delete),
100
* callers must free the memory.
101
*/
102
int u1db_delete_doc(u1database *db, const char *doc_id, char **doc_rev);
103
104
/**
105
* Get the document defined by the given document id.
106
*
107
* @param db_rev The global database revision to start at. You can pass '0' to
108
* get all changes in the database. The integer will be updated
109
* to point at the current db_rev.
110
* @param cb A callback function. This will be called passing in 'context',
111
* and a document identifier for each document that has been modified.
112
* The doc_id string is transient, so callers must copy it to
113
* their own memory if they want to keep it.
114
* If a document is changed more than once, it is currently
115
* undefined whether this will call cb() once per change, or just
116
* once per doc_id.
117
* @param context Opaque context, passed back to the caller.
118
*/
119
int u1db_whats_changed(u1database *db, int *db_rev,
120
int (*cb)(void *, char *doc_id), void *context);
121
122
123
/**
124
* Internal API, Get the global database rev.
125
*/
126
int u1db__get_db_rev(u1database *db, int *db_rev);
127
128
/**
129
* Internal API, Allocate a new document id, for cases when callers do not
130
* supply their own. Callers of this API are expected to free the result.
131
*/
132
char *u1db__allocate_doc_id(u1database *db);
133
134
/**
135
* Internal api, close the underlying sql instance.
136
*/
137
int u1db__sql_close(u1database *db);
138
139
/**
140
* Internal api, check to see if the underlying SQLite handle has been closed.
141
*/
142
int u1db__sql_is_open(u1database *db);
143
144
/**
145
* Internal api, run an SQL query directly.
146
*/
147
typedef struct _u1db_row {
148
struct _u1db_row *next;
149
int num_columns;
150
int *column_sizes;
151
unsigned char **columns;
152
} u1db_row;
153
154
typedef struct _u1db_table {
155
int status;
156
u1db_row *first_row;
157
} u1db_table;
158
159
u1db_table *u1db__sql_run(u1database *db, const char *sql, size_t n);
160
void u1db__free_table(u1db_table **table);
161
162
163
/**
164
* Internal sync api, get the stored information about another machine.
165
*/
166
int u1db__sync_get_machine_info(u1database *db, const char *other_machine_id,
167
int *other_db_rev, char **my_machine_id,
168
int *my_db_rev);
169
170
/**
171
* Internal sync api, store information about another machine.
172
*/
173
int u1db__sync_record_machine_info(u1database *db, const char *machine_id,
174
int db_rev);
175
176
typedef struct _u1db_record {
177
struct _u1db_record *next;
178
char *doc_id;
179
char *doc_rev;
180
char *doc;
181
} u1db_record;
182
183
/**
184
* Internal sync api, exchange sync records.
185
*/
186
int u1db__sync_exchange(u1database *db, const char *from_machine_id,
187
int from_db_rev, int last_known_rev,
188
u1db_record *from_records, u1db_record **new_records,
189
u1db_record **conflict_records);
190
191
/**
192
* Allocate a new u1db_record, and copy all records over.
193
*/
194
u1db_record *u1db__create_record(const char *doc_id, const char *doc_rev,
195
const char *doc);
196
197
u1db_record *u1db__copy_record(u1db_record *src);
198
199
/**
200
* Free a linked list of records. All linked records will be freed, including
201
* all memory referenced from them.
202
*/
203
void u1db__free_records(u1db_record **record);
204
205
typedef struct _u1db_vectorclock_item {
206
char *machine_id;
207
int db_rev;
208
} u1db_vectorclock_item;
209
210
typedef struct _u1db_vectorclock {
211
int num_items;
212
u1db_vectorclock_item *items;
213
} u1db_vectorclock;
214
215
u1db_vectorclock *u1db__vectorclock_from_str(const char *s);
216
217
void u1db__free_vectorclock(u1db_vectorclock **clock);
218
int u1db__vectorclock_increment(u1db_vectorclock *clock,
219
const char *machine_id);
220
221
int u1db__vectorclock_maximize(u1db_vectorclock *clock,
222
u1db_vectorclock *other);
223
/**
224
* Return a null-terminated string representation for this vector clock.
225
* Callers must take care to free() the result.
226
*/
227
int u1db__vectorclock_as_str(u1db_vectorclock *clock, char **result);
228
int u1db__vectorclock_is_newer(u1db_vectorclock *maybe_newer,
229
u1db_vectorclock *older);
230
#endif // _U1DB_H_
Loggerhead is a web-based interface for Breezy
Version: 2.0.1