Suggested outline for Termite protocol system ============================================= (c) DoggySoft, 1995 ============================================================================= Introduction to writing protocols ----------------------------------------------------------------------------- This is the file that explains how to write a protocol for Termite, hopefully Termite is future-proof and will not need modifying once it is finished, however, it is now 2 years later, and I was obviously speaking bollocks when I wrote that... Each protocol is found within a directory inside the main protocols directory and the convention is that internet protocols start with the international currency symbol, so that they are at the bottom of the directory structure! This makes sure that the internet protocols are 'seen' last by GBPB and hence menus have emulations at the top and internet protocols at the bottom. Protocols have two files inside them, the 'Module' and the 'StartupDat' file, plus any messages, data or template files. ============================================================================= StartupDat format ----------------------------------------------------------------------------- This file is for Termite to find out what menu entries to put on the menus without actually loading the entire protocol program, hence saving on memory. Header (64bytes long): ---------------------- 0 8 "Termite2" 8 4 offset to protocol name 12 4 offset to module filename 16 4 offset to protocol information 20 4 offset to menu entries 24 4 offset to StartupDat code 28 4 terminal flags } see protocol section 32 4 reserved; MUST BE 0 36 4 offset options definitions 40 4 length options definitions 44 4 reserved; MUST BE 0 48 4 version of Termite required *100 52 4 version of protocol *100 56 4 reserved; MUST BE 0 60 4 reserved; MUST BE 0 Protocol name: -------------- Null terminated string containing the name of the protocol, eg. "ANSI" or "ZModem". Protocol information: --------------------- eg. "(c) DoggySoft, 1995" Menu entries: ------------- You can have As many of these 32byte blocks as you like, terminated by a -1 word. n+0 4 menu type n+4 24 standard menu data n+28 1 0; item number (filled in by Termite) n+29 1 0; reserved n+30 1 0; reserved n+31 1 0; reserved When Termite loads and puts this menu entry on a menu somewhere, it stores the item number in +28. This is useful for the capture protocol, which looks at this at a later date to find out which entries to shade. menu type: 0 = main 1 = iconbar 2 = file 3 = session 4 = transfer 5 = prot 6 = upload 7 = download 8 = batch 9 = script Note that for 1.10 and above I swapped menu type values 0 and 1 so that the menu warning and selection messages could tally with the menu types, since no protocol used the iconbar or the main menu for adding entries, this should be ok. ============================================================================= StartupDat code ----------------------------------------------------------------------------- Preserve all registers if not used on exit! R1 must not be used in entry and exit, it is used in routine_startupdatcall R0 = 0 : Initialise ------------------- R10 = pointer to start of StartupDat file in memory R13 = stack Exit: Must preserve R7-R13 This entry is called so that you can update your menu entries so that they contain actual pinters rather than offsets (of course this is only useful if your menu entries are indirected). You should not use this entry point for anything else unless you really need it. StartupDat files are not in heap blocks, and this entry will never be called again. R0 = 1 : CallDemon Internet Enumeration --------------------------------------- R2 = 0 Exit: R2 = -1 to claim R3-> block Block: +00 = priority number +04-> button string ; don't forget to get the real locations of these +08-> sprite block ; and not the offset from the start of startupdat! +12-> help string ; ................................................ +16-> number of sprites in animation, 1 for no animation, -1 for clock +20 = 0 (used for indirected sprite name) +24 = speed (0 = 1cs, 1 = 2cs, 2 = 4cs, 3 = 8cs, 4 = 16cs etc) +28 = 0 (reserved) ******** OLD: ******** R3 = priority number ******** R4-> button string ******** R5-> sprite or -1 for clock ******** R6-> help string ******** R7 = number of sprites in animation, 1 for no animation If you want to be listed in the enumeration then you should claim the event by setting R2 to -1 on exit. Priorities: &10000000 - WWW &20000000 - Telnet &30000000 - Ftp &40000000 - Mail &50000000 - News &60000000 - Finger &70000000 - Time &80000000 - Ping &FFFFFF00 - Disconnect Do NOT use the bottom byte in a priority, and please ask DoggySoft for an allocation in any case. R0 = 2 : Key check ------------------ R2 = keycode Exit: R0 = -1 to ensure protocol R2 may be corrupted If on exit R0 is -1 then your protocol will be made sure it is loaded, this is used in the macros protocol so that ACT-F1...F8 will be caught and acted upon. R0 = 3 : Internet listen ------------------------ Exit: R0 = -1 to claim R2 = port number R3 = 0 (flags passed to TermiteIP_AllocatePort You will be loaded if any sockets are created by a client, and then a service call is sent to you with the client id. See the TermiteIP service call section below. R0 = 4 : Protocol driver enumeration ------------------------------------ Exit: R0 = -1 to claim R2-> name, eg. "PPP" R0 = 5 : Protocol driver get ---------------------------- Exit: R0 = -1 to claim R2-> driver See TermiteIP documents for details on the protocol driver specification. The SLIP driver returns R2 = 0, but others will read the size of a file and claim an RMA block and load the driver. You will not have to declaim this block because the TermiteIP module will do this when it quits. R0 = 6 : Data open ------------------ R2-> Message_DataOpen block Exit: R0 = -1 to claim Claiming this event will cause your protocol to be loaded - you will then receive the real data open message in your wimp code. If you are checking for double clicks on files, take a look at service call 35. ============================================================================= Module format ----------------------------------------------------------------------------- This file contains all the code for your protocol to work, all header entries must be valid pointers or 0. Header: ------- 0 8 "Termite1" 8 4 offset to initialise code 12 4 offset to finalise code 16 4 offset to wimp event code 20 4 offset to terminal event code 24 4 offset to option code 28 4 0 The flags and information strings will be taken from the StartupDat file previously loaded. terminal_flags: --------------- bits if set 0-2 Protocol type %000 = emulation %001 = file transfer %010 = general protocol (emulation with no block drivers) %011 = file transfer supporting batch %100 = emulationish (ie. CallDemon - requires block drivers) %101 = undefined %110 = special protocol with no responsibilities %111 = undefined 7 crc check every poll 8 protocol can be made a pre-protocol 9 protocol can be made a base-protocol 10 protocol can be made a post-protocol 11-31 reserved; must be 0 Emulations such as ANSI should have bits 8-10 all set, to allow protocols such as Telnet to use them as post-emulations. ============================================================================= Initialise code ----------------------------------------------------------------------------- R10 = start of protocol R11 = routine block R12 = -1 R13 = stack Exit: Must preserve R7-R13 This code is called as soon as the library is loaded. It is defined that the module will not be called via any other point until this entry point has been called. If you have options, this is when you should load the template file into memory from disc and create the window. ============================================================================= Finalise code ----------------------------------------------------------------------------- R0 = reason for finalisation (currently always 0) R12 = -1 R13 = stack Exit: Must preserve R7-R13 This is the reverse of initialisation, the code is called when the system is about to close a session or when there are no sessions a complete shutdown. If Termite is being quitted, you will be called for every session still active, after all sessions have been closed you will be called through this entry point. This will give you chance to unclaim any general workspace you might have claimed. ============================================================================= Workspace information ----------------------------------------------------------------------------- There are two types of workspace which I will refer to as wk and gwk, which stands for 'workspace' and 'general workspace'. When a session is started, each protocol is allocated one private word, and this is initialised to 0. This is the gwk workspace, and you pretty well always get passed this to all reason codes. Hence every protocol has a private word for every session. The other type of workspace is the workspace you ask for in your module header, and is allocated when you become installed in the current session. So you only ever have wk workspace if you are installed in the session. Type a) Sent to all protocols in current session (wk setup) b) Sent to all protocols in all sessions (wk setup) c) Sent to all protocols for current session (wk=-1) d) Sent to all protocols for all sessions (wk=-1) e) Sent to just you for current session (wk maybe, gwk maybe) f) Sent to all protocols once (wk=-1, gwk=-1) Type (a) is the most common for the 'terminal event' code, and (b) followed by (d) is the most common for the 'wimp event' code. (a) goes to the protocols installed in the session with the correct gwk and wk. (b) simply goes to every session and issues an (a). (c) goes to every protocol once with the gwk for the current session (wk is set to -1) (d) simply goes to every session and issues a (c) (e) is a direct (not broadcast) message to you, for example a drag box end event, is sent to you. (f) is a broadcast to all protocols, used to do mouse clicks etc to windows which aren't tied to a session (eg option windows). ============================================================================= Terminal event code ----------------------------------------------------------------------------- R0 = reason code R8 = pointer to private word for session if R9<>-1 R9 = termite session number or -1 for no current session R10 = options block R11 = routine block R12 = workspace pointer or -1 (if R9<>-1 or not installed) R13 = stack other registers depend on reason code Exit: R0 = preserved or -1 to claim Must preserve all registers except those returning values in R1 to R5. R0 = 0 : New session (e) ------------------------ R2 = -1 (pre) or 0 (base) or 1 (post) R3 = parameters or -1 R4 = parameters or -1 R5 = parameters or -1 If you are a file transfer, you should follow this guideline: R3-> upload, block in RMA +00 = offset to next or -1 +04 = name +24 = load } ie. filetype +28 = exec } +32 = reserved +36 = reserved +40 = filename (null term) R4 = 0 for upload, 1 for download R5 = 0 (interrupt), 1 (normal) Exit: All registers preserved or an error block in R0 with V flag set. Called with R2=0 after the user has clicked on 'Create' in the new session window to the base protocol. The order in which things happen is as follows: 1. Device is claimed. 2. Block driver is initialised. 3. Speed, emulation and modem driver are chosen. 4. Protocol is loaded and initialised if not already. 5. All protocols are allocated private words. 6. All protocols are warned 'session starting'. 7. Protocol is allocated workspace 8. Protocol is called to 'New session'. 9. Protocol is called to 'View session'. This is step 8, you have automatically been created the workspace needed for this session, normally you would enter a loop to clear out the workspace and then call the Termite library to get a terminal window. The workspace is in a heap block so do not rely on it being in a fixed place, it is initialised to 0 when the session is created. If R2=-1 or 1 then the protocol is being instated within the session as either a pre or post protocol - used by the capture protocol since depending on R2 it will either be raw or text. Note that if an error is returned it will get reported and you will get removed from the session - however any objections to being instated should preferably be dealt with at the 'New session warning' reason code 9. R3 and R4 are miscellaneous parameter strings or words, R3 used by X/Ymodem so that it knows what type of transfer to do. R4 is normally used to pass a string of null-terminated filenames to transfer terminated with another null. R0 = 1 : View session (a) ------------------------- If you have a window for the session number specified in R10 you must open the window and claim this event, otherwise it will be passed down the chain of nested emulations until it reaches the default emulation specified in one of the styles. The default emulation should not refuse a window to be opened (indeed, there should be no circumstances where protocols are both nested and default emulations, and hence should know which they are). If you are a nested emulation you can stop the default emulation from opening it's window by claiming this event and open your own. When your window receives a close request (eg. the use has clicked on the close icon) you should call this routine after you have cleared the record of this session from your workspace - hence opening up the previous emulation (be it nested or default) window. Always open the window on top of the window stack. R0 = 2 : Close pre-session -------------------------- Passed to everyone to see if it wants to proceed with the quit, if you want to stop the quit then set the V flag on exit with a suitable error block. Keylock uses this to stop the session being closed. R0 = 3 : Close session (a) or (e) --------------------------------- The user has asked for the session to be closed, remove any windows relating to this session number. Closing a session follows this proceedure: 1. Base protocol sent close pre-session 2. Pre-protocols sent close session 3. Post-protocols sent close session 4. Base protocol sent close session Usually this is a broadcast message (a) but this may just be given to you (e) for example the IEMSI calls routine_removeprotocol on itself after it has completed the session. IEMSI uses this to delete the 'negotiating...' window; it has two workspace blocks, one for when it's within the session containing information for picking up the server details etc, and another workspace within it's private word. R0 = 4 : Options changed (a) ---------------------------- Options have changed. R0 = 5 : Clear session (a) -------------------------- The user has asked for the session window to be cleared, clear any windows relating to the current session. R0 = 6 : Session starting (c) ----------------------------- Global message to all protocols when a session is just about to start, as usual R9 is the session number, but more importantly R8 will be your new private word for this session - it will be zero when you are called. You may allocate more memory and store it in the word if you like. Note that allocating memory for yourself when you receive this call should be limited in it's use - since you will be allocating this memory for every session this could eat up memory very fast. If you want to instate yourself into the session then that would be preferable. Allocating memory here would be useful if you wanted to operate a window which requires indirected text such as the IEMSI window with the system details. ZModem does not allocate any more memory, it just uses the 4 bytes to scan for strings - as soon as you have found the string you were interested in, you should instate yourself in the current session and you will be allocated the memory you specified in your header. Did all that make sense?! R0 = 7 : Session ending (c) --------------------------- Broadcast to all protocols with the private word so that you can deallocate any memory etc. Note that the session is dead by now, with all memory deallocated. The oppersite of R0 = 6. IEMSI uses this to delete the 'details' window. R0 = 8 : Service call (a/b/c/d/e) --------------------------------- R2 = service number To claim exit with R0 = -1 Service call of any type (individual, all in session or all everywhere) which is broadcast by a protocol wishing to communicate with some others. Service numbers: &0000 - &1FFF Termite service calls &2000 - &7FFF Allocated by DoggySoft for anybody &8000 - &FFFF Anybody can use Termite service calls: &0xx - Misc &1xx - Text emulation slaving &2xx - TermiteIP R0 = 9 : Pre-finish session --------------------------- Session is about to finish, tidy up. Last chance to send data while carrier is still high (if it *is* still high, that is, and we're not finishing due to the carrier dropping ;-) ) R0 = 10 : Upload warning ------------------------ R2 = your protocol number R3 = -1 R4 = pointer to RMA block R6 = 0 (interrupt), 1 (normal) Normally you should call routine_addprotocol, note that just to be nice I've called service 8 to find out if you can do interrupt file transfer :) R0 = 11 : Overstyle return -------------------------- R2-> anchor to overstyle or -1 (R3 will be 0) R3 = length of overstyle This is in return to you requesting an overstyle from the editstyle routines. You will not be called with your session workspace, ie. wk will be -1. Please call WimpExt to declaim the block after you have finished with it. R0 = 12 : Statistics -------------------- R2 = "Disconnected" or -1 R3 = "Elapsed time: xx.xx" or -1 R4 = "Estimated cost: £xx.xx" or -1 Claim this (if you are a pre emulation) to stop statistics from being entered into the session. Claim this if you are an emulation as well as displaying the text. Emulations should write the three strings to the screen, making sure they are visible. This is sent just before session finished (R0=13) is called, if nobody claims this, then obviously this text is not put anywhere. R0 = 13 : Session finished -------------------------- Broadcast to all protocols, you may remove yourself if you feel lucky, punk. No io will occur after this has been called, this is your last chance matey to send in or out data :) If you claim this, this will stop the session from finishing, note that the statistics will already have been displayed by this stage, so you must also claim R0=12 if you are going to claim this. R0 = 16 : User input (c) then (a) --------------------------------- R2 = keycode When a key is pressed, the emulation which owns the window will issue this broadcast event. If this is not claimed, any keycodes <256 will be issued as serial output and any keycodes >255 will be Wimp_ProcessKey'ed. The keycode is of the format: bits 0-23 keycode 24-30 reserved; ignore 31 if set, ACT is held down You do not need to check for the standard ACT values as documented in this file, termite will do this for you after no-one has claimed the user input message. R0 = 17 : Serial preoutput (c) ------------------------------ R2 = pointer to block R3 = bytes in block Protocols interested in specific sequences should scan the block for strings. Do not claim or alter the block! You should be installed in the current session as a pre-protocol and trap R0 = 18. R0 = 18 : Serial output (a) --------------------------- R2 = pointer to block R3 = bytes in block The block is 8k in length, with 10 undefined, please ignore) If R2=0 then R3 = pointer to last 'termite' menu entry if R2=0 R4 = menu item number (in order of startupdat) if R2=0 The block in R1 is the standard one returned by Wimp_Poll, see PRMs for details. You shall receive this message if a) the user makes a selection on an unknown entry in the main menu (due to the Startupdat file) and hence this is sent to you (and only you) with R2=0. Usually you would use R4 to decide what action to take. b) you have created a new menu, the creator of the menu is recorded by Termite and this menu selection event will be sent to you with R2=-1. Note: if you have a submenu continuation of an entry defined in startupdat then R3/R4 will be correct for the entry in the startupdat file, you should look at R1 to find out where it has gone. R0 = 10 : Scroll request event (d) then (b) ------------------------------------------- This is a block returned by Wimp_Poll, see PRMs for details. R0 = 11 : Lose caret event (d) then (b) --------------------------------------- This is a block returned by Wimp_Poll, see PRMs for details. R0 = 12 : Gain caret event (d) then (b) --------------------------------------- This is a block returned by Wimp_Poll, see PRMs for details. R0 = 13 : Create submenu request (e) ------------------------------------ R1 = message block inc. selection route at R1+32 (see PRMs) R2 = menu id (-1=user menu, 0=main, 1=iconbar, etc [same as menu types]) If R2=0 then R3 = pointer to last 'termite' menu entry if R2=0 R4 = menu item number (in order of startupdat) if R2=0 Like the menu selection route, you can use this to open submenus off any entries on the main menu that you added via the startupdat file. Note: if you have a submenu continuation of an entry defined in startupdat then R3/R4 will be correct for the entry in the startupdat file, you should look at R1 to find out where it has gone. Also, remember to write the location of your submenu into Termite's menu structure so that 'adjust' works. R0 = 14 : Data message (e) -------------------------- R1 = data block This is a block from wimp user message numbers 0 to 7, you will get this message if you claim them using routine_data. R0 = 15 : Termite menu warning (c) (a) -------------------------------------- R1-> menu structure about to be created R2 = menu id (0 = main, 1 = iconbar, etc. [same as menu types]) Termite is creating this menu but this is your chance to shade out any entries that you deam inappropriate, eg. the capture protocol shades out the close capture entry if no capture is going. R0 = 17/18 : Unknown message (c) (d) (b) ---------------------------------------- R1 = data block ============================================================================= Options code ----------------------------------------------------------------------------- R0 = reason code other registers depend on reason code Exit: Must preserve all registers except those returning values. R0 = 0 : Write options to window -------------------------------- R1 = options block anchor Exit: R0 = window handle Setup your options window and return the window handle, it will be linked to the main style window (it must be the correct size). Remember R1 and use it when the user changes something in your options window. R0 = 1 : Read options from window --------------------------------- R1 = options block anchor Return an error if something is wrong with the user's input. ============================================================================= Routine block ----------------------------------------------------------------------------- +000 routine_getwindow ====================== Exit: R0 = window handle R2 = status bar handle R3-> OS_Module RMA block containing indirected workspace (main) R4-> OS_Module RMA block containing indirected workspace (status bar) Creates a window with a detached vertical scrollbar and status bar below the horizontal bar. To open, close and delete your window, you should call WimpExt_OpenLinked, WimpExt_CloseLinked and WimpExt_DeleteLinked respectively. When you receive a session close message, delete the window and the status bar, and declaim the two RMA blocks. +004 routine_getdatafile ======================== R0 = file number Exit: R2 = anchor to data file num name 0 IBMPC24 1 IBMPC22 0,1; The hi-res version (IBMPC9b) is basically the same as the low res version but has double the number of pixels in height - these are both sprite data files (ie in raw format) to be passed to the Termite library for emulations +008 routine_userinput ====================== R0 = key code R2 = session number Exit: userinput message broadcast +012 routine_makebeep ===================== beeps to user's specifications +016 routine_openmainmenu ========================= none Opens the main menu at pointer position. +020 routine_menuclaim ====================== none When a selection is made a message will be sent directly to the session and protocol that was last called by Termite. +024 routine_crc16 ================== R2 = pointer to start of data R3 = pointer to byte after end of data (ie. R2+length) Exit: R0 = 16bit CRC Returns an EMSI/XModem compatible 16-bit CRC. +028 routine_sendoutdata ======================== R2-> start of data (flag in bit 31) R3-> byte after end of data (ie R2+length) Exit Data is sent to serial port, or error. It is preferable that not more than 256 bytes are sent at a time. If bit 31 is set then if a file transfer is active (ie routine_indirect has been called) then the output will continue as normal instead of being suppressed. +032 routine_addprotocol ======================== R0 = session number R2 = protocol number R3 = -1 for pre, 1 for post R4...R6 = parameters (mapped to R3...R5 in 'New session') Exit Protocol is added, or error. +036 routine_protocolnum ======================== R0-> protocol name Exit R0 = protocol number, or -1 +040 routine_gettemp ==================== Exit: R0-> 4k temp block (in WimpSlot area) +044 routine_loadfileheap ========================= R0-> filename Exit: R0-> anchor, or error. R2 = length +048 routine_reportmessage ========================== R0-> string Exit returns after OK clicked on +052 routine_termiteinfo ======================== Exit: R0-> "Termite alpha" etc R2-> "0.09 (19-Aug-1994) R3 = serial number +056 routine_servicecall ======================== R2 = service number R1,R3-R8 = registers R9 = session number Exit R0 = -1 if claimed. sent to all sessions, or error. This sends a class (a) message. +060 routine_removeprotocol =========================== R0 = session number R2 = protocol number Exit: removes protocol, or error. The protocols 'close session' entry is called. +064 routine_tokentermite ========================= R0 = token to look for Exit: R0 = string If the token is not found, an error will be OS_GenerateError'ed, so you will not get control back. +068 routine_crc32 ================== R2 = pointer to start of data R3 = pointer to byte after end of data (ie. R2+length) Exit: R0 = 32bit CRC Returns a ZModem compatible 32-bit CRC. +072 routine_unixdateto ======================= R2 = day R3 = month R4 = year Exit: R0 = seconds +076 routine_unixdatefrom ========================= R0 = seconds Exit: R0 = seconds left R2 = day R3 = month R4 = year +080 routine_corneropen ======================= R0 = window handle R2 = main window handle Opens the window handle in R0 using the top-left corner of the main window handle in R2. +084 routine_cornermenu ======================= R0 = window handle (or menu structure!) R2 = main window handle Opens the window handle in R0 using the top-left corner of the main window handle in R2, but instead of routine_corneropen, makes it a transient menu. +088 routine_current ==================== Exit: R0 = protocol number R9 = session number +092 routine_drag ================= R0 = protocol number (bit 31 if set means within session) R2 = anything R9 = session number Causes Termite to return directly to you when a drag ends. R2 can be used if you have more than one menu, as Termite will return the R2 to you in the wimp event (see wimp reason code 7). If bit 31 is set, then you will be called with the workspace pointer for the current session setup (of course you have to be instated in the session), if bit 31 is unset then you will just get the gwk workspace and not the wk workspace (prefered) +096 routine_dataclaim ====================== R0 = protocol number or -1 for Termite (bit 31 if set means within session) R9 = session number Causes ALL wimp user messages in the range 1-4, 6-7, &457BC, &46483 to be sent to you, and nobody else. This is required if you are doing file transfers. If bit 31 is set, then you will be called with the workspace pointer for the current session setup (of course you have to be instated in the session), if bit 31 is unset then you will just get the gwk workspace and not the wk workspace. Every null-event Termite will reset to itself incase something goes wrong. +100 routine_getmenutemp ======================== Exit: R0 = two 4k temp blocks For creating menus, the first 4k of the block is for the main menu, and the next 4k is for the sub menu. +104 routine_gettermitesprites ============================== Exit: R0 = sprite block, containing: optoff, opton, radiooff, radioon, doggylogo, termite, doggysoft, gright, left, right, pleft, pright, yes, no. The gright in termite has no border. +108 routine_tickmenu ===================== R0 = option to tick R1 = pointer to menu structure This call unticks all entries in the menu structure except the option in R2, used for option menus where you never have more than one ticked. +112 routine_tickmenustr ======================== R0 = string to tick R1 = pointer to menu structure This call unticks all entries in the menu structure except the option with the same string as in R0, used for option menus where you never have more than one ticked and want a quick way of ticking the option. +116 routine_selection ====================== R0 = tagname R1 = options block R2 = block +0 = item selected Exit: R0 = string to set icon to For list items, sets the options block to the item selected, and returns a pointer that you can pass to WimpExt_SetIconString to set the icon with. Normally you would then call routine_tickmenustr with the item selected to tick the menu item. +120 routine_controllines ========================= R0 = bit 0 set for tx, bit 1 set for rx R2 = bits to clear R3 = bits to toggle Sent around to everyone in the current session, and then if nobody claims will be sent to the block drivers. +124 routine_printmessage ========================= R0 = message Opens message window with the text pointed to by R0, there is a minimum display time of one second which occurs when two messages are displayed at the same time (the computer will not multitask within this period). After two seconds the window will close. +128 routine_indirect ===================== R0 = address to call } must of course R1 = workspace } be in RMA R2 = session R3 = delay in centiseconds Redirects all input/output to the specfied address (which must be in RMA), this is for file transfers to work under interrupts - you will be called every R3 centiseconds (0 is treated as 1). +132 routine_transfer ===================== R0-> title string R2 = session number Exit: R0 = window handle R2 = slider id R3 = icon for leafname R4 = icon for filesize R5 = icon for bps R6 = icon for time R7 = icon for text Ensures the window is created and returns details about it, you should open the window in the centre of the screen with the relavent details set. +136 routine_saveas =================== R0 = protocol R2 = session R3 = filetype R4 = filename text for writable icon Exit: R0-> window handle You should call WimpExt_CreateMenu or CreateSubMenu or whatever after you call this routine, when the user clicks on OK or the drag ends somewhere, you will be sent service call &400 or &401. +140 routine_startupdatcall =========================== R0 = reason code R1 = protocol R2-R8 = registers Exit: R1 = 0 if called, -1 if no such protocol R0,R2-R8 depend on reason code Calls the code entry in the startupdat file. +144 routine_sendindata ======================= R2 = pointer to start of data R3 = pointer to byte after end of data (ie R2+length) Exit: Data is sent to the session as if it came from the serial device, or error. It is preferable that not more than 256 bytes are sent at a time. +148 routine_sendoutdata2 ========================= R0 = reason code R0 = 0 : Get output block Exit: R0 = serial output block (1k long) R0 = 1 : Send output block registers as for routine_sendoutdata Normally routine_sendoutdata copies the data from the given block into Termite's internal serial output block. It may be useful to use these two routines so that you can bypass using a temporary buffer. +152 routine_sendindata2 ======================== R0 = reason code R0 = 0 : Get input block Exit: R0 = serial input block (1k long) R0 = 1 : Send input block registers as for routine_sendindata Normally routine_sendindata copies the data from the given block into Termite's internal serial input block. It may be useful to use these two routines so that you can bypass using a temporary buffer. +156 routine_viewsession ======================== R0 = session number Goes through the session telling protocols to open a window, the first one that opens a window will claim this event and stop the others. +160 routine_createsession ========================== R0-> overstyle or -1 R1 = overstyle length R2 = basestyle or -1 R3 = substyle or -1 R4...R6 = parameters (mapped to R3...R5 in 'New session') Exit: R0 = session number Creates a session with the emulation specified in the styles as the base protocol. Normally you would call routine_viewsession to open the main window after calling this. see routine_createsession2 +164 routine_getstylemenu ========================= R0 = bitfield, bits meaning if set 0 extra 'default style' option 1 no submenu arrows 2-31 reserved; must be 0 Exit: R1 = pointer to menu Returns a pointer to a style menu (which resides in fixed memory within termite). +168 routine_getsubstylemenu ============================ R0 = basestyle Exit: R1 = pointer to menu Returns a pointer to a substyle menu (which resides in fixed memory within termite). The basestyle starts at 0 and so the menu warning message can be directly used (or n-1 if bit 0 of R0 was set for routine_getstylemenu). +172 routine_iconset ==================== R2 = session number R3 = icon type R4 = string Sets the icon number to the string specified. Note that setting the timer icon is a silly thing to do, since it will be reset at the next wimp poll. If you want to set the timer icon permanently you would have to install yourself as a pre-protocol and then intercept all the icon set messages (reason code 23 in terminal event code). +176 routine_secstotime ======================= R0 = seconds Exit: R0-> "HH:MM:SS" +180 routine_setalphaflags ========================== R0 = session number R2 = bits to clear R3 = bits to toggle Sets the alphaflags in the terminal window for the session, see reason code 23 in terminal event code for a list of alpha flags. b0=@, b1=A, b2=B, b3=C etc. +184 routine_basestylenumbertoname ================================== R0 = base style number Exit: R0 = name or -1 +188 routine_substylenumbertoname ================================= R0 = sub style number R2 = base style number Exit: R0 = name or -1 +192 routine_basestylenametonumber ================================== R0 = base style name Exit: R0 = number or -1 +196 routine_substylenametonumber ================================= R0 = sub style name R2 = base style number Exit: R0 = number or -1 +200 routine_crc32b =================== Exit: R0-> crc routine Call the routine like so: R0 = byte R1 = old crc (start -1) Exit: R0 = corrupted R1 = new crc The routine is in RMA so can be called anytime (ie. in a file transfer). +204 routine_setcurrent ======================= R0 = session current or -2 to read R2 = protocol current or -2 to read R3 = protwk current or -2 to read Exit: R0 = old session current R2 = old protocol current R3 = old protwk current I wouldn't use this if I were you, but it's here incase we need to patch around any bugs. A legit reason for calling this would be just before you claim menus - so that the returned menu requests are returned to you outside of the session (ie you call this with -2,-2,-1). Termite should now preseve the current's when broadcast routines are called.     +208 routine_txbatchadd ======================= R0-> filename Adds the specified file to the batch list. +212 routine_compactheap ======================== Compacts the heap safely, at the moment this will also close any menu that is on the screen (hence do not use this unless you have just done a really heap-intensive process). +216 routine_closesession ========================= R0 = session number Removes the session specified, copies logs etc. +220 routine_logfileadd ======================= R0-> string to add bit 31 for extended information R2 = session number or -1 for main log bit 31 being set means that it is something only to be added if the user has 'extended logging' turned on. +224 routine_editstyle ====================== R0 = 0 for edit, 1 for create, 2 for get_overstyle 3 for alter session and R2 = options specifier (see +396) flag in bit 31 indicates use overstyle passed in R4 and R5. 4 for alter session with save, same as 3, except R1->filename, R6->first line in file (eg. description of style). the style being saved will be 'compared' with the default style so that only different options are stored. R2 = base style R3 = sub style If bit 31 set in R0: R4-> overstyle R5 = length of overstyle Sets up the style window, does not actually open any windows until you call routine_editstyleprotocol. Note that it is quite likely you will get an error back from this routine, for example if it is in use somewhere else, so make sure you handle errors correctly. If a protocol calls this routine with R0=2 then Termite will use the current session and protocol values to return the event back to you after OK is clicked on. Note that the overstyle passed in R4 and R5 (when bit 31 is set in R0) has no effect other than to merge that file with the options... ie. if you ask to edit a style and supply an overstyle, then the user might get confused since if he changes nothing, something is changed! +228 routine_editstyleprotocol ============================== R0 = protocol or -1 for main +232 routine_batchedit ====================== Opens the batch editor window +236 routine_batchconfirm ========================= R0 = session R2 = protocol Opens the batch editor window, and when the user clicks on 'Send' the protocol is called via the upload warning entry. +240 routine_callratemenu ========================= Exit: R1-> callrate menu Gets a callrate menu which (as normal) is stored in Termite's temp menu area. Subtract one to get the actual call rate number from the selection returned by the wimp, since the top entry is 'unknown' which is -1. +244 routine_callratenumbertoname ================================= R0 = number Exit: R0-> callrate name +248 routine_callratenametonumber ================================= R0-> callrate name Exit: R0 = number +252 routine_callratecrctonumber ================================ R0-> callrate 32bit crc Exit: R0 = number This is for Jon since he wanted a way of storing the callrate name as a crc value. +256 routine_callratenumbertocrc ================================ R0 = number Exit: R0 = callrate 32bit crc +260 routine_callratenumbertoinfo ================================= R0 = number Exit: R0-> callratedat +264 routine_callratetabletopointer =================================== R0 = table number Exit: R0-> band block +268 routine_callratesecstocost =============================== R0 = seconds R2 = callrate number Exit: R0 = cost in ten thousanths of pence, or -1 for error This calculates the cost of the call from the current time backwards for R0 seconds. You should round your seconds up, since it is assumed BT charge you for the forthcoming second (like they did for units). If you pass <=0 seconds, you will got 0 on exit. +272 routine_storecallrate ========================== R0 = session R2 = callrate number or -1 to blank Given session number and callrate number stores it in the session data so that the cost is updated on the status bars. +276 routine_costtopounds ========================= R0 = ten thousanths of pence Exit: R0-> "£XX.XX" +280 routine_currenttime ======================== Exit: R0 = &DDHHMMSS +284 routine_callcostinfo ========================= R0 = session Exit: R0 = seconds or -1 R2 = callrate number or -1 R3 undefined The callrate could be setup even if the call has not been started, if the call has not been started, then both R0 will be -1. +288 routine_finishsession ========================== R0 = session Finishes session (drops carrier if appropriate, freezes session, whatever). The directory notes that the carrier has dropped and finishes the session, hence raw sessions the directory does not finish the session, cunning eh? Note routine_flags, which can prevent dropping of carrier. +292 routine_rxpath =================== Exit: R0-> pathname for downloading, ie '.Received' +296 routine_basestyleloctonum ============================== R0 = location (0 to ...) Exit: R0 = base style number If you have a list of the base styles in (say) a menu, this will take the location (ie. 0 for the first entry on the menu) and convert it to the actual base style number - this is needed because if the user has deleted a base style the base styles numbers might not equal the locations on the menu. +300 routine_substyleloctonum ============================= R0 = location (0 to ...) R2 = bse style number Exit: R0 = sub style number +304 routine_protocolbroadcasta =============================== registers as necassary R10 = session number R8 = offset (mapped to R11 internally) Broadcast to every protocol currently active in the specified session. +308 routine_protocolbroadcastb =============================== registers as necassary R8 = offset (mapped to R11 internally) Goes through all sessions calling routine_protocolbroadcasta. +312 routine_protocolbroadcastc =============================== registers as necassary R10 = session number (or -1) R8 = offset (mapped to R11 internally) Broadcast to every protocol (not necassarily active) in the specified session. +316 routine_protocolbroadcastd =============================== registers as necassary R8 = offset (mapped to R11 internally) Goes through all sessions calling routine_protocolbroadcastc. offset = 20 for terminal event +320 routine_filenameconv ========================= Exit: R0-> convertor routine (in RMA) Call this routine like so: R0-> foreign filename, control or space terminated R1-> block to contain valid RISC OS filename on exit (140 bytes) Resulting string will be the pathname setup in Termite plus an unmangled filename with all illegal characters taken out. Note that the routine pointer is passed in the indirection block as well. +324 routine_currentmodem ========================= R0 = session Exit: R2 = modem make number R3 = modem model number +328 routine_modemdetails ========================= R0 = line number (bit 31 set to not process bar chars) R2 = modem make number R3 = modem model number Exit: R0-> resulting string (null terminated) Can contain control codes. +332 routine_defaultstyle ========================= Exit: R2 = default base style number R3 = default sub style number (can be -1) +336 routine_setdefaultstyle ============================ R2 = base style name R3 = sub style name (null string acceptable) Will be saved the next time the options window is saved or the routine below is called. +340 routine_saveoptions ======================== Save all options that may have changed, in particular the default style. +344 routine_txbatchremove ========================== R0-> filename Removes the specified file from the batch list. No error is returned if file does not exist in the list. +348 routine_processstring ========================== R0-> string (control terminated) R2-> buffer Exit: R0-> buffer (R2 on entry) (null terminated) R2 = length (including null) Processes the string on input so that all | characters create control codes. +352 routine_protocolbroadcastdirect ==================================== registers as necassary R9 = protocol (flag in bit 31) R10 = session number R8 = offset (mapped to R11 internally) Returns registers R0 to R5 (registers R6 upwards are stored and preserved) If bit 31 is clear then this message will be sent to the protocol with gwk setup but not wk. If bit 31 is set then Termite will search for the protocol's wk and call it with both gwk and wk setup. +356 routine_protocolload ========================= R0 = protocol number Ensures the protocol is loaded. +360 routine_servicecall2 ========================= R2 = service number R1,R3-R8 = registers R9 = session number Exit R0 = -1 if claimed. sent to all sessions, or error. THIS SENDS A CLASS C MESSAGE - ie. this does the same as routine_servicecall except that it goes to everyone in the session, rather than everyone active in the session. +364 routine_clearsession ========================= R9 = session number Clears the screen. +368 routine_idletime ===================== R0 = new idle time Sets the current idle time for the next wimp poll, set this to a very low number to cause lots of null events. Note that you should definitely NOT call this if you can help it, it will screw up Termite's lovely null handling routines! +372 routine_currentscale ========================= R0 = scale Sets Termite's record of the current scale view for the current session. +376 routine_tokenprotocol ========================== R0-> token R2-> start of messages file R3 = length of messages file Exit: R0-> string +380 routine_getemulationmenu ============================= Exit: R1-> menu Returns a pointer to an emulation menu (which resides in fixed memory within termite). Due to an unfortunate confusion of terms, this is REAL emulations which provide data display and throughput. I called all base protocols 'emulations' in the style editor, whoops (well, it's less confusing to the user I guess). +384 routine_sendoutstring ========================== R0-> string (control terminated) Sends the string using routine_sendoutdata but calculates the length for you +388 routine_sessionflags ========================= R0 = session number R2 = bic flags R3 = eor flags Exit: R0 = flags flags: bit meaning if set 0 Session has been finished (do not alter) 1 Session has a carrier 2-3 Finish carrier action %00 = ask user if Termite should drop carrier %01 = always drop carrier %10 = always maintain carrier if present %11 = undefined 4 Autologon not supported [not implemented yet] 5 Emulation slaving flag, if this bit is set then ANSI will not process serial data. 6-31 reserved; do not alter bit 4 is set by the dialling directory, so that various types of auto logon will not take affect, notably IEMSI and scripts. +392 routine_blockdriver ======================== R0 = session number R2-> new rxblockdriver (or -2 to read) R3-> new txblockdriver (or -2 to read) R4 = new rx port or -2 to read R5 = new tx port or -2 to read Exit: R2-> old rxblockdriver R3-> old txblockdriver R4 = rx port R5 = tx port used by CallDemon with R2=R3=-1 to get rid of blockdriver usage in the session. R2=R3=-1 is acceptable and Termite will suspend all i/o. All blockdriver pointers are to an RMA block, if you do remove the block drivers, then you should declaim the returned 'old' rma block(s). Make sure that you check that if they return the same pointer you only declaim the block once! +396 routine_sessiondetails =========================== R0 = session number Exit: R2 = options specifier R3 = monotonic time carrier detected (or 0) R4 = transmit buffer length (4096 if there's no block driver) R5 corrupted R6 corrupted The options specifier can be used to create a session using the options of an already active session, eg. CallDemon creates a session with the Internet Control panel with the options it already holds. [the options specifier is infact an anchor to a list of options blocks, hence this options specifier is only valid while the session is still there] The options specifier will be the options specified in the base and sub styles with any overstyle applied to it, as well as any options that may have changed since the session was started. +400 routine_createsession2 =========================== R0-> overstyle or -1 R1 = overstyle length R2 = options specifier R4...R6 = parameters (mapped to R3...R5 in 'New session') Exit: R0 = session number Like routine_createsession this creates a new session, however this takes an options specifier rather than two styles. see routine_sessiondetails for more information about the reason for this routine. +404 routine_getclientid ======================== Exit: R0 = client ID or error 'No connection' This is just a convienient way of sending routine_protocolbroadcastd with the correct reason codes (see Internet service call &200). +408 routine_termiteinfo2 ========================= Exit: R0 = wimp task handle R2 = wimp version number returned from Wimp_Initialise R3 = flags flags: bit meaning if set 0 Termite is in a 'get data from serial port' process 1-31 reserved; do not alter +412 routine_clock ================== R0 = reason code other registers depend on reason code R0 = 0 : Initialise sprite -------------------------- R1 = current sprite block anchor, or 0 R2 = window handle R3 = icon handle Exit: R0 = new sprite block anchor, or 0 if failed due to memory R0 = 1 : Draw hands ------------------- R1 = current sprite block anchor R2-> 5-byte time block R0 = 2 : Remove hands --------------------- R1 = current sprite block anchor R2-> 5-byte time block +416 routine_protocolname ========================= R0 = protocol number Exit R0-> protocol name, or -1 +420 routine_internetlog ======================== R0-> null terminated string Exit: possible error 'No connection' This is just a convienient way of sending routine_protocolbroadcastd with the correct reason codes (see Internet service call &202). +424 routine_statusbartextmsg ============================= This reports the message "To do an text upload (ie. an ASCII transfer), drag a textfile to this icon." to the user. +428 routine_statusbardatamsg ============================= This reports the message "To do a data upload (ie. a Zmodem transfer), drag a file to this icon." to the user. +432 routine_upload =================== R0-> protocol name R2-> null-terminated list of null-terminated filenames R3 = session Starts an upload, emulations use this for their icon-bar icons. +436 NOT USED ============================== Yes, you got it, an unused routine location... weird eh? +440 routine_textgotoline ========================= R2 = line number R3-> text R4-> end of text Exit: R0-> line required or error For textfiles terminated with LF only, this will handle very efficiently returning errors for invalid lines etc. +444 routine_textnextline1 ========================== R3-> current pointer R4-> end of text Exit: R3-> updated pointer (next line) or error Error occurs if EOF or a control character is encountered (invalid line) +448 routine_textnextline2 ========================== same as routine_textnextline1 except bit 31 will be set up on exit if EOF is encountered, an error will occur as usual if a line appears to be invalid. +452 routine_addoverstyle ========================= R0 = session number R2-> overstyle R3 = length of overstyle block This will apply the overstyle to the specified session, used by the Internet control panel to apply the settings in !TermiteIP.Options.Options +456 routine_finishsessiontxt ============================= R0 = session R2-> finish_message (or -1 for no message, or -2 for default) R3-> finish_elapsed, %0 = time (or -1 for no message, or -2 for default) R4-> finish_cost, %0 = cost (or -1 for no message, or -2 for default) See routine_finishsession. +460 routine_canonicalisemenu2 ============================== R0-> buffer R1-> menu structure R2-> end of buffer R3 = additional control terminator (eg ',') Exit: R2 = end of output block used (or 0 for overflow) +464 routine_changebaseprotocol =============================== R0 = session R2 = new base protocol Both protocols must be residant in the current session. +468 routine_sendbreak ====================== R0 = session Tells the block driver (if present) to generate a break. +472 routine_dropcarrier ======================== R0 = session equv. of doing ACT-X, it drops the carrier. +476 routine_heapcheck ====================== Will clear screen to mode 0 and enter Sledgehammer if an error occurs or it may bring up an error window through termite's error handlers if the length check does not pick up the heap corruption. +480 routine_currentsession =========================== Exit: R0 = current session +484 routine_internetcall [aka Internet_Call] ========================= R0 = reason code entry and exit parameters depend on reason code R0 = 0 : Force close of connect window -------------------------------------- Sends a service call to the connect window to tell it to fake a click on it's ok button. R0 = 1 : Check SMTP connection ------------------------------ R1-> filename Exit: R0 = 0 - no = 1 - yes If R0 is 0 then the specified filename is not currently being dealt with, but if it is 1, then the specified filename is being processed (being sent out). +488 routine_countsessions ========================== R0-> protocol, eg. "NEWS" Exit: R0 = number of sessions with that protocol as the base protocol +492 routine_sessionname ======================== R0 = session number R2-> string to name session Exit error if session invalid etc. You can pass strings as long as you like (truncated to 30 chars). This changes the text in the close session menu - the dialling directory changes the session from the base style to the BBS you are calling for example, telnet does this too. +496 routine_protocoltoinfo =========================== R0 = protocol number Exit R2-> module R3-> startupdat R4-> flags Flags are Termite's internal flags, not the protocols. +500 routine_recachestyle ========================= R0 = substyle number or -1 R2 = basestyle number Exit error if invalid style or file not found Termite keeps a copy of every style in memory, this call tells termite to discard it's copy and reload it from disc. +504 routine_checkprotocol ========================== R0 = session number R2 = protocol number Exit: R0 = 0 (does NOT exists in session), 1 (exists in session) Checks to see if the protocol exists in the session, this is done automatically by routine_addprotocol since the same protocol cannot be in a session twice. +508 routine_sessionsettermiteoption ==================================== R0 = session R2-> tagname R3-> data This sets a Termite option, eg. you can set local echo using this. +512 routine_updatescreen ========================= R0 = session This ensures that the current emulation has an up-to-date screen, emulations normally only update their screen every null event. This routine actually sends service call 32 around the session. +516 routine_starttask ====================== R0-> Wimp_StartTask string Exit: R0 = task handle This ensures the current wimpext task is maintained. +520 routine_filenamemangle =========================== Exit: R0-> convertor routine (in RMA) Call this routine like so: R0-> filename, control terminated R1-> block to contain unique RISC OS filename on exit (256 bytes) Note that the routine pointer is passed in the indirection block as well. +524 routine_loadfilerma ======================== R0-> filename Exit: R0-> rma block R2 = length +528 routine_createfilemenu =========================== R0-> pathname (flag in bit 31) R2-> menu title R3-> match string (0 for all in directory) Exit R0-> RMA menu block or, if bit 31 set, R0 = 0 for no entries found Indirected data is held immediately after the menu entries. If bit 31 is clear and no entries are found, a menu consisting of 'None' will be returned, otherwise R0 = 0 if no entries are found. +532 routine_txfree =================== R0 = session number exit: R0 = no. of bytes still to transmit R2 = no. of bytes free in buffer R3 = size of tx buffer (i.e. R0 + R2) Reads the serial buffer to see how many bytes are in it, how many bytes are free, and how big it is entirely. Needs to use service calls or something for 'telnet'. ============================================================================= File transfers ----------------------------------------------------------------------------- When a protocol wants to initiate a file transfer, it can do it in one of two ways: Either take input and output in the usual way by linking into the current session as a pre handler or take input and output under interrupts. Call routine_indirect, Termite will call you as follows: Entry: R12 = data block +00 = your routine +04 = workspace (R2 on entry to routine_indirect) +08 = threaded flag +12 = rx blockdriver pointer +16 = tx blockdriver pointer +20 = rx port number +24 = tx port number +28 = centisecond delay +32 = internal +36 = pointer to filenameconv routine +40 = tx buffer length +44 = pointer to filenamemangle routine Exit: All registers must be preserved On entry the threaded flag will be 1, on exit you must set the threaded flag to 0. ** Zmodem and other similar protocols should issue the file transfer service and see if it is allowed to do a background transfer, if not it should just install itself as a pre protocol in the current session and take the data normally (hence Zmodem can work in telnet). ============================================================================= ACT keys ----------------------------------------------------------------------------- The following are the assigned keys under Termite, and whether they are handled by Termite or another protocol: key: Protocol action: ACT A ACT B Termite Open batch ACT C Capture Open capture ACT D ACT E Line Editor Open line editor window ACT F ACT G ACT H *Termite Open key help window NOT IMPLEMENTED ACT I IEMSI Open IEMSI server information ACT J ACT K KeyLock Open keyboard lock window ACT L *Termite Clear screen ACT M ACT N ACT O ACT P ACT Q *Termite Quit session ACT R ACT S *Termite Style editor ACT T Split Chat Start talk mode ACT U ACT V ACT W *Termite Send break ACT X *Termite Disconnect ACT Y ACT Z Cack Spew cack ACT PGUP *Termite Upload ACT PGDN *Termite Download ACT PRINT *Termite Save screen ACT INSERT ACT DELETE ACT COPY ACT HOME ACT BREAK RISC OS Reset! Keys marked as '*Termite' are done by termite itself. Keys ticked have been implemented. ============================================================================= Termite service calls: Misc ----------------------------------------------------------------------------- 1 = Emulation service *EMULATION* if you are an emulation (ANSI, TTY etc) then you should claim the service and exit with R2 = name. 2 = IEMSI service *EMULATION* if you are an emulation then claim this with R2-> IEMSI emulation R3 = &00RRNNCC (rows, nulls, columns), for example the 'AVATAR/0+' emulation returns 'AVT0'. 3 = obsolete (was capture service) 4 = Line editor service (returns statusbar handle, not main handle) 5 = ASCII upload allowed, yesno? } *EMULATION* 6 = Key Lock service } *EMULATION* if you own the current communications window then return with R2 = window handle. This is used by the above protocols so that it can open a window in the top right corner. If you do not want the protocol to operate on your session/window, do not claim this event. 7 = Restore caret service *EMULATION* if you are an emulation then you should claim this and set the caret to your window (this is used by Key Lock to return the caret). 8 = File transfer service *TELNET/etc* If you are a protocol who is using an emulation window and you cannot allow direct blockdriver access to get data for file transfer protocols then claim this and Zmodem etc will use foreground routines. 9 = Dialling directory service *DIALLING DIRECTORY* The dialling directory responds to this message by opening it's dialling window on screen. If an error is generated Termite will not close the new session window (or if this is a result of a click on the iconbar, will open the new session window). 10 = Open capture *CAPTURE* 11 = Close capture *CAPTURE* 12 = File transfer complete *DIALLING DIRECTORY* R3 = 0 (upload), 1 (download) R4 = number of files sucessfully transfered R5 = number of bytes sucessfully transfered Send through current session (routine_sendservice)... Termite will take note of this and write to a logfile. Please log any files you transfer yourself like: XXXXload: - XXbytes at XXcps when all files have been downloaded/uploaded send this service, and Termite will enter the following: X files (XXXXbytes) successfully XXXXloaded. 13 = unused (was script service) .. 14 = Get sprite service *EMULATION* R3 = 0 for med-res, 1 for hi-res Exit R2 = anchor pointing to sprite block 15 = Get text service *EMULATION* Exit R2 = anchor, R3 = length 16 = IEMSI stop service 17 = IEMSI chat start I (claim this and the ACK will be sent) 18 = IEMSI chat start II (start your window) SplitChat will call itself with parameters so that it will not open a window 19 = IEMSI chat stop (close your window) 20 = Disconnect ok? Claim for Termite to ignore disconnect 21 = Internet click (start session please) #obselete, see 205# 22 = Generate cack quote (call after ensuring protocol is loaded) R3-> buffer, will exit with the string null terminated. 23 = Open line editor if not already open. 24 = Close line editor if already open. 25 = Directory telephone number request R3-> telephone number in directory entry Exit R2-> telephone number to dial If someone claims this, then the directory will dial the number instead of the entry it thinks the user wants to dial. 26 = Directory 'shade out auto-logon?' request If someone claims this, then the directory will shade out the icon that says 'auto-logon'. 27 = Directory 'shade out open icon?' request If someone claims this, then the directory will shade out the icon that says 'open'. 28 = Directory 'don't open connect message' request If someone claims this, then the directory will not open the window saying 'connected'. 29 = SMTP is this mail being processed, request. R3-> filename Claimed if the filename matches the one SMTP is currently processing, so you must send this around all the sessions with workspace intact ie. class C message. 30 = Internet control panel closing down News will close down too, if it gets this. 31 = Script 'do some more' service for current session. Exit: R2 = 0 (not finished yet) R2 = 1 end reached, R3-> A%-H% block R2 = 2 chain reached (not finished yet), R3-> A%-H% block R2 = 3 exec reached (not finished yet), R3-> A%-H% block R2 = 4 close reached (session finished), R3-> A%-H% block 32 = Update screen Sent around the session, this is an instruction by Termite to redraw your screen - it is sent at the end of getting data from the serial port to make it nice and fast. 33 = Nodelist service *NODELIST* The nodelist protocol responds to this by opening it's window. 34 = Directory dial *DIALLING DIRECTORY* R3-> number R4 = base style R5 = sub style or -1 35 = Environment R1-> environment string If you want the file that R3 points to, do something! ============================================================================= Termite service calls: Text emulation slaving ----------------------------------------------------------------------------- Text emulations can normally be slaved so that you do not have to handle the window etc, or so that you do not have to duplicate code (eg. Avatar, ShowControl and HexDump use this facility). Emulations that currently support this are: ANSI R2 = &100 : Get information --------------------------- Exit: R3 = ID for direct access R4 reserved to be corrupted in future The ID is a standard Termite WXII library id, so call WimpExt_CallLibrary to get information on the current cursor position, change colour, etc. R2 = &101 : Data byte --------------------- R3 = byte Exit: R4 = 0 (processed normal byte) or -1 (processed control byte) If R4 is -1 then the byte was part of a control sequence, as I'm sure you realise, the way the capture works is that it stores itself as a post- processing protocol so it gets serialinput last, text emulations normally take all the data, processes it, and leave the raw text in the serialinput buffer, so that all protocols after it only get the text rather than the text and control codes. Hence you can use the returned R4 value so that you know whether or not to take out the control bytes. R2 = &102 : Data block ---------------------- R3 = start of data (flag in bit 31, see R4 on exit) R4 = end of data Exit: R4 = new end of data (same data, just without control characters in it) [only if bit 31 is set in R3 on entry] This repeatedly uses service &101 and only stores bytes that aren't control characters back in the block if bit 31 is set. Send all the above to the text emulation through the current session, eg. use routine_servicecall. ============================================================================= Termite service calls: TermiteIP support - Internet control panel ----------------------------------------------------------------------------- Incoming: Use the relavent startupdat code to listen to a port, you will then be sent the service call &201, after Termite has made sure that you are loaded. You should create a new session with yourself in it, passing the socket pointer in one of the registers. Outgoing: In your new session entry, call service &200 and get the client id, then create a socket, and then use TelnetOp or SendTCPData. Both incoming and outgoing sessions should call TermiteIP_ReadNextEvent with your socket pointer (the TermiteIP_ReadNextEvent SWI can also take a client ID, do not use this, this is handled by the control panel). R2 = &200 : ClientID request (to the control panel) *broadcast* ---------------------------- Exit: R0 = -1 to claim R2 = Termite's TermiteIP client ID Anybody wanting to make an outgoing connection should broadcast this service call to find out our ClientID. If nobody claims this, then you should report the error 'No connection' by using routine_tokentermite with 'noconnect'. Note that the internet control panel calls this when it starts up, to make sure that there is not already a ClientID, if there is, then it will error. see routine_getclientid which sends the broadcast service call for you. R2 = &201 : Incoming socket starting (from the control panel) ------------------------------------ R3 = socket pointer R4 = Internet control panel session number Send to the protocol who asked for listening on the port the socket was created on. Call TermiteIP_SocketInformation if you want to know specifics. R2 = &202 : Internet log request (to the control panel) -------------------------------- R3-> null terminated text string Colours can be added with the $ character, eg $0 = white, $F = light blue. see routine_internetlog which sends the broadcast service call for you (it must be a type b message, so that the internet control panel has workspace intact for writing the message). R2 = &203 : Disconnect requested -------------------------------- Exit with error to stop If you wish to stop the disconnect, exit with an error, eg. the news fetcher produces the error 'News fetch in progress, please use the stop button before attempting to disconnect'. R2 = &204 : Disconnecting, close all sockets -------------------------------------------- Do not return an error! We *are* disconnecting, terminate all connections, NOW! Close all sockets, by calling TermiteIP_DropTCPConnection. Listening ports (but not the sockets on them) are declaimed automatically if registered through the control panel. R2 = &205 : Click on control panel ---------------------------------- R4 = Internet control panel session number Start a session, or do something, or something. R2 = &206 : Options request (send to Internet control panel ONLY) --------------------------- R3-> tagname R4-> buffer Exit: Buffer is updated, or error Make sure the control panel is loaded before you issue this call (use routine_servicecall2). R2 = &207 : Write options (send to Internet control panel ONLY) ------------------------- R3-> tagname R4-> buffer Writes the option, ie. the reverse of 206. ============================================================================= Termite service calls: WWW ----------------------------------------------------------------------------- &300 to &3FF are reserved for the WWW protocol. ============================================================================= Termite service calls: Saveas ----------------------------------------------------------------------------- see routine_saveas for more details. R2 = &400 : Drag finished ------------------------- R3-> filename Sent from Termite to the protocol that last setup the savebox. Remember to call Wimp_OpenMenu with -1 to close the menu if sucessful. You should probably call WimpExt_DataSave to save your file now. R2 = &401 : OK click on ----------------------- R3-> filename Sent from Termite to the protocol that last setup the savebox. Remember to call Wimp_OpenMenu with -1 to close the menu if sucessful. There is no need to check to see if you should display the error 'Please drag icon to a directory display', this is done automatically. You should probably call OS_File to save your file now. ============================================================================= Script service passing ----------------------------------------------------------------------------- A script that is run from a protocol should communicate using &1000-&10FF at at all possible. Internet logging on: (Connect protocol) ==================== R2 = &1000 : Read option ------------------------ R3-> option Exit: R2-> text Connect calls Internet to do this. R2 = &1001 : obsolete --------------------- R2 = &1002 : Write option ------------------------- R3-> option R4-> value Connect calls Internet to do this. R2 = &1003 : Display string --------------------------- R3-> string R2 = &1004 : Success -------------------- Sets the Disconnect button to OK. R2 = &1005 : Open control panel ------------------------------- Simulates a click on OK (or Disconnect). ============================================================================= Protocols with parameters: ----------------------------------------------------------------------------- All the R3 = socket pointer for incoming smtp connection Daemons R3 = -1 will be error'ed. SplitChat R3 = -1 (default, kill session) close R3 = 0 (remove SplitChat only) action R3 = 1 (do not close, report message) R4-> null terminated text message if R3 = 2 (text can be upto 64 characters) Script R3 = filename R3 = -1 will be error'ed. R3 = -2 then... R5+00 = anchor of block containing script file +04 = length of script file R4 = -1 for A%-H%=0 or -> 8 words for A%-H% WWW R3 = url R3 = -1 default ============================================================================= Copyright ----------------------------------------------------------------------------- This document is (c) DoggySoft, 1995