The API State Machine

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:

User events
Generated when API functions are called by the application.
Protocol events
Triggered by protocol messages from a layer's peer on a remote system.

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:

  1. Configuring and initializing the stack
  2. Opening and stacking protocol services
  3. Connecting each protocol layer, bringing them all into data transfer state
  4. Transferring data using the highest layer protocol
  5. Disconnecting each protocol layer, bringing them all back into the open state
  6. Unstacking and closing the protocol services
  7. Uninitializing the stack

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.

A2Waiting for Remote Accept
A4Waiting for Local Accept
A5Data Transfer On
A6Data Transfer Xoff
A7Waiting for Reset Confirmation
A8Waiting for Remote Disconnect Confirmation
A9Waiting for Local Disconnect Confirmation
Table 3-1 States of the LayGO API finite state machine

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.

State Machine
Figure 3-2 API State machine
with transitions to establish a connection
State Machine
Figure 3-3 API Flow Control state machine
with transitions caused by Xoff/Xon
State Machine
Figure 3-4 API Reset Request state machine
with transitions caused by Reset Request
State Machine
Figure 3-5 API Disconnect Request state machine
with transitions caused by Disconnect Request

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.