
The CAB-protocol
================

The CAB-protocol consists of a number of AES-messages, which can be
used by GEM programs to transfer specific operations to CAB. CAB takes
responsibility for coordinating these operations.

A possible application:
If information or updates are available on the Internet the
CAB-protocol could be used to access this information. CAB would
download and display the data.


Message descriptions
====================

CAB_HELLO ($CAB8) (message from CAB)
-----------------
After starting, CAB sends the following message to all running
programs:

msg[0] = $CAB8
msg[1] = CAB ID
msg[2] = 0
msg[3] = Version of the CAB-protocol (where, e.g. $0100 = v1.00)
msg[4] = Bit vector containing the CAB (CAB.OVL) supported Internet
         protocols:
          Bit 0: HTTP
          Bit 1: FTP
          Bit 2: GOPHER
          Bit 3: WAIS
          Bit 4: MAILTO
          Bit 5: NNTP
          Bit 6: TELNET
          Bit 7-15: 0 (reserved)
msg[5] = Bit vector containing the CAB supported messages of the
         CAB-protocol:
          Bit 0: CAB_VIEW
          Bit 1: CAB_MAIL, CAB_MAILSEND
          Bit 2: CAB_REQUESTSTATUS, CAB_RELEASESTATUS, CAB_STATUS,
                 CAB_EXIT
          Bit 3-15: 0 (reserved)
msg[6] = 0
msg[7] = 0



CAB_SUPPORT ($CABB) (message to CAB)
-------------------
If CAB receives this message it replies by sending a CAB_HELLO message.
If no CAB_HELLO message is received the CAB version must be pre
CAB-protocol.
Any programs which are interested in the information CAB_HELLO supplies
should, after starting, send a CAB_SUPPORT message to CAB. If CAB is
subsequently started it automaticallys send a CAB_HELLO message to the
program.

msg[0] = $CABB
msg[1] = ID of the PRGs
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0



CAB_VIEW ($CAB3) (message to CAB)
----------------
Similar to VA_START but instead of filename/s URLs are passed and CAB
displays the file.

msg[0] = $CAB3
msg[1] = ID of the PRGs
msg[2] = 0
msg[3] = \ Pointer to the URL
msg[4] = /
msg[5] = 1 = CAB displays URL in a new window
         0 = CAB displays URL in the top CAB window
msg[6] = 0
msg[7] = 0



CAB_REQUESTSTATUS ($CAB5) (message to CAB)
-------------------------
Can be sent CAB to determine whether CAB is currently on-line or
off-line. CAB sends the CAB_STATUS message as a reply after every
change in the on/off-line status.

msg[0] = $CAB5
msg[1] = ID of the PRGs
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0



CAB_RELEASESTATUS ($CAB7) (message to CAB)
-------------------------
A program should send this message to CAB if it's no longer interested
in receiving the CAB on/off-line status it requested via the
CAB_REQUESTSTATUS message (e.g. if the program is exited).

msg[0] = $CAB7
msg[1] = ID of the PRGs
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0



CAB_STATUS ($CAB6) (message from CAB)
------------------
CAB sends this message to all programs which have requested to be kept
informed of the CAB on/off-line status via the CAB_REQUESTSTATUS
message.

msg[0] = $CAB6
msg[1] = CAB ID
msg[2] = 0
msg[3] = 1 = CAB on-line
         0 = CAB off-line
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0



CAB_EXIT ($CAB1) (message from CAB)
----------------
CAB sends this message to all programs which have requested to be kept
informed of the CAB on/off-line status, via the CAB_REQUESTSTATUS
message as CAB is exited. Beforehand CAB sends a CAB_STATUS message to
all programs reporting CAB is in the off-line state.

msg[0] = $CAB1
msg[1] = CAB ID
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0



CAB_MAIL ($CAB9) (message to CAB)
----------------
Can be sent to CAB in order to send mail.

msg[0] = $CAB9
msg[1] = ID of the PRGs
msg[2] = 0

msg[3] = \ Pointer to the URL. A Subject line can be appended to the
msg[4] = / URL using a question mark as a separator.

msg[5] = \ Pointer to a file which contains the mail message or null
msg[6] = / in which case CAB opens an editor to enter the message.

msg[7] = Bit vector:
          Bit 0: 0 = Send mail message immediately
                 1 = Mail message from the user can be handled/edited
                     via CAB.
          Bit 1: File should be deleted by CAB after processing.
          Bil 2-15: reserved (0)


CAB_MAILSENT ($CABA) (message from CAB)
--------------------
CAB sends this message in reply to a CAB_MAIL message to inform the
program whether the mail was sent along with a status indicator.

msg[0] = $CABA
msg[1] = CAB ID
msg[2] = 0
msg[3] = 1 = Mail sent without error/s)
         0 = Error encounter, msg [4] indicates nature of error
msg[4] = Returns an error number, if msg[3] = 0
       = 0: No URL given.
       = 1: Off-line, net connection disturbed, server not accessible
       = 2: User has aborted mail send action (e.g. where mail is
            handled via CAB the user has the opportunity to abort the
            action
       = 3: GEMDOS error/s on accessing the mail message file
       = 4: Editor to handle mail message could not be found
msg[5] = 0
msg[6] = 0
msg[7] = 0




Special messages for 'Cache-Tools'
==================================

CAB_CCHANGED ($CAB0) (message to/from CAB)
--------------------
The cache (i.e. CACHE.CAB) was changed and should be re-read.

msg[0] = $CAB0
msg[1] = CAB ID/ID of the PRGs
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0



CAB_EXIT ($CAB1) (message to/from CAB)
----------------
CAB or the Cache-Tool exits (each PRG should inform the other on
exiting).

msg[0] = $CAB1
msg[1] = CAB ID/ID of the PRGs
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0



CAB_PATH ($CAB2) (message from CAB)
----------------
The local HTML folders and/or the Cache folder have been changed. For
more detailed information refer to the Cache-Tools documentation.

msg[0] = $CAB2
msg[1] = CAB ID
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0



CAB_TERM ($CAB4) (message from CAB)
----------------
The Cache-Tool should exit.

msg[0] = $CAB4
msg[1] = CAB ID
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0

