Psion Link Protocol

Copyright © Alexander Thoukydides.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Introduction

The latest version of this document will normally be available from http://www.thouky.co.uk/software/psifs/plp.html.

History

Disclaimer

All trademarks are acknowledged.

Acknowledgements

• Olaf Flebbe's document providing a partial description of the PLP.
• Phil Proudman's PLP implementation for UNIX.
• Frodo Looijaard's file format description.
• Psion documents describing the proposed differences between the SIBO and EPOC implementations.
• EPOC C++ SDK, Evaluation Edition.
• Excerpts from the EPOC source code.
• Analysis of the serial data exchanged between a Psion Series 5 and a PC running PsiWin.
• Trial and error while developing PsiFS for RISC OS computers.
• Corrections supplied by Fritz Elfert, Johan Persson, Andy Porro, David Bingham, Pauli Heikkinen, Adrian Youlden and Marcio Faustino.

Due to the diverse and incomplete nature of these sources, the description here probably contains both errors and omissions. Please send any corrections or additions to the author for inclusion in future revisions.

Layers

OSI layer		EPOC name	Description
7	Application	n/a
6	Presentation	LINK, RPCS, RFSV etc	Multiple servers, each providing a related set of services
5	Session	NCP	Multiplexing of multiple client-server communications channels with flow control
4	Transport	n/a
3	Network	n/a
2	Data link	Link	Synchronization, error detection and recovery
1	Physical	RS-232

Conventions

• Numeric values larger than a byte are stored with the least significant byte first.
• Strings are terminated by a single NUL (0x00) byte unless otherwise described.

Physical Layer

The DTR and RTS handshaking lines are both raised when the PLP is enabled and dropped when it is subsequently disabled. However, only the DSR line should be monitored to detect activity.

Any baud rate supported by both devices may be used. The data format is 8 data bits, 1 stop bit, and no parity checking.

Data Link Layer

This layer is sometimes referred to as LINK, but that leads to confusion with one of the higher level servers having the same name.

Frame Format

Bytes	1	1	1	1		n	1	1	2
Data	SYN	DLE	STX	Cont	Seq	Data	DLE	ETX	CRC

The Cont and Seq fields are combined into a single byte, with the Cont in the high nibble, and Seq in the low nibble. If the Seq value is greater than 7 then the most significant bit of the Seq nibble is set and an additional byte is inserted into the frame (EPOC variant only):

Bytes	1	1	1	1		1	n	1	1	2
Data	SYN	DLE	STX	Cont	(Seq & 7) | 8	Seq >> 3	Data	DLE	ETX	CRC

The length of the Data field (n) can vary from 0 to 300 bytes before byte stuffing. The session layer (NCP) is responsible for splitting and recombining longer messages to fit within this limit.

The 16 bit Cyclic Redundancy Check (CRC) is transmitted with the most significant byte followed by the least significant byte.

Note that the Ericsson R380 implementation uses ETB instead of SYN for the start of frame character. It also has a larger maximum frame size, with the length of the Data field (n) varying up to 2048 bytes before byte stuffing.

Special Characters

Name	Value	Description
STX	0x02	Start of frame
ETX	0x03	End of frame
EOT	0x04	A stuffed ETX character
DLE	0x10	Field delimiter within a frame
DC1	0x11	Not protocol characters, but stuffed (Ericsson R380)
DC3	0x13
SYN	0x16	Synchronize start of frame
ETB	0x17	Synchronize start of frame (Ericsson R380)

To prevent control characters within the frame body from being misinterpreted, a system of byte stuffing is employed. This replaces characters within the Cont/Seq and Data fields as follows:

Raw character		Stuffed character sequence		Variants
Name	Value	Names	Values
DLE	0x10	DLE DLE	0x10 0x10	SIBO and EPOC
ETX	0x03	DLE EOT	0x10 0x04	EPOC
DC1	0x11	DLE Space	0x10 0x20	Ericsson R380 only
DC3	0x13	DLE !	0x10 0x21

The reverse process is performed by the receiver.

Cyclic Redundancy Check

The following C code calculates a lookup table to allow efficient calculation of this CRC:

const unsigned int polynomial = 0x1021; unsigned int table[256], index; table[0] = 0; for (index = 0; index < 128; index++) {     unsigned int carry = table[index] & 0x8000;     unsigned temp = (table[index] << 1) & 0xffff;     table[index * 2 + (carry ? 0 : 1)] = temp ^ polynomial;     table[index * 2 + (carry ? 1 : 0)] = temp; }

The following line can then be used to add a byte (value) to a 16 bit CRC (old_crc) to give the new 16 bit CRC (new_crc):

new_crc = (old_crc << 8) ^ table[((old_crc >> 8) ^ value) & 0xff];

Timers

Timer	Period
Re-transmission	Baud rate dependant
Inactivity	Application dependant

The re-transmission timeout is used to trigger the re-transmission of unacknowledged frames. To optimise the timeout for the operating conditions, it is calculated by summing the following three components:

Component	Description
Baud Rate Bits Factor	The estimated time required to transmit the number of bits in a frame at the current baud rate. A suitable timeout is given by (13200 / baud) seconds.
Round Trip Time Factor	A running estimate of the additional time to receive an acknowledgement from the remote device. A constant offset of 0.2 seconds is probably adequate for simpler implementations.
Backoff Factor	An additional timeout dependant on the number of re-transmissions that have taken place. This factor may be omitted in a simple implementation.

The Baud Rate Bits Factor is most significant at low baud rates, but the Round Trip Time Factor is more significant at higher baud rates.

The inactivity timer period may be adjusted to suit the application. If no detection of an idle connection is required then it can be completely disabled, otherwise a timeout of 60 seconds is recommended.

Although two different timer events are required, they may both be implemented using a single timer since only one timer can be active at any time.

Protocol Data Units

Cont	Seq	Name	Description
0	Sequence number of last valid Data_Pdu received	Ack_Pdu	Used to complete handshaking during connection phase, and to acknowledge Data_Pdu frames.
1	0	Disc_Pdu	Used to terminate a connection.
	1	Disc_Req_Pdu	First disconnect in a handshaked disconnection. Not currently used.
2	0	Req_Pdu	Used during connection phase to request a connection.
	1 ... 3 (use 1)	Req_Req_Pdu	First request in connection establishment. EPOC variant of protocol only.
	4 ... 6 (use 4)	Req_Con_Pdu	Responding request in connection establishment. EPOC variant of protocol only.
3	Next sequence number	Data_Pdu	Data frame.

Only the Data_Pdu and Req_Con_Pdu frames contain Data fields.

The Data_Pdu and Ack_Pdu both contain a sequence number. This is used to allow acknowledgements to be matched to the corresponding data frame. Each device maintains its own sequence number that is incremented for each Data_Pdu, modulo either 8 for the SIBO variant or 2048 for the EPOC variant. More details are given in the following sections.

Connection Sequence

Both client-server and peer to peer connections are supported. The peer to peer connection sequence is a symmetrical version of the client-server sequence, with both devices processing all of the PDUs.

SIBO Connection

From client	From server	Description
Req_Pdu		Connection requested by client
	Req_Pdu	Connection accepted by server
Ack_Pdu		Connection established

The peer to peer connection sequence is very similar:

From device 1	From device 2	Description
Req_Pdu	Req_Pdu	Both devices request a connection
Ack_Pdu	Ack_Pdu	Both devices accept the connection

In both cases the sequence numbers should be initialised to 0, and the Ack_Pdu sent with a Seq field of 0. However, if the received Ack_Pdu contains a non-zero Seq field then the sequence number should be seeded from the supplied value.

EPOC Connection

From client	From server	Description
Req_Req_Pdu		Connection requested by client
	Req_Con_Pdu	Connection request confirmed by server
Ack_Pdu		Connection established

The peer to peer connection sequence is very similar:

From device 1	From device 2	Description
Req_Req_Pdu	Req_Req_Pdu	Both devices request a connection
Req_Con_Pdu	Req_Con_Pdu	Both devices confirm the connection request
Ack_Pdu	Ack_Pdu	Both devices accept the connection

The Data field of the Req_Con_Pdu frames contain a 4 byte magic number. This is a pseudo-random value generated independently by each device. If the magic numbers match then a peer to peer connection is rejected because it indicates that the device is attempting to connect to itself. To avoid the risk of the same pseudo-random number sequence being generated by both devices, it is advisable to include an additional unique element, such as the value of a clock.

In both cases the sequence numbers should be initialised to 0, and the Ack_Pdu sent with a Seq field of 0. However, if the received Ack_Pdu contains a non-zero Seq field then the sequence number should be seeded from the supplied value.

If the Ack_Pdu is not received within the re-transmission timeout, then the Req_Req_Pdu may be re-transmitted up to 4 times before aborting the connection attempt.

Universal Connection

A Req_Req_Pdu frame can always be used to initiate a connection; a device that supports the EPOC variant of the protocol will then reply with a Req_Con_Pdu frame, but if the other device only supports the SIBO variant then it will treat it as a Req_Pdu and reply with an Ack_Pdu. Hence, the protocol variant is indicated by whether a Req_Con_Pdu is received prior to the Ack_Pdu.

Similarly, if the other device initiates the connection, then the protocol variant can be detected from whether a Req_Pdu or Req_Req_Pdu is received.

Data Transfer Sequence

The EPOC variant of the data link layer is multi windowed, i.e. more than one acknowledgement can be outstanding at any time. The default configuration will send up to 8 Data_Pdu frames before waiting for an acknowledgement.

The data transfer sequence is the same for both the SIBO and EPOC variants. Either device may initiate a data transfer, providing that there are not too many outstanding acknowledgements for the previous transfers.

From device 1	From device 2	Description
Data_Pdu		Data sent
	Ack_Pdu	Data acknowledged

The only other difference between the SIBO and EPOC variants, as described earlier, is the range of sequence numbers used; the value is modulo 8 for the SIBO variant and modulo 2048 for the EPOC variant. The sequence number is incremented prior to sending the Data_Pdu.

An Ack_Pdu should always be sent in response to a received Data_Pdu, even if the sequence number does not match the expected value. However, the Seq field of the Ack_Pdu should be set to the value from the last valid Data_Pdu received, not necessarily that of the Data_Pdu being responded to.

If the Ack_Pdu is not received within the re-transmission timeout, or if an Ack_Pdu is received with a different sequence number from that sent in the Data_Pdu, then the Data_Pdu may be re-transmitted up to 8 times before the link is disconnected. The sequence number must not be incremented when re-transmitting a Data_Pdu.

Disconnection Sequence

A disconnection may also occur if the serial cable is physically disconnected, so the DSR handshaking line should also be monitored as described earlier. Additionally, if the inactivity timeout is exceeded without any frames being received then a disconnection should be assumed.

SIBO Disconnection

From device 1	From device 2	Description
Disc_Pdu		Initiator requests a disconnection

Note that there is no reply to the Disc_Pdu, so the disconnection must be assumed to have succeeded.

EPOC Disconnection

From device 1	From device 2	Description
Disc_Req_Pdu		Initiator requests a disconnection
	Disc_Pdu	Disconnection confirmed

Even if this enhanced disconnection sequence is supported, the original SIBO disconnection sequence must still be supported. In particular, if the Disc_Pdu is not received within the re-transmission timeout then a Disc_Pdu frame should be sent and the disconnection assumed to have succeeded.

State Machine

This is not intended to be the definitive implementation, but should help to clarify the operation of the protocol. In particular, only single windowed behaviour is supported, but this does not present interoperability with systems that do support multi-windowed operation; it just reduces that maximum achievable transfer rate.

States

State	Description
Idle_State	Disconnected
Idle_Req_State	Req_Req_Pdu sent, awaiting Req_Con_Pdu response
Idle_Ack_State	Req_Con_Pdu sent, awaiting Ack_Pdu response
Data_State	Connected, no acknowledgement pending
Data_Ack_State	Data_Pdu sent, awaiting Ack_Pdu acknowledgement

Events

Event	Source	Description
Ack_Rx	Received frame	Ack_Pdu (acknowledge) received
Disc_Rx		Disc_Pdu or Disc_Req_Pdu (disconnect) received
Req_Rx		Req_Pdu (connection request) received
Req_Req_Rx		Req_Req_Pdu (handshaked connection request) received
Req_Con_Rx		Req_Con_Pdu (handshaked connection accepted) received
Data_Rx		Data_Pdu (data) received
Connect	Local client	Connection requested
Disconnect		Disconnection requested
Write		Data to transmit
Timeout	Timer	Re-transmission timer or inactivity timer expired

Note that only a single timer event is used; both the re-transmission and inactivity timeouts are implemented using a single timer.

Only the SIBO disconnection sequence is implemented, so Disc_Pdu and Disc_Req_Pdu are treated identically.

Variables

Variable	Description	Default
Enabled	Is the link enabled	FALSE
Variant	The protocol variant: SIBO or EPOC	SIBO
Retries	Number of retries remaining	0
Seq_Tx	Last sequence number for transmitted data frames	0
Seq_Rx	Last sequence number for received data frames	0
Magic	Magic number for this device	Pseudo-random

State Tables

The function Inc(x) is defined to return the next sequence number after x, modulo the appropriate value.

The Reset() function sets all of the variables, except for Enabled, back to the defaults given in the above table. This should select a different pseudo-random number for Magic. It also starts the re-transmission timer.

Idle_State

Idle_Req_State

Idle_Ack_State

Data_State

Data_Ack_State

PLP Mode on Erisson R380

Starting PLP

From host	From R380	Description
0x41 0x54 0x2a 0x45 0x53 0x59 0x4e 0x3d 0x31 0x0d		Request PLP mode: AT*ESYN=1
	0x41 0x54 0x2a 0x45 0x53 0x59 0x4e 0x3d 0x31 0x0d	Echo command: AT*ESYN=1
	0x0d 0x0a 0x4f 0x4b 0x0d 0x0a	Acknowledge command: OK
	0x11 0x11	Start PLP operation

A peer to peer PLP connection is then established as described above.

Ending PLP

Session Layer

Channels

Frame Formats

Bytes	1	1	1	n
Data	Destination channel	Source channel	Frame type	Data

The channel pair (Source channel and Destination channel) specifies a connection between two processes. PDUs for channel 0 are expedited; they must be delivered and processed before any PDUs for other channels.

Command Frames

XOFF Frame

Block transmission of frames to the specified Channel until an XON frame is received. All channels default to being unblocked.

XON Frame

Unblock transmission of frames to the specified Channel. This reverses the effect on an XOFF frame.

Connect Frame

A client is requesting connection to the server called Server name. A Connect Response frame is always sent in reply.

The maximum length of the server name field is 16 characters, including the NUL terminator.

Connect Response Frame

This is the reply sent in response to a Connect frame. The source channel is set to the server's channel if the connection was successful, or 0 for the control channel otherwise. The Status code is zero (E_SIBO_NONE) for a successful connection, or non-zero (E_SIBO_FILE_NXIST) if the server cannot be found.

Connection Termination Frame

The specified server has disconnected all clients.

NCP Information Frame

This is the first frame that is sent by an invocation of NCP when a connection has been established. It enables the NCP and servers to adapt to the capabilities of the other device.

The following Version numbers are currently used:

Version	Description
0x02	SIBO (old)
0x03	SIBO (new)
0x06	EPOC (ER3)
0x10	EPOC (ER5)

For maximum compatibility it is recommended that 6 be used if the data link layer has identified the EPOC variant of the protocol, and 2 be used otherwise. The behaviour of servers should be controlled by the received version number.

The ID is a unique identifier for the current NCP process. It does not appear to be used for anything, so it is probably sufficient to generate a pseudo-random number.

Disconnection Frame

The specified client has disconnected from the specified server.

NCP Termination Frame

The NCP has shut down.

Data Frames

Complete Frame

A Complete frame serves as either the final frame in a series of Partial frames which make a single large frame, or as a single frame which fits into the data link layer's frame size.

Partial Frame

A Partial frame is sent as one of a series that should be re-assembled to form a larger frame.

Connection Sequence

From device 1	From device 2
NCP Information frame	NCP Information frame
Connect frame for LINK.*	Connect frame for LINK.*
Connect frame for other servers	Connect frame for other servers
Connect Response frames	Connect Response frames

Due to the asynchronous nature of the protocol, the Connect Response frames may occur at any time after the corresponding Connect frame has been sent. Also, with the exception of the LINK.* connection, the Connect frames may be sent at any time to connect to additional servers.

Disconnection Sequence

From disconnecting device
Disconnection frames and Connection Termination frames for each connection
NCP Termination frame

Note that no confirmations are received; it is the responsibility of the data link layer to ensure that the frames are communicated without errors. Connect frames received during this sequence should be ignored; the remote device may attempt to re-establish terminated connections.

Presentation Layer

LINK Server

Command Frames

Link Register Command

Bytes	1	2	n
Data	0x00	Operation ID	Server name

or:

Bytes	1	2	n	1	1	4
Data	0x00	Operation ID	Server name	Major version	Minor version	Build

Reply:

Bytes	1	2	2	2	n
Data	0x01	Operation ID	Status code	???	Server name

This command is used to register a server for connection using a Connect frame. It should normally be tried after a connection has been unsuccessfully attempted.

The Operation ID is a unique identifier used to verify that commands and replies match. A different value within the range 0 to 65535 should be generated for each command, and the reply checked to confirm that it contains the same value.

The Server name in the command is the name of the required server, but without any extension specified. If the reply contains a valid Server name (at least 4 characters long and not containing any control characters) then that should be used as the name within the Connect frame, otherwise ".*" should be appended to the name specified in the command.

The second form of the command allows a minimum version of the server to be specified. The two forms behave identically if the Version and Build are both set to 0.

A typical sequence of operations would be:

From client	From server
Connect frame for SYS$RPCS.*
	Connect Response frame indicating failure
Link Register command for SYS$RPCS
	Link Register response specifying SYS$RPCS.*
Connect frame for SYS$RPCS.*
	Connect Response frame indicating success

RPCS Server

Note that the Ericsson R380 uses the name "SYS$RPCSU.*" instead, where the additional "U" in the name indicates that Unicode strings are used.

Command Frames

NCP_QUERY_SUPPORT

Bytes	1	1	1
Data	0x00	Major version	Minor version

Reply:

Bytes	1	1	1
Data	Status code	Major version	Minor version

Exchange NCP version numbers.

All existing implementations use a Major version of 1, with the Minor version varying between 1 and 30.

NCP_EXEC_PROGRAM

Bytes	1	128	1	n
Data	0x01	Program name	Arguments length	Arguments

Reply:

Bytes	1
Data	Status code

Start a copy of Program name with the specified Arguments.

If the Program name is shorter than 128 characters then it is padded to 128 characters with 0 bytes, otherwise the field is extended as required. The Arguments length field specifies the length of the Arguments string, excluding the terminator character.

NCP_QUERY_DRIVE

Bytes	1	1
Data	0x02	Drive letter

Reply:

Bytes	1	Repeated fields:
		ni	mi
Data	Status code	Program name	Arguments

List the programs with open files on the specified drive.

The EPOC variant lists all applications, regardless of which drive they are using. The result is a list of Program name and Argument pairs; one for each open program.

NCP_STOP_PROGRAM

Bytes	1	n
Data	0x03	Program name

Reply:

Bytes	1
Data	Status code

Attempt to terminate the specified process.

This may result in the application opening a dialogue box to allow any modifications to be saved. NCP_PROG_RUNNING can be used to detect when the process has been stopped.

NCP_PROG_RUNNING

Bytes	1	n
Data	0x04	Program name

Reply:

Bytes	1
Data	Status code

Check whether the specified process is running.

This returns E_SIBO_NONE if the process is running, or E_SIBO_FILE_NXIST otherwise.

NCP_FORMAT_OPEN

Bytes	1	n
Data	0x05	Device name

Reply:

Bytes	1	2	2
Data	Status code	Handle	Count

Initiate formatting a drive.

This is a slow process, so NCP_FORMAT_READ should be called Count times with the returned Handle to progress the format.

NCP_FORMAT_READ

Bytes	1	2
Data	0x06	Handle

Reply:

Bytes	1
Data	Status code

Continue formatting a drive.

The Handle returned by NCP_FORMAT_OPEN must be passed to specify the operation to progress.

NCP_GET_UNIQUE_ID

Bytes	1	n
Data	0x07	Device name

Reply:

Bytes	1	4
Data	Status code	Unique ID

Read the Unique ID for the specified removable device.

NCP_GET_OWNER_INFO

Bytes	1
Data	0x08

Reply:

Bytes	1	n
Data	Status code	Owner information (not NUL terminated)

Read the user information.

The returned Owner information is plain text; any formatting is stripped.

NCP_GET_MACHINE_TYPE

Bytes	1
Data	0x09

Reply:

Bytes	1	2
Data	Status code	Machine type

Read the type of the remote machine.

The following Machine type numbers are currently used:

Machine type	Description
0x00	Unknown
0x01	PC
0x02	MC
0x03	HC
0x04	Series 3
0x05	Series 3a, 3c, or 3mx
0x06	Workabout
0x07	Sienna
0x08	Series 3c
0x20	Series 5
0x21	WinC

Be careful; some of these values are untested.

NCP_GET_CMD_LINE

Bytes	1	n
Data	0x0a	Process name

Reply:

Bytes	1	n
Data	Status code	Program name

or:

Bytes	1	n	1	m
Data	Status code	Program name	m	Command line (not NUL terminated)

or:

Bytes	1	n	256 - n	m	40 - m
Data	Status code	Program name	m	Command line	???

Read the Command line for Process name.

The first form of the reply is used if there is no open file. The other two forms are used by the EPOC and SIBO variants respectively.

NCP_STOP_FILE

Bytes	1	n
Data	0x0b	File name

Reply:

Bytes	1	n
Data	Status code	Process name

Find the Process name of the program using the named file.

NCP_GET_MACHINE_INFO

Bytes	1
Data	0x64

Reply:

Bytes	1	4	1	1	2	8	16	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	4	88
Data	Status code	Machine type	Major ROM version	Minor ROM version	ROM build	Reserved	Machine name	Display width	Display height	Machine UID low	Machine UID high	Time low	Time high	Country code	UTC offset	DST	DST zone	Main battery inserted low	Main battery inserted high	Main battery status	Main battery used low	Main battery used high	Main battery current	Main battery used power	Main battery voltage	Main battery max voltage	Backup battery status	Backup battery voltage	Backup battery maximum voltage	External power	External power used low	External power used high	???	RAM size	ROM size	RAM maximum free	RAM free	RAM disk size	Registry size	ROM reprogrammable	Language	Reserved

This command is only supported by the EPOC variant of the protocol.

See NCP_GET_MACHINE_TYPE for a description of the possible Machine type values.

The Major ROM version, Minor ROM version, and ROM build fields combine to give the version number of the operating system. This is typically displayed with the Major ROM version followed by a decimal point, Minor ROM version using two digits, and finally the ROM build in brackets. All values are displayed in decimal.

The Machine name is a string giving a textual description of the machine type and revision.

The Display width and Display height indicate the size of the LCD in pixels.

The Machine UID low and Machine UID high fields combine to form a 64 bit unique identifier for this machine.

See NCP_SET_TIME for a description of the Time low, Time high, Country code, UTC offset, DST and DST zone values.

The Main battery inserted low and Main battery inserted high fields combine to form a 64 bit date specifying when the main batteries were inserted, specified as the number of micro-seconds since 00:00 on 1st January 1.

Main battery status gives the condition of the main batteries. See RFSV32_VOLUME for a description of the possible values.

The Main battery used low and Main battery used high fields combine to form a 64 bit value giving the number of micro-seconds that the main battery has been used.

Main battery current is the main battery current in milli-amps.

Main battery used power is the integrated main battery usage in mA-seconds.

Main battery voltage and Main battery max voltage give the current and maximum main battery voltages in milli-volts.

Backup battery status gives the condition of the backup batteries. See RFSV32_VOLUME for a description of the possible values.

Backup battery voltage and Backup battery maximum voltage give the current and maximum backup battery voltages in milli-volts.

The External power field indicates whether the machine is operating on external power.

The External power used low and External power used high fields combine to form a 64 bit value giving the number of micro-seconds that the machine has been operating on external power.

RAM size and ROM size give the total size of ROM and RAM fitted.

RAM maximum free and RAM free give the maximum and current free RAM in bytes.

RAM disk sizeis the current size of the internal RAM disk in bytes.

Registry size is the current size of the registry in bytes.

The ROM reprogrammable field indicates whether the ROM can be modified.

The Language may be one of the following:

Language	Description
0x00	Test
0x01	UK English
0x02	French
0x03	German
0x04	Spanish
0x05	Italian
0x06	Swedish
0x07	Danish
0x08	Norwegian
0x09	Finnish
0x0A	American English
0x0B	Swiss French
0x0C	Swiss German
0x0D	Portuguese
0x0E	Turkish
0x0F	Icelandic
0x10	Russian
0x11	Hungarian
0x12	Dutch
0x13	Belgian Flemish
0x14	Australian English
0x15	Belgian French
0x16	Austrian German
0x17	New Zealand English
0x18	International French
0x19	Czech
0x1A	Slovak
0x1B	Polish
0x1C	Slovenian
0x1D	Taiwan Chinese
0x1E	Hong Kong Chinese
0x1F	RPC Chinese
0x20	Japanese
0x21	Thai

NCP_CLOSE_HANDLE

Bytes	1	2
Data	0x65	Handle

Reply:

Bytes	1
Data	Status code

Close a previously opened resource Handle. This command is only supported by the EPOC variant of the protocol.

NCP_REG_OPEN_ITER

Bytes	1	???
Data	0x66	???

Reply:

Bytes	1	???
Data	Status code	???

This command is only supported by the EPOC variant of the protocol.

NCP_REG_READ_ITER

Bytes	1	???
Data	0x67	???

Reply:

Bytes	1	???
Data	Status code	???

This command is only supported by the EPOC variant of the protocol.

NCP_REG_WRITE

Bytes	1	???
Data	0x68	???

Reply:

Bytes	1	???
Data	Status code	???

This command is only supported by the EPOC variant of the protocol.

NCP_REG_READ

Bytes	1	???
Data	0x69	???

Reply:

Bytes	1	???
Data	Status code	???

This command is only supported by the EPOC variant of the protocol.

NCP_REG_DELETE

Bytes	1	???
Data	0x6a	???

Reply:

Bytes	1	???
Data	Status code	???

This command is only supported by the EPOC variant of the protocol.

NCP_SET_TIME

Bytes	1	4	4	4	4	4	4
Data	0x6b	Time low	Time high	Country code	UTC offset	DST	DST zone

Reply:

Bytes	1
Data	Status code

Set the clock. This command is only supported by the EPOC variant of the protocol.

The Time low and Time high fields combine to form a 64 bit date, specified as the number of micro-seconds since 00:00 on 1st January 1 in the home time zone.

The Country code indicates the country of the home time zone. This is 0 for most countries, but should probably be the international dial code.

The UTC offset is the number of seconds offset of the home time zone from UTC.

The DST consists of a combination of the following flags, specifying which zones daylight saving time is active:

DST zone	Description
0x00000000	None
0x00000001	European
0x00000002	Northern
0x00000004	Southern
0x40000000	Home

The DST zone is a single flag, from those listed above, specifying which DST zone the home time zone is part of.

The easiest way to use this command is to read the various time zone and DST fields using NCP_GET_MACHINE_INFO and just change the Time low and Time high fields to the new time.

NCP_CONFIG_OPEN

Bytes	1	???
Data	0x6c	???

Reply:

Bytes	1	???
Data	Status code	???

This command is only supported by the EPOC variant of the protocol.

NCP_CONFIG_READ

Bytes	1	???
Data	0x6d	???

Reply:

Bytes	1	???
Data	Status code	???

This command is only supported by the EPOC variant of the protocol.

NCP_CONFIG_WRITE

Bytes	1	???
Data	0x6e	???

Reply:

Bytes	1	???
Data	Status code	???

This command is only supported by the EPOC variant of the protocol.

NCP_QUERY_OPEN

Bytes	1	1
Data	0x6f	Drive letter

Reply:

Bytes	1	2
Data	Status code	Handle

Start a query to read the files open on the specified drive. This command is only supported by the EPOC variant of the protocol.

NCP_QUERY_READ should be called repeatedly with the returned Handle to read the details, and NCP_CLOSE_HANDLE should be called to close the Handle when finished.

NCP_QUERY_READ

Bytes	1	2
Data	0x70	Handle

Reply:

Bytes	1	Repeated fields:
		ni	mi
Data	Status code	Program name	Arguments

List the programs with open files on the specified drive. This command is only supported by the EPOC variant of the protocol.

NCP_QUERY_OPEN should be used to obtain the Handle. The result is a list of Program name and Argument pairs; one for each open program. This should be called repeatedly until no further details are returned.

NCP_QUIT_SERVER

Bytes	1
Data	0xff

Reply:

Bytes	1
Data	Status code

Quit the RPCS server.

It is not necessary to use this command; use of the Connection Termination frame is adequate.

RFSV Server

The name "SYS$RFSV.*" is used in the Connect frame to start the RFSV server. The Ericsson R380 uses the name "SYS$RFSVU.*" instead, where the additional "U" in the name indicates that Unicode strings are used.

The version number specified in the NCP Information frame selects the RFSV version; a value of 6 or higher is required to use the EPOC variant, otherwise the SIBO variant is used.

SIBO Command Frames

Bytes	2	2	n
Data	Reason code	n	Request data

The maximum length of Request data is 852 bytes, leading to a maximum command frame size of 856 bytes.

All RFSV reply frames have the following general format:

Bytes	2	2	2	n
Data	0x2a	n + 2	Status code	Reply data

The Status code is a SIBO status code.

The maximum length of Reply data is 852 bytes, leading to a maximum reply frame size of 858 bytes. To make allowance for possibly buggy implementations, it is recommended that at most 640 bytes of data are read or written to a file in a single operation, but all received frames up to the maximum size of 858 bytes should be accepted.

The SIBO character set is used for any text strings.

RFSV16_FOPEN

Bytes	2	2	2	n
Data	0x00	Frame length	Mode	File name

Reply:

Bytes	2	2	2	2
Data	0x2a	Frame length	Status code	Handle

Open File name for reading or writing via the returned Handle.

The Mode consists of one of the following operations:

Mode	Description
0x0000	Open an existing file
0x0001	Create a new file
0x0002	Create a new file, or truncate an existing file to zero length
0x0003	Append to an existing file
0x0004	Create a new file with a unique name

combined with one of these stream types:

Mode	Description
0x0000	Open as a binary stream
0x0010	Open as a text stream
0x0020	Open as a binary record
0x0030	Open as a directory record
0x0040	Open as a format
0x0050	Open as a device list
0x0060	Open as a node list

and any of the following flags:

Mode	Description
0x0100	Open for read and write access
0x0200	Open for random access
0x0400	Open for sharing

RFSV16_FCLOSE must be used to close the Handle when it is no longer required.

RFSV16_FCLOSE

Bytes	2	2	2
Data	0x02	Frame length	Handle

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Close the Handle previously opened using RFSV16_FOPEN or RFSV16_OPENUNIQUE.

RFSV16_FREAD

Bytes	2	2	2	2
Data	0x04	Frame length	Handle	Length

Reply:

Bytes	2	2	2	n
Data	0x2a	Frame length	Status code	Data

Read Length bytes from the file identified by Handle.

The reply contains the Length bytes of data read.

RFSV16_FDIRREAD

Bytes	2	2	2
Data	0x06	Frame length	Handle

Reply:

Bytes	2	2	2	2	Repeated fields:
					2	2	4	4	4	ni
Data	0x2a	Frame length	Status code	Buffer length	Version	Attributes	Size	Modified	Reserved	File name

Read entries from the directory specified by Handle.

The reply contains details of entries from the specified directory. To read all of the directory entries this operation should be repeated until the returned Status code is E_SIBO_FILE_EOF.

The Buffer length is the length of the repeated fields, i.e. Frame length - 4.

The Attrubutes consists of a combination of the following flags:

Attribute	Description
0x0001	Writeable
0x0002	Hidden
0x0004	System
0x0008	Volume label
0x0010	Directory
0x0020	Modified
0x0100	Readable
0x0200	Executable
0x0400	Stream
0x0800	Text

The Size is simply the length of the file in bytes.

The Modified date is specified as the number of seconds since 13:00 on 1st January 1970. This is always a multiple of two.

RFSV16_FDEVICEREAD

Bytes	2	2	2
Data	0x08	Frame length	Handle

Reply:

Bytes	2	2	2	2	2	2	4	4	n	2	16
Data	0x2a	Frame length	Status code	Version	Media type	Removable	Size	Free	Volume label	Battery status	Reserved

Read information about the device specified by Handle.

The Media type consists of a type:

Media type	Description
0x0000	Not a known type
0x0001	Floppy disk
0x0002	Hard disk
0x0003	Flash disk
0x0004	RAM
0x0005	ROM
0x0006	Write protected

combined with any of the following flags:

Media type	Description
0x0800	Formattable
0x1000	Dual density
0x2000	Internal
0x4000	Dynamic
0x8000	Compressible

The Removable flag is non-zero for a removable device, or zero otherwise.

Size and Free give the total size and the remaining free space on the device.

The Battery status may be one of the following:

Media type	Description
0	Dead
1	Very low
2	Low
3	Good

RFSV16_FWRITE

Bytes	2	2	2	n
Data	0x0a	Frame length	Handle	Data

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Write Data to the file identified by Handle.

The number of bytes is not explicitly specified; this is inferred from the size of the frame.

RFSV16_FSEEK

Bytes	2	2	2	4	2
Data	0x0c	Frame length	Handle	Seek offset	Sense

Reply:

Bytes	2	2	2	4
Data	0x2a	Frame length	Status code	New offset

Reposition the sequential file pointer for the file specified by Handle.

The interpretation of the signed New offset value depends on the Sense specified:

Sense	Description
0x0001	Absolute position from the start of the file
0x0002	Offset from the current position
0x0003	Offset from the end of the file
0x0004	Read the current position without changing it
0x0005	Set
0x0006	Rewind

The value of the sequential file pointer after the seek is returned as New offset.

RFSV16_FFLUSH

Bytes	2	2	2
Data	0x0e	Frame length	Handle

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Flush to disk any cached data for the file specified by Handle.

RFSV16_FSETEOF

Bytes	2	2	2	4
Data	0x10	Frame length	Handle	Size

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Set the length of the file specified by Handle to Size bytes.

RFSV16_RENAME

Bytes	2	2	n	m
Data	0x12	Frame length	Source name	Destination name

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Rename Source name to Destination name.

RFSV16_DELETE

Bytes	2	2	n
Data	0x14	Frame length	File name

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Delete File name.

RFSV16_FINFO

Bytes	2	2	n
Data	0x16	Frame length	File name

Reply:

Bytes	2	2	2	2	2	4	4	4
Data	0x2a	Frame length	Status code	Version	Attributes	Size	Modified	Reserved

Read details about File name.

See RFSV16_FDIRREAD for a description of the returned values.

RFSV16_SFSTAT

Bytes	2	2	2	2	n
Data	0x18	Frame length	Set	Mask	File name

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Set the Mask attributes of File name to the state specified by Set.

See RFSV16_FDIRREAD for a description of the possible attribute values.

If both the Set and Mask values are both specified as 0x0008, indicating a volume label, then this changes the volume label. As an example, if File name is C:\FOOBAR then it will set the volume label for drive C: to FOOBAR.

RFSV16_PARSE

Bytes	2	2	n
Data	0x1a	Frame length	File name

Reply:

Bytes	2	2	2	n
Data	0x2a	Frame length	Status code	Parsed name

Parse File name to give Parsed name.

This can be used to remove wildcards from a file name.

RFSV16_MKDIR

Bytes	2	2	n
Data	0x1c	Frame length	Directory name

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Create a new directory called Directory name.

RFSV16_OPENUNIQUE

Bytes	2	2	2	n
Data	0x1e	Frame length	Mode	File name

Reply:

Bytes	2	2	2	2	n
Data	0x2a	Frame length	Status code	Handle	Opened name

Open File name for reading or writing via the returned Handle.

See RFSV16_FOPEN for a description of the possible Mode values.

The actual name of the file opened is returned as Opened name. This is useful when requesting a unique file to be opened.

RFSV16_STATUSDEVICE

Bytes	2	2	n
Data	0x20	Frame length	Device name

Reply:

Bytes	2	2	2	2	2	2	4	4	n	2	16
Data	0x2a	Frame length	Status code	Version	Media type	Removable	Size	Free	Volume label	Battery status	Reserved

Read the status of the device specified by Device name.

See RFSV16_FDEVICEREAD for details of the returned values.

RFSV16_PATHTEST

Bytes	2	2	n
Data	0x22	Frame length	File name

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Check if File name specifies a valid path.

RFSV16_STATUSSYSTEM

Bytes	2	2	n
Data	0x24	Frame length	File system

Reply:

Bytes	2	2	2	2	2	2
Data	0x2a	Frame length	Status code	Version	Type	Formattable

Read the status of the specified File system.

RFSV16_CHANGEDIR

Bytes	2	2	n
Data	0x26	Frame length	Directory name

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Change the current directory to Directory name.

RFSV16_SFDATE

Bytes	2	2	4	n
Data	0x28	Frame length	Modified	File name

Reply:

Bytes	2	2	2
Data	0x2a	Frame length	Status code

Set the Modified date of File name.

The date is specified as number of seconds since 13:00 on 1st January 1970.

EPOC Command Frames

Bytes	2	2	n
Data	Reason code	Operation ID	Request data

All RFSV reply frames have the following general format:

Bytes	2	2	4	n
Data	0x11	Operation ID	Status code	Reply data

The Operation ID is a unique identifier used to verify that commands and replies match. A different value within the range 0 to 65535 should be generated for each command, and the reply checked to confirm that it contains the same value.

The Status code is an EPOC status code.

The maximum frame size is not well defined, but to avoid potential incompatibilities it is recommended that at most 2048 bytes of data are read or written to a file in a single operation, but all received frames up to a maximum size of 2079 bytes should be accepted.

Strings are usually passed as a 2 byte length followed by the data using the EPOC character set. Strings are not NUL terminated. The most significant bit of the length field may be set to indicate Unicode strings.

RFSV32_CLOSE_HANDLE

Bytes	2	2	4
Data	0x01	Operation ID	Handle

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Close the Handle previously opened using RFSV32_OPEN_DIR, RFSV32_OPEN_FILE, RFSV32_TEMP_FILE, RFSV32_CREATE_FILE, RFSV32_REPLACE_FILE or RFSV32_OPEN_DIR_UID.

RFSV32_OPEN_DIR

Bytes	2	2	4	2 + n
Data	0x10	Operation ID	Attributes	File name

Reply:

Bytes	2	2	4	4
Data	0x11	Operation ID	Status code	Handle

Open a Handle to read files that match the wildcarded File name.

RFSV32_READ_DIR should be used to read the list of matching files. The description for that command also details the possible Attributes that may be specified.

RFSV32_READ_DIR

Bytes	2	2	4
Data	0x12	Operation ID	Handle

Reply:

Bytes	2	2	4	Repeated fields:
				0 to 3	4	4	4	4	4	4	4	4	4	ni	0 to 3	mi
Data	0x11	Operation ID	Status code	Alignment	Short name length	Attributes	Size	Modified low	Modified high	UID 1	UID 2	UID 3	Long name length	Long name	Alignment	Short name

Read directory entries specified by the Handle previously opened using RFSV32_OPEN_DIR.

The reply contains details of entries from the specified directory. To read all of the directory entries this operation should be repeated until the returned Status code is E_EPOC_EOF.

Two names are returned for each file. The Long name is the actual name of the file, and the Short name is the SIBO compatible version. Unlike the other commands, the lengths of these strings are specified by 4 byte values. If the Short name length is 0 then the Short name field is omitted, and both names should be treated as being identical.

The Attributes consist of a combination of the following flags:

Attribute	Description
0x0001	Read only
0x0002	Hidden
0x0004	System
0x0010	Directory
0x0020	Archive
0x0040	Volume label
0x0080	Normal
0x0100	Temporary
0x0800	Compressed

The Size is simply the length of the file in bytes.

The Modified low and Modified high fields combine to form a 64 bit modification date, specified as the number of micro-seconds since 00:00 on 1st January 1.

The UID 1, UID 2 and UID 3 fields are the first three words of the file, and indicate the type of data it contains. These fields are only valid if bit 28 (0x10000000) of the Attributes was passed to RFSV32_OPEN_DIR. The UIDs for some of the standard applications are:

Application	UID 1	UID 2	UID 3
Word	0x10000037	0x1000006D	0x1000007F
Sheet	0x10000037	0x1000006D	0x10000088
Record	0x10000037	0x1000006D	0x1000007E
OPL	0x10000037	0x1000006D	0x10000085
Data	0x10000050	0x1000006D	0x10000086
Agenda	0x10000050	0x1000006D	0x10000084
Sketch	0x10000037	0x1000006D	0x1000007D

The two Alignment fields ensure that the offset for the start of the following field is a multiple of 4 bytes.

RFSV32_GET_DRIVE_LIST

Bytes	2	2
Data	0x13	Operation ID

Reply:

Bytes	2	2	4	26
Data	0x11	Operation ID	Status code	Drive list

Read the status of all drives.

A single byte is returned for each drive letter A: to Z:.

RFSV32_VOLUME

Bytes	2	2	4
Data	0x14	Operation ID	Drive

Reply:

Bytes	2	2	4	4	4	4	4	4	4	4	4	4	4	n
Data	0x11	Operation ID	Status code	Media type	Battery status	Drive attributes	Media attributes	UID	Size low	Size high	Free low	Free high	Volume label length	Volume label

Read information about a single device.

The Drive is the number of the device, from 0 for A: to 25 for Z:.

The Media type may be one of the following:

Media type	Description
0	Not present
1	Not a known type
2	Floppy disk
3	Hard disk
4	CD-ROM
5	RAM
6	Flash disk
7	ROM
8	Remote

The Battery status may be one of the following:

Battery status	Description
0	Dead
1	Very low
2	Low
3	Good

The Drive attributes consists of the following flags:

Drive attribute	Description
0x01	Local
0x02	ROM
0x04	Redirected
0x08	Substituted
0x10	Internal
0x20	Removable

The Media attributes consists of the following flags:

Media attribute	Description
0x01	Variable size
0x02	Dual density
0x04	Formattable
0x08	Write protected

The Size low and Size high fields combine to give the 64 bit total size, and the Free low and Free high fields combine to give the 64 bit remaining free space on the device.

Unlike the other commands, the length of the Volume label string is specified by the 4 byte Volume label length.

RFSV32_SET_VOLUME_LABEL

Bytes	2	2	4	2 + n
Data	0x15	Operation ID	Drive	Volume label

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Set the Volume label of a device.

The Drive is the number of the device, from 0 for A: to 25 for Z:.

RFSV32_OPEN_FILE

Bytes	2	2	4	2 + n
Data	0x16	Operation ID	Mode	File name

Reply:

Bytes	2	2	4	4
Data	0x11	Operation ID	Status code	Handle

Open File name for reading or writing via the returned Handle.

The Mode consists of one of the following sharing types:

Mode	Description
0x0000	Exclusive access
0x0001	Share for read access
0x0002	Share for any access

combined with one of these stream types:

Mode	Description
0x0000	Open as a binary stream
0x0020	Open as a text stream

and any of the following flags:

0X0200

Open for read and write access

RFSV32_TEMP_FILE

Bytes	2	2	4	2 + n
Data	0x17	Operation ID	Mode	File name

Reply:

Bytes	2	2	4	4	2 + n
Data	0x11	Operation ID	Status code	Handle	Opened name

Create a new file with a unique file name for reading or writing via the returned Handle.

See RFSV32_OPEN_FILE for a description of the possible Mode values.

The actual name of the file opened is returned as Opened name.

RFSV32_READ_FILE

Bytes	2	2	4	4
Data	0x18	Operation ID	Handle	Length

Reply:

Bytes	2	2	4	n
Data	0x11	Operation ID	Status code	Data

Read Length bytes from the file identified by Handle.

The reply contains the Length bytes of data read.

RFSV32_WRITE_FILE

Bytes	2	2	4	n
Data	0x19	Operation ID	Handle	Data

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Write Data to the file identified by Handle.

The number of bytes is not explicitly specified; this is inferred from the size of the frame.

RFSV32_SEEK_FILE

Bytes	2	2	4	4	4
Data	0x1a	Operation ID	Seek offset	Handle	Sense

Reply:

Bytes	2	2	4	4
Data	0x11	Operation ID	Status code	New offset

Position the sequential file pointer for the file specified by Handle.

The interpretation of the signed New offset value depends on the Sense specified:

Sense	Description
0x0001	Absolute position from the start of the file
0x0002	Offset from the current position
0x0003	Offset from the end of the file
0x0004	Read the current position without changing it
0x0005	Set
0x0006	Rewind

The value of the sequential file pointer after the seek is returned as New offset.

RFSV32_DELETE

Bytes	2	2	2 + n
Data	0x1b	Operation ID	File name

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Delete File name.

RFSV32_REMOTE_ENTRY

Bytes	2	2	2 + n
Data	0x1c	Operation ID	File name

Reply:

Bytes	2	2	4	4	4	4	4	4	4	4	4	4	n	0 to 3	m
Data	0x11	Operation ID	Status code	Short name length	Attributes	Size	Modified low	Modified high	UID 1	UID 2	UID 3	Long name length	Long name	Alignment	Short name

Read details about File name.

See RFSV32_READ_DIR for a description of the returned values.

RFSV32_FLUSH

Bytes	2	2	4
Data	0x1d	Operation ID	Handle

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Flush to disk any cached data for the file specified by Handle.

RFSV32_SET_SIZE

Bytes	2	2	4	4
Data	0x1e	Operation ID	Handle	Size

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Set the length of the file specified by Handle to Size bytes.

RFSV32_RENAME

Bytes	2	2	2 + n	2 + m
Data	0x1f	Operation ID	Source name	Destination name

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Rename Source name to Destination name.

RFSV32_MK_DIR_ALL

Bytes	2	2	2 + n
Data	0x20	Operation ID	Directory name

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Create a new directory called Directory name.

RFSV32_RM_DIR

Bytes	2	2	2 + n
Data	0x21	Operation ID	Directory name

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Delete the directory called Directory name.

RFSV32_SET_ATT

Bytes	2	2	4	4	2 + n
Data	0x22	Operation ID	Set	Clear	File name

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Set the Set attributes and clear the Clear attributes of File name.

See RFSV32_READ_DIR for a description of the possible attribute values.

RFSV32_ATT

Bytes	2	2	2 + n
Data	0x23	Operation ID	File name

Reply:

Bytes	2	2	4	4
Data	0x11	Operation ID	Status code	Attributes

Read the attributes for File name.

See RFSV32_READ_DIR for a description of the possible attribute values.

RFSV32_SET_MODIFIED

Bytes	2	2	4	4	2 + n
Data	0x24	Operation ID	Modified low	Modified high	File name

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Set the modification date of File name.

The Modified low and Modified high fields combine to form a 64 bit modification date, specified as the number of micro-seconds since 00:00 on 1st January 1.

RFSV32_MODIFIED

Bytes	2	2	2 + n
Data	0x25	Operation ID	File name

Reply:

Bytes	2	2	4	4	4
Data	0x11	Operation ID	Status code	Modified low	Modified high

Read the modification date of File name.

The Modified low and Modified high fields combine to form a 64 bit modification date, specified as the number of micro-seconds since 00:00 on 1st January 1.

RFSV32_SET_SESSION_PATH

Bytes	2	2	2 + n
Data	0x26	Operation ID	Directory name

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Change the current directory to Directory name.

RFSV32_SESSION_PATH

Bytes	2	2
Data	0x27	Operation ID

Reply:

Bytes	2	2	4	2 + n
Data	0x11	Operation ID	Status code	Directory name

Read the current directory.

RFSV32_READ_WRITE_FILE

Bytes	2	2	4	4	4
Data	0x28	Operation ID	Length	Destination handle	Source handle

Reply:

Bytes	2	2	4	4
Data	0x11	Operation ID	Status code	Copied

Copy Length bytes from the file identified by Source handle to Destination handle.

The reply contains the Copied number of bytes.

RFSV32_CREATE_FILE

Bytes	2	2	4	2 + n
Data	0x29	Operation ID	Mode	File name

Reply:

Bytes	2	2	4	4
Data	0x11	Operation ID	Status code	Handle

Create a new file called File name for reading or writing via the returned Handle.

See RFSV32_OPEN_FILE for a description of the possible Mode values.

RFSV32_REPLACE_FILE

Bytes	2	2	4	2 + n
Data	0x2a	Operation ID	Mode	File name

Reply:

Bytes	2	2	4	4
Data	0x11	Operation ID	Status code	Handle

Create a new file called File name, overwriting any existing file of the same name, for reading or writing via the returned Handle.

See RFSV32_OPEN_FILE for a description of the possible Mode values.

RFSV32_PATH_TEST

Bytes	2	2	2 + n
Data	0x2b	Operation ID	File name

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Check if File name exists.

RFSV32_LOCK

Bytes	2	2	4	4	4
Data	0x2d	Operation ID	Length	Offset	Handle

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Lock Length bytes starting from Offset of the file identified by Handle to prevent shared access.

RFSV32_UNLOCK should be used to unlock the file.

RFSV32_UNLOCK

Bytes	2	2	4	4	4
Data	0x2e	Operation ID	Length	Offset	Handle

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Unlock Length bytes starting from Offset of the file identified by Handle to allow shared access.

This reverses the action of RFSV32_LOCK.

RFSV32_OPEN_DIR_UID

Bytes	2	2	4	4	4	2 + n
Data	0x2f	Operation ID	UID 1	UID 2	UID 3	File name

Reply:

Bytes	2	2	4	4
Data	0x11	Operation ID	Status code	Hande

Open a Handle to read files that match the wildcarded File name and UID specification.

RFSV32_READ_DIR should be used to read the list of matching files. The description for that command also describes the UID 1, UID 2 and UID 3 fields.

RFSV32_DRIVE_NAME

Bytes	2	2	4
Data	0x30	Operation ID	Drive

Reply:

Bytes	2	2	4	2 + n
Data	0x11	Operation ID	Status code	Volume label

Read the volume label of a device.

The Drive is the number of the device, from 0 for A: to 25 for Z:.

RFSV32_SET_DRIVE_NAME

Bytes	2	2	4	2 + n
Data	0x31	Operation ID	Drive	Volume label

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Set the Volume label of a device.

The Drive is the number of the device, from 0 for A: to 25 for Z:.

RFSV32_REPLACE

Bytes	2	2	2 + n	2 + m
Data	0x32	Operation ID	Source file name	Destination file name

Reply:

Bytes	2	2	4
Data	0x11	Operation ID	Status code

Replace Destination file name with Source file name.

ClipBdServer

The server is registered using a Link Register command with a parameter of CLIPSVR.RSY. The name ClipBdServer is then used in the Connect frame to start the server.

Command Frames

RCLIP_INIT

Bytes	1	2
Data	0x00	Version

Reply:

Bytes	1	2
Data	0x00	Version

Initialise the ClipBdServer. This should be performed before any other operation.

The Version in both the command and reply is currently always 0x0100.

RCLIP_LISTEN

Bytes	1
Data	0x04

Reply (delayed until the clipboard has changed):

Bytes	1
Data	0x00

Wait for the clipboard file to be changed.

Only a single reply will be sent each time that this command is issued. Hence, it must be re-issued after a reply has been received.

Note that the reply is sent for any change to the clipboard file, even if that change was via the PLP connection. Hence, it may be necessary to discard replies if the clipboard is being changed remotely.

RCLIP_NOTIFY

Bytes	1	1
Data	0x08	0x00

Reply:

Bytes	1
Data	0x08

Notify the EPOC device that the clipboard has been modified via the PLP connection. The new clipboard contents can then be pasted into EPOC applications as usual.

Attempting to use this without first modifying the clipboard file results in the server disconnecting.

Clipboard File Format

Text Only File

The UID 1, UID 2 and UID 3 fields indicate that the file contains clipboard data, and always have the values 0x10000037, 0x1000003b and 0x00000000 respectively.

The UID 4 field is a checksum of the preceding fields and always has the value 0x4739d53b for clipboard files.

The Section table offset points to the file offset of the byte containing the Section table length. If the section table is directly appended to the main header, this results in a value of 0x00000014.

The Section table length specifies the number of 4 byte words in the section table. Each entry in the section table comprises of a 4 byte Section type and a 4 byte Section offset. Hence, a clipboard file containing just a single text section has a Section table length of 0x02.

The Section type is 0x10000033 for text.

The Section offset points to the start of the section content. This is 0x0000001d if the main header is immediately followed by the section table, and that is immediately followed by the section data.

The String length is located at the start of the text section contents and specifies the length of the text string in bytes.

The Data section contains the text string followed by a 0x00 byte. The terminating NUL character is not included in the String length field.

Special Characters

EPOC Code		Description
6	0x06	New paragraph
7	0x07	New line
8	0x08	Hard page break
9	0x09	Tab
10	0x0a	Unbreakable tab
11	0x0b	Hard hyphen
12	0x0c	Soft hyphen
15	0x0f	Visible space
16	0x10	Hard space

WPRT Server

The server is registered using a Link Register command with a parameter of SYS$WPRT. The name "SYS$WPRT.*" is then used in the Connect frame to start the server.

Command Frames

WPRT_LEVEL

Bytes	1	1	1
Data	0x00	Major version	Minor version

Reply:

Bytes	1	1	1
Data	Status code	Major version	Minor version

Exchange WPRT version numbers.

The Status code is an EPOC status code, indicating whether the specified version number was acceptable.

All existing implementations have the Major version and the Minor version set to 2 and 0 respectively.

This commands should be used once, immediately after the connction to the server has been established.

WPRT_DATA

Bytes	1
Data	0xf0

Reply:

Bytes	1	1	4	n
Data	Last packet	Last page	Page length	Data

or:

Bytes	1	n
Data	Last packet	Data

Read printer data.

The first form of the reply is used for the first packet of a page, and the second form is used for all other packets.

The Last packet fields indicate whether the packet is the last one in a particular print job:

Last packet	Description
0x2A	Not the last packet
0xFF	This packet contains end of print job

The Last page field is only present in the first packet for a particular page. It indicates whether the current page is the last in the print job:

Last packet	Description
0x2A	Not the last page
0xFF	This page is last of print job

The Page length field is also only present in the first packet for a particular page. It specifies the length in bytes of the data associate with the current page, i.e. the cumulative length of the Data field in the current reply and successive replies corresponding to the same page.

The Data field contains the byte stream of printer data. The maximum supported packet length is 2048 bytes, corresponding to a maximum length for this field of 2042 or 2047 bytes for the two reply formats respectively.

WPRT_CANCEL

Bytes	1
Data	0xf1

Cancel the current print job.

The reply returns any data already pending, in the same format as for WPRT_DATA.

WPRT_STOP

Bytes	1
Data	0xff

Terminate the WPRT server.

No reply is sent.

Print Data Format

The start of a print job is indicated by a fake page consisting of the following fifteen bytes:

Bytes	15
Data	0x2a 0x2a 0x09 0x00 0x00 0x00 0x82 0x2e 0x00 0x00 0xc6 0x41 0x00 0x00 0x00

This sequence is the only way to detect that a previous job has been cancelled.

All other pages begin with the following eight bytes:

Bytes	8
Data	0xe8 0x03 0x00 0x00 0xe8 0x03 0x00 0x00

This is followed by a sequence of primitives, identified by their first byte. Unless otherwise specified, all measurements are in twips (1/1440 inch), with positions specified relative to the top-left corner of the page. Strings are not NUL terminated.

WPRT_START

Start of a major section of the page.

The least significant two bits of the Section field encode the section being started:

Section & 0x03	Description
0x00	Header
0x01	Body
0x02	Footer
0x03

The remainder of the Section field, i.e. Section >> 2, is the current page number. s the both the type of section being started and the current page number.

This primitive resets the graphics context to the default settings of:

• Drawing mode 0x20, i.e. pen and brush colours are used unmodified.
• No clipping rectangle set.
• Pen is black, solid, and a single pixel wide.
• Null brush selected.
• No text font selected.

WPRT_END

End of the page.

WPRT_SET_DRAW_MODE

Set the drawing mode.

Mode specifies how the pen and brush colours are combined with the current "screen" colour. It can be one of the following values:

Mode	Description	Action
0x01	Use the inverse of the current screen colour (ignoring the pen and brush colours)	~screen
0x02	Bitwise xor the pen and brush colours with the current screen colour	colour ^ screen
0x03	Invert the pen and brush colours and bitwise xor with the current screen colour	~colour ^ screen
0x04	Bitwise or the pen and brush colours with the current screen colour	colour | screen
0x05	Bitwise or the pen and brush colours with the inverse of the current screen colour	colour | ~screen
0x08	Bitwise and the pen and brush colours with the current screen colour	colour & screen
0x09	Bitwise and the pen and brush colours with the inverse of the current screen colour	colour & ~screen
0x14	Invert the pen and brush colours and bitwise or with the current screen colour.	~colour | screen
0x15	Invert the pen and brush colours and bitwise or with the inverse of the current screen colour	~colour | ~screen
0x18	Invert the pen and brush colours and bitwise and with the current screen colour	~colour & screen
0x19	Invert the pen and brush colours and bitwise and with the inverse of the current screen colour	~colour & ~screen
0x20	Use both the pen and brush colour as they are	colour
0x30	Invert the pen and brush colours	~colour

The default mode is 0x20, and in practice this is almost always the mode used. It should also be used for line and shape drawing when a wide pen is selected, to avoid undesired effects at line joins.

WPRT_SET_CLIPPING_RECT

Set a clipping rectangle.

The Left, Top, Right and Bottom fields specify the rectangle to which following text and graphics primitives should be clipped.

The default clipping rectangle covers the whole page, and is restored by the WPRT_START and WPRT_CANCEL_CLIPPING_RECT primitives.

WPRT_CANCEL_CLIPPING_RECT

Cancel the clipping rectangle.

This primitive resets any clipping rectange set by WPRT_SET_CLIPPING_RECT; clipping reverts back to the whole page.

WPRT_PRIMITIVE_06

The purpose of this primitive is not known.

The Boolean field appears to always have the value 0x00000000 or 0x00000001, suggesting that it is enabling or disabling some feature.

WPRT_USE_FONT

Set the font face and style.

The Length field specifies the length in bytes of the following Font face string. This may be encoded as either one or two bytes, as indicated by the least significant bit:

Length & 0x01	Bytes	Value
0	1	(n << 2) | 2
1	2	(n << 3) | 5

The Font face specifies the name of the font.

The Screen font is the number of the bitmap font used to render text on screen:

Screen font	Font face	Description
0x00	Swiss	Used for bullets, same as 0x02
0x01	Arial	Proportional, sans serif
0x02	Courier New	Monospaced
0x03	Times New Roman	Proportional, serif

The Base size is the font size before any superscript or subscript effects have been applied.

The Style consists of a combination of the following flags:

Style	Description
0x00000001	Italic
0x00000002	Bold
0x00000004	Superscript
0x00000008	Subscript

The Actual size pecifies the actual size of the font after any superscript or subscript effects have been applied. This is typically either 100% or 60% of the Base size.

The Baseline field indicates the offset of the font baseline with respect to the normal baseline position. This is positive for subscript or negative for superscript.

The font is used for all subsequently draw text. The default is no font selected.

WPRT_DISCARD_FONT

Discard the current font.

This indicates that the font selected by a preceding WPRT_USE_FONT is no longer required.

WPRT_SET_UNDERLINE_STYLE

Control underlining.

The Enable parameter sets the state of underlining for all subsequently draw text:

Enable	Description
0x00	Underlining disabled
0x01	Underlining enabled

WPRT_SET_STRIKETHROUGH_STYLE

Control strikethrough.

The Enable parameter sets the state of strikethrough for all subsequently drawn text:

Enable	Description
0x00	Strikethrough disabled
0x01	Strikethrough enabled

WPRT_LINE_FEED

Start a new line of text.

This primitive is always preceded by WPRT_CARRIAGE_RETURN, and does not appear to affect the rendering process.

WPRT_CARRIAGE_RETURN

Return to the left margin.

This primitive is always followed by WPRT_LINE_FEED, and does not appear to affect the rendering process.

WPRT_SET_PEN_COLOUR

Set the pen colour.

The Red, Green and Blue fields specify the corresponding components of the colour. The following grey scale values are usually used:

Red	Green	Blue	Description
0x00	0x00	0x00	Black
0x55	0x55	0x55	Dark grey
0xaa	0xaa	0xaa	Light grey
0xff	0xff	0xff	White

The pen colour is used in accordance with the current drawing mode to draw lines, the outlines of filled shapes, and text. The default pen colour is black.

WPRT_SET_PEN_STYLE

Set the pen style.

The Style parameter sets the line drawing style for the pen:

Style	Description	Pattern
0x00	The pen does not draw
0x01	A solid line	-----------
0x02	A dotted line	. . . . . .
0x03	A dashed line	- - - - - -
0x04	A line of alternating dashes and dots	- . - . - .
0x05	A line of alternating single dashes and pairs of dots	- . . - . .

The default pen style is 0x01, and in practice this is almost always the style used.

The dotted and dashed lines are only used for straight lines (including the outline of straight-sided filled shapes). They may be rendered as thin lines, regardless of the current pen thickness. The pattern should be continued for all consecutively drawn straight lines.

The pen style is used to draw lines and the outlines of filled shapes.

WPRT_SET_PEN_SIZE

Set the pen size.

The Width and Height specify the line drawing size for the pen in screen pixels. For printing, a scale factor of 10 twips per pixel gives acceptable results.

The default pen size is a single pixel. Lines with a thickness greater than one pixel should be rendered with rounded ends, using drawing mode 0x20 (regardless of the current drawing mode).

The pen thickness is used to draw lines and the outlines of filled shapes. A thickness of zero does not draw.

WPRT_SET_BRUSH_COLOUR

Set the brush colour.

The Red, Green and Blue fields specify the corresponding components of the colour. See WPRT_SET_PEN_COLOUR for a list of the common grey scale values.

The brush colour is used in accordance with the current drawing mode for filling shapes and the background of text boxes. The default brush colour is white.

WPRT_SET_BRUSH_STYLE

Set the brush style.

The Style parameter sets the fill drawing style for the brush:

Style	Description
0x00	Null brush (no effect)
0x01	Solid brush
0x02	Patterned brush
0x03	Vertical hatch brush
0x04	Diagonal hatch brush (bottom left to top right)
0x05	Horizontal hatch brush
0x06	Rearward diagonal hatch brush (top left to bottom right)
0x07	Square cross hatch (horizontal and vertical)
0x08	Diamond cross hatch (both diagonals)

The default brush style is 0x00, which results in only the outline of fillable shapes being drawn.

WPRT_PRIMITIVE_17

The purpose of this primitive is not known.

The Left and Top fields appear to have the same value as the corresponding fields in the preceding WPRT_SET_CLIPPING_RECT primitive.

WPRT_DRAW_LINE

Draw a straight line between two points.

The Horizontal start and Vertical start fields specify the position of one end of the line.

The Horizontal end and Vertical end fields specify the position of the other end of the line.

The line should be rendered using the current pen settings.

WPRT_PRIMITIVE_1B

The purpose of this primitive is not known.

WPRT_DRAW_ELLIPSE

Draw and fill an ellipse.

The Left, Top, Right and Bottom fields specify the position of the bounding rectangle that the ellipse fits within. If the pen is larger than a single pixel then the size of the ellipse is correspondingly reduced; the thick outline fits entirely within the bounding box.

The interior of the ellipse should be filled based on the current brush settings, and the outline drawn using the current pen settings.

WPRT_DRAW_RECT

Draw and fill a rectangle.

The Left, Top, Right and Bottom fields specify the position of corresponding sides of the rectangle.

The interior of the rectangle should be filled based on the current brush settings, and the outline drawn using the current pen settings.

WPRT_DRAW_POLYGON

Draw and fill a polygon.

The Vertices value specifies the number of coordinate pairs that follow.

The Vertical and Horizontal field pairs each specify the location of a single vertex.

The Fill rule specifies how the polygon should be filled:

Fill rule	Description
0x00	Only fill areas with odd winding numbers
0x01	Fill areas with window numbers greater than zero

The interior of the polygon, as defined by the specified winding rule, should be filled based on the current brush settings. The outline of the polygon should be drawn using the current pen settings.

WPRT_DRAW_BITMAP_RECT

Draw a bitmap in a rectangle.

The Left, Top, Right and Bottom fields specify the rectangle that the bitmap should be stretched to fit.

The Data length is the number of the bytes from the start of this field to the end of the Pixel data, i.e n + 0x28.

The Data offset is the offset in bytes from the start of the Data length field to the start of the Pixel data, i.e. 0x28.

The Pixel width and Pixel height values are the size of the bitmap in dots.

The Raw width and Raw height fields are usually zero, but may be used to indicate the original size of the bitmap.

The Display mode indicates the palette and number of bits of Pixel data for each dot in the bitmap:

Encoding	Description
0x00000000	Uncompressed
0x00000001	Run Length Encoded (RLE)
0x00000000	None
0x00000001	1bpp, black and white
0x00000002	2bpp, 4 greys
0x00000003	4bpp, 16 greys
0x00000004	8bpp, 256 greys
0x00000005	4bpp, 16 colours
0x00000006	8bpp, 256 colours
0x00000007	16bpp, 64k colours
0x00000008	32bpp, 16M colours
0x00000009	RGB
0x0000000a	4k colours

The Encoding indicates whether the Pixel data is compressed: