RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

Appendix G: The Acorn Terminal Interface Protocol


Introduction

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.

Protocol modules

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

  • Data passing between a terminal emulator and a protocol module uses the Acorn TIP, and passes over a logical link. These are grey in the drawing above.
  • 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. These are black in the drawing above.
Using the Acorn TIP

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.

Writing a protocol module

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.

Service calls

You must support the service calls detailed in this chapter.

SWIs

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

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

Multiple links and connections

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

Writing a terminal emulator

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.

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

Opening a connection

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.

Closing a connection and a link

To close a connection, call Protocol_CloseConnection. To close a logical link, call Protocol_CloseLogicalLink; this also closes any associated connections.

Examining the poll word

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.

Sending data

To send data, call 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

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.

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

Explicitly getting a file

To explicitly get a file, call Protocol_GetFile. You'll actually receive it just as we outlined above.

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

Protocol modules and the Wimp

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.

Generating a break

Finally, you can generate a Break over the connection by calling Protocol_Break.

Documentation of Service Calls and SWIs

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:

  1. What your terminal emulator should do before calling the Service Call or SWI.
  2. What a protocol module should do when it receives the Service Call or SWI.
  3. What your terminal emulator should do when the call returns to it.

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.

Service Calls


Service_FindProtocols
(Service Call &41580)

Finds all available compatible protocols

On entry

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

On exit

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

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:

  1. Repeatedly issue this service call until it is not claimed - without polling the Wimp in the meantime.
  2. Issue Service_FindProtocolsEnd (see Service_FindProtocolsEnd (Service Call &41581)).

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:

  • it uses a version of the Acorn TIP in the range supported by the terminal emulator
  • it supports links in the direction required by the terminal emulator.

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:

Bits Value Meaning
0 0 can open new link
1 can't open new link, or not useful (see below)
1 0 protocol doesn't support file transfer SWIs
1 protocol supports file transfer SWIs
2 0 protocol doesn't support Protocol_DirOp
1 protocol supports Protocol_DirOp

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.

Related Service Calls

Service_FindProtocolsEnd,
Service_ProtocolNameToNumber


Service_FindProtocolsEnd
(Service Call &41581)

Indicates that protocol modules must again respond to Service_FindProtocols

On entry

R1 = &41581 (reason code)

On exit

R1 = 0 to claim, else preserved to pass on

Use

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.

Related Service Calls

Service_FindProtocols,
Service_ProtocolNameToNumber


Service_ProtocolNameToNumber
(Service Call &41582)

Requests the conversion of a protocol name to a base SWI number

On entry

R1 = &41582
R2 = pointer to protocol name (null-terminated)

On exit

R1 = 0 to claim, else registers preserved to pass on
R2 = base SWI number for protocol

Use

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.

Related Service Calls

Service_FindProtocols,
Service_FindProtocolsEnd

SWI calls


Protocol_OpenLogicalLink
(Offset 0)

Opens a logical link to a protocol module

On entry

R0 = terminal emulator's link handle
R1 = pointer to terminal identifier string (null terminated)

On exit

R0 = protocol module's link handle
R1 = protocol module's Wimp_Poll mask
R2 = pointer to protocol information block
R3 = protocol information flags

Use

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.

Related SWIs

Protocol_CloseLogicalLink, Protocol_OpenConnection, Protocol_CloseConnection, Protocol_GetLinkState


Protocol_CloseLogicalLink
(Offset 1)

Closes a logical link to a protocol module

On entry

R0 = protocol module's link handle

On exit

R0 preserved

Use

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.

Related SWIs

Protocol_OpenLogicalLink, Protocol_OpenConnection, Protocol_CloseConnection, Protocol_GetLinkState


Protocol_GetProtocolMenu
(Offset 2)

Gets a protocol's menu tree

On entry

R0 = protocol module's link handle

On exit

R0 = terminal emulator's link handle
R1 = pointer to protocol and link specific Wimp menu block (as used by Wimp_CreateMenu)

Use

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.

Related SWIs

Protocol_MenuItemSelected, Protocol_UnknownEvent


Protocol_OpenConnection
(Offset 3)

Opens a connection from a protocol module

On entry

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

On exit

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

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:

  • If the protocol module needs no further information to open the connection these values are ignored.
  • If the user has shown they are ready to supply the information the protocol module needs (typically by moving the pointer over the arrow that shows an 'open connection' menu item to have a submenu), you must set R3 to zero, and R4 and R5 to the coordinates where you want the protocol module to open a dialogue box. You can get these coordinates by making your terminal emulator's menu issue Message_MenuWarning when the submenu is to be activated (see Wimp_CreateMenu on Wimp_CreateMenu and Wimp_SendMessage on Wimp_SendMessage).
  • If the user has already supplied you with the information that the protocol module needs (say in a script) you should pass that in R3. The values of R4 and R5 are ignored.

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:

  • If the connection failed (bits 0 and 1 are set) and no data is pending (bit 2 is clear) you must attempt to close the connection by calling Protocol_CloseConnection.
  • If the connection is pending you must wait until bit 0 of the logical link's poll word is set. Then you should call Protocol_GetLinkState to find if the connection was opened, or if it failed.
  • Bit 2 ('data pending') has exactly the same meaning as bit 0 of a logical link's poll word, and is provided to reduce the amount of polling that needs to be done. If it is set you should initiate the data transfer by calling Protocol_DataRequest.
Related SWIs

Protocol_OpenLogicalLink, Protocol_CloseLogicalLink, Protocol_CloseConnection, Protocol_GetLinkState


Protocol_CloseConnection
(Offset 4)

Closes a link's connection from a protocol module

On entry

R0 = protocol module's link handle

On exit

R0 = pointer to protocol specific information, or 0

Use

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.

Related SWIs

Protocol_OpenLogicalLink, Protocol_CloseLogicalLink, Protocol_OpenConnection, Protocol_GetLinkState


Protocol_TransmitData
(Offset 5)

Transmits data over a connection via a protocol module

On entry

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

On exit

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

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:

  • If the connection failed (bits 0 and 1 are set) and no data is pending (bit 2 is clear) you must attempt to close the connection by calling Protocol_CloseConnection.
  • If the connection is pending you have made an error in your programming by trying to use the connection before it has been properly opened.
  • Bit 2 ('more data pending') has exactly the same meaning as bit 0 of a logical link's poll word, and is provided to reduce the amount of polling that needs to be done. If it is set you should initiate the data transfer by calling Protocol_DataRequest.
  • If the data you've received is in words, each word contains one character in the least significant byte.
Related SWIs

Protocol_SendFile, Protocol_SendFileData


Protocol_DataRequest
(Offset 6)

Requests that a protocol module forwards any pending data

On entry

R0 = protocol module's link handle
R1 = pointer to receive buffer
R2 = length of receive buffer (in bytes)

On exit

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

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:

  • if bit 0 ('data pending') of the link's poll word is set
  • if the 'data pending' bit (commonly bit 2) of the protocol status flags (commonly in R3) is set on return from a Protocol... SWI call.

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:

  • If the connection failed (bits 0 and 1 are set) and no data is pending (bit 2 is clear) you must attempt to close the connection by calling Protocol_CloseConnection.
  • If the connection is pending you have made an error in your programming by trying to use the connection before it has been properly opened.
  • Bit 2 ('data pending') has exactly the same meaning as bit 0 of a logical link's poll word, and is provided to reduce the amount of polling that needs to be done. If it is set you should continue the data transfer by calling Protocol_DataRequest.
  • If the data is in words, each word contains one character in the least significant byte.
Related SWIs

Protocol_GetFileInfo, Protocol_GetFileData, Protocol_GetFile


Protocol_MenuItemSelected
(Offset 7)

Requests that a protocol module services a menu selection

On entry

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

On exit

R0 - R4 preserved

Use

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:

  • get notice of a mouse click within the protocol's menu, via a Menu_Selection reason code from Wimp_Poll
  • get notice of the pointer moving over a right arrow to activate one of the protocol's submenus, via a MenuWarning message

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

Related SWIs

Protocol_GetProtocolMenu, Protocol_UnknownEvent


Protocol_UnknownEvent
(Offset 8)

Passes on Wimp events to a protocol module

On entry

R0 = pointer to Wimp event block (as returned by Wimp_Poll)

On exit

R0 preserved

Use

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.

Related SWIs

Protocol_GetProtocolMenu, Protocol_MenuItemSelected


Protocol_GetLinkState
(Offset 9)

Gets the state of a logical link

On entry

R0 = protocol module's link handle

On exit

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

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:

  • If the connection failed (bits 0 and 1 are set) and no data is pending (bit 2 is clear) you must attempt to close the connection by calling Protocol_CloseConnection.
  • If the connection is pending you must wait until bit 0 of the logical link's poll word is set. Then you should call either Protocol_DataRequest or Protocol_GetLinkState to find if the connection was opened, or if it failed.
  • Bit 2 ('data pending') has exactly the same meaning as bit 0 of a logical link's poll word, and is provided to reduce the amount of polling that needs to be done. If it is set you should initiate the data transfer by calling Protocol_DataRequest.
Related SWIs

Protocol_OpenLogicalLink, Protocol_CloseLogicalLink, Protocol_OpenConnection, Protocol_CloseConnection


Protocol_Break
(Offset 10)

Forces a protocol module to generate a Break

On entry

R0 = protocol module's link handle

On exit

R0 = terminal emulator's link handle
R3 = protocol status flags

Use

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:

  • If the connection failed (bits 0 and 1 are set) and no data is pending (bit 2 is clear) you must attempt to close the connection by calling Protocol_CloseConnection.
  • If the connection is pending you have made an error in your programming by trying to use the connection before it has been properly opened.
  • Bit 2 ('data pending') has exactly the same meaning as bit 0 of a logical link's poll word, and is provided to reduce the amount of polling that needs to be done. If it is set you should initiate the data transfer by calling Protocol_DataRequest.
Related SWIs

None


Protocol_SendFile
(Offset 11)

Initiates sending a file over a protocol module's connection

On entry

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

On exit

R0 = terminal emulator's link handle
R1 = protocol status flags

Use

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:

  • If the connection failed (bits 0 and 1 are set) and no data is pending (bit 2 of the link's poll word is clear) you must attempt to close the connection by calling Protocol_CloseConnection.
  • If the connection is pending you have made an error in your programming by trying to use the connection before it has been properly opened.

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

Related SWIs

Protocol_TransmitData, Protocol_SendFileData, Protocol_AbortTransfer, Protocol_DirOp


Protocol_SendFileData
(Offset 12)

Sends the data in a file over a protocol module's connection

On entry

R0 = protocol module's link handle
R1 = pointer to transmit buffer
R2 = length of transmit buffer (in bytes)
R3 = emulator send data flags

On exit

R0 = terminal emulator's link handle
R1 = protocol status flags

Use

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:

  • If the connection failed (bits 0 and 1 are set) and the transfer is not paused (bits 2-3 do not have the value 01) you must attempt to close the connection by calling Protocol_CloseConnection.
  • If the connection is pending you have made an error in your programming by trying to use the connection before it has been properly opened.
  • If the transfer is paused (bits 2-3 have the value 01) you must wait for bit 2 of the link's poll word to be set before making this call again to continue the transfer.
Related SWIs

Protocol_TransmitData, Protocol_SendFile, Protocol_AbortTransfer, Protocol_DirOp


Protocol_AbortTransfer
(Offset 13)

Aborts a file transfer

On entry

R0 = protocol module's link handle

On exit

R0 preserved

Use

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.

Related SWIs

Protocol_SendFile, Protocol_SendFileData, Protocol_GetFileInfo, Protocol_GetFileData, Protocol_GetFile


Protocol_GetFileInfo
(Offset 14)

Requests that a protocol module initiates forwarding a pending file

On entry

R0 = protocol module's link handle

On exit

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

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.

Related SWIs

Protocol_DataRequest, Protocol_AbortTransfer, Protocol_GetFileData, Protocol_GetFile, Protocol_DirOp


Protocol_GetFileData
(Offset 15)

Requests that a protocol module forwards the data in a file

On entry

R0 = protocol module's link handle
R1 = pointer to receive buffer
R2 = length of receive buffer (in bytes)

On exit

R0 = terminal emulator's link handle
R1 preserved
R2 = number of bytes of data placed in receive buffer
R3 = protocol status flags

Use

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:

  • If the connection failed (bits 0 and 1 are set) and the transfer is not paused (bits 2-3 do not have the value 01) you must attempt to close the connection by calling Protocol_CloseConnection.
  • If the connection is pending you have made an error in your programming by trying to use the connection before it has been properly opened.
  • If the transfer is paused (bits 2-3 have the value 01) you must wait for bit 2 of the link's poll word to be set before making this call again to continue the transfer.
Related SWIs

Protocol_DataRequest, Protocol_AbortTransfer, Protocol_GetFileInfo, Protocol_GetFile, Protocol_DirOp


Protocol_MenuHelp
(Offset 16)

Requests that a protocol module sends its interactive help message for a menu entry

On entry

R0 = protocol module's link handle
R1 = pointer to menu selection array, relative to protocol-specific menu tree

On exit

R0, R1 preserved

Use

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.

Related SWIs

Protocol_GetProtocolMenu, Protocol_MenuItemSelected


Protocol_GetFile
(Offset 17)

Requests that a protocol module gets a file over a connection

On entry

R0 = protocol module's link handle
R1 = pointer to file name (null terminated)

On exit

R0, R1 preserved

Use

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.

Related SWIs

Protocol_DataRequest, Protocol_AbortTransfer, Protocol_GetFileInfo, Protocol_GetFileData, Protocol_DirOp


Protocol_DirOp
(Offset 18)

Performs various directory operations over a connection

On entry

R0 = protocol module's link handle
R1 = reason code
R2 = pointer to directory name - reason codes 1 & 2 only (null terminated)

On exit

R0 = terminal emulator's link handle
R1, R2 preserved
R3 = protocol status flags

Use

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:

  • If the connection failed (bits 0 and 1 are set) and there is no operation in progress (bits 2-3 do not have the value 01) you must attempt to close the connection by calling Protocol_CloseConnection.
  • If the connection is pending you have made an error in your programming by trying to use the connection before it has been properly opened.
  • If the operation is still in progress (bits 2-3 have the value 01) you must wait for bit 2 of the link's poll word to be set. You can then make this call again with a null reason code to read the flags for the completed operation.
Related SWIs

Protocol_SendFile, Protocol_SendFileData, Protocol_AbortTransfer, Protocol_GetFileInfo, Protocol_GetFileData, Protocol_GetFile

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015