Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSQUEUES
 
USHORT DosPeekQueue(hqueue, pqresc, pcbElement, ppv, pusElementCode,
    fWait, pbElemPrty, hsem)
HQUEUE hqueue;           /* handle of queue to read from                  */
PQUEUERESULT pqresc;     /* pointer to structure for PID and request code */
PUSHORT pcbElement;      /* pointer to variable for element size          */
PVOID FAR * ppv;         /* pointer to buffer for element received        */
PUSHORT pusElementCode;  /* pointer to variable for element position      */
UCHAR fWait;             /* wait/no wait indicator                        */
PBYTE pbElemPrty;        /* pointer to variable for priority of element   */
ULONG hsem;              /* semaphore handle                              */
 
The DosPeekQueue function retrieves an element without removing it from a
queue. It copies the address of the element to a pointer and fills a
structure with information about the element.
 
Parameter       Description
────────────────────────────────────────────────────────────────────────────
 
hqueue          Identifies the queue to read from. This handle must have
                been created or opened by using the DosCreateQueue or
                DosOpenQueue function.
 
pqresc          Points to the QUEUERESULT structure that receives
                information about the request.
 
pcbElement      Points to the variable that receives the length (in bytes)
                of the element.
 
ppv             Points to the pointer that receives the address of the
                element in the queue.
 
pusElementCode  Points to the variable that specifies where to look in the
                queue for the element. If this parameter is 0x0000, the
                function looks at the beginning of the queue. Otherwise, the
                function assumes the value is an element identifier and
                looks for the element that immediately follows the specified
                element. When the function returns, it copies the identifier
                of the retrieved element to the variable. The element
                identifier can then be used to search for the next element
                or to read the given element from the queue.
 
fWait           Specifies whether the function should wait for an element to
                be placed in the queue, if the queue is empty. If this
                parameter is DCWW_WAIT, the function waits until an element
                is available. If this parameter is DCWW_NOWAIT, the function
                returns immediately.
 
pbElemPrty      Points to the variable that receives the priority value
                specified when the element was added to the queue. This is a
                value in the range 0 through 15; 15 indicates the highest
                priority.
 
hsem            Identifies a semaphore. This value can be the handle of a
                system semaphore that has been created or opened by using
                the DosCreateSem or DosOpenSem function, or it can be the
                address of a RAM semaphore. This semaphore would typically
                be used in a call to the DosMuxSemWait function to wait
                until the queue has an element. If the fWait parameter is
                DCWW_WAIT, hsem is ignored.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_QUE_ELEMENT_NOT_EXIST
     ERROR_QUE_EMPTY
     ERROR_QUE_INVALID_HANDLE
     ERROR_QUE_INVALID_WAIT
     ERROR_QUE_PROC_NOT_OWNED
 
Comments
 
If the queue is empty, the DosPeekQueue function either returns immediately
or waits for an element to be written to the queue, depending on the value
of the fWait parameter.
 
Only the process that created the queue may call the DosPeekQueue function.
 
See Also
 
DosCreateQueue, DosCreateSem, DosMuxSemWait, DosOpenSem, DosOpenQueue,
DosReadQueue, QUEUERESULT
 
                                      ♦