Skip to content. | Skip to navigation

Sections
You are here: Home content generated doc.free neda PLPC 110302 current main

ESROS

ESROS

ESROS
Application Programming Interface
Neda Document Number: 103-101-06.03
Last Updated: Author unspecified
Doc. Revision: source unspecified

Neda Communications, Inc.

January 27, 1999

Contents

List of Tables

List of Figures

©1999 Neda Communications, Inc.
All rights reserved.

IBM is a registered trademark of International Business Machines Corporation. Unix is a trademark of AT&T and Unix System Laboratories. Sun is a registered trademark and Sun Workstation is a trademark of Sun Microsystems, Inc. Windows is a registered trademark of Microsoft Corporation.

This document describes the Application Programming Interface for Efficient Short Remote Operation Services (ESROS).

Published by:

Neda Communications, Inc

17005 SE 31st Place

Bellevue, WA 98008

Permission is granted to make copy and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute translations of this manual into another language provided the copyright notice and this permission notice are preserved on all copies.

1 Introduction

1.1 About This API

This document defines the ESROS’ API. This definition conforms to RFC-2188 [?]. It is recommended that for this document to be of the most use to the reader, they should be familiar with RFC-2188[2] and Open C Platform [?].

Chapter 1 consists of an introduction to the API and the whole document.

Chapter 2 provides information about the interface to ESROS services.

Appendices include a Bibliography, a list of relevant Acronyms, ESROS API Example Usage, ESROS Program Man Pages.

1.2 Architecture



Figure 1: Implementation Architecture


Figure 1, depicts the architecture of the complete ESRO protocols. ESROS-Daemon is responsible for implementation of ESRO-Protocol (RFC-2188. [?]) on both invoker and performer sides. ESROS-Daemon exposes the ESROS API (see chapter entitled ESRO API) to its users.

This chapter provides information about the interface to ESROS services. It is intended for the users of the ESROS sublayer.

The ESROS API is available in two different styles. In the first case the events are made available to the user of the API through function calls. This is known as the Function Call API. Functions of this API implementation all have the ESRO_ prefix. In the second case ESROS events trigger call backs to functions registered by the user of the ESROS API. This is known as Call back API. Functions of this API implementation all have the ESRO_CB_ prefix, in which CB stands for Call Back.

1.3 ESRO Service Primitives

This section describes the service primitives provided by the ESROP module, and the constraints on the sequence in which the ESROP primitives may occur. Each ESROP-User interacts with the ESROP module through one or more ESROP-SAPs.

Table 1 is a list of ESRO service primitive names.



ESRO Service Primitives



ESROS-INVOKE.request

ESROS-INOVKE-P.confirm

ESROS-INVOKE.indication


ESROS-RESULT.request

ESROS-RESULT.indication

ESROS-RESULT.confirm


ESROS-ERROR.request

ESROS-ERROR.indication

ESROS-ERROR.confirm


ESROS-FAILURE.indication



Table 1: ESRO Service Primitives

The Neda ESROP upper interface conforms to the ESRO Service Definition [?]. The constraints on the sequence in which ESROP primitives may occur are explained in Reference [?].

1.3.1 SAP Management

An ESROP-User must create an ESROP-SAP before it can use any of the services provided by the ESROP module. Creation of an ESROP-SAP is accomplished through the ESROP_sapBind function. Parameters to ESROP_sapBind communicate to the ESROP module both an ESRO-SAP selector address and a set of functions for handling event primitives for that ESROP-SAP. ESROP event primitives are:

  • ESROS-INVOKE.indication
  • ESROS-RESULT.indication
  • ESROS-ERROR.indication
  • ESROS-FAILURE.indication

Deletion of an ESROP-SAP is accomplished through the ESROP_sapUnbind function. A summary of Neda ESROP-SAP management facilities follows.




Function

Description



ESROP_sapBind

Bind an ESROP-SAP and register an ESROP-User.



ESROP_sapUnbind

Unbind an ESROP-SAP and deregister an ESROP-User.




Table 2: ESROS-SAP Management

1.3.2 Operation Invocation

The sequence of ESROP primitives in an OPERATION is illustrated in the time sequence diagram below.



Figure 2: Time sequence diagram for ESRO Services


To initiate an ESROP operation, the invoker ESROP-User entity issues an ESROS-INVOKE.request at the ESROP layer interface by invoking the function ESROP_invokeReq. The performer ESROP entity’s ESROP-SAP is specified as one of the parameters of this action primitive.

The ESROS-INVOKE-P.confirm primitive is communicated to the invoker user through the return value/parameter of the ESROP_invokeReq function.

An ESROS-INVOKE.indication event primitive is generated at the performer ESROP entity’s ESROP-SAP through the invocation of the (*ESROP_invokeInd)() function associated with the performer ESROP-SAP.

The performer ESROP-User can accept the operation and communicate the results by generating an ESROS-RESULT.request at the ESROP layer interface by invoking the function ESROP_resultReq. The performer ESROP-User can issue an ESROS-ERROR.request by invoking the function ESROP_errorReq.

An ESROS-RESULT.confirm or ESROS-ERROR.confirm event primitive is generated at the performer ESROP entity ESROP-SAP through the invocation of the (*ESROP_resultCnf)() or (*ESROP_errorCnf)() function associated with the performer ESROP-SAP.

An ESROS-RESULT.indication or ESROS-ERROR.indication event primitive is generated at the invoker ESROP entity ESROP-SAP through the invocation of the (*ESROP_resultInd)() or (*ESROP_errorInd)() function associated with the invoker ESROP-SAP.

A summary of all operation primitives appears below in Table 3:





Service Primitive Name

Neda Function Name

Source







ESROESROS-INVOKE.request

ESROP_invokeReq()

Invoker user

ESROS-INVOKE-P.confirm

Ret Val of ESROP_invokeReq()

Provider

ESROS-INVOKE.indication

(*ESROP_invokeInd)()

Provider




ESROS-RESULT.request

ESROP_resultReq()

Performer user

ESROS-RESULT.indication

(*ESROP_resultInd)()

Provider

ESROS-RESULT.confirm

(*ESROP_resultCnf)()

Provider




ESROS-ERROR.request

ESROP_errorReq()

Performer user

ESROS-ERROR.indication

(*ESROP_errorInd)()

Provider

ESROS-ERROR.confirm

(*ESROP_errorCnf)()

Provider




ESROS-FAILURE.indication

(*ESROP_failureInd)()

Provider





Table 3: Service Primitives and corresponding functions

The OPERATION may fail due to either the inability of the ESROS provider to transmit the INVOKE PDU or the unwillingness of the ESROS performer user to accept an ESROS-INVOKE.indication. These cases are described later in this chapter. The OPERATION may also fail as a result of the failure in delivery of RESULT or ERROR PDU. In such cases an ESROS-FAILURE.indication event primitive is issued at the invoker or performer ESROP-SAP through the invocation of the (*ESROP_failureInd)() function.

1.4 ESROS With Function Call API

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.

1.4.1 Initialize the Parameters
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.

1.4.2 Activate ESROS Service Access Point

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.

1.4.3 Deactivate ESROS Service Access Point

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.

1.4.4 ESROS Invoke Service Request

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.

1.4.5 ESROS Result Service Request

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.

1.4.6 ESROS Error Service Request

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.

1.4.7 Get an event

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: ____________

1.4.8 Sample Code

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

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

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.



Figure 3: Example of time sequence diagram for ESROS Services


1.5 ESROS With Callback API

This section provides information about the callback API functions.

The services provided by the ESROS are defined in the ESROS Protocol Specification,”RFC-2188” [?]. 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

1.5.1 Initialize the Parameters
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.

1.5.2 Activate ESROS Service Access Point

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.

1.5.3 Deactivate ESROS Service Access Point

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.

1.5.4 ESROS Invoke Service Request

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 [?] 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.

1.5.5 ESROS Result Service Request

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.

1.5.6 ESROS Error Service Request

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.

1.5.7 Sample Code

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

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

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.



Figure 4: Example of time sequence diagram for ESROS CB Services


A Acronyms

ASN.1

Abstract Syntax Notation One (ASN.1)

FSM

ESROS Finite State Machine.

IP-Message

InterPersonal Message

ESROS

Efficient Short Remote Operation Services

ESROP

ESROS Protocol Engine

ESRO-SAP

ESROS Service Access Point.

MD

Management Domain

MH

Message Handling

MHS

Message Handling System

MS

Message Store

MT

Message Transfer

MTA

Message Transfer Agent

MTS

Message Transfer Service

SEQ_

Sequence Module

TMR_

Timer Management Module

TM_

Trace Module

DU_

Data Unit Management Module

B ESRO API Example Usage

B.1 invoker.c

B.2 invoksch.c

B.3 performer.c

B.4 perfsch.c

Document Actions
Libre/Halaal Internet Services Provided At LibreCenter By Neda

Member of By* Federation Of Autonomous Libre Services

This web site has been created based exclusively on the use of Halaal Software and Halaal Internet Application Services. It is part of the By* Federation of Autonomous Libre Services which in turn are part of the Halaal/Libre By* Digitial Ecosystem which incorporate the following software components: