[svn-commits] file: branch file/sorcery r378206 - /team/file/sorcery/include/asterisk/

[SVN commits to the Digium repositories]

Author: file
Date: Wed Dec 26 10:33:27 2012
New Revision: 378206

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=378206
Log:
Add a first jab at doxygen which shows some general info on how to do things.

Modified:
    team/file/sorcery/include/asterisk/sorcery.h

Modified: team/file/sorcery/include/asterisk/sorcery.h
URL: http://svnview.digium.com/svn/asterisk/team/file/sorcery/include/asterisk/sorcery.h?view=diff&rev=378206&r1=378205&r2=378206
==============================================================================
--- team/file/sorcery/include/asterisk/sorcery.h (original)
+++ team/file/sorcery/include/asterisk/sorcery.h Wed Dec 26 10:33:27 2012
@@ -27,6 +27,61 @@
  *
  * Sorcery is a unifying data access layer which utilizies the configuration framework,
  * realtime, and astdb to allow object creation, retrieval, updating, and deletion.
+ *
+ * \par Initialization
+ *
+ * Usage of sorcery is accomplished by first opening a sorcery structure. This structure holds
+ * all information about the object types, object fields, and object mappings. All API functions
+ * require the sorcery structure to operate. When sorcery is no longer needed the structure can
+ * be unreferenced using ast_sorcery_unref.
+ *
+ * Once opened the sorcery structure must have object mappings applied to it. This maps the
+ * object types to their respective wizards (object storage modules). If the developer would like
+ * to allow the user to configure this using the sorcery.conf configuration file the
+ * ast_sorcery_apply_config API call can be used to read in the configuration file and apply the
+ * mappings. If the storage of the object types are such that a default wizard can be used this can
+ * be applied using the ast_sorcery_apply_default API call. Note that the default mappings will not
+ * override configured mappings. They are only used in the case where no configured mapping exists.
+ *
+ * Configuring object mappings implicitly create a basic version of an object type. The object type
+ * must be fully registered, however, using the ast_sorcery_object_type_register API call before any
+ * objects of the type can be allocated, created, or retrieved.
+ *
+ * Once the object type itself has been fully registered the individual fields within the object must
+ * be registered using the ast_sorcery_object_field_register API call. Note that not all fields *need*
+ * be registered. Only fields that should be accessible using the sorcery API have to be registered.
+ *
+ * \par Creating Objects
+ *
+ * Before an object can be created within the sorcery API it must first be allocated using the
+ * ast_sorcery_alloc API call. This allocates a new instance of the object, sets sorcery specific
+ * details, and applies default values to the object. A unique identifier can optionally be specified
+ * when allocating an object. If it is not provided one will be automatically generated. Allocating
+ * an object does not create it within any object storage mechanisms that are configured for the
+ * object type. Creation must explicitly be done using the ast_sorcery_create API call. This API call
+ * passes the object to each configured object storage mechanism for the object type until one
+ * successfully persists the object.
+ *
+ * \par Retrieving Objects
+ *
+ * Object retrieval is accomplished using the ast_sorcery_retrieve API call. Objects themselves can be
+ * retrieved using either the unique identifier OR by specifying specific fields within the object and the
+ * respective values to look for. If the criteria given could result in multiple objects being returned the
+ * AST_RETRIEVE_FLAG_MULTIPLE flag can be enabled which returns all objects in an astobj2 container. Note
+ * that the returned object(s) should *NOT* be modified as they may be shared.
+ *
+ * \par Updating Objects
+ *
+ * As retrieved objects may be shared the first step to updating the object with new details is creating a
+ * copy using the ast_sorcery_copy API call. This will return a new object which is specific to the caller.
+ * Any field within the object may be modified as needed. Once changes are done the changes can be committed
+ * using the ast_sorcery_update API call. Note that as the copied object is specific to the caller it must
+ * be unreferenced after use.
+ *
+ * \par Deleting Objects
+ *
+ * To delete an object simply call the ast_sorcery_delete API call with an object retrieved using the
+ * ast_sorcery_retrieve API call or a copy returned from ast_sorcery_copy.
  */
 
 #ifndef _ASTERISK_SORCERY_H