CMPI 2.1.0 API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Variables
Miscellaneous Services (Subclause 9.1)

Variables

CMPIBoolean(* CMPIBrokerEncFT::classPathIsA )(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...
 
CMPIString *(* CMPIBrokerEncFT::toString )(const CMPIBroker *mb, const void *object, CMPIStatus *rc)
 Convert any CMPI encapsulated data type object into a string representation. More...
 
CMPIBoolean(* CMPIBrokerEncFT::isOfType )(const CMPIBroker *mb, const void *object, const char *type, CMPIStatus *rc)
 Test whether a CMPI encapsulated data type object is of a specified CMPI type. More...
 
CMPIString *(* CMPIBrokerEncFT::getType )(const CMPIBroker *mb, const void *object, CMPIStatus *rc)
 Get the type name of a CMPI ensapsulated data type object. More...
 
CMPIString *(* CMPIBrokerEncFT::getMessage )(const CMPIBroker *mb, const char *msgId, const char *defMsg, CMPIStatus *rc, CMPICount count,...)
 Get a translated MB implementation-specific message text by message ID. (Deprecated) More...
 
CMPIStatus(* CMPIBrokerEncFT::logMessage )(const CMPIBroker *mb, CMPISeverity severity, const char *id, const char *text, const CMPIString *string)
 Log a diagnostic message. More...
 
CMPIStatus(* CMPIBrokerEncFT::trace )(const CMPIBroker *mb, CMPILevel level, const char *component, const char *text, const CMPIString *string)
 Trace a diagnostic message with a specific trace level. More...
 
CMPIStatus(* CMPIBrokerEncFT::openMessageFile )(const CMPIBroker *mb, const char *msgFile, CMPIMsgFileHandle *msgFileHandle)
 Open a message file and return a handle to the file. More...
 
CMPIStatus(* CMPIBrokerEncFT::closeMessageFile )(const CMPIBroker *mb, const CMPIMsgFileHandle msgFileHandle)
 Close a message file. More...
 
CMPIString *(* CMPIBrokerEncFT::getMessage2 )(const CMPIBroker *mb, const char *msgId, const CMPIMsgFileHandle msgFileHandle, const char *defMsg, CMPIStatus *rc, CMPICount count,...)
 Get a translated message text from an open message file by message ID. More...
 

Detailed Description

Variable Documentation

CMPIBoolean(* CMPIBrokerEncFT::classPathIsA)(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.

CMPIBrokerEncFT.classPathIsA() tests whether a class path is of a specified class or any of that class’s subclasses.

Parameters
mbPoints to a CMPIBroker structure.
classPathPoints to the CMPIObjectPath object representing the class path that is being tested. It shall contain the namespace and class name components. Any key components in that CMPIObjectPath object will be ignored.
classNameClass name to be tested for.
[out]rcIf not NULL, points to a CMPIStatus structure that upon return will have been updated with the function return status.
Returns
If successful, a CMPIBoolean value indicating the test result will be returned, as follows:
  • True indicates that the class path is of the specified class or any of that class's subclasses
  • False indicates that this is not the case
If not successful, false will be returned.
Errors
The function return status will indicate one of the following CMPIrc codes:
  • CMPI_RC_OK - Function successful.
  • CMPI_RC_ERR_INVALID_HANDLE - The mb or classPath handle is invalid.
  • CMPI_RC_ERR_INVALID_NAMESPACE - The namespace specified in classPath is invalid or does not exist.
  • CMPI_RC_ERR_NOT_FOUND - The class specified in classPath is invalid or does not exist.
  • CMPI_RC_ERR_INVALID_PARAMETER - The className format is invalid.
Convenience Function
CMClassPathIsA()
CMPIString*(* CMPIBrokerEncFT::toString)(const CMPIBroker *mb, const void *object, CMPIStatus *rc)

Convert any CMPI encapsulated data type object into a string representation.

CMPIBrokerEncFT.toString() converts any CMPI encapsulated data type object (see MB Encapsulated Data Type Support) into an MB implementation-specific string representation.

Parameters
mbPoints to a CMPIBroker structure.
objectPoints to a CMPI encapsulated data type object.
[out]rcIf not NULL, points to a CMPIStatus structure that upon return will have been updated with the function return status.
Returns

If successful, a pointer to a CMPIString object containing the MB implementation-specific string representation of the CMPI encapsulated data type object will be returned.

The returned CMPIString object shall not be explicitly released by the MI, because it may be an internal object of the CMPI encapsulated data type object which will be released along with that object, or a new object created by the MB which will be automatically released by the MB (see Subclause 4.1.7 of the CMPI Standard).

If not successful, NULL will be returned.

Errors
The function return status will indicate one of the following CMPIrc codes:
  • CMPI_RC_OK - Function successful.
  • CMPI_RC_ERR_INVALID_HANDLE - The mb or object handle is invalid.
Convenience Function
CDToString()
CMPIBoolean(* CMPIBrokerEncFT::isOfType)(const CMPIBroker *mb, const void *object, const char *type, CMPIStatus *rc)

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

CMPIBrokerEncFT.isOfType() tests whether a CMPI encapsulated data type object (see MB Encapsulated Data Type Support) is of a specified CMPI type.

Parameters
mbPoints to a CMPIBroker structure.
objectPoints to a CMPI encapsulated data type object.
typeType name of the encapsulated data type to be tested for (e.g., "CMPIInstance").
[out]rcIf not NULL, points to a CMPIStatus structure that upon return will have been updated with the function return status.
Returns
If successful, a CMPIBoolean value indicating the test result will be returned, as follows:
  • True indicates that the object is of the specified CMPI type
  • False indicates that this is not the case
If not successful, false will be returned.
Errors
The function return status will indicate one of the following CMPIrc codes:
  • CMPI_RC_OK - Function successful.
  • CMPI_RC_ERR_INVALID_HANDLE - The mb or object handle is invalid.
  • CMPI_RC_ERR_INVALID_PARAMETER - The type format is invalid.
Convenience Function
CDIsOfType()
CMPIString*(* CMPIBrokerEncFT::getType)(const CMPIBroker *mb, const void *object, CMPIStatus *rc)

Get the type name of a CMPI ensapsulated data type object.

CMPIBrokerEncFT.getType() gets the type name of a CMPI encapsulated data type object.

Parameters
mbPoints to a CMPIBroker structure.
[out]objectPoints to a CMPI encapsulated data type object.
[out]rcIf not NULL, points to a CMPIStatus structure that upon return will have been updated with the function return status.
Returns

If successful, a pointer to a CMPIString object specifying the type name of the encapsulated data type (e.g., "CMPIInstance") will be returned.

The returned CMPIString object shall not be explicitly released by the MI, because it may be an internal object of the CMPI encapsulated data type object which will be released along with that object, or a new object created by the MB which will be automatically released by the MB (see Subclause 4.1.7 of the CMPI Standard).

If not successful, NULL will be returned.

Errors
The function return status will indicate one of the following CMPIrc codes:
  • CMPI_RC_OK - Function successful.
  • CMPI_RC_ERR_INVALID_HANDLE - The mb or object handle is invalid.
Convenience Function
CDGetType()
CMPIString*(* CMPIBrokerEncFT::getMessage)(const CMPIBroker *mb, const char *msgId, const char *defMsg, CMPIStatus *rc, CMPICount count,...)

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

CMPIBrokerEncFT.getMessage() gets a translated MB implementation-specific message text by message ID. The language of the message text depends on the MB language setting.

Parameters
mbPoints to a CMPIBroker structure.
msgIdMessage ID that is used by the MB to locate a message template. The message ID values and corresponding message templates are MB implementation-specific.
defMsgDefault message template that will be used when message translation is not supported by the MB or msgId cannot be located. The message template string specified in defMsg may contain up to ten message insert triggers ($0 through $9). Each insert trigger string will be replaced with a string representation of the value of the corresponding insert pair in the variable arguments of this function. The MI is not affected when message translation is not supported by the MB, or the message cannot be found, because this function still succeeds and returns a message with expanded message insert triggers.
[out]rcIf not NULL, points to a CMPIStatus structure that upon return will have been updated with the function return status.
countNumber of message insert pairs in the range 0 to 10.
...The variable arguments of this function are count pairs of arguments representing the message insert pairs as follows: type, value whereby type is a CMPIType value and value is a value of that type. The following types are supported: CMPI_sint32, CMPI_uint32, CMPI_sint64, CMPI_uint64, CMPI_real64, CMPI_boolean, CMPI_chars, and CMPI_string.
Returns

If successful, a pointer to a new CMPIString object containing either the translated or default message will be returned.

If not successful, the default message without insert resolution will be returned.

In both cases, the new object will be automatically released by the MB, as described in Subclause 4.1.7 of the CMPI Standard. There is no function to explicitly release the new object. Specifically, the MI shall not use CMPIBrokerMemFT.freeString() on the new object.

Errors
The function return status will indicate one of the following CMPIrc codes:
  • CMPI_RC_OK - Function successful.
  • CMPI_RC_ERR_INVALID_HANDLE - The mb handle is invalid.
  • CMPI_RC_ERR_TYPE_MISMATCH - Invalid insert pair.
  • CMPI_RC_ERR_INVALID_PARAMETER - count value range violation.
Convenience Function
CMGetMessage()
Capabilities:
Part of the Message Translation capability.
Deprecated:
This function is deprecated since CMPI 2.1. Use CMPIBrokerEncFT.getMessage2() instead.
CMPIStatus(* CMPIBrokerEncFT::logMessage)(const CMPIBroker *mb, CMPISeverity severity, const char *id, const char *text, const CMPIString *string)

Log a diagnostic message.

CMPIBrokerEncFT.logMessage() logs a diagnostic message. This function exists to provide a mechanism to MIs by which to provide information about errors.

Parameters
mbPoints to a CMPIBroker structure.
severitySeverity of the log message. Severity levels are defined in CMPISeverity.
idIf not NULL, message ID or any other identifying string.
textIf not NULL, message text to be logged.
stringIf not NULL, points to a CMPIString object specifying the message text to be logged. string will be ignored when text is not NULL.
Returns
CMPIStatus structure containing 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_NOT_SUPPORTED - Function is not supported by the MB.
  • CMPI_RC_ERR_INVALID_HANDLE - The mb or string handle is invalid.
Convenience Function
CMLogMessage()
Capabilities:
Part of the Logging capability.
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.
CMPIStatus(* CMPIBrokerEncFT::trace)(const CMPIBroker *mb, CMPILevel level, const char *component, const char *text, const CMPIString *string)

Trace a diagnostic message with a specific trace level.

CMPIBrokerEncFT.trace() traces a diagnostic message with a specific trace level. This function exists to provide a mechanism to MIs by which debugging information may be generated.

MBs may support tracing in such a way that trace level and component ID can be used for deciding whether a diagnostic message is actually kept versus discarded.

Parameters
mbPoints to a CMPIBroker structure.
levelTrace level of the message. Trace levels are defined in CMPILevel.
componentIf not NULL, MI implementation-specific component ID.
textIf not NULL, message text to be traced.
stringIf not NULL, points to a CMPIString object specifying the message text to be traced. string will be ignored when text is not NULL.
Returns
CMPIStatus structure containing 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_NOT_SUPPORTED - Function is not supported by the MB.
  • CMPI_RC_ERR_INVALID_HANDLE - The mb or string handle is invalid.
Convenience Function
CMTraceMessage()
Capabilities:
Part of the Tracing capability.
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.
CMPIStatus(* CMPIBrokerEncFT::openMessageFile)(const CMPIBroker *mb, const char *msgFile, CMPIMsgFileHandle *msgFileHandle)

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

If the MB supports the Message Translation capability, CMPIBrokerEncFT.openMessageFile() opens a message file and returns a message file handle to that file. This function will use the CMPIAcceptLanguage entry from the current context to determine the language for the messages, and will set the CMPIContentLanguage entry in the current context to the language that was used. All subsequent calls to CMPIBrokerEncFT.getMessage2() using this message file handle will return messages based on that language.

If the MB does not support the Message Translation capability, or if the function fails for other reasons, the function returns NULL as the message file handle. Subsequent calls to CMPIBrokerEncFT.getMessage2() using the NULL message file handle will cause the default message template to be used.

Parameters
mbPoints to a CMPIBroker structure.
msgFile

Points to a string specifying the implementation-specific file path to the message file, or a part thereof.

Examples for such implementation-specific file paths are:

  • Base name of the message file (does not include file extension and directory path). The message file contains all languages, and the language is used to locate the message in the correct language within the message file.
  • Base name of the message file (does not include file extension and directory path). The message file contains messages in only one language, and some identifier for that language is part of the base name.
  • Absolute path of the message file. The message file contains all languages, and the language is used to locate the message in the correct language within the message file.
  • Absolute path of the message file. The message file contains messages in only one language, and some identifier for that language is part of the file path.

The format of the content of the message file is also implementation-specific.

Parameters
[out]msgFileHandlePoints to a CMPIMsgFileHandle structure that will have been updated with a handle that can be passed to the CMPIBrokerEncFT.getMessage2() and CMPIBrokerEncFT.closeMessageFile() functions. If the MB supports the Message Translation capability and the function was successful, the CMPIMsgFileHandle structure will have been updated with a non-NULL handle to the open message file. If the MB does not support the Message Translation capability, or if the function failed for other reasons, the CMPIMsgFileHandle structure will have been updated with a NULL handle.
Returns
CMPIStatus structure containing 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 mb handle is invalid.
  • CMPI_RC_ERR_NOT_FOUND - The MB supports the Message Translation capability and the message file was not found, or the MB does not support the Message Translation capability.
Convenience Function
CMOpenMessageFile()
Capabilities:
Part of the Message Translation capability.
Addition:
Added in CMPI 2.0.
CMPIStatus(* CMPIBrokerEncFT::closeMessageFile)(const CMPIBroker *mb, const CMPIMsgFileHandle msgFileHandle)

Close a message file.

CMPIBrokerEncFT.closeMessageFile() closes a message file previously opened by CMPIBrokerEncFT.openMessageFile(). If the message file handle is NULL, the message file is not closed, and this is not considered a failure.

Parameters
mbPoints to a CMPIBroker structure.
msgFileHandleContains a message file handle (including NULL) that was returned by a previous call to CMPIBrokerEncFT.openMessageFile().
Returns
CMPIStatus structure containing the function return status.
Errors
The function return status will indicate one of the following CMPIrc codes:
  • CMPI_RC_OK - Function successful (including if the message file handle is NULL).
  • CMPI_RC_ERR_INVALID_HANDLE - The mb or msgFileHandle handle is invalid.
Convenience Function
CMCloseMessageFile()
Capabilities:
Part of the Message Translation capability.
Addition:
Added in CMPI 2.0.
CMPIString*(* CMPIBrokerEncFT::getMessage2)(const CMPIBroker *mb, const char *msgId, const CMPIMsgFileHandle msgFileHandle, const char *defMsg, CMPIStatus *rc, CMPICount count,...)

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

CMPIBrokerEncFT.getMessage2() gets a translated message text from an open message file, by message ID.

Parameters
mbPoints to a CMPIBroker structure.
msgIdMessage ID that is used to locate a message template in the open message file.
msgFileHandleMessage file handle that was returned by a previous call to CMPIBrokerEncFT.openMessageFile(). If the MB supports the Message Translation capability, that handle identifies an open message file. If the MB does not support the Message Translation capability, that handle is NULL.
defMsg

Default message template that will be used when the MB does not support the Message Translation capability or when the message ID cannot be located.

The message template string specified in defMsg may contain up to ten message insert triggers ($0 through $9). Each insert trigger will be expanded; that is, the insert trigger string will be replaced with a string representation of the value of the corresponding insert pair in the variable arguments of this function. The MI is not affected when the MB does not support the Message Translation capability or when the message ID cannot be located, because this function still succeeds and returns a message with expanded message insert triggers.

Parameters
[out]rcIf not NULL, points to a CMPIStatus structure that upon return will have been updated with the function return status.
countNumber of message insert pairs in the range 0 to 10.
...The variable arguments of this function are count pairs of arguments representing the message insert pairs as follows: type, value whereby type is a CMPIType value and value is a value of that type. The following types are supported: CMPI_sint32, CMPI_uint32, CMPI_sint64, CMPI_uint64, CMPI_real64, CMPI_boolean, CMPI_chars, and CMPI_string.
Returns

If successful, a pointer to a new CMPIString object containing either the translated or default message will be returned. In both cases, the insert triggers will have been expanded.

If not successful, the default message template without any insert triggers expanded will be returned.

In both cases, the new object will be automatically released by the MB, as described in Subclause 4.1.7 of the CMPI Standard. There is no function to explicitly release the new object. Specifically, the MI shall not use CMPIBrokerMemFT.freeString() on the new object.

Errors
The function return status will indicate one of the following CMPIrc codes:
  • CMPI_RC_OK - Function successful.
  • CMPI_RC_ERR_INVALID_HANDLE - The mb or msgFileHandle handle is invalid.
    Note that NULL is a valid value for the msgFileHandle handle.
  • CMPI_RC_ERR_TYPE_MISMATCH - Invalid insert pair.
  • CMPI_RC_ERR_INVALID_PARAMETER - Count value range violation.
Convenience Function
CMGetMessage2()
Capabilities:
Part of the Message Translation capability.
Addition:
Added in CMPI 2.0.