[Libvirt-cim] [PATCH] [CU] Commented some structures in the std_association.h file

[Richard Maciel]

# HG changeset patch
# User Richard Maciel <richardm at br.ibm.com>
# Date 1226511618 7200
# Node ID a0bfb9da65f0ae911dbd7d18936d0a5fdcd63345
# Parent  5fbf96fedcf7df32fccc3f989aa4520af8c9a264
[CU] Commented some structures in the std_association.h file

* Commented the assoc_handler_t, make_ref_t types and the std_assoc, std_assoc_info structures
to make easier for newbies to learn how to create new associations.

Signed-off-by: Richard Maciel <richardm at br.ibm.com>

diff -r 5fbf96fedcf7 -r a0bfb9da65f0 std_association.h
--- a/std_association.h	Wed Oct 08 10:32:18 2008 -0700
+++ b/std_association.h	Wed Nov 12 15:40:18 2008 -0200
@@ -27,15 +27,68 @@
 struct std_assoc;
 struct std_assoc_info;
 
+/*
+ * This type defines the signature of the association handler function. The 
+ * handler function receives the reference of the source class of the 
+ * association and must map it to a list of CMPIInstance objects (targets
+ * of the association).
+ *
+ * In parameters:
+ *   CMPIObjectPath *        - Path to the source class
+ *   struct std_assoc_info * - See std_assoc_info comment
+ *
+ * Out parameters:
+ *   struct inst_list *      - Instances associated to ref
+ */
 typedef CMPIStatus (*assoc_handler_t)(const CMPIObjectPath *ref,
                                       struct std_assoc_info *info,
                                       struct inst_list *list);
 
+/*
+ * This type defines the signature of the handler which creates the
+ * reference. The handler function receives the source object path,
+ * and the target instance, so it can create the reference which is returned
+ * by the function.
+ *
+ * In parameters:
+ *   CMPIObjectPath *  - Path to the source class
+ *   CMPIInstance *    - Target instance
+ *   std_assoc_info    - Information from the query that called this function.
+ *                       See std_assoc_info comment for more information.
+ *   std_assoc         - This structure keeps the following necessary info to
+ *                       the creation of the association class instance:
+ *                       association class name and the names of the attributes 
+ *                       which will be set into the association class. 
+ *                       See the std_assoc comment for more info 
+ */
 typedef CMPIInstance *(*make_ref_t)(const CMPIObjectPath *,
                                     const CMPIInstance *,
                                     struct std_assoc_info *info,
                                     struct std_assoc *);
 
+/*
+ * std_assoc is the definition that the developer puts in their source file.  
+ * It must be registered using the macro STDA_AssocMIStub. 
+ *
+ * source_class - Defines the list of possible classes that can be passed to 
+ *                the association for this case
+ * source_prop  - Defines the property of the association class that refers 
+ *                to the input (source class) of this case. This must match
+ *                that of the schema, and is used for automatic generation of 
+ *                the reference object in the References() or ReferenceNames()
+ *                operation
+ * target_class - Same as source_class, applied for target
+ * target_prop  - Same as source_prop, applied for target
+ * assoc_class  - Defines the list of association classes which implement this
+ *                association
+ * handler      - Function handler responsible for doing the association and
+ *                returning the list of target instances of the association.
+ *                See assoc_handler_t comment for more info
+ * make_ref     - Function handler responsible for creating an instance of the
+ *                association class as requested by the References() or
+ *                ReferenceNames() operation. See make_ref_t comment for more
+ *                info
+ */
 struct std_assoc {
         char **source_class;
         char *source_prop;
@@ -49,6 +102,17 @@
         make_ref_t make_ref;
 };
 
+/*
+ * The std_assoc_info is used to keep information related to the query done
+ *
+ * assoc_class     - Name of the association class 
+ * result_class    - Name of the class of the target
+ * role            - Name of the property of the source class
+ * result_role     - Name of the property of the target class
+ * properties      - 
+ * context         -
+ * provider_name   - Calling provider name
+ */
 struct std_assoc_info {
         const char *assoc_class;
         const char *result_class;