This section provides information about the callback API functions.
The services provided by the ESROS are defined in the ESROS Protocol Specification,"RFC-2188" [2]. The requests are issued through function calls. Callback functions associated with ESROS events are passed to ESROS at the time of sapBind function call.
The following subsections describe the ESROS library functions
PUBLIC ESRO_RetVal ESRO_CB_init (String configFileName)
The argument is defined as follows:
configFileName Config file name
configFileName specifies the config file name that contains ESROS initialization parameters.
The ESRO_CB_sapBind function binds an ESRO Service Access Point (ESRO_SAP) for the current user process. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_CB_sapBind( ESRO_SapDesc *sapDesc, ESRO_SapSel sapSel, ESRO_FunctionalUnit functionalUnit, int (*invokeInd)( ESRO_SapDesc locSapDesc, ESRO_SapSel remESROSap, T_SapSel *remTsap, N_SapAddr *remNsap, ESRO_InvokeId invokeId, ESRO_OperationValue opValue, ESRO_EncodingType encodingType, DU_View parameter), int (*resultInd) ( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef, ESRO_EncodingType encodingType, DU_View parameter), int (*errorInd) ( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef, ESRO_EncodingType encodingType, ESRO_ErrorValue errorValue, DU_View parameter), int (*resultCnf)( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef), int (*errorCnf) ( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef), int (*failureInd)( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef, ESRO_FailureValue failureValue))
The input arguments are defined as follows:
sapDesc Local SAP descriptor (outgoing param) sapSel Local SAP selector functionalUnit Handshaking type locSapDesc Local SAP descriptor remESROSap Remote network SAP address remTsap Rmote Transport SAP. remNsap The remote SAP selector invokeId Invocation identifier userInvokeRef User's invocation reference opValue Operation value encodingType Encoding type errorValue Error value failureValue Failure value parameter parameter. (*invokeInd)() Invoke indication function (*resultInd)() Result indication function (*errorInd)() Error indication function (*resultCnf)() Result confirmation function (*errorCnf)() Error confirmation function (*failureInd)() Failure indication function
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.
After its ESRO-SAP has been activated, the user process can use the services provided by ESROS.
The function returns zero if successful, otherwise it returns a nonzero error value.
The ESRO_CB_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_CB_invokeReq function requests a remote operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_CB_invokeReq( ESRO_InvokeId *invokeId,/* out */ ESRO_UserInvokeRef userInvokeRef, ESRO_SapDesc locSapDesc, ESRO_SapSel remESROSap, T_SapSel *remTsap, N_SapAddr *remNsap, ESRO_OperationValue opValue, ESRO_EncodingType encodingType, DU_View 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 Rmote Transport SAP remNsap The remote SAP selector opValue Operation value encodingType Encoding type parameter user data
invokeId is assigned by ESROS sublayer. It is returned by ESROS sublayer and identifies an invocation for 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.
parameter is a pointer to a DU_view data structure into which user data was previously copied. Refer to the Open C Platform document [1] for a discussion of the DU_ module.
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_CB_resultReq function is issued by the performer of the operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_CB_resultReq( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef, ESRO_EncodingType encodingType, DU_View parameter)
The input arguments are defined as follows:
invokeId invocation Identifier userInvokeRef User's invocation reference encodingType Encoding type parameter Parameter.
This primitive should be issued after invokeInd function is called. If ESROS cannot serve the requestor, the function returns a nonzero reason value which is the failure value.
The ESRO_CB_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_CB_errorReq( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef, ESRO_EncodingType encodingType, ESRO_ErrorValue errorValue, DU_View parameter)
The input arguments are defined as follows:
invokeId The Invocation Identifier userInvokeRef User's invocation reference encodingType Encoding type errorValue Error value parameter Parameter.
This primitive should be issued after invokeInd function is called. If ESROS cannot serve the requestor, the function returns a negative value which is the failure value.
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 CB Services. The code fragments themselves are listed in , ESRO API Example Usage. The code sample "invoksch.c" implements the left side, and the code sample "perfsch.c" implements the right side.
invoksch.c first establishes a SAP, then issues an ESRO_invokeReq of a shell command operation. In this example, the command operation is "date". The resultInd function is called indicating that the operation was performed and the result is passed to it through data parameter.
perfsch.c establishes a SAP and waits for a request from invoksch.c. The invokeInd function is called when the request for a command operation arrives. The result of the "date" command is the system date. perfsch.c then returns the data to invoksch.c through ESRO_resultReq. perfsch.c then waits for the next request from invoksch.c.
