[asterisk-commits] ivaxer: branch ivaxer/ast_storage r282427 - /team/ivaxer/ast_storage/include/...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Mon Aug 16 06:20:39 CDT 2010
Author: ivaxer
Date: Mon Aug 16 06:20:26 2010
New Revision: 282427
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=282427
Log:
added documentation to storage.h
Modified:
team/ivaxer/ast_storage/include/asterisk/storage.h
Modified: team/ivaxer/ast_storage/include/asterisk/storage.h
URL: http://svnview.digium.com/svn/asterisk/team/ivaxer/ast_storage/include/asterisk/storage.h?view=diff&rev=282427&r1=282426&r2=282427
==============================================================================
--- team/ivaxer/ast_storage/include/asterisk/storage.h (original)
+++ team/ivaxer/ast_storage/include/asterisk/storage.h Mon Aug 16 06:20:26 2010
@@ -31,6 +31,9 @@
extern "C" {
#endif
+/*
+ * File instance.
+ */
struct ast_storage_fileinst {
int fd;
AST_RWLIST_ENTRY(ast_storage_fileinst) list;
@@ -39,6 +42,10 @@
char localfile[64];
};
+/*
+ * Virtual file in storage medium.
+ * Note: file instance and file object are not equivalent in any sense.
+ */
struct ast_storage_fileobject {
char objectname[256];
char pathname[256];
@@ -74,26 +81,30 @@
/*! \brief Register a storage backenda
* \retval Returns 1 on success or 0 on failure
+ * \retval 0 Success
+ * \retval -1 Failure
*/
int __ast_register_storage(const struct ast_storage_be *e, struct ast_module *mod);
#define ast_register_storage(e) __ast_register_storage(e, ast_module_info->self)
/*! \brief Unregister a storage backend
* \param name Storage backend name
- * \retval Returns 1 on success or 0 on failure
+ * \retval 0 Success
+ * \retval -1 Failure
*/
int ast_unregister_storage(const char *name);
/*! \brief Retrieves an instance of a storage engine
* \param uri Backend specific URI to the resource
- * \retval NULL on faulure
- * \retval non-NULL successfully created storage instance
+ * \retval non-NULL Success
+ * \retval NULL Failure
*/
struct ast_storage *ast_storage_request(const char *uri);
/*! \brief Releases a storage instance created with ast_storage_request
* \param st Storage instance
- * \retval Returns 1 on success or 0 on failure
+ * \retval 0 Success
+ * \retval -1 Failure
*/
int ast_storage_release(struct ast_storage *st);
@@ -101,8 +112,8 @@
* \param st Storage instance
* \param objectname Logical name of the file
* \param exts File extensions to retrieve (separated by | character)
- * \retval NULL on faulure
- * \retval non-NULL successfully retrieved fileobject
+ * \retval non-NULL Success
+ * \retval NULL Failure
*/
struct ast_storage_fileobject *ast_storage_get(struct ast_storage *st, const char *objectname, const char *exts);
@@ -110,50 +121,150 @@
* \param st Storage instance
* \param fo File object to store
* \param exts File extensions to store (separated by '|' character)
- * \retval Returns 1 on success or 0 on failure
+ * \retval 0 Success
+ * \retval -1 Failure
*/
int ast_storage_put(struct ast_storage *st, struct ast_storage_fileobject *fo, const char *exts);
-
+/*! \brief Reads from a file instance
+ * \param st Storage instance
+ * \param fi File instance to read
+ * \param buf Buffer to read into
+ * \param count Number of bytes to read
+ * \retval 0 Seccess
+ * \retval <0 Failure
+ * \return Returns standard POSIX codes as documented in 'man 3p read'
+ *
+ * \note For more info see 'man 3p read'
+ */
int ast_storage_read(struct ast_storage *st, struct ast_storage_fileinst *fi, void *buf, size_t count);
+
+/*! \brief Writes on a file instance
+ * \param st Storage instance
+ * \param fi File instance to write
+ * \param buf Buffer to write from
+ * \param count Number of bytes to write
+ * \retval 0 Seccess
+ * \retval <0 Failure
+ * \return Returns standard POSIX codes as documented in 'man 3p write'
+ *
+ * \note For more info see 'man 3p write'
+ */
int ast_storage_write(struct ast_storage *st, struct ast_storage_fileinst *fi, void *buf, size_t count);
/*! \brief Removes a file from the storage medium
* \param st Storage instance
* \param fileobject Logical name of the file to delete
- * \retval Returns 1 on success or 0 on failure
+ * \retval 0 Success
+ * \retval -1 Failure
*/
int ast_storage_del(struct ast_storage *st, const char *fileobject);
+/*! \brief Copies a file in the storage medium
+ * \param st Storage instance
+ * \param from Logical name of the source file
+ * \param to Logical name of the destination
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
int ast_storage_copy(struct ast_storage *st, const char *from, const char *to);
-/*! \brief Starts retrieval of objects in a resource path
+/*! \brief Retrieves a list of files in the pathname in the storage medium
* \param st Storage instance
* \param pathname Logical name of the path
- * \retval NULL on failure
- * \retval non-NULL pointer to head of fileobjects list
+ * \retval non-NULL Success
+ * \retval NULL Failure
*/
struct ast_storage_fileobjects *ast_storage_listdir(struct ast_storage *st, const char *pathname);
+/*! \brief Returns the current read/write file offset
+ * \param st Storage instance
+ * \param fi File instance
+ * \return Upon successful completion, returns the current offset, as measured
+ * in bytes from the beginning of the file. Returns (off_t)-1 on failure.
+ *
+ * /note For more info see 'man 3p lseek'.
+ */
off_t ast_storage_tell(struct ast_storage *st, struct ast_storage_fileinst *fi);
-int ast_storage_seek(struct ast_storage *st, struct ast_storage_fileinst *fi, off_t offset, int whence);
-
+
+/*! \brief Moves the read/write file offset
+ * \param st Storage instance
+ * \param fi File instance
+ * \param offset Offset to set
+ * \param whence Whence
+ * \return Upon successful completion, returns the resulting offset, as measured
+ * in bytes from the beginning of the file. Returns (off_t)-1 on failure.
+ *
+ * /note For more info see 'man 3p lseek'.
+ */
+off_t ast_storage_seek(struct ast_storage *st, struct ast_storage_fileinst *fi, off_t offset, int whence);
+
+/*! \brief Creates new fileobject
+ * \retval non-NULL Success
+ * \retval NULL Failure
+ * \return Successfully allocated and initialized fileobject.
+ */
struct ast_storage_fileobject *ast_storage_fileobject_create(void);
+
+/*! \brief Releases fileobject
+ * \param fo File object to release
+ * \return Nothing.
+ */
void ast_storage_fileobject_release(struct ast_storage_fileobject *fo);
+/*! \brief Creates new file instance
+ * \retval non-NULL Success
+ * \retval NULL Failure
+ * \return Successfully allocated and initialized file instance.
+ */
struct ast_storage_fileinst *ast_storage_fileinst_create(void);
+
+/*! \brief Releasesfile instance
+ * \param fi File instance to release
+ * \return Nothing.
+ */
void ast_storage_fileinst_release(struct ast_storage_fileinst *fi);
+/*! \brief Creates a new list of fileobjects
+ * \retval non-NULL Success
+ * \retval NULL Failure
+ * \return Head of list of fileobjects.
+ */
struct ast_storage_fileobjects *ast_storage_fileobjects_create(void);
+
+/*! \brief Releases list of fileobjects
+ * \param fobjs Head of list of fileobjects
+ * \return Nothing.
+ */
void ast_storage_fileobjects_release(struct ast_storage_fileobjects *fobjs);
+/*! \brief Opens file instance
+ * \param fi File instance to open
+ * \param flags status flags and access modes
+ * \retval -1 Failure
+ * \retval >=0 Success
+ * \return Returns standard POSIX codes as documented in 'man 3p open' and sets
+ * errno.
+ *
+ * \note For more info see 'man 3p open'.
+ */
int ast_storage_open(struct ast_storage_fileinst *fi, int flags);
+
+/*! \brief Closes file instance
+ * \param fi File instance to close
+ * \retval -1 Failure
+ * \retval 0 Success
+ * \return Returns standard POSIX codes as documented in 'man 3p open' and sets
+ * errno.
+ *
+ * \note For more info see 'man 3p close'.
+ */
int ast_storage_close(struct ast_storage_fileinst *fi);
-/*! \brief Get storage engine by name
+/*! \brief Get a storage engine by name
* \param name Name of storage engine
- * \retval NULL on failure
- * \retval non-NULL pointer to storage engine instance
+ * \retval non-NULL Success
+ * \retval NULL Failure
*/
struct ast_storage_be *ast_storage_getbyname(const char *name);
More information about the asterisk-commits
mailing list