Function table of CMPIAssociationMI object. More...

#include <cmpift.h>

Data Fields
CMPIVersion	ftVersion
	CMPI version supported by the MI for this function table. More...

int	miVersion
	Informal MI-specific version number for this MI.

const char *	miName
	Informal MI-specific name for this MI.

CMPIStatus(*	cleanup )(CMPIAssociationMI mi, const CMPIContext ctx, CMPIBoolean terminating)
	Perform cleanup for an CMPIAssociationMI object. More...

CMPIStatus(*	associators )(CMPIAssociationMI mi, const CMPIContext ctx, const CMPIResult rslt, const CMPIObjectPath instPath, const char assocClass, const char resultClass, const char role, const char resultRole, const char **properties)
	Enumerate the instances associated with a given source instance that are serviced by this MI. More...

CMPIStatus(*	associatorNames )(CMPIAssociationMI mi, const CMPIContext ctx, const CMPIResult rslt, const CMPIObjectPath instPath, const char assocClass, const char resultClass, const char role, const char resultRole)
	Enumerate the instance paths of instances associated with a given source instance that are serviced by this MI. More...

CMPIStatus(*	references )(CMPIAssociationMI mi, const CMPIContext ctx, const CMPIResult rslt, const CMPIObjectPath instPath, const char resultClass, const char role, const char **properties)
	Enumerate the association instances referencing a given source instance that are serviced by this MI. More...

CMPIStatus(*	referenceNames )(CMPIAssociationMI mi, const CMPIContext ctx, const CMPIResult rslt, const CMPIObjectPath instPath, const char resultClass, const char role)
	Enumerate the instance paths of association instances referencing a given source instance that are serviced by this MI. More...

CMPIStatus(*	associatorsFiltered )(CMPIAssociationMI mi, const CMPIContext ctx, const CMPIResult rslt, const CMPIObjectPath instPath, const char assocClass, const char resultClass, const char role, const char resultRole, const char *properties, const char filterQueryLanguage, const char *filterQuery, CMPIBoolean continueOnError)
	Enumerate the instances associated with a given source instance that are serviced by this MI, returning only those instances that match a given query filter. More...

CMPIStatus(*	referencesFiltered )(CMPIAssociationMI mi, const CMPIContext ctx, const CMPIResult rslt, const CMPIObjectPath instPath, const char resultClass, const char role, const char *properties, const char filterQueryLanguage, const char *filterQuery, CMPIBoolean continueOnError)
	Enumerate the association instances referencing a given source instance that are serviced by this MI, returning only those instances that match a given query filter. More...

Detailed Description

Function table of CMPIAssociationMI object.

Field Documentation

CMPIVersion CMPIAssociationMIFT::ftVersion

CMPI version supported by the MI for this function table.

Any later CMPI versions are implicitly also supported.

See CMPIVersion<NNN> for valid CMPI version numbers.

CMPIStatus(* CMPIAssociationMIFT::cleanup)(CMPIAssociationMI *mi, const CMPIContext *ctx, CMPIBoolean terminating)

Perform cleanup for an CMPIAssociationMI object.

CMPIAssociationMIFT.cleanup() shall perform any necessary cleanup for the Association MI identified by mi, unless the MI postpones the cleanup.

While this function executes, the MB will not call any other MI functions for this MI. This function will be called once for a specific MI (unless the MI postpones the cleanup), even if that MI services more than one namespace. After this function returns, the MB may unload the load library this MI is part of, unless the MI postpones the cleanup.

Parameters

mi Points to a CMPIAssociationMI structure.

ctx Points to a CMPIContext object containing the context data for the invocation. The context data entries are MB implementation-specific.

terminating

Indicates whether the MB is in the process of shutting down and thus cannot tolerate postponing of the cleanup, as follows:

When True, the MB is in the process of shutting down. The MI shall perform any necessary cleanup and shall not postpone the cleanup. After this function returns (successful or in error), the MB will consider this MI to be uninitialized and will not call further MI functions for this MI.

When False, the MI can choose to perform or postpone the cleanup, by performing one of these actions:

The MI performs any necessary cleanup and does not request postponing the cleanup. After this function returns (successful or in error), the MB will consider this MI to be uninitialized and will not call further MI functions for this MI.
The MI does not perform any cleanup and temporarily postpones the cleanup, by returning CMPI_RC_DO_NOT_UNLOAD. This will cause the MB to consider this MI still to be initialized, and the MB may call further MI functions of this MI. The MB may call this function again after some MB implementation-specific time.
The MI does not perform any cleanup and permanently postpones the cleanup, by returning CMPI_RC_NEVER_UNLOAD. This will cause the MB to consider this MI still to be initialized, and the MB may call further MI functions of this MI. The MB will not call this function again until the MB terminates (at which time the MB calls this function with terminating set to true).

Returns: CMPIStatus structure containing the function return status.

Errors

The following CMPIrc codes shall be used by the MI in the function return status:

CMPI_RC_OK - Function successful.
CMPI_RC_DO_NOT_UNLOAD - Function successful, do not unload now; the MB may retry an unload later.
CMPI_RC_NEVER_UNLOAD - Function successful, never unload; the MB will not retry an unload later unless it shuts down.
CMPI_RC_ERR_FAILED - Other error occurred.

Convenience Function: CMAssociationMIStub()

CMPIStatus(* CMPIAssociationMIFT::associators)(CMPIAssociationMI *mi, const CMPIContext *ctx, const CMPIResult *rslt, const CMPIObjectPath *instPath, const char *assocClass, const char *resultClass, const char *role, const char *resultRole, const char **properties)

Enumerate the instances associated with a given source instance that are serviced by this MI.

CMPIAssociationMIFT.associators() shall enumerate the instances associated with a given source instance and that are serviced by this MI, by accessing the underlying managed elements.

This function is provided by the MI in context of a particular MI name. The class of instPath for which this function will be called by the MB depends on the specifics of how the MB relates classes and MI names, which is out of scope for this standard. As a result, the MB may call this function for classes for which the MI is not responsible. In order for an MI to be portable across MB implementations with different approaches to relate MI names and classes, the MI must check whether it services the class specified in instPath.

If the assocClass or resultClass filters are specified in a call to this function, the MB is not required to scope calls to this function to only the MIs that service these classes. As a result, the MB may (and will, in most implementations) call this function for classes in assocClass or resultClass for which the MI is not responsible. In order for an MI to be portable across MB implementations, the MI must check whether it services the classes specified in the assocClass and resultClass arguments.

Parameters

mi	Points to a CMPIAssociationMI structure.
ctx	Points to a CMPIContext object containing the context data for the invocation.
rslt	Points to a CMPIResult object that is the result data container. Upon successful return, the MI shall have put all instance paths representing the result set into this container.
instPath	Points to a CMPIObjectPath object that references the given source instance and that contains the namespace, class name, and key components. The hostname component, if present, has no meaning and should be ignored. If the source instance does not exist, this function shall either return success with an empty result data container or `CMPI_RC_ERR_NOT_FOUND`. The use of `CMPI_RC_ERR_NOT_FOUND` if the source instance does not exist, is deprecated.
assocClass	If not NULL, shall be a valid association class name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an instance of this class or one of its subclasses.
resultClass	If not NULL, shall be a valid class name. It acts as a filter on the returned set of objects by mandating that each returned object shall be an instance of this class or one of its subclasses.
role	If not NULL, shall be a valid property name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an association in which the source object plays the specified role (i.e., the name of the property in the association class that refers to the source object shall match the value of this argument).
resultRole	If not NULL, shall be a valid property name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an association in which the returned object plays the specified role (i.e., the name of the property in the association class that refers to the returned object shall match the value of this argument).
properties	If not NULL, is an array of zero or more pointers to strings, each specifying a property name. The end of the array is identified by a NULL pointer. The invocation flags specified in the CMPIInvocationFlags entry of the `ctx` argument have no meaning for this function. Each returned instance shall not include elements for any properties missing from this list. If the properties argument is NULL, this indicates that all properties shall be included in each returned instance.

Returns: CMPIStatus structure containing the function return status.

Errors

The following table lists the CMPIrc codes that shall be used by the MI in the function return status, as well as the WBEM operation messages that should be used in the CMPIError object if the MI supports extended error handling (see the corresponding Extended Errors capability):

CMPIRCCode	CMPIErrorMsg	Description
`CMPI_RC_OK`	N/A	Function Successful.
`CMPI_RC_ERR_NOT_SUPPORTED`	WIPG0228	Function is not supported by the MB.
`CMPI_RC_ERR_ACCESS_DENIED`	WIPG0201	Not authorized.
`CMPI_RC_ERR_INVALID_PARAMETER`	WIPG0249	Invalid filter parameters.
`CMPI_RC_ERR_NOT_FOUND`	WIPG0213	Source instance not found. (Deprecated)
`CMPI_RC_ERR_SERVER_LIMITS_EXCEEDED`	WIPG0240	Limits exceeded.
`CMPI_RC_ERR_FAILED`	WIPG0243	Timeout occurred.
`CMPI_RC_ERR_FAILED`	WIPG0227 + implementation-specific message	Other error occurred.

Convenience Function: CMAssociationMIStub()

Change:: In CMPI 2.1, added the return codes CMPI_RC_ERR_INVALID_PARAMETER and CMPI_RC_ERR_SERVER_LIMITS_EXCEEDED.

Deprecated:: The return code CMPI_RC_ERR_NOT_FOUND of this function is deprecated since CMPI 2.1. Instead of using this return code if the source instance does not exist, the MI should return success with an empty result data container. The MB shall treat this return code as a successful return of an empty result set.

CMPIStatus(* CMPIAssociationMIFT::associatorNames)(CMPIAssociationMI *mi, const CMPIContext *ctx, const CMPIResult *rslt, const CMPIObjectPath *instPath, const char *assocClass, const char *resultClass, const char *role, const char *resultRole)

Enumerate the instance paths of instances associated with a given source instance that are serviced by this MI.

CMPIAssociationMIFT.associatorNames() shall enumerate the instance paths of instances associated with a given source instance and that are serviced by this MI, by accessing the underlying managed elements.

This function is provided by the MI in context of a particular MI name. The class of instPath for which this function will be called by the MB depends on the specifics of how the MB relates classes and MI names, which is out of scope for this standard. As a result, the MB may call this function for classes for which the MI is not responsible. In order for an MI to be portable across MB implementations with different approaches to relate MI names and classes, the MI must check whether it services the class specified in instPath.

If the assocClass or resultClass filters are specified in a call to this function, the MB is not required to scope calls to this function to only the MIs that service these classes. As a result, the MB may (and will, in most implementations) call this function for classes in assocClass or resultClass for which the MI is not responsible. In order for an MI to be portable across MB implementations, the MI must check whether it services the classes specified in the assocClass and resultClass arguments.

Parameters

mi	Points to a CMPIAssociationMI structure.
ctx	Points to a CMPIContext object containing the context data for the invocation.
rslt	Points to a CMPIResult object that is the result data container. Upon successful return, the MI shall have put all instance paths representing the result set into this container.
instPath	Points to a CMPIObjectPath object that references the given source instance and that contains the namespace, class name, and key components. The hostname component, if present, has no meaning and should be ignored. If the source instance does not exist, this function shall either return success with an empty result data container or `CMPI_RC_ERR_NOT_FOUND`. The use of `CMPI_RC_ERR_NOT_FOUND` if the source instance does not exist, is deprecated.
assocClass	If not NULL, shall be a valid association class name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an instance of this class or one of its subclasses.
resultClass	If not NULL, shall be a valid class name. It acts as a filter on the returned set of objects by mandating that each returned object shall be an instance of this class or one of its subclasses.
role	If not NULL, shall be a valid property name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an association in which the source object plays the specified role (i.e., the name of the property in the association class that refers to the source object shall match the value of this argument).
resultRole	If not NULL, shall be a valid property name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an association in which the returned object plays the specified role (i.e., the name of the property in the association class that refers to the returned object shall match the value of this argument).

Returns: CMPIStatus structure containing the function return status.

Errors

The following table lists the CMPIrc codes that shall be used by the MI in the function return status, as well as the WBEM operation messages that should be used in the CMPIError object if the MI supports extended error handling (see the corresponding Extended Errors capability):

CMPIRCCode	CMPIErrorMsg	Description
`CMPI_RC_OK`	N/A	Function Successful.
`CMPI_RC_ERR_NOT_SUPPORTED`	WIPG0228	Function is not supported by the MB.
`CMPI_RC_ERR_ACCESS_DENIED`	WIPG0201	Not authorized.
`CMPI_RC_ERR_INVALID_PARAMETER`	WIPG0249	Invalid filter parameters.
`CMPI_RC_ERR_NOT_FOUND`	WIPG0213	Source instance not found. (Deprecated)
`CMPI_RC_ERR_SERVER_LIMITS_EXCEEDED`	WIPG0240	Limits exceeded.
`CMPI_RC_ERR_FAILED`	WIPG0243	Timeout occurred.
`CMPI_RC_ERR_FAILED`	WIPG0227 + implementation-specific message	Other error occurred.

Convenience Function: CMAssociationMIStub()

Change:: In CMPI 2.1, added the return codes CMPI_RC_ERR_INVALID_PARAMETER and CMPI_RC_ERR_SERVER_LIMITS_EXCEEDED.

Deprecated:: The return code CMPI_RC_ERR_NOT_FOUND of this function is deprecated since CMPI 2.1. Instead of using this return code if the source instance does not exist, the MI should return success with an empty result data container. The MB shall treat this return code as a successful return of an empty result set.

CMPIStatus(* CMPIAssociationMIFT::references)(CMPIAssociationMI *mi, const CMPIContext *ctx, const CMPIResult *rslt, const CMPIObjectPath *instPath, const char *resultClass, const char *role, const char **properties)

Enumerate the association instances referencing a given source instance that are serviced by this MI.

CMPIAssociationMIFT.references() shall enumerate the association instances referencing a given source instance and that are serviced by this MI, by accessing the underlying managed elements.

This function is provided by the MI in context of a particular MI name. The class of instPath for which this function will be called by the MB depends on the specifics of how the MB relates classes and MI names, which is out of scope for this standard. As a result, the MB may call this function for classes for which the MI is not responsible. In order for an MI to be portable across MB implementations with different approaches to relate MI names and classes, the MI must check whether it services the class specified in instPath.

If the resultClass filter is specified in a call to this function, the MB is not required to scope calls to this function to only the MIs that service this class. As a result, the MB may (and will, in most implementations) call this function for classes in resultClass for which the MI is not responsible. In order for an MI to be portable across MB implementations, the MI must check whether it services the class specified in resultClass.

Parameters

mi	Points to a CMPIAssociationMI structure.
ctx	Points to a CMPIContext object containing the context data for the invocation.
rslt	Points to a CMPIResult object that is the result data container. Upon successful return, the MI shall have put all instance paths representing the result set into this container.
instPath	Points to a CMPIObjectPath object that references the given source instance and that contains the namespace, class name, and key components. The hostname component, if present, has no meaning and should be ignored. If the source instance does not exist, this function shall either return success with an empty result data container or `CMPI_RC_ERR_NOT_FOUND`. The use of `CMPI_RC_ERR_NOT_FOUND` if the source instance does not exist, is deprecated.
resultClass	If not NULL, shall be a valid class name. It acts as a filter on the returned set of objects by mandating that each returned object shall be an instance of this class or one of its subclasses.
role	If not NULL, shall be a valid property name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an association in which the source object plays the specified role (i.e., the name of the property in the association class that refers to the source object shall match the value of this argument).
properties	If not NULL, is an array of zero or more pointers to strings, each specifying a property name. The end of the array is identified by a NULL pointer. The invocation flags specified in the CMPIInvocationFlags entry of the `ctx` argument have no meaning for this function. Each returned instance shall not include elements for any properties missing from this list. If the properties argument is NULL, this indicates that all properties shall be included in each returned instance.

Returns: CMPIStatus structure containing the function return status.

Errors

The following table lists the CMPIrc codes that shall be used by the MI in the function return status, as well as the WBEM operation messages that should be used in the CMPIError object if the MI supports extended error handling (see the corresponding Extended Errors capability):

CMPIRCCode	CMPIErrorMsg	Description
`CMPI_RC_OK`	N/A	Function Successful.
`CMPI_RC_ERR_NOT_SUPPORTED`	WIPG0228	Function is not supported by the MB.
`CMPI_RC_ERR_ACCESS_DENIED`	WIPG0201	Not authorized.
`CMPI_RC_ERR_INVALID_PARAMETER`	WIPG0249	Invalid filter parameters.
`CMPI_RC_ERR_NOT_FOUND`	WIPG0213	Source instance not found. (Deprecated)
`CMPI_RC_ERR_SERVER_LIMITS_EXCEEDED`	WIPG0240	Limits exceeded.
`CMPI_RC_ERR_FAILED`	WIPG0243	Timeout occurred.
`CMPI_RC_ERR_FAILED`	WIPG0227 + implementation-specific message	Other error occurred.

Convenience Function: CMAssociationMIStub()

Change:: In CMPI 2.1, added the return codes CMPI_RC_ERR_INVALID_PARAMETER and CMPI_RC_ERR_SERVER_LIMITS_EXCEEDED.

Deprecated:: The return code CMPI_RC_ERR_NOT_FOUND of this function is deprecated since CMPI 2.1. Instead of using this return code if the source instance does not exist, the MI should return success with an empty result data container. The MB shall treat this return code as a successful return of an empty result set.

CMPIStatus(* CMPIAssociationMIFT::referenceNames)(CMPIAssociationMI *mi, const CMPIContext *ctx, const CMPIResult *rslt, const CMPIObjectPath *instPath, const char *resultClass, const char *role)

Enumerate the instance paths of association instances referencing a given source instance that are serviced by this MI.

CMPIAssociationMIFT.referenceNames() shall enumerate the instance paths of the association instances referencing a given source instance and that are serviced by this MI, by accessing the underlying managed elements.

This function is provided by the MI in context of a particular MI name. The class of instPath for which this function will be called by the MB depends on the specifics of how the MB relates classes and MI names, which is out of scope for this standard. As a result, the MB may call this function for classes for which the MI is not responsible. In order for an MI to be portable across MB implementations with different approaches to relate MI names and classes, the MI must check whether it services the class specified in instPath.

If the resultClass filter is specified in a call to this function, the MB is not required to scope calls to this function to only the MIs that service this class. As a result, the MB may (and will, in most implementations) call this function for classes in resultClass for which the MI is not responsible. In order for an MI to be portable across MB implementations, the MI must check whether it services the class specified in resultClass.

Parameters

mi	Points to a CMPIAssociationMI structure.
ctx	Points to a CMPIContext object containing the context data for the invocation.
rslt	Points to a CMPIResult object that is the result data container. Upon successful return, the MI shall have put all instance paths representing the result set into this container.
instPath	Points to a CMPIObjectPath object that references the given source instance and that contains the namespace, class name, and key components. The hostname component, if present, has no meaning and should be ignored. If the source instance does not exist, this function shall either return success with an empty result data container or `CMPI_RC_ERR_NOT_FOUND`. The use of `CMPI_RC_ERR_NOT_FOUND` if the source instance does not exist, is deprecated.
resultClass	If not NULL, shall be a valid class name. It acts as a filter on the returned set of objects by mandating that each returned object shall be an instance of this class or one of its subclasses.
role	If not NULL, shall be a valid property name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an association in which the source object plays the specified role (i.e., the name of the property in the association class that refers to the source object shall match the value of this argument).

Returns: CMPIStatus structure containing the function return status.

Errors

The following table lists the CMPIrc codes that shall be used by the MI in the function return status, as well as the WBEM operation messages that should be used in the CMPIError object if the MI supports extended error handling (see the corresponding Extended Errors capability):

CMPIRCCode	CMPIErrorMsg	Description
`CMPI_RC_OK`	N/A	Function Successful.
`CMPI_RC_ERR_NOT_SUPPORTED`	WIPG0228	Function is not supported by the MB.
`CMPI_RC_ERR_ACCESS_DENIED`	WIPG0201	Not authorized.
`CMPI_RC_ERR_INVALID_PARAMETER`	WIPG0249	Invalid filter parameters.
`CMPI_RC_ERR_NOT_FOUND`	WIPG0213	Source instance not found. (Deprecated)
`CMPI_RC_ERR_SERVER_LIMITS_EXCEEDED`	WIPG0240	Limits exceeded.
`CMPI_RC_ERR_FAILED`	WIPG0243	Timeout occurred.
`CMPI_RC_ERR_FAILED`	WIPG0227 + implementation-specific message	Other error occurred.

Convenience Function: CMAssociationMIStub()

Change:: In CMPI 2.1, added the return codes CMPI_RC_ERR_INVALID_PARAMETER and CMPI_RC_ERR_SERVER_LIMITS_EXCEEDED.

Deprecated:: The return code CMPI_RC_ERR_NOT_FOUND of this function is deprecated since CMPI 2.1. Instead of using this return code if the source instance does not exist, the MI should return success with an empty result data container. The MB shall treat this return code as a successful return of an empty result set.

CMPIStatus(* CMPIAssociationMIFT::associatorsFiltered)(CMPIAssociationMI *mi, const CMPIContext *ctx, const CMPIResult *rslt, const CMPIObjectPath *instPath, const char *assocClass, const char *resultClass, const char *role, const char *resultRole, const char **properties, const char *filterQueryLanguage, const char *filterQuery, CMPIBoolean continueOnError)

Enumerate the instances associated with a given source instance that are serviced by this MI, returning only those instances that match a given query filter.

CMPIAssociationMIFT.associatorsFiltered() shall enumerate instances associated with a source instance and that are serviced by this MI, returning only those instances that match a given query filter, by accessing the underlying managed elements. The returned instances shall have their instance paths set. If no such instances are found, the function shall return success with an empty result data container.

This function is provided by the MI in context of a particular MI name. The class of instPath for which this function will be called by the MB depends on the specifics of how the MB relates classes and MI names, which is out of scope for this standard. As a result, the MB may call this function for classes for which the MI is not responsible. In order for an MI to be portable across MB implementations with different approaches to relate MI names and classes, the MI must check whether it services the class specified in instPath.

If the assocClass or resultClass filters are specified in a call to this function, the MB is not required to scope calls to this function to only the MIs that service these classes. As a result, the MB may (and will, in most implementations) call this function for classes in assocClass or resultClass for which the MI is not responsible. In order for an MI to be portable across MB implementations, the MI must check whether it services the classes specified in the assocClass and resultClass arguments.

Parameters

mi	Points to a CMPIAssociationMI structure.
ctx	Points to a CMPIContext object containing the context data for the invocation.
rslt	Points to a CMPIResult object that is the result data container. Upon successful return, the MI shall have put all instance paths representing the result set into this container.
instPath	Points to a CMPIObjectPath object that references the given source instance and that contains the namespace, class name, and key components. The hostname component, if present, has no meaning and should be ignored. If the source instance does not exist, this function shall return success with an empty result data container.
assocClass	If not NULL, shall be a valid association class name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an instance of this class or one of its subclasses.
resultClass	If not NULL, shall be a valid class name. It acts as a filter on the returned set of objects by mandating that each returned object shall be an instance of this class or one of its subclasses.
role	If not NULL, shall be a valid property name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an association in which the source object plays the specified role (i.e., the name of the property in the association class that refers to the source object shall match the value of this argument).
resultRole	If not NULL, shall be a valid property name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an association in which the returned object plays the specified role (i.e., the name of the property in the association class that refers to the returned object shall match the value of this argument).
properties	If not NULL, is an array of zero or more pointers to strings, each specifying a property name. The end of the array is identified by a NULL pointer. The invocation flags specified in the CMPIInvocationFlags entry of `ctx` have no meaning for this function. Each returned instance shall not include elements for any properties missing from this list. If `properties` is NULL, this indicates that all properties shall be included in each returned instance.
filterQueryLanguage	Query language used by `filterQuery`. If NULL, no filtering is performed. Note that FQL (see DSP0212) is required to be supported by MIs as a query language; see Subclause 4.5 in the CMPI Standard.
filterQuery	Query in the query language defined by `filterQueryLanguage`. If NULL, no filtering is performed. A request that specifies a filter through valid and non-NULL `filterQueryLanguage` and `filterQuery` arguments shall return only instances that match that filter as defined in the filter specification.
continueOnError	Defines whether this operation may continue to return objects after it returns an error. If false, the MI shall terminate after returning an error to the result data container. If true, the MI may continue to returning data (objects and subsequent errors) to the result data container after returning an error. An MI that cannot continue after returning an error shall ignore the value of `continueOnError` and shall behave as if it was specified as false.

Returns: CMPIStatus structure containing the function return status.

Errors

The following table lists the CMPIrc codes that shall be used by the MI in the function return status, as well as the WBEM operation messages that should be used in the CMPIError object if the MI supports extended error handling (see the corresponding Extended Errors capability):

CMPIRCCode	CMPIErrorMsg	Description
`CMPI_RC_OK`	N/A	Function Successful.
`CMPI_RC_ERR_NOT_SUPPORTED`	WIPG0228	Function is not supported by the MB.
`CMPI_RC_ERR_ACCESS_DENIED`	WIPG0201	Not authorized.
`CMPI_RC_ERR_INVALID_PARAMETER`	WIPG0249	Invalid filter parameters.
`CMPI_RC_ERR_SERVER_LIMITS_EXCEEDED`	WIPG0240	Limits exceeded.
`CMPI_RC_ERR_FAILED`	WIPG0243	Timeout occurred.
`CMPI_RC_ERR_FAILED`	WIPG0227 + implementation-specific message	Other error occurred.

Convenience Function: CMAssociationMIStub()

Addition:: Added in CMPI 2.1.

Bug:: The CMPI Standard misses to describe the scope of the MI, as described in the second and third paragraph of this function description in the header file. That should be added.

CMPIStatus(* CMPIAssociationMIFT::referencesFiltered)(CMPIAssociationMI *mi, const CMPIContext *ctx, const CMPIResult *rslt, const CMPIObjectPath *instPath, const char *resultClass, const char *role, const char **properties, const char *filterQueryLanguage, const char *filterQuery, CMPIBoolean continueOnError)

Enumerate the association instances referencing a given source instance that are serviced by this MI, returning only those instances that match a given query filter.

CMPIAssociationMIFT.referencesFiltered() shall enumerate the association instances referencing a given source instance and that are serviced by this MI, returning only those instances that match a given query filter, by accessing the underlying managed elements. The returned instances shall have their instance paths set. If no such instances are found, the function shall return success with an empty result data container.

This function is provided by the MI in context of a particular MI name. The class of instPath for which this function will be called by the MB depends on the specifics of how the MB relates classes and MI names, which is out of scope for this standard. As a result, the MB may call this function for classes for which the MI is not responsible. In order for an MI to be portable across MB implementations with different approaches to relate MI names and classes, the MI must check whether it services the class specified in instPath.

If the resultClass filter is specified in a call to this function, the MB is not required to scope calls to this function to only the MIs that service this class. As a result, the MB may (and will, in most implementations) call this function for classes in resultClass for which the MI is not responsible. In order for an MI to be portable across MB implementations, the MI must check whether it services the class specified in resultClass.

Parameters

mi	Points to a CMPIAssociationMI structure.
ctx	Points to a CMPIContext object containing the context data for the invocation.
rslt	Points to a CMPIResult object that is the result data container. Upon successful return, the MI shall have put all instance paths representing the result set into this container.
instPath	Points to a CMPIObjectPath object that references the given source instance and that contains the namespace, class name, and key components. The hostname component, if present, has no meaning and should be ignored. If the source instance does not exist, this function shall return success with an empty result data container.
resultClass	If not NULL, shall be a valid class name. It acts as a filter on the returned set of objects by mandating that each returned object shall be an instance of this class or one of its subclasses.
role	If not NULL, shall be a valid property name. It acts as a filter on the returned set of objects by mandating that each returned object shall be associated with the source object via an association in which the source object plays the specified role (i.e., the name of the property in the association class that refers to the source object shall match the value of this argument).
properties	If not NULL, is an array of zero or more pointers to strings, each specifying a property name. The end of the array is identified by a NULL pointer. The invocation flags specified in the CMPIInvocationFlags entry of `ctx` have no meaning for this function. Each returned instance shall not include elements for any properties missing from this list. If `properties` is NULL, this indicates that all properties shall be included in each returned instance.
filterQueryLanguage	Query language used by `filterQuery`. If NULL, no filtering is performed. Note that FQL (see DSP0212) is required to be supported by MIs as a query language; see Subclause 4.5 in the CMPI Standard.
filterQuery	Query in the query language defined by `filterQueryLanguage`. If NULL, no filtering is performed. A request that specifies a filter through valid and non-NULL `filterQueryLanguage` and `filterQuery` arguments shall return only instances that match that filter as defined in the filter specification.
continueOnError	Defines whether this operation may continue to return objects after it returns an error. If false, the MI shall terminate after returning an error to the result data container. If true, the MI may continue to returning data (objects and subsequent errors) to the result data container after returning an error. An MI that cannot continue after returning an error shall ignore the value of `continueOnError` and shall behave as if it was specified as false.

Returns: CMPIStatus structure containing the function return status.

Errors

The following table lists the CMPIrc codes that shall be used by the MI in the function return status, as well as the WBEM operation messages that should be used in the CMPIError object if the MI supports extended error handling (see the corresponding Extended Errors capability):

CMPIRCCode	CMPIErrorMsg	Description
`CMPI_RC_OK`	N/A	Function Successful.
`CMPI_RC_ERR_NOT_SUPPORTED`	WIPG0228	Function is not supported by the MB.
`CMPI_RC_ERR_ACCESS_DENIED`	WIPG0201	Not authorized.
`CMPI_RC_ERR_INVALID_PARAMETER`	WIPG0249	Invalid filter parameters.
`CMPI_RC_ERR_SERVER_LIMITS_EXCEEDED`	WIPG0240	Limits exceeded.
`CMPI_RC_ERR_FAILED`	WIPG0243	Timeout occurred.
`CMPI_RC_ERR_FAILED`	WIPG0227 + implementation-specific message	Other error occurred.

Convenience Function: CMAssociationMIStub()

Addition:: Added in CMPI 2.1.

Bug:: The CMPI Standard misses to describe the scope of the MI, as described in the second and third paragraph of this function description in the header file. That should be added.

The documentation for this struct was generated from the following file:

cmpift.h

Data Fields

Detailed Description

Field Documentation