9.13. ODPI-C Queue Functions

Queue handles are used to represent Advanced Queueing (AQ) queues. They are created by calling the function dpiConn_newQueue() and are destroyed when the last reference is released by calling the function dpiQueue_release().

int dpiQueue_addRef(dpiQueue *queue)

Adds a reference to the queue. This is intended for situations where a reference to the queue needs to be maintained independently of the reference returned when the queue was created.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
queue	IN	The queue to which a reference is to be added. If the reference is NULL or invalid, an error is returned.

int dpiQueue_deqMany(dpiQueue *queue, uint32_t *numProps, dpiMsgProps **props)

Dequeues multiple messages from the queue.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
queue	IN	The queue from which messages are to be dequeued. If the reference is NULL or invalid, an error is returned.
numProps	IN/OUT	A pointer to the number of elements in the props array. When the function is called, the value refers to the length of the props array and the maximum number of messages that should be dequeued. After the function has completed successfully, the value refers to the number of messages that were actually dequeued from the queue.
props	OUT	An array of references to message properties which will be populated upon successful completion of this function. Each of these references should be released when they are no longer needed by calling the function dpiMsgProps_release().

int dpiQueue_deqOne(dpiQueue *queue, dpiMsgProps **props)

Dequeues a single message from the queue.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
queue	IN	The queue from which the messages is to be dequeued. If the reference is NULL or invalid, an error is returned.
props	OUT	A pointer to a reference to a message property which will be populated upon successful completion of this function. This reference should be released when it is no longer needed by calling the function dpiMsgProps_release(). If no messages are available, this reference will be NULL.

int dpiQueue_enqMany(dpiQueue *queue, uint32_t numProps, dpiMsgProps **props)

Enqueues multiple messages into the queue.

Warning: calling this function in parallel on different connections acquired from the same pool may fail due to Oracle bug 29928074. Ensure that this function is not run in parallel, use standalone connections or connections from different pools, or make multiple calls to dpiQueue_enqOne() instead. The function dpiQueue_deqMany() call is not affected.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
queue	IN	The queue into which the messages are to be enqueued. If the reference is NULL or invalid, an error is returned.
numProps	IN/OUT	The number of messages that are to be enqueued.
props	IN	An array of references to message properties that are to be enqueued. The length of the array is specified by the numProps parameter. Each of the message properties must have the right type of payload associated before calling this method or an error will occur.

int dpiQueue_enqOne(dpiQueue *queue, dpiMsgProps *props)

Enqueues a single mesasge into the queue.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
queue	IN	The queue into which the message is to be enqueued. If the reference is NULL or invalid, an error is returned.
props	IN	A reference to the message that is to be enqueued. The message properties must have the right type of payload associated before calling this method or an error will occur.

int dpiQueue_getDeqOptions(dpiQueue *queue, dpiDeqOptions **options)

Returns a reference to the dequeue options associated with the queue. These options affect how messages are dequeued.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
queue	IN	The queue from which the dequeue options are to be retrieved. If the reference is NULL or invalid, an error is returned.
options	OUT	A reference to the dequeue options associated with the queue which will be populated upon successful completion of this function. This reference is owned by the queue and will remain valid as long as a reference to the queue is held.

int dpiQueue_getEnqOptions(dpiQueue *queue, dpiEnqOptions **options)

Returns a reference to the enqueue options associated with the queue. These options affect how messages are enqueued.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
queue	IN	The queue from which the enqueue options are to be retrieved. If the reference is NULL or invalid, an error is returned.
options	OUT	A reference to the enqueue options associated with the queue which will be populated upon successful completion of this function. This reference is owned by the queue and will remain valid as long as a reference to the queue is held.

int dpiQueue_release(dpiQueue *queue)

Releases a reference to the queue. A count of the references to the queue is maintained and when this count reaches zero, the memory associated with the queue is freed.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
queue	IN	The queue from which a reference is to be released. If the reference is NULL or invalid, an error is returned.