main/bucket: Add a callback function for ast_bucket_file objects
[asterisk/asterisk.git] / include / asterisk / bucket.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Bucket File API
21  * \author Joshua Colp <jcolp@digium.com>
22  * \ref AstBucket
23  */
24
25 /*!
26  * \page AstBucket Bucket File API
27  *
28  * Bucket is an API which provides directory and file access in a generic fashion. It is
29  * implemented as a thin wrapper over the sorcery data access layer API and is written in
30  * a pluggable fashion to allow different backend storage mechanisms.
31  *
32  */
33
34 #ifndef _ASTERISK_BUCKET_H
35 #define _ASTERISK_BUCKET_H
36
37 #if defined(__cplusplus) || defined(c_plusplus)
38 extern "C" {
39 #endif
40
41 #include "asterisk/sorcery.h"
42
43 /*! \brief Opaque structure for internal details about a scheme */
44 struct ast_bucket_scheme;
45
46 /*! \brief Bucket metadata structure, AO2 key value pair */
47 struct ast_bucket_metadata {
48         /*! \brief Name of the attribute */
49         const char *name;
50         /*! \brief Value of the attribute */
51         const char *value;
52         /*! \brief Storage for the above name and value */
53         char data[0];
54 };
55
56 /*! \brief Bucket structure, contains other buckets and files */
57 struct ast_bucket {
58         /*! \brief Sorcery object information */
59         SORCERY_OBJECT(details);
60         /*! \brief Scheme implementation in use */
61         struct ast_bucket_scheme *scheme_impl;
62         /*! \brief Stringfields */
63         AST_DECLARE_STRING_FIELDS(
64                 /*! \brief Name of scheme in use */
65                 AST_STRING_FIELD(scheme);
66         );
67         /*! \brief When this bucket was created */
68         struct timeval created;
69         /*! \brief When this bucket was last modified */
70         struct timeval modified;
71         /*! \brief Container of string URIs of buckets within this bucket */
72         struct ao2_container *buckets;
73         /*! \brief Container of string URIs of files within this bucket */
74         struct ao2_container *files;
75 };
76
77 /*! \brief Bucket file structure, contains reference to file and information about it */
78 struct ast_bucket_file {
79         /*! \brief Sorcery object information */
80         SORCERY_OBJECT(details);
81         /*! \brief Scheme implementation in use */
82         struct ast_bucket_scheme *scheme_impl;
83         /*! \brief Stringfields */
84         AST_DECLARE_STRING_FIELDS(
85                 /*! \brief Name of scheme in use */
86                 AST_STRING_FIELD(scheme);
87         );
88         /*! \brief When this file was created */
89         struct timeval created;
90         /*! \brief When this file was last modified */
91         struct timeval modified;
92         /*! \brief Container of metadata attributes about file */
93         struct ao2_container *metadata;
94         /*! \brief Local path to this file */
95         char path[PATH_MAX];
96 };
97
98 /*!
99  * \brief A callback function invoked when creating a file snapshot
100  *
101  * \param file Pointer to the file snapshot
102  *
103  * \retval 0 success
104  * \retval -1 failure
105  */
106 typedef int (*bucket_file_create_cb)(struct ast_bucket_file *file);
107
108 /*!
109  * \brief A callback function invoked when destroying a file snapshot
110  *
111  * \param file Pointer to the file snapshot
112  */
113 typedef void (*bucket_file_destroy_cb)(struct ast_bucket_file *file);
114
115 /*!
116  * \brief Initialize bucket support
117  *
118  * \retval 0 success
119  * \retval -1 failure
120  */
121 int ast_bucket_init(void);
122
123 /*!
124  * \brief Register support for a specific scheme
125  *
126  * \param name Name of the scheme, used to find based on scheme in URIs
127  * \param bucket Sorcery wizard used for buckets
128  * \param file Sorcery wizard used for files
129  * \param create_cb Required file snapshot creation callback
130  * \param destroy_cb Optional file snapshot destruction callback
131  *
132  * \retval 0 success
133  * \retval -1 failure
134  *
135  * \note Once a scheme has been registered it can not be unregistered
136  */
137 #define ast_bucket_scheme_register(name, bucket, file, create_cb, destroy_cb) __ast_bucket_scheme_register(name, bucket, file, create_cb, destroy_cb, AST_MODULE_SELF)
138
139 /*!
140  * \brief Register support for a specific scheme
141  *
142  * \param name Name of the scheme, used to find based on scheme in URIs
143  * \param bucket Sorcery wizard used for buckets
144  * \param file Sorcery wizard used for files
145  * \param create_cb Required file snapshot creation callback
146  * \param destroy_cb Optional file snapshot destruction callback
147  * \param module The module which implements this scheme
148  *
149  * \retval 0 success
150  * \retval -1 failure
151  *
152  * \note Once a scheme has been registered it can not be unregistered
153  */
154 int __ast_bucket_scheme_register(const char *name, struct ast_sorcery_wizard *bucket,
155         struct ast_sorcery_wizard *file, bucket_file_create_cb create_cb,
156         bucket_file_destroy_cb destroy_cb, struct ast_module *module);
157
158 /*!
159  * \brief Set a metadata attribute on a file to a specific value
160  *
161  * \param file The bucket file
162  * \param name Name of the attribute
163  * \param value Value of the attribute
164  *
165  * \retval 0 success
166  * \retval -1 failure
167  *
168  * \note This function will overwrite an existing attribute of the same name, unless an error
169  * occurs. If an error occurs the existing attribute is left alone.
170  */
171 int ast_bucket_file_metadata_set(struct ast_bucket_file *file, const char *name, const char *value);
172
173 /*!
174  * \brief Unset a specific metadata attribute on a file
175  *
176  * \param file The bucket file
177  * \param name Name of the attribute
178  *
179  * \retval 0 success
180  * \retval -1 failure
181  */
182 int ast_bucket_file_metadata_unset(struct ast_bucket_file *file, const char *name);
183
184 /*!
185  * \brief Retrieve a metadata attribute from a file
186  *
187  * \param file The bucket file
188  * \param name Name of the attribute
189  *
190  * \retval non-NULL if found
191  * \retval NULL if not found
192  *
193  * \note The object is returned with reference count increased
194  */
195 struct ast_bucket_metadata *ast_bucket_file_metadata_get(struct ast_bucket_file *file, const char *name);
196
197 /*!
198  * \brief Execute a callback function on the metadata associated with a file
199  * \since 14.0.0
200  *
201  * \param file The bucket file
202  * \param cb An ao2 callback function that will be called with each \c ast_bucket_metadata
203  *           associated with \c file
204  * \param arg An optional argument to pass to \c cb
205  */
206 void ast_bucket_file_metadata_callback(struct ast_bucket_file *file, ao2_callback_fn cb, void *arg);
207
208 /*!
209  * \brief Allocate a new bucket
210  *
211  * \param uri Complete URI for the bucket
212  *
213  * \param non-NULL success
214  * \param NULL failure
215  *
216  * \note This only creates a local bucket object, to persist in backend storage you must call
217  * ast_bucket_create
218  */
219 struct ast_bucket *ast_bucket_alloc(const char *uri);
220
221 /*!
222  * \brief Create a new bucket in backend storage
223  *
224  * \param bucket The bucket
225  *
226  * \retval 0 success
227  * \retval -1 failure
228  */
229 int ast_bucket_create(struct ast_bucket *bucket);
230
231 /*!
232  * \brief Clone a bucket
233  *
234  * This will create a copy of the passed in \c ast_bucket structure. While
235  * all properties of the \c ast_bucket structure are copied, any metadata
236  * in the original structure simply has its reference count increased.
237  *
238  * \param file The bucket to clone
239  *
240  * \retval non-NULL success
241  * \retval NULL failure
242  *
243  * \note This operation should be called prior to updating a bucket
244  * object, as \c ast_bucket instances are immutable
245  */
246 struct ast_bucket *ast_bucket_clone(struct ast_bucket *bucket);
247
248 /*!
249  * \brief Delete a bucket from backend storage
250  *
251  * \param bucket The bucket
252  *
253  * \retval 0 success
254  * \retval -1 failure
255  */
256 int ast_bucket_delete(struct ast_bucket *bucket);
257
258 /*!
259  * \brief Retrieve information about a bucket
260  *
261  * \param uri Complete URI of the bucket
262  *
263  * \retval non-NULL if found
264  * \retval NULL if not found
265  *
266  * \note The object is returned with reference count increased
267  */
268 struct ast_bucket *ast_bucket_retrieve(const char *uri);
269
270 /*!
271  * \brief Retrieve whether or not the backing datastore views the bucket as stale
272  * \since 14.0.0
273  *
274  * This function will ask whatever data storage backs the bucket's schema
275  * type if the current instance of the object is stale. It will not
276  * update the bucket object itself, as said objects are immutable. If the
277  * caller of this function would like to update the object, it should perform
278  * a retrieve operation.
279  *
280  * \param bucket The bucket object to check
281  *
282  * \retval 0 if \c bucket is not stale
283  * \retval 1 if \c bucket is stale
284  */
285 int ast_bucket_is_stale(struct ast_bucket *bucket);
286
287 /*!
288  * \brief Add an observer for bucket creation and deletion operations
289  *
290  * \param callbacks Implementation of the sorcery observer interface
291  *
292  * \retval 0 success
293  * \retval -1 failure
294  *
295  * \note You must be ready to accept observer invocations before this function is called
296  */
297 int ast_bucket_observer_add(const struct ast_sorcery_observer *callbacks);
298
299 /*!
300  * \brief Remove an observer from bucket creation and deletion
301  *
302  * \param callbacks Implementation of the sorcery observer interface
303  */
304 void ast_bucket_observer_remove(const struct ast_sorcery_observer *callbacks);
305
306 /*!
307  * \brief Get a JSON representation of a bucket
308  *
309  * \param bucket The specific bucket
310  *
311  * \retval non-NULL success
312  * \retval NULL failure
313  *
314  * \note The returned ast_json object must be unreferenced using ast_json_unref
315  */
316 struct ast_json *ast_bucket_json(const struct ast_bucket *bucket);
317
318 /*!
319  * \brief Allocate a new bucket file
320  *
321  * \param uri Complete URI for the bucket file
322  *
323  * \param non-NULL success
324  * \param NULL failure
325  *
326  * \note This only creates a local bucket file object, to persist in backend storage you must call
327  * ast_bucket_file_create
328  */
329 struct ast_bucket_file *ast_bucket_file_alloc(const char *uri);
330
331 /*!
332  * \brief Create a new bucket file in backend storage
333  *
334  * \param file The bucket file
335  *
336  * \retval 0 success
337  * \retval -1 failure
338  */
339 int ast_bucket_file_create(struct ast_bucket_file *file);
340
341 /*!
342  * \brief Copy a bucket file to a new URI
343  *
344  * \param file The source bucket file
345  * \param uri The new URI
346  *
347  * \retval non-NULL success
348  * \retval NULL failure
349  *
350  * \note This operation stages things locally, you must call ast_bucket_file_create on the file
351  * that is returned to commit the copy to backend storage
352  *
353  */
354 struct ast_bucket_file *ast_bucket_file_copy(struct ast_bucket_file *file, const char *uri);
355
356 /*!
357  * \brief Clone a bucket file
358  *
359  * This will create a copy of the passed in \c ast_bucket_file structure. While
360  * all properties of the \c ast_bucket_file structure are copied, any metadata
361  * in the original structure simply has its reference count increased. Note that
362  * this copies the structure, not the underlying file.
363  *
364  * \param file The bucket file to clone
365  *
366  * \retval non-NULL success
367  * \retval NULL failure
368  *
369  * \note This operation should be called prior to updating a bucket file
370  * object, as \c ast_bucket_file instances are immutable
371  */
372 struct ast_bucket_file *ast_bucket_file_clone(struct ast_bucket_file *file);
373
374 /*!
375  * \brief Update an existing bucket file in backend storage
376  *
377  * \param file The bucket file
378  *
379  * \retval 0 success
380  * \retval -1 failure
381  *
382  * \note This operation will update both the actual content of the file and the metadata associated with it
383  */
384 int ast_bucket_file_update(struct ast_bucket_file *file);
385
386 /*!
387  * \brief Delete a bucket file from backend storage
388  *
389  * \param file The bucket file
390  *
391  * \retval 0 success
392  * \retval -1 failure
393  */
394 int ast_bucket_file_delete(struct ast_bucket_file *file);
395
396 /*!
397  * \brief Retrieve a bucket file
398  *
399  * \param uri Complete URI of the bucket file
400  *
401  * \retval non-NULL if found
402  * \retval NULL if not found
403  *
404  * \note The object is returned with reference count increased
405  */
406 struct ast_bucket_file *ast_bucket_file_retrieve(const char *uri);
407
408 /*!
409  * \brief Retrieve whether or not the backing datastore views the bucket file as stale
410  * \since 14.0.0
411  *
412  * This function will ask whatever data storage backs the bucket file's schema
413  * type if the current instance of the object is stale. It will not
414  * update the bucket file object itself, as said objects are immutable. If the
415  * caller of this function would like to update the object, it should perform
416  * a retrieve operation.
417  *
418  * \param bucket_file The bucket file object to check
419  *
420  * \retval 0 if \c bucket_file is not stale
421  * \retval 1 if \c bucket_file is stale
422  */
423 int ast_bucket_file_is_stale(struct ast_bucket_file *file);
424
425 /*!
426  * \brief Add an observer for bucket file creation and deletion operations
427  *
428  * \param callbacks Implementation of the sorcery observer interface
429  *
430  * \retval 0 success
431  * \retval -1 failure
432  *
433  * \note You must be ready to accept observer invocations before this function is called
434  */
435 int ast_bucket_file_observer_add(const struct ast_sorcery_observer *callbacks);
436
437 /*!
438  * \brief Remove an observer from bucket file creation and deletion
439  *
440  * \param callbacks Implementation of the sorcery observer interface
441  */
442 void ast_bucket_file_observer_remove(const struct ast_sorcery_observer *callbacks);
443
444 /*!
445  * \brief Get a JSON representation of a bucket file
446  *
447  * \param file The specific bucket file
448  *
449  * \retval non-NULL success
450  * \retval NULL failure
451  *
452  * \note The returned ast_json object must be unreferenced using ast_json_unref
453  */
454 struct ast_json *ast_bucket_file_json(const struct ast_bucket_file *file);
455
456 /*!
457  * \brief Common file snapshot creation callback for creating a temporary file
458  *
459  * \param file Pointer to the file snapshot
460  *
461  * \retval 0 success
462  * \retval -1 failure
463  */
464 int ast_bucket_file_temporary_create(struct ast_bucket_file *file);
465
466 /*!
467  * \brief Common file snapshot destruction callback for deleting a temporary file
468  *
469  * \param file Pointer to the file snapshot
470  */
471 void ast_bucket_file_temporary_destroy(struct ast_bucket_file *file);
472
473 #if defined(__cplusplus) || defined(c_plusplus)
474 }
475 #endif
476
477 #endif /* _ASTERISK_BUCKET_H */