sl_receive_request subroutine

Purpose

Receive a request primitive from the signaling interface.

Library

The signaling interface library (libsl.a).

C syntax

#include <slsigpr.h> 
... 
SL_RET_CODE 	           sl_receive_request(
    SL_HANDLE        	  sl_handle,
    int                	timeout,
    SL_REQUEST_ST *     psignalingRequest
);

Description

This subroutine is used by a signaling process to receive a request primitive from the signaling interface. The subroutine can be used in different ways, depending on the value of the timeout parameter specified:

The signaling process can use the poll() system call to detect the arrival of a request primitive, specifying the message queue identifier returned from the sl_register() subroutine. The signaling process must then receive the primitive by specifying a timeout of 0.
The signaling process can specify a positive timeout to block until a request is available or a timeout occurs.
The signaling process can specify a negative timeout for an indefinite wait.

If the return value is SLRC_OK, the request primitive is returned in the structure pointed to by psignalingRequest.

After processing the request primitive, the signaling process must use the sl_send_confirm() subroutine to return the result to the channel process or custom server. If the primitive fails or is not implemented, report this by using the sl_send_confirm() subroutine to send a confirm primitive with the ReplyCode field set to indicate the failure.

Parameters

sl_handle

The signaling handle returned by the sl_open() subroutine.

timeout

> 0: How long to wait, in seconds, if there is no primitive available.
= 0: The subroutine should return immediately if no primitive is available.
< 0: The subroutine should not return until a primitive is available.

psignaling

Pointer to the request primitive structure. This is filled in with the received primitive only if the function returns SLRC_OK.

Return values

SLRC_OK: Successful.
SLRC_INVALID_HANDLE: Invalid sl_handle.
SLRC_INVALID_ARGS: Invalid parameter: psignalingRequest=NULL.
SLRC_INTERNAL_ERROR: An internal error occurred in the signaling interface.
SLRC_NO_DATA: There is no outstanding request primitive for the signaling process.
SLRC_NOT_REGISTERED: The signaling process has not registered with the signaling interface, by using the sl_register() subroutine.
SLRC_ERRNO: An AIX error has occurred. Check the value of errno for more information.
SLRC_TIMEOUT: No primitive was received before the timeout expired.
SLRC_INTERRUPT: A system call was interrupted. Retry the call.