StayLinked Application Programming Interface (API) Options

API Types

APIs are available within StayLinked in three different types.

• APIs are available within Screen Recognition. This is the most common use and primary area for implementing APIs.
• Starting in server version 15.3 there are session settings that include API options at the Start, Reconnection (requires server v15.5), Global (entire session duration), and End of any session.
• Lastly, there are screen-based APIs that required adjustments to a host application or script.

Screen Recognition APIs

Screen Recognition offers an APIs tab within the recognition event. See the Screen Recognition section for details about implementing these APIs within your user workflow based on screen contents from the emulation host.

Session Setting APIs

Start, Reconnect, and End APIs are limited use to the session state as defined in the name/type. Global APIs are available at any time within the session, often launched on-demand by users by mapping a key code to one of the Global API options.

Version 15.5 of the StayLinked Server increases the number of session APIs to 999, creates a new host input API, and includes the option for comma-separated APIs in the [*API XXX,XXX,XXX] mnemonic to perform multiple APIs in a single instruction.

Screen-Based Host APIs

This article contains general information about the screen-based APIs. Screen Recognition features can be used to implement most of these functions without adjustment of the host application design. Using StayLinked Screen Recognition does not detail each API, since the functions are identical, but the dialogues are described within the Screen Recognition articles. Some APIs are available only within Screen Recognition and no new text-based APIs are planned for addition in future releases.

This article describes the StayLinked Host APIs. This Application Programming Interface that can be accessed from your own Host application is an exclusive feature of the StayLinked product. An overview is provided, along with instructions for adding these powerful functions to your end-user applications. Detailed descriptions for each Host API are available in the article for those descriptions.

Overview of StayLinked Host API

Another benefit of the host-based StayLinked architecture is its ability to extend session control functions to your host applications. As simple as writing and reading display screens, these powerful APIs provide the following power to your end-user applications:

• Determine whether the device is actually running a StayLinked session
• Retrieve StayLinked session attributes like Device Type, IP Address, MAC Address, Device Name, Client Version, Display Rows and Columns, etc.
• Wirelessly transfer files to and from the devices (great for uploading batch data)
• Reboot, Restart, Disconnect and Terminate the session
• Send special, highly-visible messages to the device
• Send long, short or double beeps to the device
• Run remote commands and programs on the device
• Control the scanner on the device; enable and disable the laser and soft-trigger the scanner
• Send audible beeps to the device or cause the device to vibrate, if supported

Control the Speech engine on the device for Text-to-Speech and Voice Recognition functions

Using the StayLinked Host Application Programming Interface

This section will explain the steps necessary to integrate this powerful interface into your end-user applications.

How the Host APIs Work

The StayLinked Host APIs are accessed using special display screens to communicate with the host-based StayLinked Server. Most application screens are forward directly to the client device for display, but the special Host API screens are intercepted by the StayLinked Server before they are forwarded to the device for display. If the server identifies a screen as a Host API function request, it will interpret the data on the screen and then perform the requested function. You can control whether the actual screen is forwarded to the device for display or not. Once the server has completed the processing of the API function, the server can respond by sending the mnemonic ([enter]) to the screen (like you pressing the Enter key), or you can specify an alternate screen response if desired.

How Host API screens are recognized by the StayLinked Server

Each time your host application writes text to the screen, a ‘presentation space event’ will be transmitted to the Telnet Client inside the StayLinked Server. This ‘presentation space event’ will have a starting position and an ending position within the telnet screen area. These ‘presentation space events’ are triggered by the host application writing text to the screen and the starting and ending positions of the event can be presented differently, depending upon the telnet server, the hardware platform operating system and type of terminal emulation. In any case, it is the starting and ending positions that are used to determine if a Host API is to be processed or not.

When a ‘presentation space event’ is transmitted from the Telnet Server to the Telnet Client inside the StayLinked Server, the event will be analyzed to determine if this event spans the Host API column and row. If this event does contain the Host API column and row, then the server will look for the ‘API Identifier’ at that column and row. If the API identifier is found, then this ‘presentation space event’ will be handled as a StayLinked Host API screen. Now, the server will parse the API arguments from the screen and perform the desired function as dictated by the API identifier and arguments. The StayLinked Server can be configured to send this specific ‘presentation space event’ to the device for display, but typically, the Host API screens are not sent to the device. It depends upon your specific implementation for displaying the Host API and whether your methodology requires the screen to be displayed on the device or not.

You can configure these options to control how StayLinked Host APIs are recognized and processed. The default settings are:

Separator Character = 0x7E (~)
Host API Column = 2
Host API Row = 1
Show API Screens = false

After a Host API screen is processed by the StayLinked Server

It can be important for your host application to know when the StayLinked Server has finished processing the API function that you have requested. After the StayLinked Server recognizes and processes a Host API function, it will respond to your application by automatically pressing the Enter key. This is the default behavior of the StayLinked Server, but this response can be changed based upon the requirements of your application. If you would rather have the StayLinked Server respond to a Host API using, for example the F1 key, then you can specify this ‘optional response’ by adding an additional argument to the specific Host API screen.

Here is a Host API string for the ‘Display Message’ API with a default server response. In this example, the server will send the message to the device and then press Enter in the Telnet session.

~API04~Mr. Watson come here, I want to see you.~

Here is a Host API string for the ‘Display Message’ API with an optional server response of F1. In this example, the server will send the message to the device and then press F1 in the Telnet session.

~API04~Mr. Watson come here, I want to see you.~[pf1]~

The ‘optional response’ can be a script and can implement any mnemonic supported by StayLinked. Here is an example optional response that will type OK and send a carriage return.

~API04~Mr. Watson come here, I want to see you.~OK[hex 0D]~

If you want to prevent the StayLinked Server from providing any response at all, use the [null] mnemonic as the optional response. In this example, the server will send the message to the device and provide no response to the application.

~API04~Mr. Watson come here, I want to see you.~[null]~

There are some Host APIs that require a response from the server, so the following Host APIs do not support the ‘optional response’ feature.

• API01 – Retrieve Session Properties
• API02 – Send File to Device
• API03 – Retrieve File from Device
• API15 – Verify StayLinked

Host API Configuration Options

There are a few options that you can configure to control the behavior and processing of the StayLinked Host APIs. The options are available in the ‘Telnet Host Entry’ dialog in the ‘Host API Configuration’ section. If you open your ‘Telnet Host Group’ and then update one of the ‘Telnet Host Entries’ you will be presented with this dialog:

Separator Char
You can configure the screen character that the StayLinked Server will look for to identify the Host API String and to separate the arguments for the specific API command. The default separator character is a tilde (~) defined with an ASCII value of 0x7E in hexadecimal notation. If you must use a different separator character, then you can specify the ASCII value in hexadecimal notation.

Host API Row / Col
You can configure the row and column on the application screen where the StayLinked Server will look for the ‘API Identifier’ which always starts with the separator character (~). The default values are Row 1 and Column 2. If the server processes a ‘presentation space event’ that includes the specified row and column, then the server will look for the ‘API Identifier’ string at this location. The API Identifier string will start with a separator character (~), followed by the capital letters ‘API’ and then the  two-digit API Number. Here are some example API signatures: ~API01, ~API12, etc.

Show API
By checking this box, you can configure the Host API processing to cause the ‘presentation space event’ that includes a Host API to be displayed on the device if needed. The default for this setting is to NOT display any ‘presentation space event’ that includes a Host API. Depending upon how you have written the screen logic in your application and how you display Host APIs in your application, you may need to display Host API screens on the device or not.

A Sample Host API Screen

The various StayLinked Host APIs have different requirements – some need inputs, some provide outputs, some have both, and some have neither. But all of the API screens have one thing in common – a specific set of characters (~API##) at the top of the screen. This is the API Identifier which is used to identify the Host API screen to the StayLinked Server. The following screen sample illustrates an API that requires both inputs and outputs: