LinPac internal events
----------------------

This list contains the description of almost all events that can occur in
LinPac. Each application can generate any of these events and in can also
handle any of them.


a) User interaction

EV_KEY_PRESS (key pressed)
Generated by: The user interface when a keyboard button is pressed
Handled by  : User interface
Data        : x - key code (ncurses-compatibile)
              y - 0 when Alt wasn't pressed

EV_TEXT_RAW (raw output text)
Generated by: Text editor when the text line is dismissed
              Macro processor (line from a macro)
              Remote command source
Handled by  : Text variables processor
Data        : chn - channel number
              data - pointer to c-string
              x - contains source description:
                  FLAG_REMOTE - remote command
                  FLAG_MACRO  - command from macro, wasn't processed with
                                macro command interpreter (can contain
                                some macro command such as IF ot GOTO)
                  FLAG_FM_MACRO - command from macro that is not a special
                                macro command (already processed with macro
                                command interpreter)
                  FLAG_EDIT   - from text editor (local user)

EV_TEXT_COOKED (cooked output text)
Generated by: Text variables processor after receiving the EV_TEXT_RAW event
                and replacing the variables with their values.
              Any application that wants to send out some text or command.
Handled by  : Command processor (when the text starts with ':')
              I/O interface (when the text doesn't start with ':') - the
                output is cached (text is not transmitted immediately)
Data        : chn - channel number
              data - pointer to c-string
              x - source description copied from the received EV_TEXT_RAW 
                  event

EV_TEXT_FLUSH (flush output)
Generated by: any source
Handled by  : I/O interface - transmits the cache contents and clears the
                              cache
Data        : chn - channel number
              x = FLAG_FLUSH_IMMEDIATE - flush the output buffer now
                = 0 - flush after cooking last EV_TEXT_RAW (usual value)

EV_EDIT_INFO (insert info into editor)
Generated by: Command processor
Handled by  : Text editor - inserts the information behind current line and
                            moves after this text
Data        : chn - channel number
              data - pointer to c-string

EV_CALL_CHANGE (change the callsign)
Generated by: Command processor (:mycall command, :connect command)
Handled by  : AX.25 I/O interface - changes the callsign of the channel
Data        : chn - channel number
              data - new callsign (c-string)

EV_UNPROTO_SRC (change unproto source)
Generated by: Command processor (:unsrc)
Handled by  : AX.25 I/O interface - changes the unproto source callsign
Data        : chn - channel number
              data - new callsign (c-string)

EV_UNPROTO_DEST (change unproto destination)
Generated by: Command processor (:undest)
Handled by  : AX.25 I/O interface - changes the unproto destination callsign
Data        : chn - channel number
              data - new callsign (c-string)

EV_UNPROTO_PORT (change unproto port)
Generated by: Command processor (:unport)
Handled by  : AX.25 I/O interface - changes the unproto port
Data        : chn - channel number
              data - new port name (c-string)

EV_WANT_RESULT (execute the command and generate a result event)
Generated by: Variable processor (replacing %(command))
Handled by  : Command processor - executes the command and generates the
                                  EV_CMD_RESULT event containing the result
Data        : chn - channel number
              data - command string (without the initial ':') (c-string)
              x - result ID. The EV_CMD_RESULT generated by command
                  processor will have the same ID (for recognizing the right
                  result)

EV_CMD_RESULT (the command result)
Generated by: Command processor as the answer to EV_WANT_RESULT event or
                after executing a command that returns some result (:strlen
                ...)
              The application using the appl_result() function.
Handled by  : Command processor - when ID == FLAG_NO_HANDLE then generates
                                  the EV_EDIT_INFO event to display the
                                  result in editor
Data        : chn - channel number
              data - result text (c-string)
              x - result ID - can contain the ID of the EV_WANT_RESULT event
                              that caused this event or it can contain
                              FLAG_NO_HANDLE (value -1) when this is not the
                              answer to any EV_WANT_RESULT

EV_DO_COMMAND (execute the command)
Generated by: any source
Handled by  : Command processor - executes this command
Data        : chn - channel number
              data - command without the initial ':' (c-string)

EV_SELECT_CHN (current channel change)
Generated by: User interface (user pressed F1 - F10)
              Applications that want to switch the channel
Handled by  : User interface, ...
Data        : chn - new channel number:
                 1 to 8 - normal channels (F1 - F8)
                      0 - unproto channel (F10)
               -1 to -8 - channels for fullscreen applications (Alt-1 - Alt-8)
                    -10 - channel for fullscreen application (Alt-0)

EV_USER_ACT (user is active)
Geterated by: User interface (user has done some action)
Handled by  : User activity counter (clears)
Data        : none


b) Macros
                    
EV_MACRO_STARTED (macro processing has been started)
Generated by: Macro processor
Handled by  : Macro processor - pauses processing other macros on the
                                channel
Data        : chn - channel nuber
              data - pointer to new macro processor (for identification)

EV_MACRO_FINISHED (macro processing has been finished)
Generated by: Macro processor
Handled by  : Macro processor - resumes processing other macros on the
                                channel
Data        : chn - channel nuber
              data - pointer to finishing macro processor (for identification)


c) Character input/output

EV_DATA_INPUT (data block received)
Generated by: I/O interface after receiving some data
Handled by  : User interface - display incomming text
              Incomming text watcher - scan for pattrens
Data        : chn - channel number
              data - pointer to char buffer (char[])
              x - block length (characters)
              
EV_DATA_OUTPUT (data block transmitted)
Generated by: I/O interface after transmitting some data
Handled by  : User interface - display outgoing text
Data        : chn - channel number
              data - pointer to char buffer (char[])
              x - block length (characters)
              
EV_LOCAL_MSG (local info text)
Generated by: I/O interface
Handled by  : User interface - display local info
Data        : chn - channel number
              data - pointer to char buffer (char[])
              x - block length (characters)

EV_LINE_RECV (text line received)
Generated by: I/O interface after receiving end of line in incomming data
Handled by  : Command processor - check for "//" - external commands
              Incomming text watcher - check for "connected to" ...
Data        : chn - channel number
              data - pointer to char buffer (char[])
              x - block length (characters)


d) Connection

EV_CONN_LOC (begin connection)
Generated by: Command processor (:connect)
              Application that wants to initiate the connection
Handled by  : I/O interface - begins the connection
Data        : chn - channel number
              data - c-string with destination address in format
                     port:CALL DIGI1 DIGI2 ...

EV_DISC_LOC (close connection)
Generated by: Command processor (:disconnect)
              Application that wants to close the connection
Handled by  : I/O interface - closes the connection
Data        : chn - channel number

EV_CONN_TO (connection established)
Generated by: I/O interface when connection establishes
Handled by  : User interface (display the message...)
Data        : chn - channel number
              data - connected callsign (c-string)
              x - 0 when we initiated the connection
                  (else other party has initiated the connection)

EV_DISC_FM (connection closed)
Generated by: I/O interface when station disconnects
Handled by  : User interface (display the message...)
Data        : chn - channel number
              data - disconnected callsign (c-string)

EV_DISC_TIME (disconnected for timeout)
Generated by: I/O interface when station disconnects for timeout
Handled by  : User interface (display the message...)
Data        : chn - channel number
              data - disconnected callsign (c-string)

EV_CONN_REQ (unsuccesful connect request)
Generated by: I/O interface when some station requests the connection and 
              there is no free channel
Handled by  : User interface (display the message...)
Data        : chn - channel number
              data - callsign (c-string)

EV_FAILURE (connection failure)
Generated by: I/O interface when connection breaks
Handled by  : User interface (display the message...)
Data        : chn - channel number
              data - callsign (c-string)

EV_RECONN_TO (reconnected to)
Generated by: Incomming text watcher when the message is detected
Handled by  : User interface
Data        : chn - channel number
              data - new callsign (c-string)
              x - 1 when connected forward ("connected to" message)
                  else connected back ("reconnected to" message)

EV_STATUS_CHANGE (connection status changed)
Generated by: I/O interface when connection status changes
Handled by  : User interface (display new status)
Data        : chn - channel number
              x - new status:
                 ST_DISC - disconnected
                 ST_DISP - disconnecting
                 ST_TIME - disconnecting for timeout
                 ST_CONN - connected
                 ST_CONP - connecting in progress

EV_DISABLE_CHN (disable connections to the channel)
Generated by: Command processor (:priv)
              Applications that want to reserve the channel
Handled by  : I/O interface (marks the channel)
              User interface (shows the ++++++ instead of ------)
Data        : chn - channel number

EV_ENABLE_CHN (enable connections to the channel)
Generated by: Command processor (:priv)
              Application
Handled by  : I/O interface
              User interface
Data        : chn - channel number

EV_LISTEN_ON (enable incomming connections)
Generated by: Command processor (:list)
Handled by  : I/O interface (creates listening sockets)
Data        : none

EV_LISTEN_OFF (disable (=ignore) incomming connections)
Generated by: Command processor (:list)
Handled by  : I/O interface (closes listening sockets)
Data        : none


e) Screen

EV_DISABLE_SCREEN (disable output to QSO window)
Generated by: Applications (in case of binary transfer...)
Handled by  : User interface (stops displaying the data in QSO window)
Data        : chn - channel number

EV_ENABLE_SCREEN (enable output to QSO window)
Generated by: Applications (end of binary transfer...)
Handled by  : User interface (enables output to window)
Data        : chn - channel number

EV_CHANGE_STLINE (change or create additional status line)
Generated by: Command processor (:infoline)
              Applications using the statline() function
Handled by  : User interface (add or change the status line)
Data        : chn - channel number
              data - status text (c-string)
              x - line ID. If the line with this ID doesn't exist, it's
                  created. If it exists, the content is changed.

EV_REMOVE_STLINE (remove aditional statusline)
Generated by: Command processor (:removeinfo)
              Applications using the remove_statline() function
Handled by  : User interface
Data        : chn - channel number
              x - line ID

EV_CONV_IN (install input conversion table)
EV_CONV_OUT (install output conversion table)
Generated by: Command processor (:trans)
Handled by  : User interface
Data        : chn - channel number, 0 means all channels and monitor window
              x - table length, max 256
              data - x bytes, each byte represents the output character when 
                     the character with ASCII value equal to index of that 
                     byte is received. When the value of received character
                     is greater than x no conversion is done.

EV_CONV_NAME (use specified i/o character encoding)
Generated by: Command processor (:trans)
Handled by  : User interface
Data        : chn - channel number, 0 means all channels and monitor window
              data - c-string containing encoding name

EV_SET_TERM (set terminal type - none, ansi, ...)
Generated by: Command processor (:term)
Handled by  : User interface
Data        : chn - channel number
              data - terminal name (c-string)

EV_REDRAW_SCREEN (redraw the screen)
Generated by: Command processor (:redraw)
Handled by  : User interface
Data        : none

EV_MONITOR_CTL (control the monitor)
Generated by: Command processor (:monitor)
Handled by  : User interface (monitor window)
Data        : x = 0 : disable monitor function (stop displaying anything
                      into the monitor window)
              x = 1 : enable monitor function

f) Other events

EV_STAT_REQ (application requests the AX.25 connection status)
Generated by: application
Handled by  : LinPac status server
Data        : chn - channel number

EV_STATUS (connection status info)
Generated by: LinPac status server (the answer to EV_STAT_REQ event)
Handled by  : application
Data        : chn - channel number
              data - points to the ax25_status structure

EV_APP_MESSAGE (message from application to other application)
Generated by: application
Handled by  : application
Data        : data - message text (c-string)

EV_APP_RESULT (an application result)
Generated by: application
Handled by  : Event manager - after the application finishes the
                              EV_CMD_RESULT with the same data is generated.
Data        : data - the result message (c-string)

EV_ABORT (abort application)
Generated by: Command processor (:abort)
Handled by  : application (compares the address with its own one and aborts)
Data        : chn - channel number
              data - abort address (command parameter) (c-string)

EV_VOID (void event - synchronization reasons)
Generated by: anybody
Handled by  : nobody
Data        : none

EV_SYSREQ (request special actions - debugging...)
Generated by: normally nobody
Handled by  : Event manager
Data        : x - request number. Currently implemented:
                0: check if debugging is supported
                1: dump a list of active internal modules to errorlog
                2: toggle macro debugging (this dumps the internal macro
                   notation to errorlog each time a macro is executed)

EV_QUIT (quit LinPac)
Generated by: Command processor (:system)
Handled by  : Event manager (stops working)
Data        : none
