The Acorn Terminal Interface Protocol (changes)

Showing changes from revision #4 to #5: Added | Removed | Changed

Programmer's Reference Manuals

» The Acorn Terminal Interface Protocol

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.

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.

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 relocatable module works. Your protocol module must conform to the standards specified.

Service Calls

Your Protocol Module must support all service calls detailed.

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 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.

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:

Protocol Information Block

The three strings are all null-terminated, and have a maximum length of 30 characters. More information is available on Protocol_OpenLogicalLink? (Offset 0).

Poll Word

For more infomation, please see Protocol_OpenConnection?.

Multiple Links and Connections

All protocol modules must (if physically possible) support multiple logical links, and multiple connections.

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.

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

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 to provide menus so that your user can set up the way the protocol and connection will work.

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)

Closing a Connection and a Link

• Call Protocol_CloseConnection?, or
• To close a logical link, call Protocol_CloseLogicalLink? – this also closes any associated connections

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.

Sending Data

Sending data is achieved by Calling Protocol_TransmitData?

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?.

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

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?

Aborting File Operations

• To abort any file operation, call Protocol_AbortTransfer?

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).

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.

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.

Generating a Break

• Generate a break over the connection by calling Protocol_Break?