This section provides information about the Function Call API.
The services provided by the ESROS are defined in the ESROS Protocol Specification. The requests and responses are communicated via non-blocking function calls. Remote operation requests, and error and failure indications are communicated to the ESROS user via a call to the ESRO_getEvent function, which may be a blocking call in some implementations.
Remote operation requests, result, error and failure indications are delivered to the ESROS user in an event structure. The reader should consult the following chapters for information about the parameters which make up the structures.
The following subsections describe the ESROS library functions.
PUBLIC ESRO_RetVal ESRO_init (String configFileName)
The argument is defined as follows:
configFileName Config file name
configFileName specifies the config file name that contains ESROS initialization values.
The ESRO_sapBind function binds an ESRO Service Access Point (ESRO_SAP) to the current user process. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_sapBind(ESRO_SapDesc*sapDesc, /* out */ ESRO_SapSelsapSel ESRO_FunctionalUnitfunctionalUnit)
The arguments are defined as follows:
sapDesc Return value: the SAP descriptor sapSel SAP selector functionalUnitHandshaking type
sapDesc is a pointer to an ESRO_SapDesc structure that is created for the current user.
sapSel identifies the ESROS SAP. If the SAP is in use by another user the function returns an error value.
functionalUnit specifies the type of handshaking that is in effect for the SAP. ESRO_2Way specifies two-way handshaking. ESRO_3Way specifies three-way handshaking. In order for ESROS user processes to interact with one another over a network, they must specify local SAPs that use the same type of handshaking. Furthermore, once a SAP is created the handshaking type stays in effect until the SAP is released. Once an ESRO-SAP has been activated, the user process can use the services provided by ESROS sublayer.
The function returns zero if successful, otherwise it returns a nonzero error value.
The ESRO_sapUnbind function deactivates the ESROs service access point which is currently in use. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_sapUnbind(ESRO_SapSel sapSel)
The argument is defined as follows:
sapSel SAP selector
sapSel identifies the ESROS SAP which is already in use.
The function would return 0 if successful, and a nonzero error value otherwise.
The ESRO_invokeReq function requests a remote operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_invokeReq( ESRO_InvokeId*invokeId,/* out */ ESRO_UserInvokeRefuserInvokeRef, ESRO_SapDesclocSapDesc, ESRO_SapSelremESROSap, T_SapSel*remTsap, N_SapAddr*remNsap, ESRO_OperationValueopValue, ESRO_EncodingTypeencodingType, IntparameterLen, Byte*parameter)
The input arguments are defined as follows:
invokeId Return value: invocation identifier userInvokeRef User's invocation reference locSapDesc The local SAP descriptor remESROSap Remote network SAP address remTsap Remote Transport SAP. remNsap The remote SAP selector opValue Operation value encodingType Encoding type parameterLen The length of the parameter parameter The address of the parameter buffer.
invokeId is assigned by ESROS sublayer. It is returned by ESROS sublayer. This identifier is used in future communications between ESROS sublayer and service user to identify the invocation for ESROS sublayer.
userInvokeRef is assigned by ESROS user. It is passed to ESROS sublayer by the user of service. This identifier is used in future communications between ESROS sublayer and service user to identify the invocation for the user of ESROS.
locSapDesc is the local SAP descriptor which is provided by ESROS sublayer at the time of SAP bind.
If ESROS can serve the invoker, the function returns 0 and the invocation identifier is returned through the invokeId parameter. If ESROS cannot serve the invoker, the function returns a nonzero failure reason value.
The ESRO_resultReq function is issued by the performer of the operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_resultReq( ESRO_InvokeIdinvokeId, ESRO_UserInvokeRefuserInvokeRef, ESRO_EncodingTypeencodingType, IntparameterLen, Byte*parameter)
The input arguments are defined as follows:
invokeId Invocation Identifier. userInvokeRef User's invocation reference encodingType Encoding type parameterLen Length of the parameter parameter Address of the parameter buffer.
This primitive should be issued after an ESRO_INVOKEIND event. If ESROS cannot serve the requestor, the function returns a nonzero reason value which is the failure value.
The ESRO_errorReq function is issued by the performer of the operation in case of error in performing the operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_errorReq( ESRO_InvokeIdinvokeId, ESRO_UserInvokeRefuserInvokeRef, ESRO_EncodingTypeencodingType, ESRO_ErrorValueerrorValue, IntparameterLen, Byte*parameter)
The input arguments are defined as follows:
invokeId The Invocation Identifier. userInvokeRef User's invocation reference encodingType Encoding type errorValue Identifies the nature of the error. parameterLen The length of the parameter parameter String describing the error.
This primitive should be issued after a INVOKEIND event. If esros cannot serve the requestor, the function returns a negative value which is the failure value.
If any event has occurred in ESROS sublayer, the ESRO_getEvent function gets the event(s). Based on the value of wait, it either waits for and event (if no event available) or immediately returns.
PUBLIC ESRO_RetVal ESRO_getEvent( ESRO_SapDesc sapDesc, ESRO_Event *event, Bool wait)
The input arguments are defined as follows:
sapDesc Return value: the SAP descriptor event ESROS event wait Blocking/non-blocking flag
The function returns any of the following event codes as the corresponding events are detected:
ESRO_INVOKEIND Remote user is requesting an operation ESRO_FAILUREIND Operation has failed ESRO_RESULTIND ESRO-RESULT-PDU recieved ESRO_ERRORIND ESRO-ERROR-PDU received ESRO_RESULTCNF ESROS RESULT confirm ESRO_ERRORCNF ESROS ERROR confirm
The function returns negative error number if unsuccessful, or the number of events (0 or greater than 0).
The data structures of ESROS events and the corresponding event codes are listed below:
Click here to see the complete codes.
The code fragments described in the following sections illustrate the steps required to create a ESRO service access point, and invoke and perform an operation. They are patterned after the primitives of the time sequence in , Example of time sequence diagram for ESROS Services. The code fragments themselves are listed in , ESRO API Example Usage. The code sample "invoker.c" implements the left side, and the code sample "performer.c" implements the right side.
invoker.c first establishes a SAP, then issues an ESRO_invokeReq of a shell command operation. In this example, the command operation is "date". It receives a confirmation (ESROESRO_ResultInd) indicating that the operation was performed. It then retrieves the results which are communicated through the ESRO_ResultInd.
performer.c receives the ESRO_InvokeInd of a "date" command operation in the struct ESRO_InvokeInd. The result of the command is the system date which is returned to invoker.c through ESRO_resultReq. performer.c then waits for the next request from invoker.c.
