For MB Functions of Encapsulated Data Types

Modules
	CMPIContext Support
	CMPIResult Support
	CMPIString Support
	CMPIArray Support
	CMPIEnumeration Support
	CMPIInstance Support
	CMPIObjectPath Support
	CMPIArgs Support
	CMPIDateTime Support
	CMPISelectExp Support
	CMPISelectCond Support
	CMPISubCond Support
	CMPIPredicate Support
	CMPIError Support
	CMPIPropertyList Support
	CMPIEnumerationFilter Support

Macros
#define	CMRelease(obj)
	Release an encapsulated data type object. More...
#define	CMClone(obj, rc)
	Clone an encapsulated data type object. More...

Detailed Description

MB Functions of Encapsulated Data Types.

The convenience functions in this group call functions on encapsulated data type objects.

The factory functions creating encapsulated data type objects are covered in MB Functions in Broker Function Tables.

They simplify the code by eliminating the references to function tables.

Macro Definition Documentation

#define CMRelease

(

obj

)

Release an encapsulated data type object.

CMRelease() releases an encapsulated data type object, by calling the release() function in the function table of the object.

This indicates to the MB that the object (including any objects it contains) will no longer be used by the MI. The MB may free the resources associated with the object during the call to this function, or later during some garbage collection cycle.

Parameters

obj	Points to the encapsulated data type object to be released.

Returns

CMPIStatus structure indicating the function return status.

Errors

The function return status will indicate one of the following CMPIrc codes:

• CMPI_RC_OK - Function successful.
• CMPI_RC_ERR_INVALID_HANDLE - The rslt handle is invalid.

Full Description

CMPIContextFT.release(), CMPIResultFT.release(), CMPIStringFT.release(), CMPIArrayFT.release(), CMPIEnumerationFT.release(), CMPIInstanceFT.release(), CMPIObjectPathFT.release(), CMPIArgsFT.release(), CMPIDateTimeFT.release(), CMPISelectExpFT.release(), CMPISelectCondFT.release(), CMPISubCondFT.release(), CMPIPredicateFT.release(), CMPIErrorFT.release(), CMPIPropertyListFT.release(), CMPIEnumerationFilterFT.release()

Examples

Code to clean up after attempting to create an instance:

 (.c)
CMPIStatus rc = { CMPI_RC_OK, NULL };
CMPISelectExp *se_def = NULL;
clone = CMClone(se_def, &rc);
// . . . test @rc for good completion and use clone if
CMRelease(clone);

Status for OpenPegasus:

TBD

#define CMClone	(		obj,
			rc
	)

Clone an encapsulated data type object.

CMClone() clones an encapsulated data type object, by calling the clone() function in the function table of the object.

Parameters

	obj	Points to the encapsulated data type object to be cloned.
[out]	rc	Function return status (suppressed when NULL).

Returns

If successful, returns a pointer to the copied clone of the object defined by obj.

The returned object shall be explicitly released by the MI using its release() function, or the CMRelease() macro.

If not successful, returns NULL.

Errors

The following CMPIrc codes shall be recognized:

• CMPI_RC_OK Operation successful.
• CMPI_RC_ERR_INVALID_HANDLE The ef handle is invalid.

Full Description

CMPIContextFT.clone(), CMPIResultFT.clone(), CMPIStringFT.clone(), CMPIArrayFT.clone(), CMPIEnumerationFT.clone(), CMPIInstanceFT.clone(), CMPIObjectPathFT.clone(), CMPIArgsFT.clone(), CMPIDateTimeFT.clone(), CMPISelectExpFT.clone(), CMPISelectCondFT.clone(), CMPISubCondFT.clone(), CMPIPredicateFT.clone(), CMPIErrorFT.clone(), CMPIPropertyListFT.clone(), CMPIEnumerationFilterFT.clone()

Examples

Clone an instance to add to an array:

 (.c)
// preexisting instance CMPIInstance *ci)
{
    CMPIStatus rc = { CMPI_RC_OK, NULL };
    CMPIInstance *inst;
    if (ci)
    {
        // clone the instance to be added to the array
        inst = CMClone(ci, &rc);
        . . .
    }

Status for OpenPegasus:

TBD

Todo:

TBD KS: test if we need brief in this and release doc