Helper Functions and Macros

Macros
#define	CMReturn(rc)
	Return the calling function with CMPIStatus specifying a return code and no message. More...
#define	CMReturnWithString(rc, str)
	Return the calling function with CMPIStatus specifying a return code and a message (from CMPIString object). More...
#define	CMReturnWithChars(mb, rc, chars)
	Return the calling function with CMPIStatus specifying a return code and a message (from C string). More...

Functions
static void	CMSetStatus (CMPIStatus *st, CMPIrc rc)
	Initialize a CMPIStatus structure with a return code and no message. More...
static void	CMSetStatusWithString (CMPIStatus *st, CMPIrc rc, CMPIString *msg)
	Initializes a CMPIStatus object with CMPIStatus and message. More...
static void	CMSetStatusWithChars (const CMPIBroker *mb, CMPIStatus *st, CMPIrc rc, const char *msg)
	Initializes CMPIStatus struct with return code and message text message. More...
static CMPIBoolean	CMIsNullObject (const void *objptr)
	Test an encapsulated data type object pointer for NULL. More...
static CMPIBoolean	CMIsNullValue (CMPIData data)
	Test a CMPIData value for NULL. More...
static CMPIBoolean	CMIsKeyValue (CMPIData data)
	Test a CMPIData value for being a key. More...
static CMPIBoolean	CMIsArray (CMPIData data)
	Test a CMPIData value for having an array type. More...
static unsigned int	CBGetCapabilities (const CMPIBroker *mb)
	Get the MB capabilities. More...
static CMPIVersion	CBBrokerVersion (const CMPIBroker *mb)
	Get the CMPI version supported by the MB. More...
static const char *	CBBrokerName (const CMPIBroker *mb)
	Get the MB name. More...

Detailed Description

Helper Functions and Macros.

The helper functions and macros encapsulate the access to selected structure members or otherwise provide functionality that is not directly available through an MB function.

Macro Definition Documentation

#define CMReturn

(

rc

)

Return the calling function with CMPIStatus specifying a return code and no message.

The CMReturn() macro builds a CMPIStatus object specifying a return code and no message and exits the function in which it was called, causing it to return that CMPIStatus object. CMReturn() can only be used in functions that return CMPIStatus.

Parameters

rc	A CMPIrc value specifying the return code.

Returns

This macro never returns to its caller; it contains a return statement and therefore exits the function from which it was called.

Examples

Example of enumerateInstanceNames() MI function that returns CMPI_RC_OK to the MB.

 (.c)
CMPIStatus testEnumInstanceNames (CMPIInstanceMI *mi,
    const CMPIContext *ctx, const CMPIResult *rslt,
    const CMPIObjectPath *classPath)
{
    // .... code to return instance names
    CMReturn(CMPI_RC_OK);
}

Status for OpenPegasus:

TBD

#define CMReturnWithString	(		rc,
			str
	)

Return the calling function with CMPIStatus specifying a return code and a message (from CMPIString object).

The CMReturnWithString() macro builds a CMPIStatus object specifying a return code and a message and exits the function in which it was executed, causing it to return that CMPIStatus object. CMReturnWithString() can only be used in functions that return CMPIStatus.

Parameters

rc	A CMPIrc value specifying the return code.
str	Points to a CMPIString object specifying the message.

Returns

This macro never returns to its caller; it contains a return statement and therefore exits the function from which it was called.

Examples

Example of code in an MI function that checks for an optional MB capability and returns with an error to the MB if the capability is not available.

 (.c)
static const CMPIBroker * _broker;
// ...
if (_broker->brokerCapabilities & CMPI_MB_PropertyFiltering)
{
    // ...
}
else
{
    CMReturnWithString(CMPI_RC_ERR_NOT_SUPPORTED,
        CMNewString(_broker, "Property Filtering capability not available",
            NULL));
}

See Also

CMPIStatus

Status for OpenPegasus:

TBD

#define CMReturnWithChars	(		mb,
			rc,
			chars
	)

Return the calling function with CMPIStatus specifying a return code and a message (from C string).

The CMReturnWithChars() macro builds a CMPIStatus object specifying a return code and a message and exits the function in which it was executed, causing it to return that CMPIStatus object. CMReturnWithChars() can only be used in functions that return CMPIStatus.

Parameters

mb	CMPIBroker structure.
rc	A CMPIrc value specifying the return code.
chars	A C string (char*) specifying the message.

Returns

This macro never returns to its caller; it contains a return statement and therefore exits the function from which it was called.

Examples

Example of code in a modifyInstance() MI function that is not implemented and returns to the MB with CMPI_RC_ERR_NOT_SUPPORTED and an according error message.

 (.c)
static const CMPIBroker * _broker;
// ...
CMPIStatus testModifyInstance (...)
{
    CMReturnWithChars(_broker, CMPI_RC_ERR_NOT_SUPPORTED,
        "ModifyInstance is not supported");
}

See Also

CMPIStatus

Status for OpenPegasus:

TBD

Function Documentation

static void CMSetStatus ( CMPIStatus *  st, CMPIrc  rc  )

inlinestatic

Initialize a CMPIStatus structure with a return code and no message.

CMSetStatus() initializes a CMPIStatus structure with a return code and no message.

Parameters

st	If not NULL, points to the CMPIStatus structure that is being intialized.
rc	A CMPIrc value specifying the return code.

Returns

Nothing.

Examples

 (.c)
CMPIStatus st = { CMPI_RC_OK, NULL };
if (....) // something bad happened
{
    CMSetStatus(&st, CMPI_RC_ERR_NOT_SUPPORTED);
    return st;
}

See Also

CMPIStatus

Status for OpenPegasus:

Not tested

static void CMSetStatusWithString ( CMPIStatus *  st, CMPIrc  rc, CMPIString *  msg  )

inlinestatic

Initializes a CMPIStatus object with CMPIStatus and message.

CMSetStatusWithString() initialized the CMPIStatus object st with CMPIStatus rc and message text defined by msg

Parameters

st	Points to target CMPIStatus object.
rc	A CMPIrc value specifying the return code.
msg	CMPIString containing message text to be inserted into st.

See Also

CMPIStatus

Status for OpenPegasus:

TBD

static void CMSetStatusWithChars ( const CMPIBroker *  mb, CMPIStatus *  st, CMPIrc  rc, const char *  msg  )

inlinestatic

Initializes CMPIStatus struct with return code and message text message.

CMSetStatusWithChars() initializes a CMPIStatus structure with rcp and either a null msg or a new CMPIString object created from msg if msg is not NULL.

Parameters

mb	CMPIBroker structure.
st	Points to CMPIStatus object.
rc	A CMPIrc value specifying the return code.
msg	C string character string containing the message text or NULL if no text is to be added to the CMPIStatus st.

Examples

 (.c)
static CMPIBroker *_broker; // Cany be populated with stub macro
. . .
CMPIStatus rc = { CMPI_RC_OK, NULL };
CMSetStatusWithChars (_broker, &rc,
    CMPI_RC_ERR_NOT_SUPPORTED, "CIM_ERR_NOT_SUPPORTED");

See Also

CMPIStatus

Status for OpenPegasus:

TBD

static CMPIBoolean CMIsNullObject ( const void *  objptr )

inlinestatic

Test an encapsulated data type object pointer for NULL.

This test is suitable for checking any pointers to encapsulated data type objects for NULL, including the pointers returned by their factory functions.

Parameters

objptr

Pointer to the encapsulated data type object to be tested. This argument is defined as void* to encompass any encapsulated data type object.

Return values

true	The object is NULL.
false	The object is NOT NULL.

Examples

 (.c)
cop = CMNewObjectPath(_broker, "root/SampleProvider", _ClassName, &rc);
CMAddKey(cop2, "Identifier", (CMPIValue *)&value1, CMPI_uint8);
// test for NULL before creating instance from cop
if (!CMIsNullObject(cop))
{
    instance2 = CMNewInstance(_broker, cop2, &rc);
    ...
}

Status for OpenPegasus:

TBD

Todo:

TODO_KS The example seems to be somewhat confused. Why is a test of cop meaningful when it is not used at all, and cop2 is used instead?
Karl to review the example.

static CMPIBoolean CMIsNullValue ( CMPIData  data )

inlinestatic

Test a CMPIData value for NULL.

CMIsNullValue() tests a CMPIData value for NULL. This is done based on the CMPI_nullValue flag in its state member.

Parameters

data	The CMPIData value to be tested.

Return values

true	The CMPIData value is NULL.
false	The CMPIData value is not NULL.

Examples

Process received method call that includes a CIMObject path ref for classname, method name, arguments, argument name and value in the argument

 (.c)
CMPIStatus *rc;
className = CMGetClassName(ref, &rc);
name = CMGetCharsPtr(className, &rc);
if (!strcmp(name, _ClassName))
{
    if (!strcmp ("SayHello", methodName))
    {
        // gets the number of arguments contained in "in" Args.
        if (CMGetArgCount(in, &rc) > 0)
        {
            // gets Name argument value
            data = CMGetArg(in, "MethodName", &rc);
            // should we check rc on response.
            // check for data type and !null value of
            // argument value rcvd
            if (data.type == CMPI_string && !(CMIsNullValue(data)))
            {
                strCat = CMGetCharsPtr(data.value.string, &rc);
                strcat(result, strCat);
                strcat(result, "!");
                // create the new string to return to client
                str1 = CMNewString(_broker, result, &rc);
                val1.string = str1;
            }
        . . .

See Also

CMPIData, CMPIValueState

Status for OpenPegasus:

TBD

Todo:

TODO_KS The example is way too complex if it just intends to show how to use this function.
Karl to come up with simpler example.

static CMPIBoolean CMIsKeyValue ( CMPIData  data )

inlinestatic

Test a CMPIData value for being a key.

CMIsKeyValue() tests a CMPIData value for being a key. This is done based on the CMPI_keyValue flag in its state member.

Parameters

data	The CMPIData value to be tested.

Return values

true	The CMPIData value is a key.
false	The CMPIData value is not a key.

See Also

CMPIData, CMPIValueState

Status for OpenPegasus:

Not tested

static CMPIBoolean CMIsArray ( CMPIData  data )

inlinestatic

Test a CMPIData value for having an array type.

CMIsArray() tests a CMPIData value for having an array type. This is done based on the CMPI_ARRAY flag in its type member.

Parameters

data	The CMPIData value to be tested.

Return values

true	The CMPIData value has array type.
false	The CMPIData value does not have array type.

See Also

CMPIData, CMPIType

Status for OpenPegasus:

Not tested

Todo:

TODO_KS This needs an example.

static unsigned int CBGetCapabilities ( const CMPIBroker *  mb )

inlinestatic

Get the MB capabilities.

The MB capabilities are defined as bits in the returned integer value. See MB Capabilities for details.

Parameters

mb	CMPIBroker structure.

Returns

MB capabilities.

Full Description

CMPIBrokerFT.brokerCapabilities

Change:

In CMPI 2.1, CBGetClassification() was removed as not working, and this function was introduced.

See Also

MB Capabilities

Status for OpenPegasus:

TBD

static CMPIVersion CBBrokerVersion ( const CMPIBroker *  mb )

inlinestatic

Get the CMPI version supported by the MB.

Any earlier CMPI versions are implicitly also supported. See CMPIVersion<NNN> for valid CMPI version numbers.

Note: This is not the version of the MB.

Parameters

mb	CMPIBroker structure.

Returns

CMPI version supported by the MB.

Full Description

CMPIBrokerFT.brokerVersion

Status for OpenPegasus:

Not used

static const char* CBBrokerName ( const CMPIBroker *  mb )

inlinestatic

Get the MB name.

The MB name is an informal MB-specific string.

Parameters

mb	CMPIBroker structure.

Returns

Name of the MB.

Full Description

CMPIBrokerFT.brokerName

Status for OpenPegasus:

TBD