Make sorcery details opaque and add extended fields.

Sorcery specific object information is now opaque and allocated with the object.
This means that modules do not need to be recompiled if the sorcery specific part
is changed. It also means that sorcery can store additional information on objects
and ensure it is freed or the reference count decreased when the object goes away.

To facilitate the above a generic sorcery allocator function has been added which
also ensures that allocated objects do not have a lock.

Extended fields have been added thanks to all of the above which allows specific fields
to be marked as extended, and thus simply stored as-is within the object. Type safety
is *NOT* enforced on these fields. A consumer of them has to query and ultimately perform
their own safety check. What does this mean? Extra modules can extend already defined
structures without having to modify them.

Tests have also been included to verify extended field functionality.

Review: https://reviewboard.asterisk.org/r/2585/


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@392586 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 44 insertions, 5 deletions

diff --git a/include/asterisk/sorcery.h b/include/asterisk/sorcery.h
index ae97da5cc..464a83c83 100644
--- a/include/asterisk/sorcery.h
+++ b/include/asterisk/sorcery.h
@@ -247,13 +247,13 @@ struct ast_sorcery_observer {
 	void (*loaded)(const char *object_type);
 };
 
+/*! \brief Opaque structure for internal sorcery object */
+struct ast_sorcery_object;
+
 /*! \brief Structure which contains details about a sorcery object */
 struct ast_sorcery_object_details {
-	/*! \brief Unique identifier of this object */
-	char id[AST_UUID_STR_LEN];
-
-	/*! \brief Type of object */
-	char type[MAX_OBJECT_TYPE];
+	/*! \brief Pointer to internal sorcery object information */
+	struct ast_sorcery_object *object;
 };
 
 /*! \brief Macro which must be used at the beginning of each sorcery capable object */
@@ -529,6 +529,17 @@ int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object,
 int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
 
 /*!
+ * \brief Allocate a generic sorcery capable object
+ *
+ * \param size Size of the object
+ * \param destructor Optional destructor function
+ *
+ * \retval non-NULL success
+ * \retval NULL failure
+ */
+void *ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor);
+
+/*!
  * \brief Allocate an object
  *
  * \param sorcery Pointer to a sorcery structure
@@ -695,6 +706,34 @@ const char *ast_sorcery_object_get_id(const void *object);
  */
 const char *ast_sorcery_object_get_type(const void *object);
 
+/*!
+ * \brief Get an extended field value from a sorcery object
+ *
+ * \param object Pointer to a sorcery object
+ * \param name Name of the extended field value
+ *
+ * \retval non-NULL if found
+ * \retval NULL if not found
+ *
+ * \note The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object
+ */
+const char *ast_sorcery_object_get_extended(const void *object, const char *name);
+
+/*!
+ * \brief Set an extended field value on a sorcery object
+ *
+ * \param object Pointer to a sorcery object
+ * \param name Name of the extended field
+ * \param value Value of the extended field
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * \note The field name MUST begin with '@' to indicate it is an extended field.
+ * \note If the extended field already exists it will be overwritten with the new value.
+ */
+int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value);
+
 #if defined(__cplusplus) || defined(c_plusplus)
 }
 #endif