WebSphere Message Service Clients for C/C++ and .NET, Version 1.2 Operating Systems: Linux, Windows

C functions that return a byte array by value

This topic describes the interface used by C functions that return a byte array by value.

In the C API, certain functions return a byte array as a parameter. Each of these functions uses the same interface for retrieving a byte array. Here is an example of one of these functions, xmsGetByteArrayProperty() in the PropertyContext class:
xmsRC xmsGetByteArrayProperty(xmsHObj object
                              xmsCHAR *propertyName,
                              xmsSBYTE *propertyValue,
                              xmsINT length,
                              xmsINT *actualLength
                              xmsHErrorBlock errorBlock) const;
Three parameters control the retrieval of a byte array:
propertyValue
This parameter is a pointer to a buffer provided by the application into which XMS copies the bytes in the array.
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 byte array is not returned, but its length is returned in the actualLength parameter.
actualLength
This output parameter is the number of bytes in the array that XMS copies into buffer. If you specify a null pointer for this parameter on input, the length of the array is not returned.

If the buffer is not large enough to store the whole array, XMS returns the array truncated to the length of the buffer, sets the actualLength parameter to the length of the whole array, and returns error code XMS_E_DATA_TRUNCATED.

Two functions, xmsBytesMsgReadBytes() and xmsStreamMsgReadBytes(), have a slightly different interface. Using one of these functions, an application can retrieve a byte array in stages by successive calls to the function. Each call reads bytes into the buffer provided by the application starting from the current position of an internal cursor, and an output parameter, returnedLength, tells the application how many bytes have been read into the buffer. Neither function has the equivalent of the actualLength parameter in its interface, but an application can specify XMSC_QUERY_SIZE to determine the number of bytes remaining in an array starting from the current position of the cursor.


Concept topic

Terms of Use | Rate this page

Last updated: 7 Dec 2005

© Copyright IBM Corporation 2005. All Rights Reserved.