h6. [[Programmer's Reference Manuals]] h6(. » The Acorn Terminal Interface Protocol h2(#system). Introduction The Acorn Terminal Interface Protocol (Acorn TIP) is used to communicate between a terminal emulator and a protocol module. It is possible to integrate your own terminal emulators and protocol modules with those provided by the TCP/IP Protocol Suite. h2(#protocol). Protocol Modules The purpose of a __Protocol Module__ is to convert one of the many different protocols computers use for input and output to the Acorn TIP. * Data passing between a terminal emulator and a protocol module uses the Acorn TIP, and passes over a __logical link__ * Data passing between a protocol module and a remote machine or process uses whatever protocol the module is designed to support, and passes over a __connection__. h2(#devmod). How to develop a Protocol Module It is strongly advised that before developing a Protocol Module, you should first familiarise yourself with how a RISC OS [[File formats: Relocatable Module|relocatable module]] works. Your protocol module must conform to the standards specified. h3(#service). Service Calls Your Protocol Module must support all service calls detailed. h3(#swi). SWI Calls Your Protocol Module must support various SWIs, and they vary based on the functionality it will provide. These must be at the defined offsets from your module’s SWI base number, which is "allocated":/content/allocate by RISC OS Open. To support many of these SWIs you will need to send suitable commands over the physical connection to the remote host. table(bordered). |_<^{width:4em}. Offset |_<^{width:16em}. SWI name |_<^. Supports sending of data |_<^. Supports sending of data & file transfer |_<^. Supports receipt of data |_<^. Supports receipt of data & file transfer |_<^. Optional | |<^. 0 |<^. [[Protocol_OpenLogicalLink]] |<^. ✔ |<^. ✔ |<^. ✔ |<^. ✔ |<^. - | |<^. 1 |<^. [[Protocol_CloseLogicalLink]] |<^. ✔ |<^. ✔ |<^. ✔ |<^. ✔ |<^. - | |<^. 2 |<^. [[Protocol_GetProtocolMenu]] |<^. ✔ |<^. ✔ |<^. ✔ |<^. ✔ |<^. - | |<^. 3 |<^. [[Protocol_OpenConnection]] |<^. ✔ |<^. ✔ |<^. ✔ |<^. ✔ |<^. - | |<^. 4 |<^. [[Protocol_CloseConnection]] |<^. ✔ |<^. ✔ |<^. ✔ |<^. ✔ |<^. - | |<^. 5 |<^. [[Protocol_TransmitData]] |<^. ✔ |<^. ✔ |<^. - |<^. - |<^. - | |<^. 6 |<^. [[Protocol_DataRequest]] |<^. - |<^. - |<^. ✔ |<^. ✔ |<^. - | |<^. 7 |<^. [[Protocol_MenuItemSelected]] |<^. ✔ |<^. ✔ |<^. ✔ |<^. ✔ |<^. - | |<^. 8 |<^. [[Protocol_UnknownEvent]] |<^. ✔ |<^. ✔ |<^. ✔ |<^. ✔ |<^. - | |<^. 9 |<^. [[Protocol_GetLinkState]] |<^. ✔ |<^. ✔ |<^. ✔ |<^. ✔ |<^. - | |<^. 10 |<^. [[Protocol_Break]] |<^. ✔ |<^. ✔ |<^. ✔ |<^. ✔ |<^. - | |<^. 11 |<^. [[Protocol_SendFile]] |<^. - |<^. ✔ |<^. - |<^. - |<^. - | |<^. 12 |<^. [[Protocol_SendFileData]] |<^. - |<^. ✔ |<^. - |<^. - |<^. - | |<^. 13 |<^. [[Protocol_AbortTransfer]] |<^. - |<^. ✔ |<^. - |<^. ✔ |<^. - | |<^. 14 |<^. [[Protocol_GetFileInfo]] |<^. - |<^. - |<^. - |<^. ✔ |<^. - | |<^. 15 |<^. [[Protocol_GetFileData]] |<^. - |<^. - |<^. - |<^. ✔ |<^. - | |<^. 17 |<^. [[Protocol_GetFile]] |<^. - |<^. - |<^. - |<^. ✔ |<^. - | |<^. 18 |<^. [[Protocol_DirOp]] |<^. - |<^. - |<^. - |<^. |<^. ✔ | h2(#data). Data Structures Your protocol module must keep two different types of data structure constantly updated, as terminal emulators may directly access these any time they need to. These are: * A single __protocol information block__ which contains the following information: * A __poll word__ for each logical link that shows the status of that link by the state of various bit flags: h3(#infoblock). Protocol Information Block |_<^{width:4em}. Offset |_<^. Contents | |<^. 0 |<^. Pointer to protocol name string | |<^. 4 |<^. Pointer to protocol version string | |<^. 8 |<^. Pointer to protocol copyright string | |<^. 12 |<^. Maximum number of connections allowed by module | |<^. 16 |<^. Current number of open connections | The three strings are all null-terminated, and have a maximum length of 30 characters. More information is available on [[Protocol_OpenLogicalLink]] (Offset 0). h3(#pollword). Poll Word |_<^{width:4em}. Bit |_<^. Meaning when set | |<^. 0 |<^. Data is pending | |<^. 1 |<^. File is pending | |<^. 2 |<^. Paused operation is to continue | For more infomation, please see [[Protocol_OpenConnection]]. h3(#multiple). Multiple Links and Connections All protocol modules must (if physically possible) support multiple logical links, and multiple connections. h2(#devterm). Developing a Terminal Emulator There are various functions that your Terminal Emulator will need to support. This section details which SWI calls you need to use for many such functions, and outlines how to use them. h3(#find). Finding available and compatible Protocols To find what protocols are available and compatible with the needs of your emulator, you must: * Repeatedly issue [[Service_FindProtocols]] until it is not claimed * Then issue [[Service_FindProtocolsEnd]] h3(#choose). Choosing a protocol and opening a link For your user to choose a protocol, you’ll probably want to give them a menu of the ones you found to be available. Once they’ve made the choice, you can then issue [[Service_ProtocolNameToNumber]] to find the base SWI number of their chosen protocol module. You can then use this base number to call [[Protocol_OpenLogicalLink]], since its offset from the base number you just found is zero. You can also use the facilities outlined in the section below entitled "Protocol Modules and the Wimp":#modules to provide menus so that your user can set up the way the protocol and connection will work. h3(#conopen). Opening a Connections * Call [[Protocol_OpenConnection]] * Call [[Protocol_GetLinkState]] to determine if the connection eventually is succefful or not. (Sometime the protocol module won't immediately be able to open the connection) h3(#conclose). Closing a Connection and a Link * Call [[Protocol_CloseConnection]], or * To close a logical link, call [[Protocol_CloseLogicalLink]] - this also closes any associated connections h3(#examine). Examining the Poll Word When a connection is established/opened, you set the address of a poll word. The protocol module sets bits in this word when it needs attention. It’s vital that your emulator regularly examines this word so that the protocol module gets adequate service. *Note:* It is good practice to check the poll word each time a null event from [[Wimp_Poll]] is received. h3(#datasend). Sending Data Sending data is achieved by Calling [[Protocol_TransmitData]] h3(#datareceive). Receiving Data When the protocol module receives data over a connection, it will notify your emulator by setting a bit in the poll word. To get the data forwarded to your emulator, call [[Protocol_DataRequest]]. h3(#filesend). Sending Files * Call [[Protocol_SendFile]] to give details of the file to the protocol module * Scan the poll word bits to identify when the protocol module is ready to receive the file data * Send the file in one more more data packets by by repeatedly calling [[Protocol_SendFileData]] * Call [[Protocol_GetFileData]] to mark the end of the file transfer h3(#filereceive). Receiving Files When the protocol module receives a file over a connection, it will notify your emulator by setting a bit in the poll word. * To get the file forwarded to your emulator, call [[Protocol_GetFileInfo]] * Scan the poll word to identify when the protocol module shows it is ready to forward the file * Call [[Protocol_GetFileData]] until all the data packets making up the file have been received *Note:* To explicitly get a file, call [[Protocol_GetFile]] h3(#fileabort). Aborting File Operations * To abort any file operation, call [[Protocol_AbortTransfer]] h3(#dirop). Directory Operations There are no SWIs specified in the Acorn TIP to send, receive or get entire directories in one call. Instead, a single SWI call, [[Protocol_DirOp]] is provided. This call allows you to create a directory, move into a directory, and move one level up a directory tree. Combining this SWI with the ones outlined above allows you to move around a remote file system, creating directories, and sending and getting files at will (subject, to access rights). h3(#modules). Protocol Modules and the Wimp Several calls are provided which help interaction between the Wimp and protocol menus. These are necessary because the ‘pick and mix’ nature of protocol modules and terminal emulators means you’ll have to combine menus from each; and because protocol modules are not foreground tasks, and so don’t receive notice of menu selections and Wimp events. h3(#menu). Retrieving a Protocol's Menu Tree * Call [[Protocol_GetProtocolMenu]] and you combine it with your emulator's menu tree * If a user clicks on the protocol module’s part of the menu tree, pass it on using [[Protocol_MenuItemSelected]] * To pass on a Wimp event to a protocol module, call [[Protocol_UnknownEvent]]. You should do this for every event your emulator can’t deal with, as the protocol module may be able to. h3(#break). Generating a Break * Generate a break over the connection by calling [[Protocol_Break]]