LinPac - Packet Radio Terminal for Linux

External Application Programming Guide

1 Introduction

2 What is an external program?

3 Basic concepts of the API

4 How applications communicate with LinPac

5 Using the application library
5.1 The simplest application

6 Application programming
6.1 Events
6.2 Sending and receiving events
6.3 Synchronization
6.4 Shared variables and configuration
6.5 Connection status
6.6 Event usage examples
6.6.1 Connecting to a remote station
6.6.2 Using LinPac commands in programs

7 The application library interface
7.1 Constants
7.2 Data structures
7.3 Functions
7.3.1 Uninterruptable versions of some system calls
7.3.2 Basic communication functions
7.3.3 Automatic event handling functions
7.3.4 Environment functions
7.3.5 User functions
7.3.6 Tool functions
7.3.7 Application information functions

8 The shell interface
8.1 Writing the script
8.1.1 Ensuring that LinPac is running
8.1.2 Accessing configuration and state
8.1.3 Executing commands
8.1.4 Simple shell example
8.2 Creating the command

1 Introduction

2 What is an external program?

• Standard Linux applications that use standard input and output streams. These programs can be used without LinPac too. LinPac allows redirection of the input stream (stdin) of the application and any of the output streams (stdout, stderr) or both of them. LinPac can also provide CR/LF conversions in these streams. These parameters are set when adding the external program to LinPac - see Section 7, "Creating new commands", in the User Manual.
• Applications written using LinPac's application interface. These applications can share some information with LinPac, and they can control almost all functions of LinPac.

3 Basic concepts of the API

All the events generated by any object are put into the common event queue. The LinPac kernel simply takes the events from the queue one by one and sends them to all the objects (including the one that generated the event). Thus each event generated by any part of LinPac is forwarded to all of the objects. The reaction of each object fully depends on its functionality, but of course it can include generation of other events.

The list of LinPac internal objects and their names can be found in the file objects.txt.

An additional feature of the API is a shared variable environment. This is a set of variables that is shared with LinPac; the values are automatically synchronized with all the external programs. These variables are accessed using special functions of the API as described below.

4 How applications communicate with LinPac

• The application is started by LinPac, through being associated with a LinPac command. In this case LinPac registers the channel on which the application was started and expects the connection attempt from the application. After the application initializes and contacts LinPac, it is provided with the working channel and whether it was started by a remote or local user. LinPac may also redirect the input and output streams of the application (depending upon LinPac settings).
• The application is started without using LinPac. In this case LinPac assumes that the application runs on channel 0 and was started by the local user. The input and output streams of the application are not redirected.

NOTE: All of the communication via TCP/IP sockets is provided by the LinPac application library. The user application should not attempt to access the sockets directly.

5 Using the application library

5.1 The simplest application

#include <stdio.h>
#include <unistd.h>
#include <linpac/lpapp.h>

int main()
{
    if (lp_start_appl())
    {
        printf("Application started\n");
        sleep(10);
        printf("Application finished\n");
        lp_end_appl();
    }
    else
    {
        printf("LinPac is not running\n");
        return 1;
    }
    return 0;
}

The function lp_start_appl() tries to contact LinPac and returns 1 in case of success or 0 when a connection to LinPac cannot be made (probably because it's not running). This function should precede the usage of any other application library functions.

The function lp_end_appl() closes the connection to LinPac.

To compile this example, use:

$ gcc -o test1 test1.c -llinpac

This example just detects if LinPac is running, and it can be executed directly from the shell. When running from the shell, no streams are redirected to LinPac, and the application appears to run on channel 0 of LinPac. This is useful for some applications that are used to control LinPac from outside. However this is not a typical use case.

For most applications, it is better to copy the executable to the $LINPACDIR/bin directory and then add it to the file $LINPACDIR/bin/commands as described in the User Manual. After this, the application can be executed as a LinPac command. In this scenario, the streams are properly redirected and the application output is visible in the LinPac QSO window. It is also possible to select the channel on which to run the application.

NOTE: The LinPac application library (liblinpac) can be linked without problems with both C and C++ code.

6 Application programming

6.1 Events

An event is represented by the following structure:

struct Event
{
    int type;
    int chn;
    int x,y;
    char ch;
    void *data;
};

The meaning of each field is as follows: