DosReadQueue

DosReadQueue reads (removes) an element from a queue.

Syntax
DosReadQueue(hq, pRequest, pcbData, ppbuf, element, wait, ppriority, hsem)

Parameters

 * hq (HQUEUE) - input: The handle of the queue from which an element is to be removed.
 * pRequest (PREQUESTDATA) - output: A pointer to a REQUESTDATA that returns a PID and an event code.
 * The data in the ulData field of the REQUESTDATA structure is the same as the data that was furnished in the request parameter of DosWriteQueue for the corresponding queue element.


 * pcbData (PULONG) - output : A pointer to the length, in bytes, of the data that is being removed.
 * ppbuf (PPVOID) - output: A pointer to the element that is being removed from the queue.
 * (This field may or may not be the same as the value of pbData that was specified with DosWriteQueue when the element was added to the queue. If QUE_CONVERT_ADDRESS was specified when the queue was created, the addresses of any elements that are written to the queue by the 16-bit DosWriteQueue function are converted to 32-bit addresses.)


 * element (ULONG) - input : An indicator that specifies whether to remove the first element in the queue or the queue element that was previously examined by DosPeekQueue.
 * Possible values are shown in the following list:
 * 0 : This field is set to 0 by the application to indicate "remove the first element in the queue," according to the order that was specified when the queue was created (FIFO, LIFO, or priority).
 * Any other value: The field is set to the value that was returned by a previous DosPeekQueue operation to indicate "remove the element that was examined by DosPeekQueue."


 * wait (BOOL32) - input: The action to be performed when no entries are found in the queue.
 * Possible values are shown in the following list:
 * 0 DCWW_WAIT The requesting thread waits for an element to be added to the queue.
 * 1 DCWW_NOWAIT The requesting thread does not wait, and DosReadQueue returns with ERROR_QUE_EMPTY.


 * ppriority (PBYTE) - output: The address of the element's priority value.
 * This is the value that was specified for ppriority by DosWriteQueue when it added the element to the queue. ppriority is a numerical value in the range of 0 to 15, with 15 being the highest priority.


 * hsem (HEV) - input: The handle of an event semaphore that is to be posted when data is added to the queue and wait is set to 1.
 * This parameter is ignored if wait is set to 0.

The event semaphore may be shared or private, depending on whether the queue is shared across processes.

Note: The first time an event-semaphore handle is supplied in a DosReadQueue or DosPeekQueue request for which wait is set to 1, the handle is saved by the system. The same handle must be supplied in all subsequent DosReadQueue and DosPeekQueue requests that are issued for that queue.

Return Code

 * ulrc (APIRET) - returns:DosReadQueue returns one of the following values:
 * 0 NO_ERROR
 * 87 ERROR_INVALID_PARAMETER
 * 330 ERROR_QUE_PROC_NOT_OWNED
 * 333 ERROR_QUE_ELEMENT_NOT_EXIST
 * 337 ERROR_QUE_INVALID_HANDLE
 * 342 ERROR_QUE_EMPTY
 * 433 ERROR_QUE_INVALID_WAIT

Remarks
This function can be issued only by the server process and its threads.

If the wait parameter is set to 1, an event semaphore must be provided so that the calling thread can determine when an element has been placed into the queue. The semaphore is created by calling DosCreateEventSem, and its handle is supplied in the hsem parameter of DosReadQueue.

The first time an event-semaphore handle is supplied in a DosReadQueue or DosPeekQueue request for which wait has been set to 1, the handle is saved by the system. The same handle must be supplied in all subsequent DosReadQueue and DosPeekQueue requests that are issued for the same queue; if a different handle is supplied, ERROR_INVALID_PARAMETER is returned.

When a client process adds an element to the queue, the system automatically opens and posts the semaphore. The server can either issue DosQueryEventSem periodically to determine whether the semaphore has been posted, or it can issue DosWaitEventSem. DosWaitEventSem causes the calling thread to block until the semaphore is posted.

After the event semaphore has been posted, the calling thread must issue DosReadQueue again to remove the newly added queue element.

Related Functions

 * DosCloseQueue
 * DosCreateQueue
 * DosOpenQueue
 * DosPeekQueue
 * DosPurgeQueue
 * DosQueryQueue
 * DosWriteQueue