bucket.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2013, Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Bucket File API
00021  * \author Joshua Colp <jcolp@digium.com>
00022  * \ref AstBucket
00023  */
00024 
00025 /*!
00026  * \page AstBucket Bucket File API
00027  *
00028  * Bucket is an API which provides directory and file access in a generic fashion. It is
00029  * implemented as a thin wrapper over the sorcery data access layer API and is written in
00030  * a pluggable fashion to allow different backend storage mechanisms.
00031  *
00032  */
00033 
00034 #ifndef _ASTERISK_BUCKET_H
00035 #define _ASTERISK_BUCKET_H
00036 
00037 #if defined(__cplusplus) || defined(c_plusplus)
00038 extern "C" {
00039 #endif
00040 
00041 #include "asterisk/sorcery.h"
00042 
00043 /*! \brief Opaque structure for internal details about a scheme */
00044 struct ast_bucket_scheme;
00045 
00046 /*! \brief Bucket metadata structure, AO2 key value pair */
00047 struct ast_bucket_metadata {
00048    /*! \brief Name of the attribute */
00049    const char *name;
00050    /*! \brief Value of the attribute */
00051    const char *value;
00052    /*! \brief Storage for the above name and value */
00053    char data[0];
00054 };
00055 
00056 /*! \brief Bucket structure, contains other buckets and files */
00057 struct ast_bucket {
00058    /*! \brief Sorcery object information */
00059    SORCERY_OBJECT(details);
00060    /*! \brief Scheme implementation in use */
00061    struct ast_bucket_scheme *scheme_impl;
00062    /*! \brief Stringfields */
00063    AST_DECLARE_STRING_FIELDS(
00064       /*! \brief Name of scheme in use */
00065       AST_STRING_FIELD(scheme);
00066    );
00067    /*! \brief When this bucket was created */
00068    struct timeval created;
00069    /*! \brief When this bucket was last modified */
00070    struct timeval modified;
00071    /*! \brief Container of string URIs of buckets within this bucket */
00072    struct ao2_container *buckets;
00073    /*! \brief Container of string URIs of files within this bucket */
00074    struct ao2_container *files;
00075 };
00076 
00077 /*! \brief Bucket file structure, contains reference to file and information about it */
00078 struct ast_bucket_file {
00079    /*! \brief Sorcery object information */
00080    SORCERY_OBJECT(details);
00081    /*! \brief Scheme implementation in use */
00082    struct ast_bucket_scheme *scheme_impl;
00083    /*! \brief Stringfields */
00084    AST_DECLARE_STRING_FIELDS(
00085       /*! \brief Name of scheme in use */
00086       AST_STRING_FIELD(scheme);
00087    );
00088    /*! \brief When this file was created */
00089    struct timeval created;
00090    /*! \brief When this file was last modified */
00091    struct timeval modified;
00092    /*! \brief Container of metadata attributes about file */
00093    struct ao2_container *metadata;
00094    /*! \brief Local path to this file */
00095    char path[PATH_MAX];
00096 };
00097 
00098 /*!
00099  * \brief A callback function invoked when creating a file snapshot
00100  *
00101  * \param file Pointer to the file snapshot
00102  *
00103  * \retval 0 success
00104  * \retval -1 failure
00105  */
00106 typedef int (*bucket_file_create_cb)(struct ast_bucket_file *file);
00107 
00108 /*!
00109  * \brief A callback function invoked when destroying a file snapshot
00110  *
00111  * \param file Pointer to the file snapshot
00112  */
00113 typedef void (*bucket_file_destroy_cb)(struct ast_bucket_file *file);
00114 
00115 /*!
00116  * \brief Initialize bucket support
00117  *
00118  * \retval 0 success
00119  * \retval -1 failure
00120  */
00121 int ast_bucket_init(void);
00122 
00123 /*!
00124  * \brief Register support for a specific scheme
00125  *
00126  * \param name Name of the scheme, used to find based on scheme in URIs
00127  * \param bucket Sorcery wizard used for buckets
00128  * \param file Sorcery wizard used for files
00129  * \param create_cb Required file snapshot creation callback
00130  * \param destroy_cb Optional file snapshot destruction callback
00131  *
00132  * \retval 0 success
00133  * \retval -1 failure
00134  *
00135  * \note Once a scheme has been registered it can not be unregistered
00136  */
00137 #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_info ? ast_module_info->self : NULL)
00138 
00139 /*!
00140  * \brief Register support for a specific scheme
00141  *
00142  * \param name Name of the scheme, used to find based on scheme in URIs
00143  * \param bucket Sorcery wizard used for buckets
00144  * \param file Sorcery wizard used for files
00145  * \param create_cb Required file snapshot creation callback
00146  * \param destroy_cb Optional file snapshot destruction callback
00147  * \param module The module which implements this scheme
00148  *
00149  * \retval 0 success
00150  * \retval -1 failure
00151  *
00152  * \note Once a scheme has been registered it can not be unregistered
00153  */
00154 int __ast_bucket_scheme_register(const char *name, struct ast_sorcery_wizard *bucket,
00155    struct ast_sorcery_wizard *file, bucket_file_create_cb create_cb,
00156    bucket_file_destroy_cb destroy_cb, struct ast_module *module);
00157 
00158 /*!
00159  * \brief Set a metadata attribute on a file to a specific value
00160  *
00161  * \param file The bucket file
00162  * \param name Name of the attribute
00163  * \param value Value of the attribute
00164  *
00165  * \retval 0 success
00166  * \retval -1 failure
00167  *
00168  * \note This function will overwrite an existing attribute of the same name, unless an error
00169  * occurs. If an error occurs the existing attribute is left alone.
00170  */
00171 int ast_bucket_file_metadata_set(struct ast_bucket_file *file, const char *name, const char *value);
00172 
00173 /*!
00174  * \brief Unset a specific metadata attribute on a file
00175  *
00176  * \param file The bucket file
00177  * \param name Name of the attribute
00178  *
00179  * \retval 0 success
00180  * \retval -1 failure
00181  */
00182 int ast_bucket_file_metadata_unset(struct ast_bucket_file *file, const char *name);
00183 
00184 /*!
00185  * \brief Retrieve a metadata attribute from a file
00186  *
00187  * \param file The bucket file
00188  * \param name Name of the attribute
00189  *
00190  * \retval non-NULL if found
00191  * \retval NULL if not found
00192  *
00193  * \note The object is returned with reference count increased
00194  */
00195 struct ast_bucket_metadata *ast_bucket_file_metadata_get(struct ast_bucket_file *file, const char *name);
00196 
00197 /*!
00198  * \brief Allocate a new bucket
00199  *
00200  * \param uri Complete URI for the bucket
00201  *
00202  * \param non-NULL success
00203  * \param NULL failure
00204  *
00205  * \note This only creates a local bucket object, to persist in backend storage you must call
00206  * ast_bucket_create
00207  */
00208 struct ast_bucket *ast_bucket_alloc(const char *uri);
00209 
00210 /*!
00211  * \brief Create a new bucket in backend storage
00212  *
00213  * \param bucket The bucket
00214  *
00215  * \retval 0 success
00216  * \retval -1 failure
00217  */
00218 int ast_bucket_create(struct ast_bucket *bucket);
00219 
00220 /*!
00221  * \brief Delete a bucket from backend storage
00222  *
00223  * \param bucket The bucket
00224  *
00225  * \retval 0 success
00226  * \retval -1 failure
00227  */
00228 int ast_bucket_delete(struct ast_bucket *bucket);
00229 
00230 /*!
00231  * \brief Retrieve information about a bucket
00232  *
00233  * \param uri Complete URI of the bucket
00234  *
00235  * \retval non-NULL if found
00236  * \retval NULL if not found
00237  *
00238  * \note The object is returned with reference count increased
00239  */
00240 struct ast_bucket *ast_bucket_retrieve(const char *uri);
00241 
00242 /*!
00243  * \brief Add an observer for bucket creation and deletion operations
00244  *
00245  * \param callbacks Implementation of the sorcery observer interface
00246  *
00247  * \retval 0 success
00248  * \retval -1 failure
00249  *
00250  * \note You must be ready to accept observer invocations before this function is called
00251  */
00252 int ast_bucket_observer_add(const struct ast_sorcery_observer *callbacks);
00253 
00254 /*!
00255  * \brief Remove an observer from bucket creation and deletion
00256  *
00257  * \param callbacks Implementation of the sorcery observer interface
00258  */
00259 void ast_bucket_observer_remove(const struct ast_sorcery_observer *callbacks);
00260 
00261 /*!
00262  * \brief Get a JSON representation of a bucket
00263  *
00264  * \param bucket The specific bucket
00265  *
00266  * \retval non-NULL success
00267  * \retval NULL failure
00268  *
00269  * \note The returned ast_json object must be unreferenced using ast_json_unref
00270  */
00271 struct ast_json *ast_bucket_json(const struct ast_bucket *bucket);
00272 
00273 /*!
00274  * \brief Allocate a new bucket file
00275  *
00276  * \param uri Complete URI for the bucket file
00277  *
00278  * \param non-NULL success
00279  * \param NULL failure
00280  *
00281  * \note This only creates a local bucket file object, to persist in backend storage you must call
00282  * ast_bucket_file_create
00283  */
00284 struct ast_bucket_file *ast_bucket_file_alloc(const char *uri);
00285 
00286 /*!
00287  * \brief Create a new bucket file in backend storage
00288  *
00289  * \param file The bucket file
00290  *
00291  * \retval 0 success
00292  * \retval -1 failure
00293  */
00294 int ast_bucket_file_create(struct ast_bucket_file *file);
00295 
00296 /*!
00297  * \brief Copy a bucket file to a new URI
00298  *
00299  * \param file The source bucket file
00300  * \param uri The new URI
00301  *
00302  * \retval non-NULL success
00303  * \retval NULL failure
00304  *
00305  * \note This operation stages things locally, you must call ast_bucket_file_create on the file
00306  * that is returned to commit the copy to backend storage
00307  *
00308  */
00309 struct ast_bucket_file *ast_bucket_file_copy(struct ast_bucket_file *file, const char *uri);
00310 
00311 /*!
00312  * \brief Update an existing bucket file in backend storage
00313  *
00314  * \param file The bucket file
00315  *
00316  * \retval 0 success
00317  * \retval -1 failure
00318  *
00319  * \note This operation will update both the actual content of the file and the metadata associated with it
00320  */
00321 int ast_bucket_file_update(struct ast_bucket_file *file);
00322 
00323 /*!
00324  * \brief Delete a bucket file from backend storage
00325  *
00326  * \param file The bucket file
00327  *
00328  * \retval 0 success
00329  * \retval -1 failure
00330  */
00331 int ast_bucket_file_delete(struct ast_bucket_file *file);
00332 
00333 /*!
00334  * \brief Retrieve a bucket file
00335  *
00336  * \param uri Complete URI of the bucket file
00337  *
00338  * \retval non-NULL if found
00339  * \retval NULL if not found
00340  *
00341  * \note The object is returned with reference count increased
00342  */
00343 struct ast_bucket_file *ast_bucket_file_retrieve(const char *uri);
00344 
00345 /*!
00346  * \brief Add an observer for bucket file creation and deletion operations
00347  *
00348  * \param callbacks Implementation of the sorcery observer interface
00349  *
00350  * \retval 0 success
00351  * \retval -1 failure
00352  *
00353  * \note You must be ready to accept observer invocations before this function is called
00354  */
00355 int ast_bucket_file_observer_add(const struct ast_sorcery_observer *callbacks);
00356 
00357 /*!
00358  * \brief Remove an observer from bucket file creation and deletion
00359  *
00360  * \param callbacks Implementation of the sorcery observer interface
00361  */
00362 void ast_bucket_file_observer_remove(const struct ast_sorcery_observer *callbacks);
00363 
00364 /*!
00365  * \brief Get a JSON representation of a bucket file
00366  *
00367  * \param file The specific bucket file
00368  *
00369  * \retval non-NULL success
00370  * \retval NULL failure
00371  *
00372  * \note The returned ast_json object must be unreferenced using ast_json_unref
00373  */
00374 struct ast_json *ast_bucket_file_json(const struct ast_bucket_file *file);
00375 
00376 /*!
00377  * \brief Common file snapshot creation callback for creating a temporary file
00378  *
00379  * \param file Pointer to the file snapshot
00380  *
00381  * \retval 0 success
00382  * \retval -1 failure
00383  */
00384 int ast_bucket_file_temporary_create(struct ast_bucket_file *file);
00385 
00386 /*!
00387  * \brief Common file snapshot destruction callback for deleting a temporary file
00388  *
00389  * \param file Pointer to the file snapshot
00390  */
00391 void ast_bucket_file_temporary_destroy(struct ast_bucket_file *file);
00392 
00393 #if defined(__cplusplus) || defined(c_plusplus)
00394 }
00395 #endif
00396 
00397 #endif /* _ASTERISK_BUCKET_H */

Generated on Thu Apr 16 06:27:16 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6