|
www.riscos.com Technical Support: |
This appendix describes version 1.00 of the Acorn Terminal Interface Protocol (or Acorn TIP) used to communicate between a terminal emulator and a protocol module. By using this protocol you can integrate your own terminal emulators and protocol modules with those provided by the TCP/IP Protocol Suite.
Although this chapter only talks about the Acorn TIP in the context of terminal emulators and protocol modules, there's no reason why you shouldn't use it for other applications that involve input and output.
A protocol module converts one of the many different protocols computers use for input and output to the Acorn TIP. For example in the case of the VT220 application and the protocol modules supplied as part of the TCP/IP Protocol Suite, we have:
Structure of the VT220 module and protocol modules
If you decide to write other protocol modules and/or terminal emulators, you should use the Acorn TIP. Since this provides a standard interface between protocol modules and terminal emulators, users will be able to use your modules and emulators with the TCP/IP ones, and with ones that other programmers write too. If your software is compatible, we think it's more likely users will buy it.
If you're writing a protocol module, you must first familiarise yourself with how a RISC OS relocatable module works. You'll find full details of this in the Modules. Your protocol module must conform to the standards laid out in that chapter.
You must support the service calls detailed in this chapter.
You must also support various SWIs from the set detailed in this chapter. These must be at the defined offsets from your module's SWI base number, which is allocated by Acorn. To support many of these SWIs you will need to send suitable commands over the physical connection to the remote host.
You must support:
| Offset | SWI name |
|---|---|
| 0 | Protocol_OpenLogicalLink |
| 1 | Protocol_CloseLogicalLink |
| 2 | Protocol_GetProtocolMenu |
| 3 | Protocol_OpenConnection |
| 4 | Protocol_CloseConnection |
| 7 | Protocol_MenuItemSelected |
| 8 | Protocol_UnknownEvent |
| 9 | Protocol_GetLinkState |
| 10 | Protocol_Break |
If your protocol module supports the sending of data over a connection to a remote machine (or process) you must also support:
| Offset | SWI Name |
|---|---|
| 5 | Protocol_TransmitData |
If you have chosen to support file transfer SWIs you must furthermore support:
| Offset | SWI Name |
|---|---|
| 11 | Protocol_SendFile |
| 12 | Protocol_SendFileData |
| 13 | Protocol_AbortTransfer |
If your protocol module supports the receipt of data over a connection from a remote machine (or process) you must also support:
| Offset | SWI Name |
|---|---|
| 6 | Protocol_DataRequest |
If you have chosen to support file transfer SWIs you must furthermore support:
| Offset | SWI Name |
|---|---|
| 13 | Protocol_AbortTransfer |
| 14 | Protocol_GetFileInfo |
| 15 | Protocol_GetFileData |
| 17 | Protocol_GetFile |
You may also choose to support:
| Offset | SWI Name |
|---|---|
| 18 | Protocol_DirOp |
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:
| Offset | Information |
|---|---|
| 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. For more details see Protocol_OpenLogicalLink (Offset 0).
A poll word for each logical link that shows the status of that link by the state of various bit flags:
| Bit | Meaning when set |
|---|---|
| 0 | data is pending |
| 1 | file is pending |
| 2 | paused operation is to continue |
For more details see Protocol_OpenConnection (Offset 3).
All protocol modules must (if physically possible) support multiple logical links, and multiple connections.
If you're writing a terminal emulator there are various functions that it's likely you'll want it to support. This section tells you which SWIs you'll need to use for many such functions, and outlines how to use them. The later section that details each SWI will give you the detailed information you need.
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 you must issue Service_FindProtocolsEnd.
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 the SWI Protocol_OpenLogicalLink, since its offset from the base number you just found is zero.
You can also use the facilities outlined in the Protocol modules and the Wimp section to provide menus so that your user can set up the way the protocol and connection will work.
To open a connection, call Protocol_OpenConnection. Sometimes the protocol module won't immediately be able to open the connection; you'll need to use Protocol_GetLinkState to find out whether the connection eventually makes or fails.
To close a connection, call Protocol_CloseConnection. To close a logical link, call Protocol_CloseLogicalLink; this also closes any associated connections.
When you open a connection, 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. We suggest you do so each time you get a null event from Wimp_Poll.
To send data, call Protocol_TransmitData.
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.
To send a file, call Protocol_SendFile to give details of the file to the protocol module. When the protocol module shows it is ready for you to send the file (by using the poll word), send the file in one or more data packets by repeatedly calling Protocol_SendFileData. Finally, call Protocol_SendFileData a last time to mark the end of the file transfer.
You can use this call to send multiple files.
Wherever possible you should make sure that the data packets are small enough that they can be quickly sent, so your emulator doesn't hog the computer for long periods.
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 to get details of the file. When the protocol module shows it is ready to forward the file (again by using the poll word), call Protocol_GetFileData until you've received all the data packets making up the file.
To explicitly get a file, call Protocol_GetFile. You'll actually receive it just as we outlined above.
To abort any file operation, call Protocol_AbortTransfer.
There are no SWIs specified in the Acorn TIP to send, receive or get entire directories in one call. Instead we provide a single SWI call - Protocol_DirOp - with which you can create a directory, move into a directory, and move one level up a directory tree. You can combine this SWI with the ones outlined above to move around a remote file system, creating directories, and sending and getting files at will (subject, of course, to your having access rights).
The Acorn TIP provides several calls 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.
To get a protocol's menu tree, call Protocol_GetProtocolMenu; you can then combine it with your emulator's menu tree. If a user clicks on the protocol module's part of the menu tree, call Protocol_MenuItemSelected to pass this on. 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.
Finally, you can generate a Break over the connection by calling Protocol_Break.
The rest of this chapter details in turn each Service Call and SWI used to communicate between a protocol module and a terminal emulator. It looks at each in three stages:
We've followed the same viewpoint throughout as we have above: we assume that you're writing a terminal emulator to work with someone else's protocol module. So we talk about your terminal emulator, but the protocol module. If, in fact, you're writing a protocol module, you should find it easy enough to make the necessary shift of viewpoint.
R1 = &41580 (reason code)
R2 = lowest TIP version supported × 100 (first public version was 1.00)
R3 = last TIP version known × 100 (current version is 1.00)
R4 = emulator flags
R1 = 0 to claim, else registers preserved to pass on
R2 = pointer to protocol name string (null terminated)
R3 = base SWI number of protocol module
R4 = pointer to protocol information block
R5 = protocol flags
Use this service call in your terminal emulator to find all available compatible protocol modules. (For full details of OS_ServiceCall see OS_ServiceCall.) You should:
The emulator flags have the following meanings:
| Bits | Value | Meaning |
|---|---|---|
| 0 | 0 | emulator doesn't support file transfer calls |
| 1 | emulator supports file transfer calls | |
| 1 - 2 | 00 | direction of link immaterial |
| 01 | one-way link wanted - protocol to emulator | |
| 10 | one-way link wanted - emulator to protocol | |
| 11 | two-way link needed | |
| 3 | 0 | bits 1-2 are minimum requirement |
| 1 | bits 1-2 are exact requirement |
All other bits are reserved and must be zero.
The protocol module checks to see if:
If one of the above isn't true, the protocol module must not claim the call - that is, it must return with registers preserved.
If both the above are true it must claim the call - that is, it must return with the values shown above in the On exit. It must then set an internal flag so it doesn't claim this call again until it receives a Service_FindProtocolsEnd.
The protocol information block it returns contains the following information:
| Offset | Information |
|---|---|
| 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. The protocol module must always keep this block updated so terminal emulators can directly access it.
The protocol flags it returns have the following meanings:
If the protocol is mainly for file transfer (such as Ftp) and the terminal emulator doesn't support file transfer calls (bit 0 of R3 was clear on entry) the protocol module should set bit 0 to show it's 'not useful'.
All other bits are reserved and must be zero.
Service_FindProtocolsEnd,
Service_ProtocolNameToNumber
Indicates that protocol modules must again respond to Service_FindProtocols
R1 = &41581 (reason code)
R1 = 0 to claim, else preserved to pass on
Use this service call in your terminal emulator to indicate the end of your search for available protocols.
Protocol modules must change their internal flag so they respond again to Service_FindProtocols calls - from whatever terminal emulator the calls originate. They must not claim this call.
Service_FindProtocols,
Service_ProtocolNameToNumber
Requests the conversion of a protocol name to a base SWI number
R1 = &41582
R2 = pointer to protocol name (null-terminated)
R1 = 0 to claim, else registers preserved to pass on
R2 = base SWI number for protocol
Use this service call in your terminal emulator to request the conversion of a protocol name to a base SWI number.
If a protocol module recognises the protocol name it must claim the call and return the base SWI number of the protocol. Otherwise it must pass the call on.
R0 = terminal emulator's link handle
R1 = pointer to terminal identifier string (null terminated)
R0 = protocol module's link handle
R1 = protocol module's Wimp_Poll mask
R2 = pointer to protocol information block
R3 = protocol information flags
Use this call in your terminal emulator to open a logical link to a protocol module. The handle you pass on entry will be returned to you by future SWI calls you make to the protocol module - we suggest you use a pointer to your data structures that are specific to this link.
You may use the terminal identifier string for such things as setting the 'type' of your terminal emulator on the remote machine.
The protocol module returns its own handle for the link - again this is typically a pointer to its own data that is specific to the link. The Wimp_Poll mask it returns specifies those Wimp events that it doesn't need.
The protocol information block contains the following information:
| Offset | Information |
|---|---|
| 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. The protocol module must always keep this block updated so terminal emulators can directly access it.
The protocol information flags have the following meanings:
| Bit | Meaning when set |
|---|---|
| 0 | protocol needs more information to open a connection |
| 1 | protocol supports file transfer SWIs |
| 2 | protocol supports Protocol_DirOp |
All other bits are reserved and must be zero.
When this call returns to your terminal emulator you should examine bit 0 of the protocol information flags. If it is clear then you should immediately call Protocol_OpenConnection; if it is set you will have to wait until the user shows they are ready to supply the information the protocol module needs (by, for instance, moving the pointer over the arrow that shows an 'open connection' menu item to have a submenu).
Also, you should AND the protocol module's Wimp_Poll mask with your terminal emulator's own one. Use the resultant mask whenever you call Wimp_Poll.
Protocol_CloseLogicalLink, Protocol_OpenConnection, Protocol_CloseConnection, Protocol_GetLinkState
R0 = protocol module's link handle
R0 preserved
Use this call in your terminal emulator to close a logical link to a protocol module.
The protocol module closes any connections that are associated with the logical link.
Protocol_OpenLogicalLink, Protocol_OpenConnection, Protocol_CloseConnection, Protocol_GetLinkState
Gets a protocol's menu tree
R0 = protocol module's link handle
R0 = terminal emulator's link handle
R1 = pointer to protocol and link specific Wimp menu block (as used by Wimp_CreateMenu)
Use this call in your terminal emulator to get a protocol's menu tree. You must use this call each time you want to open the protocol's menu, as it may change depending on the state of the logical link. For example items may become unavailable and so be greyed out, or the user may change the contents of a writable entry.
The protocol module returns a pointer to a menu block that is the same as that used by Wimp_CreateMenu. (See Wimp_CreateMenu for details of this call.) This menu block must accurately reflect the current state of the logical link between the terminal emulator and the protocol module.
Protocol_MenuItemSelected, Protocol_UnknownEvent
R0 = protocol module's link handle
R1 = pointer to poll word for this connection
R3 = pointer to protocol specific string (null-terminated), or 0
R4 = x coordinate of top-left corner of dialogue box
R5 = y coordinate of top-left corner of dialogue box
R0 = terminal emulator's link handle
R1 = pointer to connection name (null-terminated)
R2 = pointer to protocol specific information, or 0
R3 = protocol status flags
Use this call in your terminal emulator to open a connection from a protocol module. At the same time you pass the protocol module the address of a poll word in your workspace, which your terminal emulator must regularly check to review the state of the logical link to the protocol module. We suggest you do so each time you get a null event from Wimp_Poll.
When a bit is set in the poll word, something needs attention. The table below shows the meaning of each bit, and the initial SWI call you have to make to handle the situation. See the relevant pages for details of what to do, and of any further calls you may need to make.
| Bit | Meaning when set | Call needed |
|---|---|---|
| 0 | data is pending | Protocol_DataRequest |
| 1 | file is pending | Protocol_GetFileInfo |
| 2 | paused operation is to continue | Protocol_GetFileData or Protocol_SendFileData or Protocol_DirOp |
The poll word must be in RMA space, so the protocol module can update it whether or not your terminal emulator is the foreground task.
The values you need to pass in R3, R4 and R5 depend on circumstances:
The protocol module opens the connection after first (if necessary) using a dialogue box to get any information it needs.
The documentation of a protocol module must state the format of information it expects to find in R3 (if it needs any). Wherever possible, this format should consist of the same fields that the protocol module provides in its dialogue box, in the same order, and comma-separated.
The protocol module returns a connection name suitable for the terminal emulator to use as a window title (if the connection is open or pending). The protocol specific information it returns may be used for error messages. The protocol status flags it returns have the following meanings:
| Bits | Value | Meaning |
|---|---|---|
| 0 - 1 | 00 | no connection opened |
| 01 | connection pending | |
| 10 | connection open | |
| 11 | connection failed | |
| 2 | 0 | no data pending |
| 1 | data pending |
All other bits are reserved and must be zero. The protocol module should select 'connection failed' in preference to 'no connection opened'.
When this call returns to your terminal emulator you must examine the state of these flags:
Protocol_OpenLogicalLink, Protocol_CloseLogicalLink, Protocol_CloseConnection, Protocol_GetLinkState
R0 = protocol module's link handle
R0 = pointer to protocol specific information, or 0
Use this call in your terminal emulator to close a link's connection from a protocol module.
The protocol module closes the connection associated with the given link.
Protocol_OpenLogicalLink, Protocol_CloseLogicalLink, Protocol_OpenConnection, Protocol_GetLinkState
R0 = protocol module's link handle
R1 = pointer to receive buffer
R2 = length of receive buffer (in bytes)
R3 = pointer to transmit buffer
R4 = length of transmit buffer (in bytes)
R5 = emulator transmit flags
R0 = terminal emulator's link handle
R2 = number of bytes of data placed in receive buffer
R3 = protocol status flags
R4 = pointer to protocol specific information
Use this call in your terminal emulator to transmit data over a connection via a protocol module. You'll also receive any pending data that the protocol module has been holding for you.
The emulator transmit flags have the following meanings:
| Bit | Value | Meaning |
|---|---|---|
| 3 | 0 | transmitted data is in bytes |
| 1 | transmitted data is in words |
All other bits are reserved and must be zero. If the transmitted data is in words, each word contains one character in the least significant byte.
The protocol module transmits the data over the connection. Also, if it has any pending data for the terminal emulator it forwards as much as it is able to place in the emulator's receive buffer.
The protocol specific information it returns may be used for error messages.
The protocol status flags it returns have the following meanings:
| Bits | Value | Meaning |
|---|---|---|
| 0 - 1 | 00 | no connection opened |
| 01 | connection pending | |
| 10 | connection open | |
| 11 | connection failed | |
| 2 | 0 | no data pending |
| 1 | more data pending | |
| 3 | 0 | data is in bytes |
| 1 | data is in words |
All other bits are reserved and must be zero.
When this call returns to your terminal emulator you must check R2 to see if you have received any data, and process it if necessary. You must also examine the protocol status flags in R3:
Protocol_SendFile, Protocol_SendFileData
R0 = protocol module's link handle
R1 = pointer to receive buffer
R2 = length of receive buffer (in bytes)
R0 = terminal emulator's link handle
R1 preserved
R2 = number of bytes of data placed in receive buffer
R3 = protocol status flags
R4 = pointer to protocol specific information
Use this call in your terminal emulator to request that a protocol module forwards any pending data. You should do so in either of these cases:
The protocol module forwards as much of the pending data as it is able to place in the emulator's receive buffer.
The protocol specific information it returns may be used for error messages. The protocol status flags it returns have the following meanings:
| Bits | Value | Meaning |
|---|---|---|
| 0 - 1 | 00 | no connection opened |
| 01 | connection pending | |
| 10 | connection open | |
| 11 | connection failed | |
| 2 | 0 | no data pending |
| 1 | more data pending | |
| 3 | 0 | data is in bytes |
| 1 | data is in words |
All other bits are reserved and must be zero.
When this call returns to your terminal emulator you must examine the state of these flags:
Protocol_GetFileInfo, Protocol_GetFileData, Protocol_GetFile
R0 = protocol module's link handle
R1 = pointer to menu selection block
R2 = x coordinate of mouse
R3 = y coordinate of mouse
R4 = emulator menu flags
R0 - R4 preserved
Use this call in your terminal emulator to request that a protocol module services a selection made within its own menu. You should call this if you:
(See the descriptions of Wimp_Poll on Wimp_Poll and Wimp_SendMessage on Wimp_SendMessage for more details.)
The menu selection block contains:
| R1 | item in protocol menu that was selected (starting with 1) |
| R1 + 1 | item in first protocol submenu that was selected |
| R1 + 2 | item in second protocol submenu that was selected |
| ... | |
| terminated by 0 byte |
Note: There are several important differences between this menu selection block and that returned by Wimp_Poll with a Menu_Selection reason code:
| Wimp menu selection block | Protocol menu selection block |
|---|---|
| Menu items start from 0 | Menu items start from 1 |
| Each number is a word | Each number is a byte |
| List is terminated by -1 | List is terminated by 0 |
| R1 gives item in main menu | R1 gives item at root of protocol menu |
The emulator menu flags show why you have made this call:
| Bit | Value | Meaning |
|---|---|---|
| 0 | 0 | called because of a mouse click |
| 1 | called because of a MenuWarning message |
All other bits are reserved and must be zero.
The protocol module services the menu selection, either doing what the user clicked over, or displaying the necessary submenu.
Protocol_GetProtocolMenu, Protocol_UnknownEvent
Passes on Wimp events to a protocol module
R0 = pointer to Wimp event block (as returned by Wimp_Poll)
R0 preserved
Use this call in your terminal emulator to pass on Wimp events you can't deal with to the protocol module you're using. You should also pass on idle events if the protocol module's Wimp_Poll mask (see Protocol_OpenLogicalLink) doesn't mask them out - even if your terminal emulator uses them.
The protocol module processes the Wimp event if it is one in which it is interested.
Protocol_GetProtocolMenu, Protocol_MenuItemSelected
R0 = protocol module's link handle
R0 = terminal emulator's link handle
R1 = pointer to connection name (null-terminated)
R2 = pointer to protocol specific information, or 0
R3 = protocol status flags
Use this call in your terminal emulator to get the state of a logical link.
One time you should do so is if an attempt you've made to open a connection has resulted in a pending connection. You should then wait for bit 0 of the logical link's poll word ('data pending') to be set before making this call to find if the connection was opened, or if it failed.
The protocol module returns a connection name suitable for the terminal emulator to use as a window title (if the connection is open or pending). The protocol specific information it returns may be used for error messages. The protocol status flags it returns have the following meanings:
| Bits | Value | Meaning |
|---|---|---|
| 0 - 1 | 00 | no connection opened |
| 01 | connection pending | |
| 10 | connection open | |
| 11 | connection failed | |
| 2 | 0 | no data pending |
| 1 | data pending |
All other bits are reserved and must be zero.
When this call returns to your terminal emulator you must examine the state of these flags:
Protocol_OpenLogicalLink, Protocol_CloseLogicalLink, Protocol_OpenConnection, Protocol_CloseConnection
R0 = protocol module's link handle
R0 = terminal emulator's link handle
R3 = protocol status flags
Use this call in your terminal emulator to force a protocol module to generate a Break.
The protocol module generates a Break. The precise interpretation of this varies from module to module.
The documentation of a protocol module must state how it interprets this call.
The protocol status flags it returns have the following meanings:
| Bits | Value | Meaning |
|---|---|---|
| 0 - 1 | 00 | no connection opened |
| 01 | connection pending | |
| 10 | connection open | |
| 11 | connection failed | |
| 2 | 0 | no data pending |
| 1 | data pending |
All other bits are reserved and must be zero.
When this call returns to your terminal emulator you must examine the state of these flags:
Initiates sending a file over a protocol module's connection
R0 = protocol module's link handle
R1 = RISC OS file type
R2 = pointer to file name (null terminated)
R3 = estimated size of file (in bytes)
R4 = emulator send flags
R0 = terminal emulator's link handle
R1 = protocol status flags
Use this call in your terminal emulator to initiate sending a file over a protocol module's connection.
The emulator send flags have the following meanings:
| Bit | Meaning when set |
|---|---|
| 0 | transfer cannot be safely paused (ie is a RAM transfer) |
| 1 | transfer is part of a multiple file transfer |
All other bits are reserved and must be zero.
The protocol module must ready itself to accept the file over the terminal emulator's logical link, and to send it over the connection that is associated with the link. When it is ready it must show this by setting bit 2 of the link's poll word.
If bit 1 of the emulator send flags is set (a multiple file transfer) and the protocol module uses dialogue box(es) to show the state of the transfer, it must use the same box(es) for each file in turn, rather than using a new one for each file.
The protocol status flags it returns have the following meanings:
| Bits | Value | Meaning |
|---|---|---|
| 0 - 1 | 00 | no connection opened |
| 01 | connection pending | |
| 10 | connection open | |
| 11 | connection failed |
All other bits are reserved and must be zero.
When this call returns to your terminal emulator you must examine the state of these flags:
When you start a file transfer with this call the link is in a paused state. You should wait for bit 2 of the link's poll word to be set before you try to resume the transfer by calling Protocol_SendFileData (see the next page).
Protocol_TransmitData, Protocol_SendFileData, Protocol_AbortTransfer, Protocol_DirOp
Sends the data in a file over a protocol module's connection
R0 = protocol module's link handle
R1 = pointer to transmit buffer
R2 = length of transmit buffer (in bytes)
R3 = emulator send data flags
R0 = terminal emulator's link handle
R1 = protocol status flags
Use this call in your terminal emulator to send the data in a file over a protocol module's connection. You can (if necessary) split the file into separate data packets and repeatedly use this call to transmit each packet.
The emulator send data flags have the following meanings:
| Bit | Meaning when set |
|---|---|
| 0 | last data packet of a file (ie EOF) |
| 1 | no data is included - end of file transfer |
All other bits are reserved and must be zero.
You must not set both these bits at once, so a file transfer must end with two calls of this SWI: the first with bit 0 set (EOF), the second with bit 1 set (end of file transfer).
The protocol module sends the file over the connection that is associated with the link. If it has to pause the transfer it must show when it is ready to resume by setting bit 2 of the link's poll word.
The protocol status flags it returns have the following meanings:
| Bits | Value | Meaning |
|---|---|---|
| 0 - 1 | 00 | no connection opened |
| 01 | connection pending | |
| 10 | connection open | |
| 11 | connection failed | |
| 2 - 3 | 00 | transfer not started |
| 01 | transfer paused | |
| 10 | transfer completed | |
| 11 | transfer failed or aborted |
All other bits are reserved and must be zero.
When this call returns to your terminal emulator you must examine the state of these flags:
Protocol_TransmitData, Protocol_SendFile, Protocol_AbortTransfer, Protocol_DirOp
R0 = protocol module's link handle
R0 preserved
Use this call in your terminal emulator to abort a file transfer.
The protocol module aborts the transfer and makes sure that the connection associated with the link is ready for other use.
Protocol_SendFile, Protocol_SendFileData, Protocol_GetFileInfo, Protocol_GetFileData, Protocol_GetFile
Requests that a protocol module initiates forwarding a pending file
R0 = protocol module's link handle
R0 = terminal emulator's link handle
R1 = RISC OS file type
R2 = pointer to file name (null terminated)
R3 = 0, or estimated size of file if available (in bytes)
Use this call in your terminal emulator to request that a protocol module initiates forwarding a pending file. You should do so:
if bit 1 ('file pending') of the link's poll word is set.
This will usually be as a result of your calling Protocol_GetFile to request that the file be sent.
The protocol module returns details of the file to the terminal emulator.
When this call returns to your terminal emulator you must use these details to get ready to receive the file, before calling Protocol_GetFileData to actually get the data.
Protocol_DataRequest, Protocol_AbortTransfer, Protocol_GetFileData, Protocol_GetFile, Protocol_DirOp
R0 = protocol module's link handle
R1 = pointer to receive buffer
R2 = length of receive buffer (in bytes)
R0 = terminal emulator's link handle
R1 preserved
R2 = number of bytes of data placed in receive buffer
R3 = protocol status flags
Use this call in your terminal emulator to request that a protocol module forwards the data in a file.
The protocol module must forward the file data to the terminal emulator. It can (if necessary) split the file into separate data packets, pausing the transfer after each packet. If so, it must show when it is ready to forward the next packet by setting bit 2 of the link's poll word.
The protocol status flags it returns have the following meanings:
| Bits | Value | Meaning |
|---|---|---|
| 0 - 1 | 00 | no connection opened |
| 01 | connection pending | |
| 10 | connection open | |
| 11 | connection failed | |
| 2 - 3 | 00 | transfer not started |
| 01 | transfer paused | |
| 10 | transfer completed | |
| 11 | transfer failed or aborted |
All other bits are reserved and must be zero.
When this call returns to your terminal emulator you must examine the state of these flags:
Protocol_DataRequest, Protocol_AbortTransfer, Protocol_GetFileInfo, Protocol_GetFile, Protocol_DirOp
Requests that a protocol module sends its interactive help message for a menu entry
R0 = protocol module's link handle
R1 = pointer to menu selection array, relative to protocol-specific menu tree
R0, R1 preserved
Use this call in your terminal emulator to request that a protocol module sends its interactive help message for the menu entry. The menu selection array you send must be terminated by a null.
The protocol module must send the appropriate help message.
Protocol_GetProtocolMenu, Protocol_MenuItemSelected
Requests that a protocol module gets a file over a connection
R0 = protocol module's link handle
R1 = pointer to file name (null terminated)
R0, R1 preserved
Use this call in your terminal emulator to request that a protocol module gets a file over a connection.
The protocol module gets the necessary information to respond to a Protocol_GetFileInfo call, and the first packet of the file to respond to a Protocol_GetFileData call, before showing that it is ready by setting bit 1 ('file pending') of the link's poll word.
Protocol_DataRequest, Protocol_AbortTransfer, Protocol_GetFileInfo, Protocol_GetFileData, Protocol_DirOp
R0 = protocol module's link handle
R1 = reason code
R2 = pointer to directory name - reason codes 1 & 2 only (null terminated)
R0 = terminal emulator's link handle
R1, R2 preserved
R3 = protocol status flags
Use this call in your terminal emulator to perform various directory operations over a connection. The type of operation is set by a reason code in R1:
| Reason code | Type of operation |
|---|---|
| 0 | null - see below |
| 1 | create directory |
| 2 | move into directory |
| 3 | move up one level in directory tree |
The protocol module performs the specified operation. The protocol status flags it returns have the following meanings:
| Bits | Value | Meaning |
|---|---|---|
| 0 - 1 | 00 | no connection opened |
| 01 | connection pending | |
| 10 | connection open | |
| 11 | connection failed | |
| 2 - 3 | 00 | invalid context |
| 01 | operation in progress - paused | |
| 10 | operation completed | |
| 11 | operation failed or aborted |
All other bits are reserved and must be zero.
When this call returns to your terminal emulator you must examine the state of these flags:
Protocol_SendFile, Protocol_SendFileData, Protocol_AbortTransfer, Protocol_GetFileInfo, Protocol_GetFileData, Protocol_GetFile