DosPeekQueue examines a queue element without removing it from the queue. This function can be used only by the queue's server process and its threads.

If the nowait 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 DosPeekQueue.

The first time an event-semaphore handle is supplied in a DosPeekQueue or DosReadQueue request for which nowait has been set to 1, the handle is saved by the system. The same handle must be supplied in all subsequent DosPeekQueue and DosReadQueue 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 call DosPeekQueue again to examine the newly added queue element.