CMPIStringFT Struct Reference

Function table of CMPIString encapsulated data type object. More...

#include <cmpift.h>

Data Fields
CMPIVersion	ftVersion
	CMPI version supported by the MB for this function table. More...
CMPIStatus(*	release )(CMPIString *str)
	Release a CMPIString object. More...
CMPIString *(*	clone )(const CMPIString *str, CMPIStatus *rc)
	Create an independent copy of a CMPIString object. More...
const char *(*	getCharPtr )(const CMPIString *str, CMPIStatus *rc)
	Get a pointer to a C-language string representation of a CMPIString object. More...
char *(*	newCharsCP )(const CMPIString *str, const CMPICodepageID cpid, CMPIStatus *rc)
	Create a C-language string that has converted a CMPIString object into a specific codepage. More...

Detailed Description

Function table of CMPIString encapsulated data type object.

Field Documentation

CMPIVersion CMPIStringFT::ftVersion

CMPI version supported by the MB for this function table.

Any earlier CMPI versions are implicitly also supported.

See CMPIVersion<NNN> for valid CMPI version numbers.

CMPIStatus(* CMPIStringFT::release)(CMPIString *str)

Release a CMPIString object.

CMPIStringFT.release() releases a CMPIString object. This indicates to the MB that the object (including any objects it contains) will no longer be used by the MI. The MB may free (=reclaim) the memory associated with the object during the call to this function, or later during some garbage collection cycle (see Subclause 4.1.7 of the CMPI Standard).

Parameters

str	Points to the CMPIString object that is to be released. That object shall have been created using CMPIStringFT.clone().

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 str handle is invalid.

Convenience Function

CMRelease()

CMPIString*(* CMPIStringFT::clone)(const CMPIString *str, CMPIStatus *rc)

Create an independent copy of a CMPIString object.

CMPIStringFT.clone() creates an independent copy of a CMPIString object.

Parameters

	str	Points to the CMPIString object that is to be copied.
[out]	rc	If 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 the copied CMPIString object will be returned.

The returned CMPIString object shall be explicitly released by the MI using CMPIStringFT.release().

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 str handle is invalid.

Convenience Function

CMClone()

const char*(* CMPIStringFT::getCharPtr)(const CMPIString *str, CMPIStatus *rc)

Get a pointer to a C-language string representation of a CMPIString object.

CMPIStringFT.getCharPtr() gets a pointer to a C-language string that represents the characters of the CMPIString object.

Parameters

	str	Points to the CMPIString object for this function.
[out]	rc	If 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 C-language string will be returned.

The character array of the returned string shall not be explicitly released by the MI, because it may point to an internal data area in the CMPIString object which will be released along with that object, or it may point to a new character array created by the MB which will be released automatically 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 str handle is invalid.

Convenience Function

CMGetCharsPtr()

char*(* CMPIStringFT::newCharsCP)(const CMPIString *str, const CMPICodepageID cpid, CMPIStatus *rc)

Create a C-language string that has converted a CMPIString object into a specific codepage.

CMPIStringFT.newCharsCP() creates a new C-language string that contains the string in a CMPIString object, converted into a specific codepage.

Parameters

	str	Points to the CMPIString object for this function.
	cpid	CMPI-specific codepage ID for the codepage to convert to. See CMPICodepageID for a list of supported codepages and their codepage ID values.
[out]	rc	If not NULL, points to a CMPIStatus structure that upon return will have been updated with the function return status.

Returns

If successful, a new C-language string will be returned, in the codepage specified in cpid.

The returned C-language string must be freed by the MI using CMPIBrokerMemFT.freeChars().

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 str handle is invalid.
• CMPI_RC_ERR_INVALID_PARAMETER - cpid is invalid.
• CMPI_RC_ERR_NOT_IN_CODEPAGE - The string contains characters that are not representable in the specified codepage.

Convenience Function

CMNewCharsCP()

Capabilities:

Part of the Codepage Conversion capability.

Addition:

Added in CMPI 2.1.

---

The documentation for this struct was generated from the following file:

• cmpift.h