DosReadQueue reads (removes) an element from a queue. 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.


[Back] [Next]