1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; I; Linux 2.2.17 i586) [Netscape]">
<title>LinPac Extrenal Application Programming Guide</title>
</head>
<body>
<center>
<h1>
LinPac - Packet Radio Terminal for Linux
<hr WIDTH="100%"></h1></center>
<center>Version 0.16
<p>(c) 1998 - 2001 by Radek Burget OK2JBG</center>
<p><br>
<center>
<h2>
Extrenal Application Programming Guide</h2></center>
<b>Contents</b>
<p>1 <a href="#POS1">Introduction</a>
<p>2 <a href="#POS2">What is an extrenal program</a>
<p>3 <a href="#POS3">Basic concepts of the API</a>
<p>4 <a href="#POS4">How do applications communicate with LinPac</a>
<p>5 <a href="#POS5">Using the application library</a>
<br>5.1 <a href="#POS5_1">The simplest application</a>
<p>6 <a href="#POS6">Application programming</a>
<br>6.1 <a href="#POS6_1">Events</a>
<br>6.2 <a href="#POS6_2">Sending and receiving events</a>
<br>6.3 <a href="#POS6_3">Synchronization</a>
<br>6.4 <a href="#POS6_4">Shared variables and configuration</a>
<br>6.5 <a href="#POS6_5">Connection status</a>
<br>6.6 <a href="#POS6_6">Event usage examples</a>
<br>6.6.1 <a href="#POS6_6_1">Connecting a remote station</a>
<br>6.6.2 <a href="#POS6_6_2">Using LinPac commands in programs</a>
<p>7 <a href="#POS7">The application library interface</a>
<br>7.1 <a href="#POS7_1">Constants</a>
<br>7.2 <a href="#POS7_2">Data structures</a>
<br>7.3 <a href="#POS7_3">Functions</a>
<br>7.3.1 <a href="#POS7_3_1">Uninterruptable versions of some system calls</a>
<br>7.3.2 <a href="#POS7_3_2">Basic communication functions</a>
<br>7.3.3 <a href="#POS7_3_3">Automatic event handling functions</a>
<br>7.3.4 <a href="#POS7_3_4">Environment functions</a>
<br>7.3.5 <a href="#POS7_3_5">User functions</a>
<br>7.3.6 <a href="#POS7_3_6">Tool functions</a>
<br>7.3.7 <a href="#POS7_3_7">Application information functions</a>
<br>
<p><a NAME="POS1"></a>
<h2>
1 Introduction</h2>
This guide is written for the programmers who want to add some new functions
to LinPac. In following text the basic knowledge about Linux programming
is assumed. It's also recommended to read the user manual first.
<br>
<p><a NAME="POS2"></a>
<h2>
2 What is an external program</h2>
An external program is a standard Linux application which uses LinPac to
communicate with remote station. There are basicaly two types of LinPac
external programs:
<ul>
<li>
Standard Linux applications that use standard input and output streams.
This programs can be used without LinPac too. LinPac allows redirect ion
of the input stream (stdin) of the application and any of the output streams
(stdout, stderr) or both of them. LinPac can also provide the CR/LF conversions
in this streams. This parametres are set when adding the external program
to LinPac - see the <a href="manual.html#POS7">section 7</a> "Creating
new commands" in the user manual.</li>
<li>
Application written using the application interface of LinPac. This applications
can share some information with LinPac and they can control almost all
functions of LinPac.</li>
</ul>
No special knowledge about LinPac is needed for creating the first type
of programs because no LinPac functions are used. Following sections of
this guide are dedicated to the second type of applications.
<br>
<p><a NAME="POS3"></a>
<h2>
3 Basic concepts of the API</h2>
The application interface of LinPac is based on <i>events</i>. Every action
in LinPac such as pressing a key, receiving a data, executing a command,
etc. is represented by a data structure called <i>event</i> which describes
what exactly happened. LinPac's internal structure consists of separate
<i>objects
</i>which
communicate with each other using the events. Each object provides its
own functionality, it often generates events - e.g. the object <b>Keyscan</b>
produces an event each time any key is pressed.
<p>All the events generated by any object are put to the common <i>event
queue</i>. 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 <b>each event generated by any part of LinPac is forwarded
to all the objects</b>. The reaction of each object fully depends on its
functionality but of course it can include generation of another events.
<p>The list of LinPac internal objects and their names can be found in
the file <tt><a href="objects.txt">objects.txt</a></tt>.
<p>An additional feature of the API is shared variable environment. This
is a set of variables that are shared with linpac - their values are automaticaly
synchronized in all the external programs. These variables are accessed
using special functions of interface library as described below.
<br>
<p><a NAME="POS4"></a>
<h2>
4 How do applications communicate with LinPac</h2>
LinPac uses the TCP/IP sockets for the communication with the external
programs (applications). The connection is always initiated by the application
after it starts. There are basicaly two ways how the application is started:
<ol>
<li>
The application is started by LinPac (it is associated to some LinPac command).
In this case LinPac registers the channel where the application was started
and expects the connection attempt from the application. After the application
initializes and contacts LinPac, it is told the working channel and whether
it was started by remote or local user. LinPac may also redirect the input
and output streams of the application (depends on LinPac settings).</li>
<li>
The application is started without using LinPac. In this case LinPac assumes
that the application runs on channel 0 and was started by local user. The
input and output streams of the application are not redirected.</li>
</ol>
In both cases the start of an application causes the creation of a new
object in LinPac called <i>event gate</i>. This object represents the application
within LinPac. Considering previous chapter it means that the application
is forwarded all the events generated by any LinPac object and all the
events generated by an application are forwarded to all the objects.
<p><b>NOTE: </b>All the communication via TCP/IP sockets is provided by
the LinPac application library. The user application shouldn't access the
sockets directly.
<br>
<p><a NAME="POS5"></a>
<h2>
5 Using the application library</h2>
During LinPac installation the application library <tt>liblinpac</tt> is
created and installed by default to <tt>/usr/local/lib</tt>. The interface
to this library is contained in the files <tt>lpapp.h</tt> and it's installed
by default to <tt>/usr/local/include/linpac</tt>. Next chapter shows how
to use the library with the user program.
<p><a NAME="POS5_1"></a>
<h3>
5.1 The simplest application</h3>
Following application example just tries to contact LinPac and prints the
result.
<p><tt>---------------------------- File test1.c ---------------------------</tt>
<br><tt>#include <stdio.h></tt>
<br><tt>#include <unistd.h></tt>
<br><tt>#include <linpac/lpapp.h></tt>
<p><tt>int main()</tt>
<br><tt>{</tt>
<br><tt> if (lp_start_appl())</tt>
<br><tt> {</tt>
<br><tt> printf("Application started\n");</tt>
<br><tt> sleep(10);</tt>
<br><tt> printf("Application finished\n");</tt>
<br><tt> lp_end_appl();</tt>
<br><tt> }</tt>
<br><tt> else</tt>
<br><tt> {</tt>
<br><tt> printf("LinPac is not running\n");</tt>
<br><tt> return 1;</tt>
<br><tt> }</tt>
<p><tt> return 0;</tt>
<br><tt>}</tt>
<p><tt>-----------------------------------------------------------------</tt>
<p>The function <tt>lp_start_appl()</tt> tries to contact LinPac and returns
<b>1</b>
in case of succes or <b>0</b> when LinPac cannot be connected (probably
it's not running). This function should precede the usage of any other
application library function.
<p>The function <tt>lp_end_appl()</tt> closes the connection to LinPac.
<p>How to compile this example:
<p><tt>gcc -o test1 test1.c -llinpac</tt>
<p>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 seems to run on channel 0 of LinPac. It's
useful for some applications that are used to control linpac from outside.
However it's not a typical case.
<p>For most of the applications it's better to copy the executable to the
<tt>$LINPACDIR/bin</tt>
directory and add it to the file
<br><tt>$LINPACDIR/bin/commands</tt> as described in the <a href="manual.html">user
manual</a>. After this the application can be executed as the LinPac command.
In this case the streams are properly redirected and the application output
is visible in LinPac window. It's also possible to select the channel for
running the application.
<p><b>NOTE:</b> the LinPac application library (<b>liblinpac</b>) can be
linked without problems with both C and C++ code.
<br>
<p><a NAME="POS6"></a>
<h2>
6 Application programming</h2>
<a NAME="POS6_1"></a>
<h3>
6.1 Events</h3>
LinPac is completely driven by events. Each part of LinPac including the
application can generate the event to inform other parts (internal modules
or applications) that something has happend. Each event is sent to all
LinPac components and application. For example when some station connects
to some LinPac channel, the internal AX.25 interface generates the event
reporting that the station has connected and includes its callsign. All
components and applications now know who has connected and they can do
some actions (the output window prints the information about the connect,
the macro processor executes the cinit.mac macro ...). Each application
can handle all the events too and it can generate events which are handled
by other components.
<p>The event is represented by the following structure:
<p><tt>struct Event</tt>
<br><tt>{</tt>
<br><tt> int type;</tt>
<br><tt> int chn;</tt>
<br><tt> int x,y;</tt>
<br><tt> char ch;</tt>
<br><tt> void *data;</tt>
<br><tt>};</tt>
<p>The meaning of each field is following:
<p><b><tt>type</tt></b> - Determines the type of the event. Actually it
says what happend. There is a symbolic constant defined for each known
event.
<br><b><tt>chn</tt></b> - It says the channel for which the event applies
(for example if the type of the event reports some data received, the chn
field contains the number of the channel which has received data). There
are many events that apply for all the channels. For this events this field
is not significant.
<br><b><tt>x</tt></b>, <b><tt>y</tt></b> - The meaning of field depends
on the event type. The y field is usually not used (it's used by some internale
events only).
<br><b><tt>ch</tt></b> - This field is used by some internal events only.
<br><b><tt>data</tt></b> - Depends on the type of the event too. It usually
points to some string data or a char buffer.
<p>All the event types are described in the <a href="events.txt">event
list</a>.
<p><a NAME="POS6_2"></a>
<h3>
6.2 Sending and receiving events</h3>
For sending events the function
<p><tt>int lp_emit_event(int chn, int type, int x, void *data);</tt>
<p>is used. This generates new event using specified values. Each argument
corresponds with one of the fields in the Event structure.
<p>There are two modes of handling the incomming events:
<p><b><i>a) Reading each event on demand</i></b>
<br>This mode is started by the <tt>lp_event_handling_off()</tt> call.
In this mode events are read using the function
<p><tt>int get_event(Event *ev);</tt>
<p>This function returns 0 when no event is available. When there is some
event available, it returns 1 and fills the Event structure with the received
event data.
<p><b>WARNING1</b>: The <tt>data</tt> field in your Event structure must
point to some dynamicaly allocated buffer. The size of the buffer is reallocated
automaticaly after receiving an event. When the <tt>data</tt> field is
set to NULL, new buffer is allocated. This field <u>must not be uninitialized</u>.
<p><b>WARNING2</b>: The application <u>must</u> read all events in this
mode. It's not a good idea to stop reading the events because the event
queue can overflow. LinPac automatically kills the application when the
event queue exceeds some reasonable number of events.
<p><b><i>b) Automatical event processing</i></b>
<br>This mode is started by the <tt>lp_event_handling_on()</tt> call. All
the events are read automaticaly. The user can define his own function
that is called automaticaly when an event occurs. When there's no such
function defined, all events are discarted.
<p>The event handling function must have following prototype:
<p><tt>void some_function(Event *ev);</tt>
<p>(the function name can be different). After initializing the application
the event handling function must be registered using the function <tt>lp_set_event_handler(</tt>)
from the apllication library.
<p>Following example is an application that prints the types of all events
received and stops when an event <tt>EV_ABORT</tt> is received. This event
can be generated using the <tt>:ABort</tt> command in LinPac.
<p><tt>---------------------------------------------------------------------------</tt>
<br><tt>#include <stdio.h></tt>
<br><tt>#include <linpac/lpapp.h></tt>
<p><tt>int aborted = 0;</tt>
<p><tt>//User event handling function. This function is called each time</tt>
<br><tt>//an event occurs</tt>
<br><tt>void my_event_handler(Event *ev)</tt>
<br><tt>{</tt>
<br><tt> printf("The event of type %i has been received\n", ev->type);</tt>
<br><tt> if (ev->type == EV_ABORT) aborted = 1;</tt>
<br><tt>}</tt>
<p><tt>int main()</tt>
<br><tt>{</tt>
<br><tt> if (lp_start_appl())</tt>
<br><tt> {</tt>
<br><tt> lp_event_handling_on(); //turn on automatical
event handling</tt>
<br><tt> lp_set_event_handler(my_event_handler); //define
own event handler</tt>
<p><tt> printf("Application started\n");</tt>
<br><tt> printf("Stop with the ':Abort' command\n");</tt>
<p><tt> do ; while(!aborted); //wait until application
is aborted</tt>
<p><tt> printf("Application finished\n");</tt>
<p><tt> lp_end_appl();</tt>
<br><tt> }</tt>
<br><tt> else</tt>
<br><tt> {</tt>
<br><tt> printf("LinPac is not running\n");</tt>
<br><tt> return 1;</tt>
<br><tt> }</tt>
<p><tt> return 0;</tt>
<br><tt>}</tt>
<p><tt>----------------------------------------------------------------------------</tt>
<p>This example contains "active waiting" (the <tt>do ; while(...)</tt>
construction). This is very ugly. For this reasons LinPac API offers an
alternative for waiting for the events: the <tt>lp_wait_event()</tt> function.
Let's change the example to use this function:
<p><tt>---------------------------------------------------------------------------</tt>
<br><tt>#include <stdio.h></tt>
<br><tt>#include <linpac/lpapp.h></tt>
<p><tt>int main()</tt>
<br><tt>{</tt>
<br><tt> if (lp_start_appl())</tt>
<br><tt> {</tt>
<br><tt> lp_event_handling_on(); //turn on automatical
event handling</tt>
<p><tt> printf("Application started\n");</tt>
<br><tt> printf("Stop with the ':Abort' command\n");</tt>
<p><tt> lp_wait_event(lp_channel(), EV_ABORT); //wait
for the abort event</tt>
<p><tt> printf("Application finished\n");</tt>
<br><tt> lp_end_appl();</tt>
<br><tt> }</tt>
<br><tt> else</tt>
<br><tt> {</tt>
<br><tt> printf("LinPac is not running\n");</tt>
<br><tt> return 1;</tt>
<br><tt> }</tt>
<p><tt> return 0;</tt>
<br><tt>}</tt>
<p><tt>----------------------------------------------------------------------------</tt>
<p><b>WARNING</b>: Note that some system calls can be interrupted when
the event is received. Interrupted system call returns the error result
and sets <tt>errno</tt> to EAGAIN (for example the <tt>read()</tt> call
returns -1) and it must be called again. To avoid this use the interrupt-safe
versions of the system calls contained in the application library (see
<a href="#POS7_3_1">chapter
7.3.1</a>)
<p><a NAME="POS6_3"></a>
<h3>
6.3 Synchronization</h3>
The event generated by an applicatoin is sent to all the modules and applications
including the application that has generated the event. When there's the
need to wait until the event is accepted by LinPac, the simplest way is
to wait until the event we have sent is received back.
<p>For testing that all the events were processed there is an event <tt>EV_VOID</tt>.
It's not handled by any module. After sending all events just generate
the <tt>EV_VOID</tt> event and wait until it returns. After that it's sure
that all previous events have been processed.
<p><a NAME="POS6_4"></a>
<h3>
6.4 Shared variables and configuration</h3>
Each shared variable denoted by its name (string) and channel number. Each
variable has its value represented by a string (char[]). The access to
the variables is provided by following functions:
<p><b><tt>void lp_set_var(int chn, const char *name, const char *value)</tt></b>
<br>Changes the value of the variable. If the variable doesn't exist, it
is created.
<p><b><tt>char *lp_get_var(int chn, const char *name)</tt></b>
<br>Reads the value of the variable. Returns NULL if the variable doesn't
exist.
<p><b><tt>void lp_del_var(int chn, const char *name)</tt></b>
<br>Deletes the variable.
<p><b><tt>void lp_clear_var_names(int chn, const char *prefix)</tt></b>
<br>Deletes all variables with the name
<p>The value of each variable is automaticaly synchronized with LinPac
and all running applications. The variables whose names start with "_"
are reserved for system use. These variables can be used for obtaining
system configuration and status but it may be potentialy dangerous to change
some of these variables. Currently following system variables are defined
(in channel 0):
<p><b>_remote</b> - contains 1 when remote commands are enabled
<p><b>_cbell</b> - 1 when connect sound is enabled
<br><b>_knax</b> - 1 when sound signal for each frame is enabled
<p><b>_def_port</b> - default port name
<br><b>_unportname</b> - port name for unproto frames
<br><b>_unport</b> - port number for unproto frames
<p><b>_info_level</b> - status-line level (0 to 2)
<br><b>_no_name</b> - default station name
<br><b>_timezone</b> - local timezone name
<br><b>_swap_edit</b> - 1 when swapedit is on
<br><b>_fixpath</b> - 1 when fixpath is on
<br><b>_daemon</b> - 1 when linpac works as a daemon
<br><b>_monitor</b> - 1 when monitor is enabled
<br><b>_no_monitor</b> - 1 when monitor is disabled from command line
<br><b>_listen</b> - 1 when accepting connections is enabled
<br><b>_disable_spyd</b> - 1 when ax25spyd support is disabled from command
line
<br><b>_mon_bin</b> - 1 when monitor filters binary characters
<br><b>_monparms</b> - command line of 'listen' program
<br><b>_maxchn</b> - maximal number of channels
<br><b>_last_act</b> - time of last user activity (same format as the time()
call).
<p>These variables can be read using the <b>get_var</b> function defined
above. Furthermore there are two special functions defined for reading
these variables. This functions expect the name of the system variable
without the initial _.
<p><b><tt>char *lp_sconfig(const char *name)</tt></b>
<br>Returns the value of configuration variable as a string.
<p><b><tt>int lp_iconfig(const char *name)</tt></b>
<br>Returns the value of configuration variable as an integer.
<p>Following system variables are defined for each channel:
<br><b>_call</b> - callsign for each channel
<br><b>_cwit</b> - connected with callsign
<br><b>_cphy</b> - physical connection to
<br><b>_port</b> - connected on which port
<br><b>_state</b> - connection status
<p>There are also special functions for reading values of these variables:
<p><b><tt>int lp_chn_status(int chn)</tt></b>
<br>Returns the status of a channel. There are following status constants
defined:
<br><tt>ST_DISC</tt> - channel disconnected
<br><tt>ST_DISP</tt> - disconnect in progress
<br><tt>ST_TIME</tt> - disconnecting for timeout
<br><tt>ST_CONN</tt> - channel connected
<br><tt>ST_CONP</tt> - connecting in progress
<p><b><tt>char *lp_chn_call(int chn)</tt></b>
<br>Returns channel callsign.
<p><b><tt>char *lp_chn_cwit(int chn)</tt></b>
<br>Returns the callsign of connected station.
<p><b><tt>char *lp_chn_cphy(int chn)</tt></b>
<br>Returns the callsign of physicaly connected station (the first connected
station).
<p><b><tt>int lp_chn_port(int chn)</tt></b>
<br>Returns the number of the port used for connection.
<p>Last two functions enable changing the time of last users's response:
<p><b><tt>time_t lp_last_activity()</tt></b>
<br>Returns the time of last activity of the user.
<p><b><tt>void lp_set_last_activity(time_t timeval)</tt></b>
<br>Sets the last activity time.
<p><a NAME="POS6_5"></a>
<h3>
6.5 Connection status</h3>
There are two special events reserved for obtaining the AX.25 connection
status. When the application wants to get the status of the connection
on certain LinPac channel, it generates the EV_STAT_REQ event on this channel.
As the answer LinPac generates the EV_STATUS event. The <b>data</b> field
of this event points to the ax25_status structure (see <a href="#POS7_2">chapter
7.2</a>). When there is no active connection on the channel, no EV_STATUS
event is generated.
<p><a NAME="POS6_6"></a>
<h3>
6.6 Event usage examples</h3>
Following examples show how to use the events for controlling LinPac. The
complete list of events can be found in the file events.txt.
<p><a NAME="POS6_6_1"></a>
<h4>
6.6.1 Connecting a remote station</h4>
When initiating the connection, the first step is to check, if the channel
is free (it is not used for other connection). The status of a channel
can be checked using the <tt>lp_chn_status()</tt> function (see
<a href="#POS6_4">chapter
6.4</a>).
<p>The second step is emiting the <tt>EV_CONN_LOC</tt> event on apropriate
channel. The <tt>data</tt> field of the event contains a c-string with
the destination address like <b>port:callsign [digi [digi ...]]</b>.
<p>The last step is to wait until the connection establishes. For this
the function <tt>lp_wait_connect()</tt> can ve used. An example piece of
code follows:
<p><tt>---------------------------------------------------------</tt>
<p><tt>int chn = lp_channel();</tt>
<br><tt>if (lp_chn_status(chn) == ST_DISC)</tt>
<br><tt>{</tt>
<br><tt> char addr[30];</tt>
<br><tt> strcpy(addr, "kiss:OK0PAB OK0NMA");</tt>
<br><tt> lp_emit_event(chn, EV_CONN_LOC, 0, addr);</tt>
<br><tt> lp_wait_connect(chn, "OK0PAB");</tt>
<br><tt> /* ... connection established ... */</tt>
<br><tt>}</tt>
<p>-------------------------------------------------
<p><a NAME="POS6_6_2"></a>
<h4>
6.6.2 Using LinPac commands in programs</h4>
Any of the applications can run LinPac commands by emiting the <tt>EV_DO_COMMAND</tt>
event. E.g. for downloading a message from a BBS using the <tt>getmsg</tt>
command following code can be used:
<p><tt>----------------------------------------------------</tt>
<p><tt>char cmd[30];</tt>
<br><tt>sprintf(cmd, "getmsg %i", message_number);</tt>
<br><tt>lp_emit_event(lp_channel(), EV_DO_COMMAND, 0, cmd);</tt>
<p><tt>----------------------------------------------------</tt>
<p>Other posibility is using the <tt>EV_WAND_RESULT</tt> event. The usage
is similar to previous exaple, but the <b>x</b> field of the event has
special meaning: as an reaction to this event LinPac will generate an event
<tt>EV_CMD_RESULT</tt>
with the same <b>x</b> field and with the <b>data</b> field containing
a result of the command.
<br>An example follows:
<p><tt>----------------------------------------------------</tt>
<p><tt>char cmd[30];</tt>
<br><tt>int id = 0;</tt>
<br><tt>Event *ev;</tt>
<p><tt>sprintf(cmd, "getmsg %i", message_number);</tt>
<br><tt>lp_emit_event(lp_channel(), EV_WANT_RESULT, 1234, cmd);</tt>
<br><tt>while (id != 1234) /* wait for the command result */</tt>
<br><tt>{</tt>
<br><tt> lp_wait_event(lp_channel(), EV_CMD_RESULT);</tt>
<br><tt> ev = lp_awaited_event();</tt>
<br><tt> id = ev->x;</tt>
<br><tt>}</tt>
<br><tt>printf("The result is: %s\n", (char *)ev.data);</tt>
<br>
<p><tt>----------------------------------------------------</tt>
<br>
<p><a NAME="POS7"></a>
<h2>
7 The application library interface</h2>
<a NAME="POS7_1"></a>
<h3>
7.1 Constants</h3>
<b><tt>LPAPP_VERSION</tt></b> - version of LinPac that the linrary came
with
<br><b><tt>ST_xxxx</tt></b> - connection status constants (see <a href="#POS6_4">chapter
6.4</a>)
<p><a NAME="POS7_2"></a>
<h3>
7.2 Data structures</h3>
<i>struct ax25_status</i> - contains the AX.25 connection status:
<p><tt>typedef struct</tt>
<br><tt>{</tt>
<br><tt> char devname[8];</tt>
<br><tt> int state;</tt>
<br><tt> int vs, vr, va;</tt>
<br><tt> int t1, t2, t3, t1max, t2max, t3max;</tt>
<br><tt> int idle, idlemax;</tt>
<br><tt> int n2, n2max;</tt>
<br><tt> int rtt;</tt>
<br><tt> int window;</tt>
<br><tt> int paclen;</tt>
<br><tt> bool dama;</tt>
<br><tt> int sendq, recvq;</tt>
<br><tt>} ax25_status;</tt>
<p><a NAME="POS7_3"></a>
<h3>
7.3 Functions</h3>
<a NAME="POS7_3_1"></a>
<h4>
7.3.1 Uninterruptable versions of some system calls</h4>
Following functions work the same way as the original system calls, but
they are interrupt-safe (they don't fail with <tt>errno == EAGAIN</tt>).
<p><b><tt>size_t safe_read(int fd, void *buf, size_t count);</tt></b>
<br><b><tt>size_t safe_write(int fd, const void *buf, size_t count);</tt></b>
<br><b><tt>char *safe_fgets(char *s, int size, FILE *stream);</tt></b>
<br><b><tt>int safe_fgetc(FILE *stream);</tt></b>
<p><a NAME="POS7_3_2"></a>
<h4>
7.3.2 Basic communication functions</h4>
<b><tt>int lp_start_appl()</tt></b>
<br>Starts the communication with LinPac. The <tt>pipename</tt> parameter
contains the name of the named pipe used for communication (use LP_PIPE_PATH
here). Non-zero return value means success, zero value means that LinPac
cannot be contacted (probably it's not running).
<p><b><tt>int lp_get_event(Event *ev)</tt></b>
<br>Read the event from the queue. Non-zero return value means succesful
read, zero value means that the event queue is empty. The <tt>data</tt>
field of the event structure <u>must</u> be initialized before using this
function (to NULL or to some buffer). This function shouldn't be used when
automatic event processing is used.
<p><b><tt>int lp_emit_event(int chn, int type, int x, void *data)</tt></b>
<br>Generate new event. The arguments correspond with the fields in the
event structure. Return value is always 0.
<p><b><tt>void lp_wait_event(int chn, int type)</tt></b>
<br>Wait until the event with the same <tt>chn</tt> and <tt>type</tt> values
are received.
<p><b><tt>void lp_wait_init(int chn, int type)</tt></b>
<br>The same as <tt>wait_event()</tt> but returns immediately, waiting
is provided by following function <tt>wait_realize()</tt>.
<p><b><tt>void lp_wait_realize()</tt></b>
<br>Realizes waiting initialized by <tt>lp_wait_init()</tt>. All the events
that arrived since last wait_init() call are registered. <tt>wait_realize()</tt>
can exit immediately if the event has already arrived.
<p><b><tt>Event *lp_awaited_event()</tt></b>
<br>After return from <tt>lp_wait_event()</tt> or <tt>lp_wait_realize()</tt>
this function returns the event that stopped the waiting.
<p><b><tt>Event *lp_copy_event(Event *dest, const Event *src)</tt></b>
<br>Copy the event structure (deep copy).
<p><b><tt>void lp_discard_event(Event *ev)</tt></b>
<br>Free the memory used by the data field of Event structure received
using <tt>get_event()</tt>.
<p><b><tt>void lp_clear_event_queue()</tt></b>
<br>Removes all events from the event queue. This has no use when automatic
event processing is on.
<p><b><tt>void lp_end_appl()</tt></b>
<br>Closes the connection to LinPac.
<p><a NAME="POS7_3_3"></a>
<h4>
7.3.3 Automatic event handling functions</h4>
<b><tt>void lp_event_handling_on()</tt></b>
<br>Switches the automatic event handling on. From this point each event
is automaticaly read from the queue, treated with an event handler function
(if defined) and discarted.
<p><b><tt>void lp_event_handling_off()</tt></b>
<br>Switches the automatic event handling off. Events must be read from
the queue using the lp_get_event() function.
<p><b><tt>void lp_set_event_handler(handler_type handler)</tt></b>
<br>Defines the event handler function - a function like
<br><tt>void my_handler(Event *ev)</tt>
<p>The event handler is called automaticaly each time some event is received
and the automatic event handling is on.
<p><a NAME="POS7_3_4"></a>
<h4>
7.3.4 Environment functions</h4>
LinPac owns its own environment for storing the variables. Each application
can share and modify this environment using following functions. The environment
is separated for each channel. See <a href="#POS6_4">chapter 6.4</a> for
more detailed description and list of functions.
<p><a NAME="POS7_3_5"></a>
<h4>
7.3.5 User functions</h4>
<b><tt>void lp_appl_result(const char *fmt, ...)</tt></b>
<br>Set the result of the application. This function generates the EV_APP_RESULT
event with the message string. The argument format is the same as for <tt>printf()</tt>
<p><b><tt>void lp_statline(const char *fmt, ...)</tt></b>
<br>Displays or changes the additional status line. Using this function
can be displayed one status line only. This function generates the EV_CHANGE_STLINE
event with the x field (line ID) containing the PID of the application.
For displaying more than one status line for the application other EV_CHANGE_STLINE
events must be generated manualy.
<p><b><tt>void lp_remove_statline()</tt></b>
<br>Removes the status line.
<p><b><tt>void lp_disable_screen()</tt></b>
<br>Disables displaying the data in the QSO window on application's channel.
The EV_DISABLE_SCREEN event is used.
<p><b><tt>void lp_enable_screen()</tt></b>
<br>Enables displaying the data in the QSO window. The EV_ENABLE_SCREEN
event is generated.
<p><b><tt>void lp_wait_connect(int chn, const char *call)</tt></b>
<br>Waits for a connection with specified callsign on specified channel.
<p><a NAME="POS7_3_6"></a>
<h4>
7.3.6 Tool functions</h4>
<b><tt>char *time_stamp(int utc)</tt></b>
<br>Returns the pointer to a c-string that contains actual time. If
<tt>utc</tt>=0
then local time is used else the UTC time is used.
<p><b><tt>char *date_stamp(int utc)</tt></b>
<br>Returns the date-string.
<p><b><tt>void replace_macros(int chn, char *s)</tt></b>
<br>Replaces the variables in the string (<tt>%xxx</tt>) with their values.
The <tt>%(command)</tt> macro is not replaced.
<p><b><tt>void get_port_name(int n)</tt></b>
<br>Returns the name of the n-th port in axports (starting with 0).
<p><a NAME="POS7_3_7"></a>
<h4>
7.3.7 Application information functions</h4>
<b><tt>char *lp_version()</tt></b>
<br>Returns current LinPac version.
<p><b><tt>int lp_channel()</tt></b>
<br>Returns the channel number where the application was started. Returns
0 when tha application was not started using linpac.
<p><b><tt>int lp_app_remote()</tt></b>
<br>Returns non-zero value if the application was started using a remote
command in LinPac (application communicates with remote user).
<p>
<hr>
<center>
<p><i><font size=-1>Last update: 15.9.2001</font></i></center>
</body>
</html>
|
