For MB Functions in Broker Function Tables

Modules
	CMFmtArgs<N>()
	Helper macros for message translation.
	CMFmt<type>()
	Helper macros for message translation.

Macros
#define	CMGetMessage(mb, msgId, defMsg, rc, args)
	Get a translated MB implementation-specific message text by message ID. (Deprecated) More...
#define	CMGetMessage2(mb, msgId, msgFileHandle, defMsg, rc, args)
	Get a translated message text from an open message file by message ID. More...

Functions
static CMPIContext *	CBPrepareAttachThread (const CMPIBroker *mb, const CMPIContext *ctx)
	Prepare the MB to accept a new thread that will be using MB functions. More...
static CMPIStatus	CBAttachThread (const CMPIBroker *mb, const CMPIContext *ctx)
	Inform the MB that the current thread will begin using MB functions. More...
static CMPIStatus	CBDetachThread (const CMPIBroker *mb, const CMPIContext *ctx)
	Inform the MB that the current thread will no longer use MB functions. More...
static CMPIStatus	CBDeliverIndication (const CMPIBroker *mb, const CMPIContext *ctx, const char *ns, const CMPIInstance *ind)
	Request delivery of an indication. More...
static CMPIEnumeration *	CBEnumInstanceNames (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *classPath, CMPIStatus *rc)
	Enumerate the instance paths of the instances of a given class (and its subclasses). More...
static CMPIEnumeration *	CBEnumInstances (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *classPath, const char **properties, CMPIStatus *rc)
	Enumerate the instances of a given class (and its subclasses). More...
static CMPIInstance *	CBGetInstance (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath, const char **properties, CMPIStatus *rc)
	Get an existing instance. More...
static CMPIObjectPath *	CBCreateInstance (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *classPath, const CMPIInstance *newInst, CMPIStatus *rc)
	Create an instance of a given class. More...
static CMPIStatus	CBModifyInstance (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath, const CMPIInstance *modInst, const char **properties)
	Modify property values of an existing instance. More...
static CMPIStatus	CBDeleteInstance (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath)
	Delete an existing instance. More...
static CMPIEnumeration *	CBExecQuery (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *classPath, const char *query, const char *lang, CMPIStatus *rc)
	Execute a query on a given class and return the query result. More...
static CMPIEnumeration *	CBAssociators (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath, const char *assocClass, const char *resultClass, const char *role, const char *resultRole, const char **properties, CMPIStatus *rc)
	Enumerate the instances associated with a given source instance. More...
static CMPIEnumeration *	CBAssociatorNames (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath, const char *assocClass, const char *resultClass, const char *role, const char *resultRole, CMPIStatus *rc)
	Enumerate the instance paths of the instances associated with a given source instance. More...
static CMPIEnumeration *	CBReferences (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath, const char *resultClass, const char *role, const char **properties, CMPIStatus *rc)
	Enumerate the association instances referencing a given source instance. More...
static CMPIEnumeration *	CBReferenceNames (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath, const char *resultClass, const char *role, CMPIStatus *rc)
	Enumerate the instance paths of the association instances referencing a given source instance. More...
static CMPIData	CBInvokeMethod (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *objPath, const char *method, const CMPIArgs *in, CMPIArgs *out, CMPIStatus *rc)
	Invoke a method on a target object. More...
static CMPIStatus	CBSetProperty (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath, const char *name, const CMPIValue *value, const CMPIType type)
	Set or modify a property of an existing instance. (Deprecated) More...
static CMPIData	CBGetProperty (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath, const char *name, CMPIStatus *rc)
	Get a property of an existing instance. (Deprecated) More...
static CMPIEnumeration *	CBEnumInstancesFiltered (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *classPath, const char **properties, const char *filterQueryLanguage, const char *filterQuery, CMPIStatus *rc)
	Enumerate the instances of a given class (and its subclasses), returning only those that match the given query filter. More...
static CMPIEnumeration *	CBAssociatorsFiltered (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath, const char *assocClass, const char *resultClass, const char *role, const char *resultRole, const char **properties, const char *filterQueryLanguage, const char *filterQuery, CMPIStatus *rc)
	Enumerate the instances associated with a given source instance, returning only those that match the given filters. More...
static CMPIEnumeration *	CBReferencesFiltered (const CMPIBroker *mb, const CMPIContext *ctx, const CMPIObjectPath *instPath, const char *resultClass, const char *role, const char **properties, const char *filterQueryLanguage, const char *filterQuery, CMPIStatus *rc)
	Enumerate the instances referencing a given source instance, returning only those that match the given filters. More...
static CMPIInstance *	CMNewInstance (const CMPIBroker *mb, const CMPIObjectPath *instPath, CMPIStatus *rc)
	Create a new CMPIInstance object initialized to a given instance path. More...
static CMPIObjectPath *	CMNewObjectPath (const CMPIBroker *mb, const char *ns, const char *cn, CMPIStatus *rc)
	Create a new CMPIObjectPath initialized to a given namespace and class name. More...
static CMPIArgs *	CMNewArgs (const CMPIBroker *mb, CMPIStatus *rc)
	Create a new CMPIArgs object initialized to have no method parameters. More...
static CMPIString *	CMNewString (const CMPIBroker *mb, const char *data, CMPIStatus *rc)
	Create a new CMPIString object initialized from a C-language string. More...
static CMPIArray *	CMNewArray (const CMPIBroker *mb, CMPICount size, CMPIType type, CMPIStatus *rc)
	Create a new CMPIArray object of a given size and type of elements. More...
static CMPIDateTime *	CMNewDateTime (const CMPIBroker *mb, CMPIStatus *rc)
	Create a new CMPIDataTime object to the current date and time. More...
static CMPIDateTime *	CMNewDateTimeFromBinary (const CMPIBroker *mb, CMPIUint64 binTime, CMPIBoolean interval, CMPIStatus *rc)
	Create a new CMPIDateTime object initialized to a specific value. More...
static CMPIDateTime *	CMNewDateTimeFromChars (const CMPIBroker *mb, const char *datetime, CMPIStatus *rc)
	Create a new CMPIDateTime object initialized to a specified value. More...
static CMPISelectExp *	CMNewSelectExp (const CMPIBroker *mb, const char *query, const char *lang, CMPIArray **projection, CMPIStatus *rc)
	Create a new CMPISelectExp object initialized from a select expression specified in a query language. More...
static CMPIError *	CMNewCMPIError (const CMPIBroker *mb, const char *owner, const char *msgID, const char *msg, const CMPIErrorSeverity sev, const CMPIErrorProbableCause pc, const CMPIrc cimStatusCode, CMPIStatus *rc)
	Create a new CMPIError object initialized with certain core attributes. More...
static CMPIPropertyList *	CMNewPropertyList (const CMPIBroker *mb, const char **properties, CMPIStatus *rc)
	Create a new CMPIPropertyList object initialized to a list of property names. More...
static CMPIString *	CMNewStringCP (const CMPIBroker *mb, const char *data, const CMPICodepageID cpid, CMPIStatus *rc)
	Create a new CMPIString object from a C-language string in a specific codepage. More...
static CMPIEnumerationFilter *	CMNewEnumerationFilter (const CMPIBroker *mb, const char *filterQueryLanguage, const char *filterQuery, CMPIStatus *rc)
	Create a new CMPIEnumerationFilter object initialized with a filter query. More...
static CMPIBoolean	CMClassPathIsA (const CMPIBroker *mb, const CMPIObjectPath *classPath, const char *className, CMPIStatus *rc)
	Test whether a class path is of a specified class or any of its subclasses. More...
static CMPIString *	CDToString (const CMPIBroker *mb, const void *object, CMPIStatus *rc)
	Convert an encapsulated data type object into a string representation. More...
static CMPIBoolean	CDIsOfType (const CMPIBroker *mb, const void *object, const char *type, CMPIStatus *rc)
	Test whether an encapsulated data type object is of a specified CMPI type. More...
static CMPIString *	CDGetType (const CMPIBroker *mb, const void *object, CMPIStatus *rc)
	Get the type name of an ensapsulated data type object. More...
static CMPIStatus	CMLogMessage (const CMPIBroker *mb, CMPISeverity severity, const char *id, const char *text, const CMPIString *string)
	Log a diagnostic message. More...
static CMPIStatus	CMTraceMessage (const CMPIBroker *mb, CMPILevel level, const char *component, const char *text, const CMPIString *string)
	Trace a diagnostic message with a specific trace level and component. More...
static CMPIStatus	CMOpenMessageFile (const CMPIBroker *mb, const char *msgFile, CMPIMsgFileHandle *msgFileHandle)
	Open a message file and return a handle to the file. More...
static CMPIStatus	CMCloseMessageFile (const CMPIBroker *mb, const CMPIMsgFileHandle msgFileHandle)
	Close a message file. More...
static CMPIGcStat *	CMMemMark (const CMPIBroker *mb, CMPIStatus *rc)
	Mark a new object lifecycle level for subsequent newly created CMPI encapsulated data type objects. More...
static CMPIStatus	CMMemRelease (const CMPIBroker *mb, const CMPIGcStat *gc)
	Release all CMPI encapsulated data type objects created at the specified object lifecycle level, and remove that level. More...
static void *	CMMalloc (const CMPIBroker *mb, size_t size)
	Allocate an uninitalized memory block of the specified size. More...
static void *	CMCalloc (const CMPIBroker *mb, size_t nElems, size_t sizeElem)
	Allocate a memory block of the specified size and initialize it to zero. More...
static void *	CMRealloc (const CMPIBroker *mb, void *ptr, size_t size)
	Change the size of a memory block. More...
static void *	CMStrDup (const CMPIBroker *mb, const char *str)
	Allocate a memory block and initialize it with a string. More...
static void	CMFree (const CMPIBroker *mb, void *ptr)
	Release a memory block. More...
static void	CMFreeInstance (const CMPIBroker *mb, CMPIInstance *inst)
	Release a CMPIInstance object. More...
static void	CMFreeObjectPath (const CMPIBroker *mb, CMPIObjectPath *obj)
	Release a CMPIObjectPath object. More...
static void	CMFreeArgs (const CMPIBroker *mb, CMPIArgs *args)
	Release a CMPIArgs object. More...
static void	CMFreeString (const CMPIBroker *mb, CMPIString *str)
	Release a CMPIString object. More...
static void	CMFreeArray (const CMPIBroker *mb, CMPIArray *array)
	Release a CMPIArray object. More...
static void	CMFreeDateTime (const CMPIBroker *mb, CMPIDateTime *dt)
	Release a CMPIDateTime object. More...
static void	CMFreeSelectExp (const CMPIBroker *mb, CMPISelectExp *se)
	Release a CMPISelectExp object. More...
static void	CMFreeChars (const CMPIBroker *mb, char *chars)
	Free the memory of a C-language string. More...

Detailed Description

MB Functions in Broker Function Tables.

The convenience functions in this group call MB functions provided by the broker function tables (that is, the function tables pointed to by CMPIBroker members).

They simplify the code by eliminating the references to function tables, and by eliminating the need to know which of the function tables has the desired function.

Macro Definition Documentation

#define CMGetMessage	(		mb,
			msgId,
			defMsg,
			rc,
			args
	)

Get a translated MB implementation-specific message text by message ID. (Deprecated)

Parameters

	mb	CMPIBroker structure.
	msgId	Message ID that is used by the MB to locate a message template. The message ID values and corresponding message templates are MB implementation-specific.
	defMsg	The default message. See the full description for details.
[out]	rc	Function return status (suppressed when NULL).
	args	The message insert values, specified as CMFmtArgs<N>(<vlist>), where <N> is the number of values, and <vlist> is a comma-separated list of CMFmt<type>(<v>) macros.

Returns

Points to a CMPIString object representing the translated message.

Full Description

CMPIBrokerEncFT.getMessage()

Examples

Assuming the message identified by the message ID is the same as the default message "Test $0 $1", the following example creates a message "Test message 42" where "message" is passed as a C string for the first message trigger ($0), and "42" is passed as an integer for the second message trigger ($1):

 (.c)
CMGetMessage(_broker, "msgid", "Test $0 $1",
    NULL, CMFmtArgs2(CMFmtChars("message"), CMFmtSint(42)));

Deprecated:

This function is deprecated since CMPI 2.1. Use CMGetMessage2() instead.

Status for OpenPegasus:

TBD

#define CMGetMessage2	(		mb,
			msgId,
			msgFileHandle,
			defMsg,
			rc,
			args
	)

Get a translated message text from an open message file by message ID.

Parameters

	mb	CMPIBroker structure.
	msgId	The message identifier.
	msgFileHandle	The handle representing the open message file.
	defMsg	The default message. See the full description for details.
[out]	rc	Function return status (suppressed when NULL).
	args	The message insert values, specified as CMFmtArgs<N>(<vlist>), where <N> is the number of values, and <vlist> is a comma-separated list of CMFmt<type>(<v>) macros.

Returns

Points to a CMPIString object representing the translated message.

Full Description

CMPIBrokerEncFT.getMessage2()

Examples

Assuming the message identified by the message ID is the same as the default message "Test $0 $1", the following example creates a message "Test message 42" where "message" is passed as a C string for the first message trigger ($0), and "42" is passed as an integer for the second message trigger ($1):

 (.c)
CMGetMessage2(_broker, "msgid", msgFileHandle, "Test $0 $1",
    NULL, CMFmtArgs2(CMFmtChars("message"), CMFmtSint(42)));

Addition:

Added in CMPI 2.0.

Status for OpenPegasus:

Tested in cmpiTestBrokerEncProvider.c

Function Documentation

static CMPIContext* CBPrepareAttachThread ( const CMPIBroker *  mb, const CMPIContext *  ctx  )

inlinestatic

Prepare the MB to accept a new thread that will be using MB functions.

This function is expected to be called in the existing thread.

Parameters

mb	CMPIBroker structure.
ctx	CMPIContext object.

Returns

CMPIContext object that is to be used by the thread to be attached.

Full Description

CMPIBrokerFT.prepareAttachThread()

Status for OpenPegasus:

TBD

static CMPIStatus CBAttachThread ( const CMPIBroker *  mb, const CMPIContext *  ctx  )

inlinestatic

Inform the MB that the current thread will begin using MB functions.

Parameters

mb	CMPIBroker structure.
ctx	CMPIContext object that was returned by a prior call to CBPrepareAttachThread().

Returns

Function return status.

Full Description

CMPIBrokerFT.attachThread()

Status for OpenPegasus:

TBD

static CMPIStatus CBDetachThread ( const CMPIBroker *  mb, const CMPIContext *  ctx  )

inlinestatic

Inform the MB that the current thread will no longer use MB functions.

Parameters

mb	CMPIBroker structure.
ctx	CMPIContext object that was returned by a prior call to CBPrepareAttachThread().

Returns

Function return status.

Full Description

CMPIBrokerFT.detachThread()

Status for OpenPegasus:

TBD

static CMPIStatus CBDeliverIndication ( const CMPIBroker *  mb, const CMPIContext *  ctx, const char *  ns, const CMPIInstance *  ind  )

inlinestatic

Request delivery of an indication.

Parameters

mb	CMPIBroker structure.
ctx	CMPIContext object.
ns	Name of the origin namespace of the indication (see DSP1054 for a definition).
ind	The indication instance.

Returns

Function return status.

Full Description

CMPIBrokerFT.deliverIndication()

Status for OpenPegasus:

TBD

static CMPIEnumeration* CBEnumInstanceNames ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  classPath, CMPIStatus *  rc  )

inlinestatic

Enumerate the instance paths of the instances of a given class (and its subclasses).

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	classPath	Class path of the given class.
[out]	rc	Function return status (suppressed when NULL).

Returns

A new CMPIEnumeration object containing CMPIObjectPath objects that represent the enumerated instance paths.

Full Description

CMPIBrokerFT.enumerateInstanceNames()

Status for OpenPegasus:

TBD

static CMPIEnumeration* CBEnumInstances ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  classPath, const char **  properties, CMPIStatus *  rc  )

inlinestatic

Enumerate the instances of a given class (and its subclasses).

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	classPath	Class path of the given class.
	properties	Property list controlling the properties in the returned instances: Each returned instance will not include properties missing from this list. If @ properties is NULL, all properties will be included in each returned instance.
[out]	rc	Function return status (suppressed when NULL).

Returns

A new CMPIEnumeration object containing CMPIInstance objects that represent the enumerated instances.

Full Description

CMPIBrokerFT.enumerateInstances()

Status for OpenPegasus:

Not used, not tested

static CMPIInstance* CBGetInstance ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath, const char **  properties, CMPIStatus *  rc  )

inlinestatic

Get an existing instance.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	instPath	Instance path of the instance to be retrieved.
	properties	Property list controlling the properties in the returned instances: Each returned instance will not include properties missing from this list. If @ properties is NULL, all properties will be included in each returned instance.
[out]	rc	Function return status (suppressed when NULL).

Returns

The instance.

Full Description

CMPIBrokerFT.getInstance()

Status for OpenPegasus:

TBD

static CMPIObjectPath* CBCreateInstance ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  classPath, const CMPIInstance *  newInst, CMPIStatus *  rc  )

inlinestatic

Create an instance of a given class.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	classPath	Class path of the creation class for the new instance.
	newInst	Property values for the new instance.
[out]	rc	Function return status (suppressed when NULL).

Returns

Instance path of the new instance.

Full Description

CMPIBrokerFT.createInstance()

Status for OpenPegasus:

TBD

static CMPIStatus CBModifyInstance ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath, const CMPIInstance *  modInst, const char **  properties  )

inlinestatic

Modify property values of an existing instance.

Parameters

mb	CMPIBroker structure.
ctx	CMPIContext object.
instPath	Instance path of the instance to be modified.
modInst	New property values for the instance to be modified.
properties	The names of the properties to be modified. If NULL, all properties will be modified.

Returns

Function return status.

Full Description

CMPIBrokerFT.modifyInstance()

Status for OpenPegasus:

TBD

static CMPIStatus CBDeleteInstance ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath  )

inlinestatic

Delete an existing instance.

Parameters

mb	CMPIBroker structure.
ctx	CMPIContext object.
instPath	Instance path of the instance to be deleted.

Returns

Function return status.

Full Description

CMPIBrokerFT.deleteInstance()

Status for OpenPegasus:

TBD

static CMPIEnumeration* CBExecQuery ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  classPath, const char *  query, const char *  lang, CMPIStatus *  rc  )

inlinestatic

Execute a query on a given class and return the query result.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	classPath	Class path of the class to be queried.
	query	Select expression.
	lang	Query language.
[out]	rc	Function return status (suppressed when NULL).

Returns

A new CMPIEnumeration object containing CMPIInstance objects that represent the query result.

Full Description

CMPIBrokerFT.execQuery()

Status for OpenPegasus:

TBD

static CMPIEnumeration* CBAssociators ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath, const char *  assocClass, const char *  resultClass, const char *  role, const char *  resultRole, const char **  properties, CMPIStatus *  rc  )

inlinestatic

Enumerate the instances associated with a given source instance.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	instPath	Instance path of the given source instance.
	assocClass	If not NULL, a valid association class name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an instance of this class or one of its subclasses.
	resultClass	If not NULL, a valid class name that acts as a filter on the returned set of instances by mandating that each returned instance shall be either an instance of this class or one of its subclasses.
	role	If not NULL, a valid property name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an association in which the source instance plays the specified role.
	resultRole	If not NULL, a valid property name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an association in which the returned instance plays the specified role.
	properties	Property list controlling the properties in the returned instances: Each returned instance will not include properties missing from this list. If @ properties is NULL, all properties will be included in each returned instance.
[out]	rc	Function return status (suppressed when NULL).

Returns

A new CMPIEnumeration object containing CMPIInstance objects that represent the enumerated instances.

Full Description

CMPIBrokerFT.associators()

Status for OpenPegasus:

TBD

static CMPIEnumeration* CBAssociatorNames ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath, const char *  assocClass, const char *  resultClass, const char *  role, const char *  resultRole, CMPIStatus *  rc  )

inlinestatic

Enumerate the instance paths of the instances associated with a given source instance.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	instPath	Instance path of the given source instance.
	assocClass	If not NULL, a valid association class name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an instance of this class or one of its subclasses.
	resultClass	If not NULL, a valid class name that acts as a filter on the returned set of instances by mandating that each returned instance shall be either an instance of this class or one of its subclasses.
	role	If not NULL, a valid property name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an association in which the source instance plays the specified role.
	resultRole	If not NULL, a valid property name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an association in which the returned instance plays the specified role.
[out]	rc	Function return status (suppressed when NULL).

Returns

A new CMPIEnumeration object containing CMPIObjectPath objects that represent the enumerated instance paths.

Full Description

CMPIBrokerFT.associatorNames()

Status for OpenPegasus:

TBD

static CMPIEnumeration* CBReferences ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath, const char *  resultClass, const char *  role, const char **  properties, CMPIStatus *  rc  )

inlinestatic

Enumerate the association instances referencing a given source instance.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	instPath	Instance path of the given source instance.
	resultClass	If not NULL, a valid class name that acts as a filter on the returned set of instances by mandating that each returned instance shall be either an instance of this class or one of its subclasses.
	role	If not NULL, a valid property name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an association in which the source instance plays the specified role.
	properties	Property list controlling the properties in the returned instances: Each returned instance will not include properties missing from this list. If @ properties is NULL, all properties will be included in each returned instance.
[out]	rc	Function return status (suppressed when NULL).

Returns

A new CMPIEnumeration object containing CMPIInstance objects that represent the enumerated instances.

Full Description

CMPIBrokerFT.references()

Status for OpenPegasus:

TBD

static CMPIEnumeration* CBReferenceNames ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath, const char *  resultClass, const char *  role, CMPIStatus *  rc  )

inlinestatic

Enumerate the instance paths of the association instances referencing a given source instance.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	instPath	Instance path of the given source instance.
	resultClass	If not NULL, a valid class name that acts as a filter on the returned set of instances by mandating that each returned instance shall be either an instance of this class or one of its subclasses.
	role	If not NULL, a valid property name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an association in which the source instance plays the specified role.
[out]	rc	Function return status (suppressed when NULL).

Returns

A new CMPIEnumeration object containing CMPIObjectPath objects that represent the enumerated instance paths.

Full Description

CMPIBrokerFT.referenceNames()

Status for OpenPegasus:

TBD

static CMPIData CBInvokeMethod ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  objPath, const char *  method, const CMPIArgs *  in, CMPIArgs *  out, CMPIStatus *  rc  )

inlinestatic

Invoke a method on a target object.

Instance methods (i.e., non-static methods) can be invoked only on instances. Class methods (i.e., static methods) can be invoked on instances and classes.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	objPath	Object path of the target object.
	method	Method name.
	in	A CMPIArgs object containing the method input parameters.
[out]	out	An empty CMPIArgs object that, upon successful return of the method, will have been updated to contain the method output parameters.
[out]	rc	Function return status (suppressed when NULL).

Returns

The method return value and type.

Full Description

CMPIBrokerFT.invokeMethod()

Examples

The example invokes static method "TestCMPIError" on class "TestCMPI_BrokerInstance" in namespace "test/TestProvider", and tests for success and correct data type of the method return value.

 (.c)
const CMPIArgs *in;
CMPIArgs *out
CMPIObjectPath *objPath;
CMPIData retData;
// define input arguments here

objPath = CMNewObjectPath(_broker, "test/TestProvider",
    "TestCMPI_BrokerInstance", &rc);

retData = CBInvokeMethod(_broker, ctx, objPath, "TestCMPIError",
    in, out, &rc);
    PROV_LOG_OPEN (_ClassName, _ProviderLocation);

// test to confirm return date data type and return status
if (!retData.value.uint32 && rc.rc != CMPI_RC_OK)
{
    // execute error function
}
// clean up and use retData
rc = CMRelease(objPath);

Status for OpenPegasus:

TBD

Todo:

TODO_KS AM: I think the CMRelease() is incorrect, because the object is not a result of CMClone().
Karl to verify whether the using release() on objects resulting from newXXX() does any harm in the OpenPegasus implementation.

static CMPIStatus CBSetProperty ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath, const char *  name, const CMPIValue *  value, const CMPIType  type  )

inlinestatic

Set or modify a property of an existing instance. (Deprecated)

Parameters

mb	CMPIBroker structure.
ctx	CMPIContext object.
instPath	Instance path of the instance to be modified.
name	Property name.
value	CMPIValue structure containing the non-NULL value to be assigned to the property, or NULL to specify that NULL is to be assigned.
type	Type of the value to be assigned.

Returns

Function return status.

Full Description

CMPIBrokerFT.setProperty()

Deprecated:

This function is deprecated since CMPI 2.1, in accord with the deprecation of property client operations in DMTF specifications.

Note

No example because this function is deprecated.

Status for OpenPegasus:

TBD

static CMPIData CBGetProperty ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath, const char *  name, CMPIStatus *  rc  )

inlinestatic

Get a property of an existing instance. (Deprecated)

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	instPath	Instance path of the instance to be retrieved.
	name	Property name.
[out]	rc	Function return status (suppressed when NULL).

Returns

Property value and type.

Full Description

CMPIBrokerFT.setProperty()

Deprecated:

This function is deprecated since CMPI 2.1, in accord with the deprecation of property client operations in DMTF specifications.

Note

No example because this function is deprecated.

Status for OpenPegasus:

TBD

static CMPIEnumeration* CBEnumInstancesFiltered ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  classPath, const char **  properties, const char *  filterQueryLanguage, const char *  filterQuery, CMPIStatus *  rc  )

inlinestatic

Enumerate the instances of a given class (and its subclasses), returning only those that match the given query filter.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	classPath	Class path of the given class.
	properties	Property list controlling the properties in the returned instances: Each returned instance will not include properties missing from this list. If @ properties is NULL, all properties will be included in each returned instance.
	filterQueryLanguage	Query language used by filterQuery (no filtering when NULL).
	filterQuery	Query for filtering the result (no filtering when NULL).
[out]	rc	Function return status (suppressed when NULL).

Returns

A new CMPIEnumeration object containing CMPIInstance objects that represent the enumerated instances.

Full Description

CMPIBrokerFT.enumerateInstancesFiltered()

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used, not tested

static CMPIEnumeration* CBAssociatorsFiltered ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath, const char *  assocClass, const char *  resultClass, const char *  role, const char *  resultRole, const char **  properties, const char *  filterQueryLanguage, const char *  filterQuery, CMPIStatus *  rc  )

inlinestatic

Enumerate the instances associated with a given source instance, returning only those that match the given filters.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	instPath	Instance path of the given source instance.
	assocClass	If not NULL, a valid association class name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an instance of this class or one of its subclasses.
	resultClass	If not NULL, a valid class name that acts as a filter on the returned set of instances by mandating that each returned instance shall be either an instance of this class or one of its subclasses.
	role	If not NULL, a valid property name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an association in which the source instance plays the specified role.
	resultRole	If not NULL, a valid property name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an association in which the returned instance plays the specified role.
	properties	Property list controlling the properties in the returned instances: Each returned instance will not include properties missing from this list. If @ properties is NULL, all properties will be included in each returned instance.
	filterQueryLanguage	Query language used by filterQuery (no filtering when NULL).
	filterQuery	Query for filtering the result (no filtering when NULL).
[out]	rc	Function return status (suppressed when NULL).

Returns

A new CMPIEnumeration object containing CMPIInstance objects that represent the enumerated instances.

Full Description

CMPIBrokerFT.associatorsFiltered()

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

TBD

static CMPIEnumeration* CBReferencesFiltered ( const CMPIBroker *  mb, const CMPIContext *  ctx, const CMPIObjectPath *  instPath, const char *  resultClass, const char *  role, const char **  properties, const char *  filterQueryLanguage, const char *  filterQuery, CMPIStatus *  rc  )

inlinestatic

Enumerate the instances referencing a given source instance, returning only those that match the given filters.

Parameters

	mb	CMPIBroker structure.
	ctx	CMPIContext object.
	instPath	Instance path of the given source instance.
	resultClass	If not NULL, a valid class name that acts as a filter on the returned set of instances by mandating that each returned instance shall be either an instance of this class or one of its subclasses.
	role	If not NULL, a valid property name that acts as a filter on the returned set of instances by mandating that each returned instance shall be associated to the source instance via an association in which the source instance plays the specified role.
	properties	Property list controlling the properties in the returned instances: Each returned instance will not include properties missing from this list. If @ properties is NULL, all properties will be included in each returned instance.
	filterQueryLanguage	Query language used by filterQuery (no filtering when NULL).
	filterQuery	Query for filtering the result (no filtering when NULL).
[out]	rc	Function return status (suppressed when NULL).

Returns

A new CMPIEnumeration object containing CMPIInstance objects that represent the enumerated instances.

Full Description

CMPIBrokerFT.referencesFiltered()

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

TBD

static CMPIInstance* CMNewInstance ( const CMPIBroker *  mb, const CMPIObjectPath *  instPath, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIInstance object initialized to a given instance path.

Parameters

	mb	CMPIBroker structure.
	instPath	The class path or instance path for the new CMPIInstance object.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIInstance object.

Full Description

CMPIBrokerEncFT.newInstance()

Examples

 (.c)
CMPIStatus testProvEnumInstances (CMPIInstanceMI *cThis,
    const CMPIContext *ctx, const CMPIResult *rslt,
    const CMPIObjectPath *ref, const char **properties)
{
    int i;
    CMPIStatus rc;
    CMPIObjectPath *cop;
    CMPIInstance *inst;

    cop = CMNewObjectPath(
              broker,
              CMGetCharsPtr(CMGetNameSpace(ref, &rc), NULL),
              CMGetCharsPtr(CMGetClassName (ref, &rc),NULL),
              &rc);
    for (i = 0; i < dataNext; i++)
    {
        CMAddKey (cop, "Identifier", &store[i].key, CMPI_string);
        inst = CMNewInstance (broker, cop, &rc);
        CMSetProperty (inst, "Identifier", &store[i].key, CMPI_string);
        CMSetProperty (inst, "data", &store[i].data, CMPI_string);
        CMReturnInstance (rslt, inst);
    }
    CMReturnDone (rslt);
    CMReturn (CMPI_RC_OK);
}

Status for OpenPegasus:

TBD

Todo:

TODO_KS AM: Example is too complex for this function. Simplify.

static CMPIObjectPath* CMNewObjectPath ( const CMPIBroker *  mb, const char *  ns, const char *  cn, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIObjectPath initialized to a given namespace and class name.

Parameters

	mb	CMPIBroker structure.
	ns	Namespace name.
	cn	Class name.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIObjectPath object.

Full Description

CMPIBrokerEncFT.newObjectPath()

Examples

 (.c)
const char* class = "myClass";
CMPIObjectPath *objPath = NULL;
CMPIStatus rc = { CMPI_RC_OK, NULL };
objPath = CMNewObjectPath (broker, ns, class, &rc);
assert ( rc.rc == CMPI_RC_OK);
CMAddKey (objPath, "ElementName", (CMPIValue *) class, CMPI_chars);

Status for OpenPegasus:

TBD

static CMPIArgs* CMNewArgs ( const CMPIBroker *  mb, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIArgs object initialized to have no method parameters.

Parameters

	mb	CMPIBroker structure.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIArgs object.

Full Description

CMPIBrokerEncFT.newArgs()

Examples

 (.c)
CMPIArgs *args_ptr = NULL;
CMPIStatus rc = { CMPI_RC_OK, NULL };
args_ptr = CMNewArgs(_broker, &rc);

Status for OpenPegasus:

TBD

static CMPIString* CMNewString ( const CMPIBroker *  mb, const char *  data, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIString object initialized from a C-language string.

Parameters

	mb	CMPIBroker structure.
	data	C-language string.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIString object.

Full Description

CMPIBrokerEncFT.newString()

Examples

 (.c)
CMPIStatus rc;
CMPIString *cmpiStr1;
CMPIString *cmpiStr2;
cmpiStr1 = CMNewString(_broker, NULL, &rc);
// test rc for OK
cmpiStr2 = CMNewString(_broker, "Tracing for level 5", &rc);
// test rc for OK

Status for OpenPegasus:

TBD

Todo:

TODO_KS AM: Clarify whether NULL is allowed as data argument. The example in the convenience function specifies NULL, but the 2.1 and 2.0 specs are silent about whether NULL is allowed.
Karl to double check in the implementation.

static CMPIArray* CMNewArray ( const CMPIBroker *  mb, CMPICount  size, CMPIType  type, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIArray object of a given size and type of elements.

Parameters

	mb	CMPIBroker structure.
	size	Size of the array. A value of 0 is valid and specifies an empty array.
	type	Type of each array element.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIArray object.

Full Description

CMPIBrokerEncFT.newArray()

Status for OpenPegasus:

Tested in cmpiTestMethodProvider.c

static CMPIDateTime* CMNewDateTime ( const CMPIBroker *  mb, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIDataTime object to the current date and time.

Parameters

	mb	CMPIBroker structure.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIDateTime object.

Full Description

CMPIBrokerEncFT.newDateTime()

Status for OpenPegasus:

TBD

static CMPIDateTime* CMNewDateTimeFromBinary ( const CMPIBroker *  mb, CMPIUint64  binTime, CMPIBoolean  interval, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIDateTime object initialized to a specific value.

CMNewDateTimeFromBinary() executes CMPIBrokerEncFT.newDateTimeFromBinary() to create a new CMPIDateTime object initialized from binTime.

Parameters

	mb	CMPIBroker structure.
	binTime	When interval is false, a point in time value expressed as a 64-bit unsigned integer in microseconds since 00:00:00 GMT, January 1, 1970. Otherwise, a time interval expressed as a 64-bit unsigned integer in microseconds.
	interval	If true, indicates that binTime is considered to be a time interval.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIDateTime object.

Full Description

CMPIBrokerEncFT.newDateTimeFromBinary()

Status for OpenPegasus:

TBD

static CMPIDateTime* CMNewDateTimeFromChars ( const CMPIBroker *  mb, const char *  datetime, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIDateTime object initialized to a specified value.

Parameters

	mb	CMPIBroker structure.
	datetime	Date/time value to be used for the new object in the string format for CIM datetime values defined in DSP0004. Both the interval and point in time formats are supported.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIDateTime object.

Full Description

CMPIBrokerEncFT.newDateTimeFromChars()

Status for OpenPegasus:

TBD

static CMPISelectExp* CMNewSelectExp ( const CMPIBroker *  mb, const char *  query, const char *  lang, CMPIArray **  projection, CMPIStatus *  rc  )

inlinestatic

Create a new CMPISelectExp object initialized from a select expression specified in a query language.

Parameters

	mb	CMPIBroker structure.
	query	Select expression.
	lang	Query language.
[out]	projection	A new CMPIArray object of CMPIString entries containing the projection specification.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPISelectExp object.

Full Description

CMPIBrokerEncFT.newSelectExp()

Status for OpenPegasus:

TBD

static CMPIError* CMNewCMPIError ( const CMPIBroker *  mb, const char *  owner, const char *  msgID, const char *  msg, const CMPIErrorSeverity  sev, const CMPIErrorProbableCause  pc, const CMPIrc  cimStatusCode, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIError object initialized with certain core attributes.

Parameters

	mb	CMPIBroker structure.
	owner	Value for the OwningEntity attribute of the CMPIError object. For a description of the OwningEntity attribute, see the description of the OwningEntity property in the CIM_Error class in the CIM Schema. If the error message is defined in a DMTF message registry, the string value of owner shall be the content of the OWNING_ENTITY element defined for the registry.
	msgID	Value for the MessageID attribute of the CMPIError object. For a description of the MessageID attribute, see the description of the MessageID property in the CIM_Error class in the CIM Schema. If the error message is defined in a DMTF message registry, the string value of msgID shall be the message ID defined for the message in the registry (the concatenation of the values of the PREFIX and SEQUENCE_NUMBER attributes of the MESSAGE_ID element for the message).
	msg	Value for the Message attribute of the CMPIError object. For a description of the Message attribute, see the description of the Message property in the CIM_Error class in the CIM Schema. This message is the formatted and translated message, with any dynamic values expanded.
	sev	Value for the PerceivedSeverity attribute of the CMPIError object. For a description of the PerceivedSeverity attribute, see the description of the PerceivedSeverity property in the CIM_Error class in the CIM Schema. If the error message is defined in a DMTF message registry, the string value of sev shall be the content of the PERCEIVED_SEVERITY element defined for the message in the registry.
	pc	value for the ProbableCause attribute of the CMPIError object. For a description of the ProbableCause attribute, see the description of the ProbableCause property in the CIM_Error class in the CIM Schema. If the error message is defined in a DMTF message registry, note that the string value of pc is not defined in the message in the registry.
	cimStatusCode	Value for the CIMStatusCode attribute of the CMPIError object. For a description of the CIMStatusCode attribute, see the description of the CIMStatusCode property in the CIM_Error class in the CIM Schema. Not all status codes are valid for each operation. The specification for each MI function defines the status codes that may be returned. If the error message is defined in a DMTF message registry, cimStatusCode shall reflect the content of the CIMSTATUSCODE element defined for the message in the registry.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIError object.

Full Description

CMPIBrokerEncFT.newCMPIError()

Examples

 (.c)
cmpiError = CMNewCMPIError(_broker, inOwningEntity, inMsgID, inMsg,
                inSev, inPc, inCIMStatusCode, &rc);

Addition:

Added in CMPI 2.0.

Status for OpenPegasus:

Tested in TestCMPIErrorProvider.c

static CMPIPropertyList* CMNewPropertyList ( const CMPIBroker *  mb, const char **  properties, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIPropertyList object initialized to a list of property names.

Parameters

	mb	CMPIBroker structure.
	properties	The property names in the property list, in any order and in any lexical case.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIPropertyList object.

Full Description

CMPIBrokerEncFT.newPropertyList()

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

TBD

static CMPIString* CMNewStringCP ( const CMPIBroker *  mb, const char *  data, const CMPICodepageID  cpid, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIString object from a C-language string in a specific codepage.

Parameters

	mb	CMPIBroker structure.
	data	C-language string represented in the codepage specified in cpid. data is used to initialize the new CMPIString object after converting it from its codepage to UTF-8.
	cpid	CMPI-specific codepage ID for the codepage that is used to interpret the Bytes in the data argument. See CMPICodepageID for a list of supported codepages and their codepage ID values.
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIString object.

Full Description

CMPIBrokerEncFT.newStringCP()

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

TBD

static CMPIEnumerationFilter* CMNewEnumerationFilter ( const CMPIBroker *  mb, const char *  filterQueryLanguage, const char *  filterQuery, CMPIStatus *  rc  )

inlinestatic

Create a new CMPIEnumerationFilter object initialized with a filter query.

Parameters

	mb	CMPIBroker structure.
	filterQueryLanguage	Query language used by filterQuery (no filtering when NULL).
	filterQuery	Filter query (no filtering when NULL).
[out]	rc	Function return status (suppressed when NULL).

Returns

The new CMPIEnumerationFilter object.

Full Description

CMPIBrokerEncFT.newEnumerationFilter()

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

TBD

static CMPIBoolean CMClassPathIsA ( const CMPIBroker *  mb, const CMPIObjectPath *  classPath, const char *  className, CMPIStatus *  rc  )

inlinestatic

Test whether a class path is of a specified class or any of its subclasses.

Parameters

	mb	CMPIBroker structure.
	classPath	Class path that is being tested.
	className	Class name to be tested for.
[out]	rc	Function return status (suppressed when NULL).

Return values

true	The class path is of the specified class or any of that class's subclasses.
false	The class path is not of the specified class nor any of that class's subclasses.

Full Description

CMPIBrokerEncFT.classPathIsA()

Status for OpenPegasus:

Not tested

static CMPIString* CDToString ( const CMPIBroker *  mb, const void *  object, CMPIStatus *  rc  )

inlinestatic

Convert an encapsulated data type object into a string representation.

Parameters

	mb	CMPIBroker structure.
	object	Encapsulated data type object.
[out]	rc	Function return status (suppressed when NULL).

Returns

MB implementation-specific string representation of the encapsulated data type object.

Full Description

CMPIBrokerEncFT.toString()

Status for OpenPegasus:

TBD

static CMPIBoolean CDIsOfType ( const CMPIBroker *  mb, const void *  object, const char *  type, CMPIStatus *  rc  )

inlinestatic

Test whether an encapsulated data type object is of a specified CMPI type.

Parameters

	mb	CMPIBroker structure.
	object	Encapsulated data type object.
	type	Type name of the encapsulated data type to be tested for (e.g., "CMPIInstance").
[out]	rc	Function return status (suppressed when NULL).

Return values

true	The object is of the specified CMPI type.
false	The object is not of the specified CMPI type.

Full Description

CMPIBrokerEncFT.isOfType()

Examples

 (.c)
CMPIStatus rc = { CMPI_RC_OK, NULL };
CMPIBoolean isOfType = 0;
CMInstance* inst = CMNewInstance(_broker, . . .);
isOfType = CDIsOfType (_broker, inst, "CMPIInstance", &rc);
assert(isOfType);

Status for OpenPegasus:

Tested

static CMPIString* CDGetType ( const CMPIBroker *  mb, const void *  object, CMPIStatus *  rc  )

inlinestatic

Get the type name of an ensapsulated data type object.

Parameters

	mb	CMPIBroker structure.
	object	Encapsulated data type object.
[out]	rc	Function return status (suppressed when NULL).

Returns

Type name of the encapsulated data type (e.g., "CMPIInstance").

Full Description

CMPIBrokerEncFT.getType()

Status for OpenPegasus:

TBD

static CMPIStatus CMLogMessage ( const CMPIBroker *  mb, CMPISeverity  severity, const char *  id, const char *  text, const CMPIString *  string  )

inlinestatic

Log a diagnostic message.

Parameters

mb	CMPIBroker structure.
severity	Severity of the log message. Severity levels are defined in CMPISeverity.
id	If not NULL, message ID or any other identifying string.
text	If not NULL, message text to be logged.
string	If not NULL, message text to be logged. string will be ignored when text is not NULL.

Returns

Function return status.

Examples

 (.c)
CMLogMessage(_broker, 1, "TestProvider",
             "Entering EnumerateInstance", NULL);

Full Description

CMPIBrokerEncFT.logMessage()

Change:

In CMPI 2.1, fixed inconsistencies in presence and definition of severity by changing its type from int to CMPISeverity. This is a compatible change for MIs.

Status for OpenPegasus:

Tested in cmpiTestMethodProvider.c

static CMPIStatus CMTraceMessage ( const CMPIBroker *  mb, CMPILevel  level, const char *  component, const char *  text, const CMPIString *  string  )

inlinestatic

Trace a diagnostic message with a specific trace level and component.

Parameters

mb	CMPIBroker structure.
level	Trace level of the message. Trace levels are defined in CMPILevel.
component	If not NULL, MI implementation-specific component ID.
text	If not NULL, message text to be traced.
string	If not NULL, message text to be traced. string will be ignored when text is not NULL.

Returns

Function return status.

Full Description

CMPIBrokerEncFT.trace()

Examples

 (.c)
CMPIStatus rc = { CMPI_RC_OK, NULL };
CMPIString *str = CMNewString(_broker, "CMTraceMessage", &rc);
rc = CMTraceMessage(_broker, 4, "Authorization", NULL, str);

Change:

In CMPI 2.1, fixed inconsistencies in presence and definition of level by changing its type from int to CMPILevel. This is a compatible change for MIs.

Status for OpenPegasus:

Tested in cmpiTestMethodProvider.c

static CMPIStatus CMOpenMessageFile ( const CMPIBroker *  mb, const char *  msgFile, CMPIMsgFileHandle *  msgFileHandle  )

inlinestatic

Open a message file and return a handle to the file.

Depends on whether the MB supports the MessageTranslation" capability.

Parameters

	mb	CMPIBroker structure.
	msgFile	Implementation-specific file path to the message file, or a part thereof.
[out]	msgFileHandle	Handle representing the open message file.

Returns

Function return status

Full Description

CMPIBrokerEncFT.openMessageFile()

Examples

 (.c)
CMOpenMessageFile(_broker, "/path/msgFile", &msgFileHandle);

Addition:

Added in CMPI 2.0.

Status for OpenPegasus:

Used

static CMPIStatus CMCloseMessageFile ( const CMPIBroker *  mb, const CMPIMsgFileHandle  msgFileHandle  )

inlinestatic

Close a message file.

Parameters

mb	CMPIBroker structure.
msgFileHandle	Handle representing the open message file.

Returns

Function return status.

Full Description

CMPIBrokerEncFT.closeMessageFile()

Examples

 (.c)
CMPIString *msg;
rc = CMOpenMessageFile(_broker, path, &msgFileHandle);
msg = CMGetMessage2 (_broker,
    "Common.CIMStatusCode.CIM_ERR_SUCCESS",
    msgFileHandle,
    "Test $0 $1, $2, $3, $4, $5, $6, $7, $8",
    &rc,
    CMFmtArgs9(CMFmtChars("Sint32, Uint32, Sint64, Uint64, Real64,"
        " Boolean, chars, String :: "), CMFmtSint(-1),
        CMFmtUint(1), CMFmtSint64(-64), CMFmtUint64(64),
        CMFmtReal(64.64), CMFmtBoolean(1),
        CMFmtChars("chars"), CMFmtString(cmpiStr)));
// . . . do something with msg
rc = CMCloseMessageFile(_broker, msgFileHandle);

Addition:

Added in CMPI 2.0.

Status for OpenPegasus:

Tested in cmpiTestBrokerEncProvider.c

static CMPIGcStat* CMMemMark ( const CMPIBroker *  mb, CMPIStatus *  rc  )

inlinestatic

Mark a new object lifecycle level for subsequent newly created CMPI encapsulated data type objects.

Parameters

	mb	CMPIBroker structure.
[out]	rc	Function return status (suppressed when NULL).

Returns

CMPIGcStat structure for use with CMPIBrokerMemFT.release().

Full Description

CMPIBrokerMemFT.mark()

Examples

The following code fragment shows the general principle, using new…() functions as an example for allocating encapsulated data objects:

 (.c)
CMPIBroker *_broker;
CMPIStatus st;
CMPIGcStat gc;

i1 = CMNewInstance(_broker, . . .);   // creates object i1 at default
                                      // object lifecycle level

gc1 = CMMemMark(_broker, &st);        // marks object lifecycle level #1

i2 = CMNewInstance(_broker, . . .);   // creates object i2 at object
                                      // lifecycle level #1

st = CMMemRelease(_broker, gc1);      // releases objects at lifecycle
                                      // level #1 (i2)

i3 = CMNewInstance(_broker, . . .);   // creates object i3 at default
                                      // object lifecycle level

The following code fragment demonstrates the stacked use of these functions:

 (.c)
CMPIBroker *_broker;
CMPIStatus st;
CMPIGcStat gc;

i1 = CMNewInstance(_broker, . . .);   // creates i1 at default level

gc1 = CMMemMark(_broker, &st);        // marks level #1

i2 = CMNewInstance(_broker, . . .);   // creates i2 at level #1

gc2 = CMMemMark(_broker, &st);        // marks level #2

i3 = CMNewInstance(_broker, . . .);   // creates i3 at level #2

st = CMMemRelease(_broker, gc2);      // releases level #2 (i3)

i4 = CMNewInstance(_broker, . . .);   // creates i4 at level #1

st = CMMemRelease(_broker, gc1);      // releases level #1 (i2,i4)

i5 = CMNewInstance(_broker, . . .);   // creates i5 at default level

The requirement not to overlap stacked use of these functions implies that in the previous code fragment, the first CMMemRelease() call can pass the gc2 pointer as an argument, identifying the current object lifecycle level #2, but cannot pass the gc1 pointer.

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static CMPIStatus CMMemRelease ( const CMPIBroker *  mb, const CMPIGcStat *  gc  )

inlinestatic

Release all CMPI encapsulated data type objects created at the specified object lifecycle level, and remove that level.

Parameters

mb	CMPIBroker structure.
gc	CMPIGcStat structure returned from the CMPIBrokerMemFT.mark() function.

Returns

Function return status.

Full Description

CMPIBrokerMemFT.release()

Examples

See CMMemMark()

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void* CMMalloc ( const CMPIBroker *  mb, size_t  size  )

inlinestatic

Allocate an uninitalized memory block of the specified size.

Parameters

mb	CMPIBroker structure.
size	Amount of memory to allocate, in Bytes.

Returns

A pointer to the allocated memory block.

Full Description

CMPIBrokerMemFT.cmpiMalloc()

Examples

This example shows an instance MI that in its initialization function allocates a structure for its opaque handle, and a buffer of charthat is remembered in that data structure. The cleanup function releases both. See CMInstanceMIStub() for details on the initialization and cleanup functions.

 (.c)
// Data structure that is hanging off of the opaque MI handle.
struct InstanceMIHdl {
    char *buffer;           // some character buffer
};

static const CMPIBroker *_broker;

static CMPIStatus MyProvInstanceInitialize(
    CMPIInstanceMI *mi,
    const CMPIContext *ctx)
{
    struct InstanceMIHdl *hdl = (struct InstanceMIHdl *)
                                CMMalloc(_broker, sizeof(InstanceMIHdl));
    mi->hdl = hdl;
    if (!hdl) {
        CMReturn(CMPI_RC_ERR_FAILED);
    }

    char *buffer = (char*)CMCalloc(_broker, 4096, sizeof(char));
    hdl->buffer = buffer;
    if (!buffer) {
        CMReturn(CMPI_RC_ERR_FAILED);
    }

    CMReturn(CMPI_RC_OK);
}

static CMPIStatus MyProvCleanup (
    CMPIInstanceMI *mi,
    const CMPIContext *ctx,
    CMPIBoolean terminating)
{
    struct InstanceMIHdl *hdl = (struct InstanceMIHdl*)mi->hdl;
    CMFree(_broker, hdl->buffer);
    CMFree(_broker, hdl);
    CMReturn(CMPI_RC_OK);
}

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void* CMCalloc ( const CMPIBroker *  mb, size_t  nElems, size_t  sizeElem  )

inlinestatic

Allocate a memory block of the specified size and initialize it to zero.

Parameters

mb	CMPIBroker structure.
nElems	Number of elements to allocate.
sizeElem	Size of each element to allocate, in Bytes.

Returns

A pointer to the allocated and initialized memory block.

Full Description

CMPIBrokerMemFT.cmpiCalloc()

Examples

See CMMalloc()

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void* CMRealloc ( const CMPIBroker *  mb, void *  ptr, size_t  size  )

inlinestatic

Change the size of a memory block.

Parameters

mb	CMPIBroker structure.
ptr	If not NULL, points to previosuly allocated memory. Passing a non-NULL pointer to this function which was not allocated explicitly by CMMalloc() or CMCalloc() is undefined. If ptr is NULL, the function behaves like CMMalloc(), assigning a new memory block of size Bytes and returning a pointer to its beginning.
size	New size of the memory block, in Bytes. The new size may be larger or smaller than (or equal to) the current size.

Returns

A pointer to the resized memory block.

Full Description

CMPIBrokerMemFT.cmpiRealloc()

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void* CMStrDup ( const CMPIBroker *  mb, const char *  str  )

inlinestatic

Allocate a memory block and initialize it with a string.

Parameters

mb	CMPIBroker structure.
str	C-language string to be duplicated.

Returns

A pointer to the new memory block (that is, to the new C-language string).

Full Description

CMPIBrokerMemFT.cmpiStrDup()

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void CMFree ( const CMPIBroker *  mb, void *  ptr  )

inlinestatic

Release a memory block.

Parameters

mb	CMPIBroker structure.
ptr	Points to the memory block to free. The memory block shall have been allocated via the CMMalloc(), CMCalloc(), CMRealloc(), or CMStrDup() functions.

Returns

None.

Full Description

CMPIBrokerMemFT.cmpiFree()

Examples

See CMMalloc()

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void CMFreeInstance ( const CMPIBroker *  mb, CMPIInstance *  inst  )

inlinestatic

Release a CMPIInstance object.

Parameters

mb	CMPIBroker structure.
inst	The CMPIInstance object to be released. That object shall have been created using CMNewInstance().

Returns

None.

Full Description

CMPIBrokerMemFT.freeInstance()

Examples

 (.c)
TBD

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void CMFreeObjectPath ( const CMPIBroker *  mb, CMPIObjectPath *  obj  )

inlinestatic

Release a CMPIObjectPath object.

Parameters

mb	CMPIBroker structure.
obj	The CMPIObjectPath object to be released. That object shall have been created using CMNewObjectPath().

Returns

None.

Full Description

CMPIBrokerMemFT.freeObjectPath()

Examples

 (.c)
TBD

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void CMFreeArgs ( const CMPIBroker *  mb, CMPIArgs *  args  )

inlinestatic

Release a CMPIArgs object.

Parameters

mb	CMPIBroker structure.
args	The CMPIArgs object to be released. That object shall have been created using CMNewArgs().

Returns

None.

Full Description

CMPIBrokerMemFT.freeArgs()

Examples

 (.c)
TBD

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void CMFreeString ( const CMPIBroker *  mb, CMPIString *  str  )

inlinestatic

Release a CMPIString object.

Parameters

mb	CMPIBroker structure.
str	The CMPIString object to be released. That object shall have been created using CMNewString() or CMNewStringCP().

Returns

None.

Full Description

CMPIBrokerMemFT.freeString()

Examples

 (.c)
TBD

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void CMFreeArray ( const CMPIBroker *  mb, CMPIArray *  array  )

inlinestatic

Release a CMPIArray object.

Parameters

mb	CMPIBroker structure.
array	The CMPIArray object to be released. That object shall have been created using CMNewArray().

Returns

None.

Full Description

CMPIBrokerMemFT.freeArray()

Examples

 (.c)
TBD

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void CMFreeDateTime ( const CMPIBroker *  mb, CMPIDateTime *  dt  )

inlinestatic

Release a CMPIDateTime object.

Parameters

mb	CMPIBroker structure.
dt	The CMPIDateTime object to be released. That object shall have been created using CMNewDateTime(), CMNewDateTimeFromBinary(), or CMNewDateTimeFromChars().

Returns

None.

Full Description

CMPIBrokerMemFT.freeDateTime()

Examples

 (.c)
TBD

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void CMFreeSelectExp ( const CMPIBroker *  mb, CMPISelectExp *  se  )

inlinestatic

Release a CMPISelectExp object.

Parameters

mb	CMPIBroker structure.
se	The CMPISelectExp object to be released. That object shall have been created using CMNewSelectExp().

Returns

None.

Full Description

CMPIBrokerMemFT.freeSelectExp()

Examples

 (.c)
TBD

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.

static void CMFreeChars ( const CMPIBroker *  mb, char *  chars  )

inlinestatic

Free the memory of a C-language string.

Parameters

mb	CMPIBroker structure.
chars	The C-language string to be released. This C-language string shall have been created using CMNewCharsCP().

Returns

None.

Full Description

CMPIBrokerMemFT.freeChars()

Examples

 (.c)
TBD

Capabilities:

Part of the Memory Enhancement Services capability.

Addition:

Added in CMPI 2.1.

Status for OpenPegasus:

Not used

Todo:

New convenience function - please review.