The abstraction provided by the LayGO API is based on a finite state machine which implements a general model of data communication. The protocol layers map the general concepts in which the API state machine is expressed into the concrete terms defined by a protocol. All protocol-specific details of connection setup, data transfer and connection termination are handled automatically by the protocol layers.
The API state machine is driven by 2 kinds of control events:
Data also arrives in the form of data events, but these do not cause state machine transitions in the API.
A typical LayGO session has 7 phases:
Source code for a typical LayGO session can be found in dlaygo.c, part of the dlaygo sample program. This program builds a device consisting of an X.21 bis physical layer, an HDLC/LAPB link layer, and an X.25 network layer. An X.25 Permanent Virtual Circuit (PVC) is opened through which data is transferred. The device is then disconnected and disassembled. LayGO API function calls are prototyped in laygo.h. Types are defined in laygodef.h. laygomsg.h exports functions which access human-readable strings for error conditions and for other system information.
| Code | State |
|---|---|
| A0 | Closed |
| A1 | Open |
| A2 | Waiting for Remote Accept |
| A3 | Listening |
| A4 | Waiting for Local Accept |
| A5 | Data Transfer On |
| A6 | Data Transfer Xoff |
| A7 | Waiting for Reset Confirmation |
| A8 | Waiting for Remote Disconnect Confirmation |
| A9 | Waiting for Local Disconnect Confirmation |
State transitions are caused when the application calls a core function, when the application receives control events from a remote system, or through timeout and error conditions. The following control events are defined:
The state transitions are shown in Figures 3-2 through 3-5. Transitions
not shown are errors and are rejected by the API.
The API uses a single state machine for each device. The state machine handles all phases: opening/closing, connecting/disconnecting, writing/reading data. State dependencies between major and minor devices are handled at the protocol level, and not in the API. For instance, if a major device is disconnected, its minor devices are automatically disconnected.
In the CCITT X.25 packet level state machine, once the major device is connected, all minor devices using SVCs enter the Ready state (p1), and all minor devices using PVCs are entering the FlowControlReady state (d1). This scheme does not take into account that the application controlling the devices may not be ready to handle incoming calls or data. In the API model, after a device is successfully opened and configured, it must either initiate a connection or enter the listen state to wait for an incoming connect request. If the device is not in the listening state, an incoming connect request will either be ignored or refused by the protocol layer. There is no state in the API for collisions, they are resolved at the protocol level.
The API function lgo_State() returns the current state of the API on a connection. lgo_StateMessage() returns a human-readable string describing the state.
The application also receives data events and protocol message events, but these do not cause state transitions. The following data events are defined:
Protocol message events are reserved for protocol-specific events which have no affect on state and have no analogue in the API state machine. For instance, X.25 interrupt and interrupt confirmation packets are passed to the application as protocol message events.
For a detailed discussion of each API function and its return values, see the LayGO API Manual.