DosPeekQueue - Parameters

hq (HQUEUE) - input

The handle of the queue from which an element is to be examined.

pRequest (PREQUESTDATA) - output

A pointer to the REQUESTDATA in which PID and event codes are returned.

pcbData (PULONG) - output

A pointer to the length of the examined data.

This field is the same as the pcbData that was furnished by DosWriteQueue when the element was added to the queue.

ppbuf (PPVOID) - output

A pointer to the address of the element that is to be examined.

This field may or may not be the same as the ppbuf that was returned by DosWriteQueue when the element was added to the queue. If QUE_CONVERT_ADDRESS was specified when the queue was created, then the addresses of any elements that are written to the queue by the 16-bit DosWriteQueue function are converted to 32-bit addresses.

element (PULONG) - in/out

A pointer to an indicator that specifies whether to start at the beginning of the queue or at a particular element.

Possible values are described in the following list:

• Set by the application to indicate "examine 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

  Set by the DosPeekQueue function to identify the element that has been examined (output), or by the owner to indicate "examine the next element" (input).
  Note: By contrast, when a DosReadQueue request follows DosPeekQueue, DosReadQueue removes the same element that is identified by element, not the next element in the queue.

nowait (BOOL32) - input

The action to be performed when there are no elements in the queue.

Possible values are shown in the following list:

• DCWW_WAIT The requesting thread waits until an element is placed in the queue.

• DCWW_NOWAIT
  The requesting thread does not wait, and DosPeekQueue returns with ERROR_QUE_EMPTY.

ppriority (PBYTE) - output

A pointer to the element's priority value.

This is the value that was specified for ppriority when DosWriteQueue added the element to the queue. ppriority is a numeric 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 the data is added to the queue and nowait is set to 1.

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

hsem is ignored if nowait is set to 0.

Note: The first time an event-semaphore handle is supplied in a DosPeekQueue or DosReadQueue request for which nowait is 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 that queue.

ulrc (APIRET) - returns

Return Code.

DosPeekQueue returns one of the following values:

• NO_ERROR 87
  ERROR_INVALID_PARAMETER
  330
  ERROR_QUE_PROC_NOT_OWNED
  333
  ERROR_QUE_ELEMENT_NOT_EXIST
  337
  ERROR_QUE_INVALID_HANDLE
  340
  ERROR_QUE_PREV_AT_END
  342
  ERROR_QUE_EMPTY
  433
  ERROR_QUE_INVALID_WAIT
  For a full list of error codes, see Errors.

---

[Back: DosPeekQueue Return Value - ulrc]
[Next: DosPeekQueue - Remarks]