This topic describes
the interface used by C functions that return a string by value.
In the C API, certain functions return a string as a parameter. Each of
these functions uses the same interface for retrieving a string. The following
example C code illustrates the function,
xmsGetStringProperty() in
the
PropertyContext class:
xmsRC xmsGetStringProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR *propertyValue,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);
Three parameters control the retrieval of a string:
- propertyValue
- This parameter is a pointer to a buffer provided by the application into
which XMS copies
the characters in the string. If data conversion is required, XMS converts
the characters into the code page used by the application before copying them
into the buffer.
- length
- This parameter is the length of the buffer in bytes. This is an input
parameter that must be set by the application before the call. If you specify XMSC_QUERY_SIZE instead,
the string is not returned, but its length is returned in the actualLength
parameter.
- actualLength
- This output parameter is the length of the string that XMS copies
into the buffer. If data conversion is required, this is the length after
conversion. The length is measured in bytes. XMS always
returns a null terminated string, and the length reported to the application
includes the terminating null character. If you specify a null pointer for
this parameter on input, the length of the string is not returned.
If the buffer is not large enough to store the whole string, including
the terminating null character, XMS returns
the string truncated to the length of the buffer, sets the actualLength parameter
to the length of the whole string, and returns error code XMS_E_DATA_TRUNCATED.
If an XMS application
receives a message sent by a JMS application, strings in the header fields,
properties, and body of the message might contain embedded null characters.
Strings containing embedded nulls cannot be manipulated using the standard
C string manipulator because they read the first null character to be the
end of the string.