Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

MQe_DynamicBuffer.h File Reference

The implementation of a simple DynamicBuffer. More...


Defines

#define MQE_DYNAMIC_BUFFER_SIZE_DEFAULT
 default dynamic buffer size

#define MQE_DYNAMIC_BUFFER_SIZE_EXTRA_SMALL
 extra small dynamic buffer size

#define MQE_DYNAMIC_BUFFER_SIZE_SMALL
 small dynamic buffer size

#define MQE_DYNAMIC_BUFFER_SIZE_MEDIUM
 mediuml dynamic buffer size

#define MQE_DYNAMIC_BUFFER_SIZE_LARGE
 large dynamic buffer size

#define MQE_DYNAMIC_BUFFER_SIZE_EXTRA_LARGE
 extra large dynamic buffer size


Functions

MQERETURN mqeDynamicBuffer_new (MQeExceptBlock *pExceptBlock, MQeDynamicBufferHndl *phDynamicBuffer, MQEINT16 blockSize)
 create a new dynamic buffer.

MQERETURN mqeDynamicBuffer_free (MQeDynamicBufferHndl hDynamicBuffer, MQeExceptBlock *pExceptBlock)
 free a dynamic buffer.

MQERETURN mqeDynamicBuffer_append (MQeDynamicBufferHndl hDynamicBuffer, MQeExceptBlock *pExceptBlock, MQEBYTE *pInput, MQEINT32 offset, MQEINT32 *pInputLength)
 Append bytes into dynamic buffer.

MQERETURN mqeDynamicBuffer_prefix (MQeDynamicBufferHndl hDynamicBuffer, MQeExceptBlock *pExceptBlock, MQEBYTE *pInput, MQEINT32 offset, MQEINT32 *pInputLength)
 Prefix bytes into dynamic buffer.

MQERETURN mqeDynamicBuffer_read (MQeDynamicBufferHndl hDynamicBuffer, MQeExceptBlock *pExceptBlock, MQEBYTE *pOutput, MQEINT32 offset, MQEINT32 *pOutputLength)
 Read bytes (destructive) from dynamic buffer into a byte array.

MQERETURN mqeDynamicBuffer_examine (MQeDynamicBufferHndl hDynamicBuffer, MQeExceptBlock *pExceptBlock, MQEBYTE *pOutput, MQEINT32 offset, MQEINT32 *pOutputLength, MQEINT32 startFrom)
 Examine (non-destructive read) the content of dynamic buffer.

MQERETURN mqeDynamicBuffer_erase (MQeDynamicBufferHndl hDynamicBuffer, MQeExceptBlock *pExceptBlock)
 Erase the content of dynamic buffer.


Detailed Description

This item represents a simple implementation of a DynamicBuffer. The DynamicBuffer is designed to store byte sequences.

When the user invokes mqeDynamicBuffer_new() to instantiate a DynamicBuffer, the system creates an empty buffer. Byte sequences can appended/prefixed into a dynamic buffer using mqeDynamicBuffer_append()/mqeDynamicBuffer_prefix(). The leading bytes stored in the buffer can read destructively using mqeDynamicBuffer_read(). The amount read off is the same as the size of the output byte array provided by the caller (provided that there is enough bytes available. The DynamicBuffer dynamically increases or reduces its memory allocation as bytes are added or read off. Non-destructive read can be achieved by using mqeDynamicBuffer_examine(). The read/examine and append/prefix operations can be intermixed if so wished.


Function Documentation

MQERETURN mqeDynamicBuffer_new MQeExceptBlock   pExceptBlock,
MQeDynamicBufferHndl *    phDynamicBuffer,
MQEINT16    blockSize
 

Parameters:
pExceptBlock  [in/out] Exception block to be filled in case of error
phDynamicBuffer  [in/out] Pointer to a location to place the handle to the new dynamic buffer
blockSize  [in] Size (number of bytes) of individaul internal memory blocks (advisery only). The following five choices can be specified:
  • MQE_DYNAMIC_BUFFER_SIZE_DEFAULT:
  • system default size,
  • MQE_DYNAMIC_BUFFER_SIZE_EXTRA_SMALL:
  • extra smal size,
  • MQE_DYNAMIC_BUFFER_SIZE_SMALL:
  • smal size,
  • MQE_DYNAMIC_BUFFER_SIZE_MEDIUM:
  • medium size,
  • MQE_DYNAMIC_BUFFER_SIZE_LARGE:
  • large size, and
  • MQE_DYNAMIC_BUFFER_SIZE_EXTRA_LARGE:
  • extra large size. Numerical values other than the above five will result in MQE_DYNAMIC_BUFFER_SIZE_DEFAILT being adopted. The actual size adopted by MQe may very across actual platforms (50 <= n <= 2000 as a guideline). Each block carries an overhead (around 20 bytes added by MQe). A smaller blockSize incurs a larger overhead. However, a larger blockSize results in a lower memory usage rate on average.
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  - Buffer was successfully created.
MQERETURN_OSA_MEMORY_ERROR 
  • MQEREASON_ALLOCATION_FAILED memory allocation failed internally and is subject to an adjust to an even number if necessary.
Note:
MQeDynamicBuffer only allocates new memory blocks of blockSize bytes incrementally when necessary.
Warning:
It is the responsibility of the user to remove the dynamic buffer by calling mqeDynamicBuffer_free() even if all the content in the buffer has been destructively read. An MQeDynamicBuffer is not thread safe.

MQERETURN mqeDynamicBuffer_free MQeDynamicBufferHndl    hDynamicBuffer,
MQeExceptBlock   pExceptBlock
 

Parameters:
hDynamicBuffer  [in] Handle of dynamic buffer
pExceptBlock  [in/out] Exception block to be filled in case of error
bTrace  [in] Boolean to say whether to trace IF tracing is enabled. Used to prevent recursion
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  - Buffer was successfully freed.
MQERETURN_OSA_DYNAMIC_BUFFER_ERROR 
  • MQEREASON_INVALID_SIGNATURE - Not a dynamic buffer. Not freed.
MQERETURN_OSA_MEMORY_ERROR 
  • MQEREASON_INVALID_PARAM2 - Buffer memory could not be freed.

MQERETURN mqeDynamicBuffer_append MQeDynamicBufferHndl    hDynamicBuffer,
MQeExceptBlock   pExceptBlock,
MQEBYTE *    pInput,
MQEINT32    offset,
MQEINT32 *    pInputLength
 

Parameters:
hDynamicBuffer  [in] Handle of dynamic buffer
pExceptBlock  [in/out] Exception block to be filled in case of error
pInput  [in/out] pointer to input byte buffer
offset  [in] input offset (number of bytes) into pInput
pInputLength  [in/out] pointer to number of bytes to be written/actually written
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  - Data was successfully appended to.
MQERETURN_OSA_DYNAMIC_BUFFER_ERROR 
  • MQEREASON_INVALID_SIGNATURE - Not a dynamic buffer. Operation not executed.
MQERETURN_OSA_MEMORY_ERROR 
  • MQEREASON_ALLOCATION_FAILED - Memory was not allocated

MQERETURN mqeDynamicBuffer_prefix MQeDynamicBufferHndl    hDynamicBuffer,
MQeExceptBlock   pExceptBlock,
MQEBYTE *    pInput,
MQEINT32    offset,
MQEINT32 *    pInputLength
 

Parameters:
hDynamicBuffer  [in] Handle of dynamic buffer
pExceptBlock  [in/out] Exception block to be filled in case of error
pInput  [in/out] pointer to input byte buffer
offset  [in] input offset (number of bytes) into pInput
pInputLength  [in/out] pointer to number of bytes to be written/actually written
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  - Data was successfully appended to.
MQERETURN_OSA_DYNAMIC_BUFFER_ERROR 
  • MQEREASON_INVALID_SIGNATURE - Not a dynamic buffer. Operation not executed.
MQERETURN_OSA_MEMORY_ERROR 
  • MQEREASON_ALLOCATION_FAILED - Memory was not allocated

MQERETURN mqeDynamicBuffer_read MQeDynamicBufferHndl    hDynamicBuffer,
MQeExceptBlock   pExceptBlock,
MQEBYTE *    pOutput,
MQEINT32    offset,
MQEINT32 *    pOutputLength
 

Parameters:
hDynamicBuffer  [in] Handle of dynamic buffer
pExceptBlock  [in/out] Exception block to be filled in case of error
pOutput  [in/out] pointer to output byte buffer
offset  [in] output offset (number of bytes) into pOutput
pOutputLength  [in/out] pointer to variable for size of output buffer/number of bytes read
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Note:
Call the function with a NULL pOutput to find out the required size for output byte array.
Return values:
MQERETURN_OK  - Data was successfully appended to.
MQERETURN_OSA_DYNAMIC_BUFFER_ERROR 
  • MQEREASON_INVALID_SIGNATURE - Not a dynamic buffer. Operation not executed.

MQERETURN mqeDynamicBuffer_examine MQeDynamicBufferHndl    hDynamicBuffer,
MQeExceptBlock   pExceptBlock,
MQEBYTE *    pOutput,
MQEINT32    offset,
MQEINT32 *    pOutputLength,
MQEINT32    startFrom
 

Parameters:
hDynamicBuffer  [in] Handle of dynamic buffer
pExceptBlock  [in/out] Exception block to be filled in case of error
pOutput  [in/out] pointer to output byte buffer
offset  [in] output offset (number of bytes) into pOutput
pOutputLength  [in/out] pointer to variable for size of output buffer/number of bytes read
startFrom  [in] number of bytes at the beginning of the buffer to skip over
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Note:
Call the function with a NULL pOutput to find out the required size for output byte array.
Return values:
MQERETURN_OK  - Data was successfully appended to.
MQERETURN_OSA_DYNAMIC_BUFFER_ERROR 
  • MQEREASON_INVALID_SIGNATURE - Not a dynamic buffer. Operation not executed.

MQERETURN mqeDynamicBuffer_erase MQeDynamicBufferHndl    hDynamicBuffer,
MQeExceptBlock   pExceptBlock
 

Parameters:
hDynamicBuffer  [in] Handle of dynamic buffer
pExceptBlock  [in/out] Exception block to be filled in case of error
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  - Operation was successfully.


Generated Thu Aug 11 23:41:18 2005 for Websphere MQ Everyplace for Multiplatforms C Bindings Reference