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 it can also
handle any of them.

The names of the source objects are written in parenthesis. The list of 
internal LinPac objects can be found in the file objects.txt.


a) User interaction

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

EV_KEY_PRESS_MULTI (multiple keys pressed)
Generated by: The user interface (Keyscan) when multiple printable keyboard
                keys are pressed in rapid succession
Handled by  : User interface
Data        : data - pointer to c-string

EV_TEXT_RAW (raw output text)
Generated by: Text editor (Editor*) when the text line is confirmed
              Macro processor (Macro*) (line from a macro)
              Remote command source (Command)
Handled by  : Text cooker (Cooker) - replacing the text macros
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_ARGS (cooking arguments for EV_TEXT_RAW, must be sent just before
              each EV_TEXT_RAW when needed).
Generated by: Macro processor (Macro*) before sending EV_TEXT_RAW line
                to tell the Cooker object the arguments of the Macro
                (for cooking %1 - %9).
Handled by  : Text cooker (Cooker)
Data        : chn - channel number
              data - strings arguments separated by \0
              x - data length

EV_TEXT_COOKED (cooked output text)
Generated by: Text variables processor (Cooker) 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 (Command) (when the text starts with ':')
              I/O interface (Ax25io) (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 (Ax25io) - 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 (Command)
Handled by  : Text editor (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 (Command) (:mycall command, :connect command)
Handled by  : AX.25 I/O interface (Ax25io) - 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 (Command) (:unsrc)
Handled by  : AX.25 I/O interface (Ax25io) - changes the unproto source 
                                             callsign
Data        : chn - channel number
              data - new callsign (c-string)

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

EV_UNPROTO_PORT (change unproto port)
Generated by: Command processor (Command) (:unport)
Handled by  : AX.25 I/O interface (Ax25io) - 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 (Cooker) when 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
              The creator if EV_WANT_RESULT with the same result ID.
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 (Keyscan) (user pressed F1 - F10)
              Applications that want to switch the channel
Handled by  : Many objects (object activation/deactivation etc...)
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 (Keyscan) (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 (Macro*)
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 (Ax25io) after receiving some data
Handled by  : User interface (QSOWin*) - display incomming text
              Incomming text watcher (Watch) - 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 (Ax25io) after transmitting some data
Handled by  : User interface (QSOWin*) - 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 (Ax25io) 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)

EV_RX_CTL (rx data flow control)
Generated by: Command processor (Command) - :rxflow on/off
              I/O interface when new incomming connection establishes
                (for synchronization reasons)
Handled by  : I/O interface (Ax25io)
Data        : x - 0 = rxflow is off, 1 = rxflow is on


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 (QSOWin*) (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 (QSOWin*) (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 (QSOWin*) (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 (QSOWin*) (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 (QSOWin*) (display the message...)
Data        : chn - channel number
              data - callsign (c-string)

EV_RECONN_TO (reconnected to)
Generated by: Incomming text watcher (Watch) when the message is detected
Handled by  : User interface (InfoLine...)
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) Application communication

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_REG_COMMAND (register a command for an application)
Genereted by: application (wants to provide an user command)
Handled by  : Command processor (Command) - considers the command as the
                known one, when execution of this commands is requested,
                generates EV_APP_COMMAND.
Data	    : data - command name (c-string)

EV_UNREG_COMMAND (cancel command registration)
Generated by: application
Handled by  : Command processor (Command) - command registration is
                caneclled.
Data        : data - command name (c-string)

EV_APP_COMMAND (a command to be executed by an application)
Generated by: Command processor (Command) - registered command requested
Handled by  : application that provides such command
Data	    : chn - execution channel
              data - command name and arguments (c-string)


g) Other events

EV_STAT_REQ (application requests the AX.25 connection status)
Generated by: application
Handled by  : LinPac status server (Status) - generates EV_STATUS
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_DISABLE_OBJ (temporarily disable an internal object)
Generated by: anybody
Handled by  : Event manager (stops sending the events to this object)
Data        : data - object name (e.g. QSOWindow1) (c-string)

EV_ENABLE_OBJ (enable an internal object)
Generated by: anybody
Handled by  : Event manager (resumes sending the events to this object)
Data        : data - object name (c-string)

EV_ADD_WATCH (watch for pattern in input data)
Generated by: Command processor (Command) - :watch
Handled by  : Input text watcher (Watch)
Data        : chn - channel (0 = all the channels)
              data - text pattern

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
