CMPI Convenience Functions

Modules
	For MB Functions in Broker Function Tables
	For MB Functions of Encapsulated Data Types
	Helper Functions and Macros
	MI Factory Stubs

Detailed Description

The convenience functions in cmpimacs.h are a set of macros and inline functions that ease the use of the various CMPI function tables. They are provided to help the CMPI developer and are NOT required to be used. They do, however, make for cleaner and more readable code.

In CMPI 1.0, the CMPI convenience functions were defined as C preprocessor macros, which coined the term "CMPI macros".

Since CMPI 2.0, they are defined as C inline functions wherever possible. Only a small number of them is still defined as C preprocessor macros.

Since CMPI 2.1, those convenience functions that are defined as C inline functions can also be generated as C preprocessor macros, if the CMPI user defines the symbol CMPI_NO_INLINE.

The convenience functions are NOT documented in the CMPI Standard, just the existence of the cmpimacs.h header file. However, this online documentation documents the convenience functions and includes hyperlinks between the convenience functions and the underlying MB functions or other components of CMPI, in both directions.

The convenience functions follow the same rules for backwards compatibility as the other CMPI functions (see Subclause 1.7 in the CMPI Standard).

The convenience functions can be broken down into the following groups:

• Convenience functions for MB functions in broker function tables.

  The use of these convenience functions simplifies the code, largely by bypassing the added step of getting from the CMPIBroker structure to the right one of its function tables and to the corresponding MB function.

  These convenience functions have the same set of arguments as the corresponding MB functions. They have a simplified description of their functionality and arguments. For a full description, the linked description of the corresponding MB functions and arguments may need to be consulted.

  For example, the following MB function call:

  _broker->bft->attachThread(_broker, ctx);

  is simplified when using a convenience function to:

  CBAttachThread(_broker, ctx);

  For a list of those convenience functions, see MB Functions in Broker Function Tables.

• Convenience functions for MB functions of encapsulated data type objects.

  The use of these convenience functions simplifies the code, largely by bypassing the added step of getting from the encapsulated data type object to its function table and to the corresponding MB function.

  These convenience functions have the same set of arguments as the corresponding MB functions. They have a simplified description of their functionality and arguments. For a full description, the linked description of the corresponding MB functions and arguments may need to be consulted.

  For example, the following MB function call:

  inst->ft->getProperty(inst, name, rc);

  is simplified when using a convenience function to:

  CMGetProperty(inst, name, rc);

  For a list of those convenience functions, see MB Functions of Encapsulated Data Types.

• 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. Examples of this are CMReturn() and CMIsNullObject(). For details, see Helper Functions and Macros.

• MI Factory Stubs

  The MI factory stubs are macros that generate the MI factory functions and function tables. Examples of this are CMInstanceMIStub() and CMInstanceMIFactory(). For details, see MI Factory Stubs.