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

# HG changeset patch # User Richard Maciel <richardm(a)br.ibm.com&gt; # 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(a)br.ibm.com&gt; 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;