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

# HG changeset patch # User Richard Maciel <richardm(a)br.ibm.com&gt; # Date 1227019634 7200 # Node ID 80174662fa42b0752b7a1b5b73618c53b66b312a # Parent 5fbf96fedcf7df32fccc3f989aa4520af8c9a264 [CU](#2) Commented some structures in the std_association.h file * Commented the std_assoc and std_assoc_info structures to make easier for newbies to learn how to create new associations. * Rev 1: Fixed conceptual errors on comments * Rev 2: changed structures' comment style and changed comments based on feedback from Kaitlin and Dan Signed-off-by: Richard Maciel <richardm(a)br.ibm.com&gt; diff -r 5fbf96fedcf7 -r 80174662fa42 std_association.h --- a/std_association.h Wed Oct 08 10:32:18 2008 -0700 +++ b/std_association.h Tue Nov 18 12:47:14 2008 -0200 @@ -31,24 +31,62 @@ struct std_assoc_info *info, struct inst_list *list); -typedef CMPIInstance *(*make_ref_t)(const CMPIObjectPath *, - const CMPIInstance *, +typedef CMPIInstance *(*make_ref_t)(const CMPIObjectPath *ref, + const CMPIInstance *inst, struct std_assoc_info *info, - struct std_assoc *); + struct std_assoc *assoc); +/* + * std_assoc is the definition that the developer puts in their source file. It + * defines an association relationship between a set of source and target + * classes, through a named (set of) association classes and the function + * handler which does the work. + * It must be registered using the macro STDA_AssocMIStub. + */ struct std_assoc { + /* Defines the list of possible classes that can be passed to the + association for this case */ char **source_class; + + + /* 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 */ char *source_prop; + /* Defines a list of possible classes that can be returned by the + association for a given source_class list */ char **target_class; + + /* Same as source_prop, applied for target */ char *target_prop; + /* Defines the list of association classes which are implemented by + this handler */ char **assoc_class; + /* Function handler responsible for doing the association and + returning the list of target instances of the association. + 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). */ assoc_handler_t handler; + + /* Function handler responsible for creating an instance of the + association class. + The handler function receives the source object path, + and the target instance, so it can create the reference which is + returned by the function. */ make_ref_t make_ref; }; +/* + * The std_assoc_info is used to hold the query components of the query done + * All members of this structure contain the corresonding formal CIM association + * query components. + */ struct std_assoc_info { const char *assoc_class; const char *result_class;