Psion Link Protocol

Version 1.18, 18-Jul-07
by Alexander Thoukydides (alex@thouky.co.uk)

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 SIBO and EPOC operating systems use a proprietary serial protocol, called the Psion Link Protocol (PLP), to allow remote access to their filesystems and to permit synchronization. This document attempts to provide sufficient information to allow the implementation of clients that communicate with SIBO or EPOC devices via the PLP.

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

History

RevisionDateAuthorDescription
1.1818-Jul-07Alexander ThoukydidesAdded standard names and other uses for the CRC algorithm.
1.1722-Aug-02Alexander ThoukydidesCorrected details of Connection Termination Frame and Disconnection Frame.
1.1631-Mar-02Alexander ThoukydidesCorrected some details of the WPRT print data format and NCP_GET_MACHINE_INFO parameters.
1.1502-Mar-02Alexander ThoukydidesAdded some details of the WPRT print data format.
1.1405-Feb-02Alexander ThoukydidesAdded information on the WPRT server.
1.1330-Jun-01Alexander ThoukydidesReplaced CRC table with algorithm to generate it.
Improved the GENCSERV server description.
1.1227-Jun-01Alexander ThoukydidesAdded more details of Ericsson R380 variant.
1.1117-Jun-01Alexander ThoukydidesAdded some details of Ericsson R380 variant.
Improved clipboard and CRC descriptions.
1.1010-Jun-01Alexander ThoukydidesModified clipboard description to fit the rest of the document better.
1.0910-Jun-01Fritz ElfertAdded description of Clipboard server and clipboard data.
1.0808-Jun-01Alexander ThoukydidesCorrected sense parameter for RFSV16_FSEEK and RFSV32_SEEK_FILE.
1.0730-Jan-01Alexander ThoukydidesCorrected parameters for RFSV32_READ_WRITE_FILE and added description of missing RFSV16_FDIRREAD parameter.
1.0609-Oct-00Alexander ThoukydidesAdded note that the EPOC variant of the data link layer is multi-windowed.
1.0528-Jul-00Alexander ThoukydidesAdded command line length parameter to NCP_GET_CMD_LINE response.
1.0402-Jun-00Alexander ThoukydidesReleased under version 1.1 of the GNU Free Documentation License.
1.0321-Apr-00Alexander ThoukydidesCorrected HTML
Updated email address.
Added URL for latest version of this document.
1.0223-Jan-00Alexander ThoukydidesAdded details for NCP_SET_TIME and NCP_GET_MACHINE_INFO.
1.0122-Dec-99Alexander ThoukydidesAdded descriptions for most RFSV server commands.
1.0009-Dec-99Alexander ThoukydidesFirst draft.
No descriptions for RFSV server commands.

Disclaimer

This document is supplied "as is"; no warranty, express or implied, of the merchantability of this document or its fitness for any particular purpose is given. In no circumstances shall the author, or any provider or distributor of this document, be liable for any damage, loss of profits, or any indirect or consequential loss arising out of the use or misuse of any information or particular in this document.

All trademarks are acknowledged.

Acknowledgements

The information contained within this document was collated from many different sources, including (but not restricted to):

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

The PLP consists of a stack of layers that can be mapped onto the layers of the Open Systems Interconnection model:

OSI layerEPOC nameDescription
7Applicationn/a
6PresentationLINK, RPCS, RFSV etcMultiple servers, each providing a related set of services
5SessionNCPMultiplexing of multiple client-server communications channels with flow control
4Transportn/a
3Networkn/a
2Data linkLinkSynchronization, error detection and recovery
1PhysicalRS-232

Conventions

Unless otherwise specified the following conventions apply:

Physical Layer

At the lowest level, the PLP uses standard RS-232 for the physical layer. Depending on the exact devices being used, a special cable or converter may be required.

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

The data link layer provides a simple byte orientated protocol to allow reliable communication between two devices. It is a connection orientated protocol with clear phases of link establishment, information transfer, and link termination. An acknowledgement and retry strategy is used to guarantee error free exchange of data.

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

All data is transmitted within frames of the following format:

Bytes1111n112
DataSYNDLESTXContSeqDataDLEETXCRC

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

Bytes11111n112
DataSYNDLESTXCont(Seq & 7) | 8Seq >> 3DataDLEETXCRC

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

The following special characters are used within the protocol:

NameValueDescription
STX0x02Start of frame
ETX0x03End of frame
EOT0x04A stuffed ETX character
DLE0x10Field delimiter within a frame
DC10x11Not protocol characters, but stuffed (Ericsson R380)
DC30x13
SYN0x16Synchronize start of frame
ETB0x17Synchronize 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 characterStuffed character sequenceVariants
NameValueNamesValues
DLE0x10DLE DLE0x10 0x10SIBO and EPOC
ETX0x03DLE EOT0x10 0x04EPOC
DC10x11DLE Space0x10 0x20Ericsson R380 only
DC30x13DLE !0x10 0x21

The reverse process is performed by the receiver.

Cyclic Redundancy Check

The standard x16 + x12 + x5 + 1 polynomial is used with an initial remainder of zero to generate a 16 bit CRC. This is the CRC-16-CCITT algorithm (also known as CRC-CCITT), as used by the XMODEM, X.25, V.41, Bluetooth, PPP and IrDA protocols. It is calculated over the Cont/Seq and Data bytes prior to any stuffing.

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];

The CRC value should be initialised to 0 before any bytes are processed. It may be necessary to use unsigned values to prevent implementation dependant problems on systems with 16 bit integers.

Timers

Two timer events are used to implement timeouts:

TimerPeriod
Re-transmissionBaud rate dependant
InactivityApplication 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:

ComponentDescription
Baud Rate Bits FactorThe 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 FactorA 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 FactorAn 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

There are four major types of frame or Protocol Data Unit (PDU):

ContSeqNameDescription
0Sequence number of last valid Data_Pdu receivedAck_PduUsed to complete handshaking during connection phase, and to acknowledge Data_Pdu frames.
10Disc_PduUsed to terminate a connection.
1Disc_Req_PduFirst disconnect in a handshaked disconnection. Not currently used.
20Req_PduUsed during connection phase to request a connection.
1 ... 3 (use 1)Req_Req_PduFirst request in connection establishment. EPOC variant of protocol only.
4 ... 6 (use 4)Req_Con_PduResponding request in connection establishment. EPOC variant of protocol only.
3Next sequence numberData_PduData 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

The connection sequence is slightly different with the SIBO and EPOC variants of the protocol. The original SIBO implementation suffers from a modem echo problem, whereby the data link layer can establish a connection with itself if serial data is echoed back; this was corrected in the EPOC implementation.

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

The client-server connection sequence is initiated by the client:

From clientFrom serverDescription
Req_PduConnection requested by client
Req_PduConnection accepted by server
Ack_PduConnection established

The peer to peer connection sequence is very similar:

From device 1From device 2Description
Req_PduReq_PduBoth devices request a connection
Ack_PduAck_PduBoth 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

The client-server connection sequence is initiated by the client:

From clientFrom serverDescription
Req_Req_PduConnection requested by client
Req_Con_PduConnection request confirmed by server
Ack_PduConnection established

The peer to peer connection sequence is very similar:

From device 1From device 2Description
Req_Req_PduReq_Req_PduBoth devices request a connection
Req_Con_PduReq_Con_PduBoth devices confirm the connection request
Ack_PduAck_PduBoth 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

With a little care it is possible to support both variants of the protocol within a single state machine. The modulo value for sequence numbers can then be selected once the protocol variant has been identified.

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 SIBO variant of the data link layer is single windowed, i.e. only a single acknowledgement can be outstanding at any time. This guarantees that only a single transmit buffer and a single receive buffer is required. Beware though, that due to the asynchronous nature of data transfer, the data transmission and acknowledgement in each direction may be interleaved.

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 1From device 2Description
Data_PduData sent
Ack_PduData 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

No handshaking occurs during the PLP disconnection sequence, so there is a risk of one device disconnecting without the other noticing. A fix was planned for the EPOC variant of the protocol, but does not appear to have been implemented.

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

Either device may initiate the disconnection:

From device 1From device 2Description
Disc_PduInitiator requests a disconnection

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

EPOC Disconnection

The following disconnection sequence was proposed to fix the problem described above, but does not appear to be implemented. Either device may initiate the disconnection:

From device 1From device 2Description
Disc_Req_PduInitiator requests a disconnection
Disc_PduDisconnection 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 section describes a sample state machine that implements both the SIBO and EPOC variants of the data link layer. A peer to peer connection is attempted, but client-server connections should also be supported.

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

Five states are used:

StateDescription
Idle_StateDisconnected
Idle_Req_StateReq_Req_Pdu sent, awaiting Req_Con_Pdu response
Idle_Ack_StateReq_Con_Pdu sent, awaiting Ack_Pdu response
Data_StateConnected, no acknowledgement pending
Data_Ack_StateData_Pdu sent, awaiting Ack_Pdu acknowledgement

Events

The following events are processed by the state machine:

EventSourceDescription
Ack_RxReceived frameAck_Pdu (acknowledge) received
Disc_RxDisc_Pdu or Disc_Req_Pdu (disconnect) received
Req_RxReq_Pdu (connection request) received
Req_Req_RxReq_Req_Pdu (handshaked connection request) received
Req_Con_RxReq_Con_Pdu (handshaked connection accepted) received
Data_RxData_Pdu (data) received
ConnectLocal clientConnection requested
DisconnectDisconnection requested
WriteData to transmit
TimeoutTimerRe-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

The following variables are required to store additional state:

VariableDescriptionDefault
EnabledIs the link enabledFALSE
VariantThe protocol variant: SIBO or EPOCSIBO
RetriesNumber of retries remaining0
Seq_TxLast sequence number for transmitted data frames0
Seq_RxLast sequence number for received data frames0
MagicMagic number for this devicePseudo-random

State Tables

The following tables detail the actions taken for each event, with a separate table for each state.

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
EventConditionActionNext state
Ack_RxAlwaysNo actionIdle_State
Disc_RxAlwaysNo actionIdle_State
Req_RxEnabledVariant = SIBO
Send Req_Con with Magic as data
Start re-transmission timer
Retries = 4
Idle_Ack_State
elseNo actionIdle_State
Req_Req_RxEnabledVariant = EPOC
Send Req_Con with Magic as data
Start re-transmission timer
Retries = 4
Idle_Ack_State
elseNo actionIdle_State
Req_Con_RxAlwaysNo actionIdle_State
Data_RxAlwaysNo actionIdle_State
ConnectAlwaysEnabled = TRUEIdle_State
DisconnectAlwaysEnabled = FALSEIdle_State
WriteAlwaysError - not connectedIdle_State
TimeoutEnabledSend Req_Req_Pdu
Start re-transmission timer
Idle_Req_State
elseNo actionIdle_State
Idle_Req_State
EventConditionActionNext state
Ack_RxEnabledSeq_Tx = sequence number
Seq_Rx = 0
Start inactivity timer
Connection established
Data_State
elseNo actionIdle_Req_State
Disc_RxAlwaysReset()Idle_State
Req_RxEnabledVariant = SIBO
SeqTx = 0
Seq_Rx = 0
Send Ack_Pdu with sequence number Seq_Rx
Start inactivity timer
Connection established
Data_State
elseNo actionIdle_Req_State
Req_Req_RxEnabledVariant = EPOC
Send Req_Con with Magic as data
Start re-transmission timer
Retries = 4
Idle_Ack_State
elseNo actionIdle_Req_State
Req_Con_RxAlwaysNo actionIdle_Req_State
Data_RxAlwaysNo actionIdle_Req_State
ConnectAlwaysError - already enabledIdle_Req_State
DisconnectAlwaysEnabled = FALSE
Send Disc_Pdu
Reset()
Idle_State
WriteAlwaysError - not connectedIdle_Req_State
TimeoutEnabledTry next baud rate if attempting auto-baud rate identification
Send Req_Req_Pdu
Start re-transmission timer
Idle_Req_State
elseReset()Idle_State
Idle_Ack_State
EventConditionActionNext state
Ack_RxEnabledSeq_Tx = sequence number
Seq_Rx = 0
Start inactivity timer
Connection established
Data_State
elseNo actionIdle_Ack_State
Disc_RxAlwaysReset()Idle_State
Req_RxEnabledVariant = SIBO
SeqTx = 0
Seq_Rx = 0
Send Ack_Pdu with sequence number Seq_Rx
Start inactivity timer
Connection established
Data_State
elseNo actionIdle_Ack_State
Req_Req_RxEnabledVariant = EPOC
Send Req_Con with Magic as data
Start re-transmission timer
Retries = 4
Idle_Ack_State
elseNo actionIdle_Ack_State
Req_Con_RxEnabled and (magic number != Magic)Variant = EPOC
Seq_Tx = 0
Seq_Rx = 0
Send Ack_Pdu with sequence number Seq_Rx
Start inactivity timer
Connection established
Data_State
elseNo actionIdle_Ack_State
Data_RxAlwaysNo actionIdle_Ack_State
ConnectAlwaysError - already enabledIdle_Ack_State
DisconnectAlwaysEnabled = FALSE
Send Disc_Pdu
Reset()
Idle_State
WriteAlwaysError - not connectedIdle_Ack_State
TimeoutEnabled and (0 < Retries)Retries = Retries - 1
Send Req_Con with Magic as data
Idle_Ack_State
elseResetIdle_State
Data_State
EventConditionActionNext state
Ack_RxAlwaysNo actionData_State
Disc_RxAlwaysReset()
Connection terminated
Idle_State
Req_RxAlwaysReset()
Connection terminated
Idle_State
Req_Req_RxAlwaysReset()
Connection terminated
Idle_State
Req_Con_RxAlwaysReset()
Connection terminated
Idle_State
Data_Rxsequence number == Inc(Seq_Rx)Seq_Rx = Inc(Seq_Rx)
Send Ack_Pdu with sequence number Seq_Rx
Start inactivity timer
Data_State
elseSend Ack_Pdu with sequence number Seq_RxData_State
ConnectAlwaysError - already enabledData_State
DisconnectAlwaysEnabled = FALSE
Send Disc_Pdu
Reset()
Connection terminated
Idle_State
WriteAlwaysSeq_Tx = Inc(Seq_Tx)
Send Data_Pdu with sequence number Seq_Tx
Start re-transmission timer
Retries = 8
Data_Ack_State
TimeoutAlwaysSend Disc_Pdu
Reset()
Connection terminated
Idle_State
Data_Ack_State
EventConditionActionNext state
Ack_Rxsequence number == Seq_TxStart inactivity timerData_State
elseNo actionData_Ack_State
Disc_RxAlwaysReset()
Connection terminated
Idle_State
Req_RxAlwaysReset()
Connection terminated
Idle_State
Req_Req_RxAlwaysReset()
Connection terminated
Idle_State
Req_Con_RxAlwaysReset()
Connection terminated
Idle_State
Data_Rxsequence number == Inc(Seq_Rx)Seq_Rx = Inc(Seq_Rx)
Send Ack_Pdu with sequence number Seq_Rx
Start re-transmission timer
Data_Ack_State
elseSend Ack_Pdu with sequence number Seq_RxData_Ack_State
ConnectAlwaysError - already enabledData_Ack_State
DisconnectAlwaysEnabled = FALSE
Send Disc_Pdu
Reset()
Connection terminated
Idle_State
WriteAlwaysError - connection busyData_Ack_State
Timeout0 < RetriesRetries = Retries - 1
Send Data_Pdu with sequence number Seq_Tx
Start re-transmission timer
Data_Ack_State
elseSend Disc_Pdu
Reset()
Connection terminated
Idle_State

PLP Mode on Erisson R380

The Ericsson R380 incorporates a modem, so it is necessary to reconfigure the serial port for PLP use.

Starting PLP

An "AT" command is used to start the PLP connection:

From hostFrom R380Description
0x41 0x54 0x2a 0x45 0x53 0x59 0x4e 0x3d 0x31 0x0dRequest PLP mode: AT*ESYN=1
0x41 0x54 0x2a 0x45 0x53 0x59 0x4e 0x3d 0x31 0x0dEcho command: AT*ESYN=1
0x0d 0x0a 0x4f 0x4b 0x0d 0x0aAcknowledge command: OK
0x11 0x11Start PLP operation

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

Ending PLP

Following the Req_Req_Pdu the Erisson R380 sends a single DC1 character and returns to "AT" mode.

Session Layer

The Network Control Protocol (NCP) provides multiplexed communication channels between multiple clients and servers. It also supports fragmentation and recombination to allow arbitrary sized messages to be transmitted via data link layer frames that have a maximum permitted data field size.

Channels

Numbered channels are used to address frames to the appropriate process. The SIBO variant supports 8 simultaneous channels, but the EPOC variant increases this to 256. Channel 0 is always used for the NCP control channel, and channel 1 is always used for the special LINK channel used to register additional servers. Other channels are dynamically allocated as required.

Frame Formats

The general format for an NCP frame is:

Bytes111n
DataDestination channelSource channelFrame typeData

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

Command frames are always send to channel 0. The interpretation of the source channel is defined below for each command.
XOFF Frame
Bytes111
Data0x00Channel0x01

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

XON Frame
Bytes111
Data0x00Channel0x02

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

Connect Frame
Bytes111n
Data0x00Client channel0x03Server name

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
Bytes11111
Data0x00Server channel0x04Client channelStatus code

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
Bytes111
Data0x00Server channel0x05

The specified server has disconnected all clients.

NCP Information Frame
Bytes11114
Data0x000x000x06VersionID

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:

VersionDescription
0x02SIBO (old)
0x03SIBO (new)
0x06EPOC (ER3)
0x10EPOC (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
Bytes1111
Data0x00Client channel0x07Server channel

The specified client has disconnected from the specified server.

NCP Termination Frame
Bytes111
Data0x00Channel0x08

The NCP has shut down.

Data Frames

As described above, the NCP fragments and recombines messages to fit within the data link layer's maximum data field size. Zero or more Partial frames are sent followed by a Complete frame to transmit the full message.
Complete Frame
Bytes111n
DataDestination channelSource channel0x01Data

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
Bytes111n
DataDestination channelSource channel0x02Data

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

Connection Sequence

The following general sequence of frames are exchanged after a connection has been established:

From device 1From device 2
NCP Information frameNCP Information frame
Connect frame for LINK.*Connect frame for LINK.*
Connect frame for other serversConnect frame for other servers
Connect Response framesConnect 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

There may not be an opportunity to perform a controlled disconnection sequence, for example if the cable is physically disconnected, but the ideal sequence would be:

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

Named servers provide a set of related services, such as remote file system access. All operations consist of a command sent by the client and a reply from the server.

LINK Server

The LINK server is closely associated with the NCP; it is always connected before any other servers, always uses channel 1, and allows allows additional servers to be registered. The name "LINK.*" is used in the Connect frame to start the LINK server.

Command Frames

LINK only supports a single command.
Link Register Command
Command:

Bytes12n
Data0x00Operation IDServer name

or:

Bytes12n114
Data0x00Operation IDServer nameMajor versionMinor versionBuild

Reply:

Bytes1222n
Data0x01Operation IDStatus 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 clientFrom 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

The RPCS server provides Remote Command Services. This supports general operations, such as launching and terminating processes. The name "SYS$RPCS.*" is used in the Connect frame to start the RPCS server. However, as mentioned above, it may be necessary to use the Link Register command to register the server first. On some SIBO devices, the RPCS server is not present by default, and is normally downloaded as M:\SYS$RPCS.IMG by either RCOM or PsiWin.

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

All RPCS command frames generate a response frame. The first byte of the response is a result code; this is always a SIBO status code, even with the EPOC variant of the protocol. However, the SIBO variant uses the SIBO character set for any text strings, and the EPOC variant uses the EPOC character set.
NCP_QUERY_SUPPORT
Command:

Bytes111
Data0x00Major versionMinor version

Reply:
Bytes111
DataStatus codeMajor versionMinor 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
Command:

Bytes11281n
Data0x01Program nameArguments lengthArguments

Reply:
Bytes1
DataStatus 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
Command:

Bytes11
Data0x02Drive letter

Reply:
Bytes1Repeated fields:
nimi
DataStatus codeProgram nameArguments

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

Bytes1n
Data0x03Program name

Reply:
Bytes1
DataStatus 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
Command:

Bytes1n
Data0x04Program name

Reply:
Bytes1
DataStatus 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
Command:

Bytes1n
Data0x05Device name

Reply:
Bytes122
DataStatus codeHandleCount

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

Bytes12
Data0x06Handle

Reply:
Bytes1
DataStatus 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
Command:

Bytes1n
Data0x07Device name

Reply:
Bytes14
DataStatus codeUnique ID

Read the Unique ID for the specified removable device.

NCP_GET_OWNER_INFO
Command:

Bytes1
Data0x08

Reply:
Bytes1n
DataStatus codeOwner information (not NUL terminated)

Read the user information.

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

NCP_GET_MACHINE_TYPE
Command:

Bytes1
Data0x09

Reply:
Bytes12
DataStatus codeMachine type

Read the type of the remote machine.

The following Machine type numbers are currently used:

Machine typeDescription
0x00Unknown
0x01PC
0x02MC
0x03HC
0x04Series 3
0x05Series 3a, 3c, or 3mx
0x06Workabout
0x07Sienna
0x08Series 3c
0x20Series 5
0x21WinC

Be careful; some of these values are untested.

NCP_GET_CMD_LINE
Command:

Bytes1n
Data0x0aProcess name

Reply:
Bytes1n
DataStatus codeProgram name
or:
Bytes1n1m
DataStatus codeProgram namemCommand line (not NUL terminated)
or:
Bytes1n256 - nm40 - m
DataStatus codeProgram namemCommand 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
Command:

Bytes1n
Data0x0bFile name

Reply:
Bytes1n
DataStatus codeProcess name

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

NCP_GET_MACHINE_INFO
Command:

Bytes1
Data0x64

Reply:
Bytes14112816444444444444444444444444444444444488
DataStatus codeMachine typeMajor ROM versionMinor ROM versionROM buildReservedMachine nameDisplay widthDisplay heightMachine UID lowMachine UID highTime lowTime highCountry codeUTC offsetDSTDST zoneMain battery inserted lowMain battery inserted highMain battery statusMain battery used lowMain battery used highMain battery currentMain battery used powerMain battery voltageMain battery max voltageBackup battery statusBackup battery voltageBackup battery maximum voltageExternal powerExternal power used lowExternal power used high???RAM sizeROM sizeRAM maximum freeRAM freeRAM disk sizeRegistry sizeROM reprogrammableLanguageReserved

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:

LanguageDescription
0x00Test
0x01UK English
0x02French
0x03German
0x04Spanish
0x05Italian
0x06Swedish
0x07Danish
0x08Norwegian
0x09Finnish
0x0AAmerican English
0x0BSwiss French
0x0CSwiss German
0x0DPortuguese
0x0ETurkish
0x0FIcelandic
0x10Russian
0x11Hungarian
0x12Dutch
0x13Belgian Flemish
0x14Australian English
0x15Belgian French
0x16Austrian German
0x17New Zealand English
0x18International French
0x19Czech
0x1ASlovak
0x1BPolish
0x1CSlovenian
0x1DTaiwan Chinese
0x1EHong Kong Chinese
0x1FRPC Chinese
0x20Japanese
0x21Thai

NCP_CLOSE_HANDLE
Command:

Bytes12
Data0x65Handle

Reply:
Bytes1
DataStatus code

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

NCP_REG_OPEN_ITER
Command:

Bytes1???
Data0x66???

Reply:
Bytes1???
DataStatus code???

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

NCP_REG_READ_ITER
Command:

Bytes1???
Data0x67???

Reply:
Bytes1???
DataStatus code???

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

NCP_REG_WRITE
Command:

Bytes1???
Data0x68???

Reply:
Bytes1???
DataStatus code???

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

NCP_REG_READ
Command:

Bytes1???
Data0x69???

Reply:
Bytes1???
DataStatus code???

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

NCP_REG_DELETE
Command:

Bytes1???
Data0x6a???

Reply:
Bytes1???
DataStatus code???

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

NCP_SET_TIME
Command:

Bytes1444444
Data0x6bTime lowTime highCountry codeUTC offsetDSTDST zone

Reply:
Bytes1
DataStatus 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 zoneDescription
0x00000000None
0x00000001European
0x00000002Northern
0x00000004Southern
0x40000000Home

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

Bytes1???
Data0x6c???

Reply:
Bytes1???
DataStatus code???

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

NCP_CONFIG_READ
Command:

Bytes1???
Data0x6d???

Reply:
Bytes1???
DataStatus code???

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

NCP_CONFIG_WRITE
Command:

Bytes1???
Data0x6e???

Reply:
Bytes1???
DataStatus code???

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

NCP_QUERY_OPEN
Command:

Bytes11
Data0x6fDrive letter

Reply:
Bytes12
DataStatus codeHandle

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

Bytes12
Data0x70Handle

Reply:
Bytes1Repeated fields:
nimi
DataStatus codeProgram nameArguments

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

Bytes1
Data0xff

Reply:
Bytes1
DataStatus code

Quit the RPCS server.

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

RFSV Server

The RFSV server provides Remote File Services. This provides a remote interface that behaves similarly to local file accesses; files must be opened before they can be read or written, and a sequential file pointer is maintained for each open file. A current directory is also maintained, allowing use of relative file names.

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

All RFSV command frames have the following general format:

Bytes22n
DataReason codenRequest 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:

Bytes222n
Data0x2an + 2Status codeReply 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
Command:

Bytes222n
Data0x00Frame lengthModeFile name

Reply:

Bytes2222
Data0x2aFrame lengthStatus codeHandle

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

The Mode consists of one of the following operations:

ModeDescription
0x0000Open an existing file
0x0001Create a new file
0x0002Create a new file, or truncate an existing file to zero length
0x0003Append to an existing file
0x0004Create a new file with a unique name

combined with one of these stream types:

ModeDescription
0x0000Open as a binary stream
0x0010Open as a text stream
0x0020Open as a binary record
0x0030Open as a directory record
0x0040Open as a format
0x0050Open as a device list
0x0060Open as a node list

and any of the following flags:

ModeDescription
0x0100Open for read and write access
0x0200Open for random access
0x0400Open for sharing

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

RFSV16_FCLOSE
Command:

Bytes222
Data0x02Frame lengthHandle

Reply:

Bytes222
Data0x2aFrame lengthStatus code

Close the Handle previously opened using RFSV16_FOPEN or RFSV16_OPENUNIQUE.

RFSV16_FREAD
Command:

Bytes2222
Data0x04Frame lengthHandleLength

Reply:

Bytes222n
Data0x2aFrame lengthStatus codeData

Read Length bytes from the file identified by Handle.

The reply contains the Length bytes of data read.

RFSV16_FDIRREAD
Command:

Bytes222
Data0x06Frame lengthHandle

Reply:

Bytes2222Repeated fields:
22444ni
Data0x2aFrame lengthStatus codeBuffer lengthVersionAttributesSizeModifiedReservedFile 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:

AttributeDescription
0x0001Writeable
0x0002Hidden
0x0004System
0x0008Volume label
0x0010Directory
0x0020Modified
0x0100Readable
0x0200Executable
0x0400Stream
0x0800Text

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

Bytes222
Data0x08Frame lengthHandle

Reply:

Bytes22222244n216
Data0x2aFrame lengthStatus codeVersionMedia typeRemovableSizeFreeVolume labelBattery statusReserved

Read information about the device specified by Handle.

The Media type consists of a type:

Media typeDescription
0x0000Not a known type
0x0001Floppy disk
0x0002Hard disk
0x0003Flash disk
0x0004RAM
0x0005ROM
0x0006Write protected

combined with any of the following flags:

Media typeDescription
0x0800Formattable
0x1000Dual density
0x2000Internal
0x4000Dynamic
0x8000Compressible

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 typeDescription
0Dead
1Very low
2Low
3Good

RFSV16_FWRITE
Command:

Bytes222n
Data0x0aFrame lengthHandleData

Reply:

Bytes222
Data0x2aFrame lengthStatus 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
Command:

Bytes22242
Data0x0cFrame lengthHandleSeek offsetSense

Reply:

Bytes2224
Data0x2aFrame lengthStatus codeNew 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:

SenseDescription
0x0001Absolute position from the start of the file
0x0002Offset from the current position
0x0003Offset from the end of the file
0x0004Read the current position without changing it
0x0005Set
0x0006Rewind

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

RFSV16_FFLUSH
Command:

Bytes222
Data0x0eFrame lengthHandle

Reply:

Bytes222
Data0x2aFrame lengthStatus code

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

RFSV16_FSETEOF
Command:

Bytes2224
Data0x10Frame lengthHandleSize

Reply:

Bytes222
Data0x2aFrame lengthStatus code

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

RFSV16_RENAME
Command:

Bytes22nm
Data0x12Frame lengthSource nameDestination name

Reply:

Bytes222
Data0x2aFrame lengthStatus code

Rename Source name to Destination name.

RFSV16_DELETE
Command:

Bytes22n
Data0x14Frame lengthFile name

Reply:

Bytes222
Data0x2aFrame lengthStatus code

Delete File name.

RFSV16_FINFO
Command:

Bytes22n
Data0x16Frame lengthFile name

Reply:

Bytes22222444
Data0x2aFrame lengthStatus codeVersionAttributesSizeModifiedReserved

Read details about File name.

See RFSV16_FDIRREAD for a description of the returned values.

RFSV16_SFSTAT
Command:

Bytes2222n
Data0x18Frame lengthSetMaskFile name

Reply:

Bytes222
Data0x2aFrame lengthStatus 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
Command:

Bytes22n
Data0x1aFrame lengthFile name

Reply:

Bytes222n
Data0x2aFrame lengthStatus codeParsed name

Parse File name to give Parsed name.

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

RFSV16_MKDIR
Command:

Bytes22n
Data0x1cFrame lengthDirectory name

Reply:

Bytes222
Data0x2aFrame lengthStatus code

Create a new directory called Directory name.

RFSV16_OPENUNIQUE
Command:

Bytes222n
Data0x1eFrame lengthModeFile name

Reply:

Bytes2222n
Data0x2aFrame lengthStatus codeHandleOpened 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
Command:

Bytes22n
Data0x20Frame lengthDevice name

Reply:

Bytes22222244n216
Data0x2aFrame lengthStatus codeVersionMedia typeRemovableSizeFreeVolume labelBattery statusReserved

Read the status of the device specified by Device name.

See RFSV16_FDEVICEREAD for details of the returned values.

RFSV16_PATHTEST
Command:

Bytes22n
Data0x22Frame lengthFile name

Reply:

Bytes222
Data0x2aFrame lengthStatus code

Check if File name specifies a valid path.

RFSV16_STATUSSYSTEM
Command:

Bytes22n
Data0x24Frame lengthFile system

Reply:

Bytes222222
Data0x2aFrame lengthStatus codeVersionTypeFormattable

Read the status of the specified File system.

RFSV16_CHANGEDIR
Command:

Bytes22n
Data0x26Frame lengthDirectory name

Reply:

Bytes222
Data0x2aFrame lengthStatus code

Change the current directory to Directory name.

RFSV16_SFDATE
Command:

Bytes224n
Data0x28Frame lengthModifiedFile name

Reply:

Bytes222
Data0x2aFrame lengthStatus 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

All RFSV command frames have the following general format:

Bytes22n
DataReason codeOperation IDRequest data

All RFSV reply frames have the following general format:

Bytes224n
Data0x11Operation IDStatus codeReply 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
Command:

Bytes224
Data0x01Operation IDHandle

Reply:

Bytes224
Data0x11Operation IDStatus 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
Command:

Bytes2242 + n
Data0x10Operation IDAttributesFile name

Reply:

Bytes2244
Data0x11Operation IDStatus codeHandle

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

Bytes224
Data0x12Operation IDHandle

Reply:

Bytes224Repeated fields:
0 to 3444444444ni0 to 3mi
Data0x11Operation IDStatus codeAlignmentShort name lengthAttributesSizeModified lowModified highUID 1UID 2UID 3Long name lengthLong nameAlignmentShort 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:

AttributeDescription
0x0001Read only
0x0002Hidden
0x0004System
0x0010Directory
0x0020Archive
0x0040Volume label
0x0080Normal
0x0100Temporary
0x0800Compressed

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:

ApplicationUID 1UID 2UID 3
Word0x100000370x1000006D0x1000007F
Sheet0x100000370x1000006D0x10000088
Record0x100000370x1000006D0x1000007E
OPL0x100000370x1000006D0x10000085
Data0x100000500x1000006D0x10000086
Agenda0x100000500x1000006D0x10000084
Sketch0x100000370x1000006D0x1000007D

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

Bytes22
Data0x13Operation ID

Reply:

Bytes22426
Data0x11Operation IDStatus codeDrive list

Read the status of all drives.

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

RFSV32_VOLUME
Command:

Bytes224
Data0x14Operation IDDrive

Reply:

Bytes2244444444444n
Data0x11Operation IDStatus codeMedia typeBattery statusDrive attributesMedia attributesUIDSize lowSize highFree lowFree highVolume label lengthVolume 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 typeDescription
0Not present
1Not a known type
2Floppy disk
3Hard disk
4CD-ROM
5RAM
6Flash disk
7ROM
8Remote

The Battery status may be one of the following:

Battery statusDescription
0Dead
1Very low
2Low
3Good

The Drive attributes consists of the following flags:

Drive attributeDescription
0x01Local
0x02ROM
0x04Redirected
0x08Substituted
0x10Internal
0x20Removable

The Media attributes consists of the following flags:

Media attributeDescription
0x01Variable size
0x02Dual density
0x04Formattable
0x08Write 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
Command:

Bytes2242 + n
Data0x15Operation IDDriveVolume label

Reply:

Bytes224
Data0x11Operation IDStatus 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
Command:

Bytes2242 + n
Data0x16Operation IDModeFile name

Reply:

Bytes2244
Data0x11Operation IDStatus codeHandle

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

The Mode consists of one of the following sharing types:

ModeDescription
0x0000Exclusive access
0x0001Share for read access
0x0002Share for any access

combined with one of these stream types:

ModeDescription
0x0000Open as a binary stream
0x0020Open as a text stream

and any of the following flags:

0X0200Open for read and write access

RFSV32_TEMP_FILE
Command:

Bytes2242 + n
Data0x17Operation IDModeFile name

Reply:

Bytes22442 + n
Data0x11Operation IDStatus codeHandleOpened 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
Command:

Bytes2244
Data0x18Operation IDHandleLength

Reply:

Bytes224n
Data0x11Operation IDStatus codeData

Read Length bytes from the file identified by Handle.

The reply contains the Length bytes of data read.

RFSV32_WRITE_FILE
Command:

Bytes224n
Data0x19Operation IDHandleData

Reply:

Bytes224
Data0x11Operation IDStatus 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
Command:

Bytes22444
Data0x1aOperation IDSeek offsetHandleSense

Reply:

Bytes2244
Data0x11Operation IDStatus codeNew 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:

SenseDescription
0x0001Absolute position from the start of the file
0x0002Offset from the current position
0x0003Offset from the end of the file
0x0004Read the current position without changing it
0x0005Set
0x0006Rewind

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

RFSV32_DELETE
Command:

Bytes222 + n
Data0x1bOperation IDFile name

Reply:

Bytes224
Data0x11Operation IDStatus code

Delete File name.

RFSV32_REMOTE_ENTRY
Command:

Bytes222 + n
Data0x1cOperation IDFile name

Reply:

Bytes224444444444n0 to 3m
Data0x11Operation IDStatus codeShort name lengthAttributesSizeModified lowModified highUID 1UID 2UID 3Long name lengthLong nameAlignmentShort name

Read details about File name.

See RFSV32_READ_DIR for a description of the returned values.

RFSV32_FLUSH
Command:

Bytes224
Data0x1dOperation IDHandle

Reply:

Bytes224
Data0x11Operation IDStatus code

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

RFSV32_SET_SIZE
Command:

Bytes2244
Data0x1eOperation IDHandleSize

Reply:

Bytes224
Data0x11Operation IDStatus code

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

RFSV32_RENAME
Command:

Bytes222 + n2 + m
Data0x1fOperation IDSource nameDestination name

Reply:

Bytes224
Data0x11Operation IDStatus code

Rename Source name to Destination name.

RFSV32_MK_DIR_ALL
Command:

Bytes222 + n
Data0x20Operation IDDirectory name

Reply:

Bytes224
Data0x11Operation IDStatus code

Create a new directory called Directory name.

RFSV32_RM_DIR
Command:

Bytes222 + n
Data0x21Operation IDDirectory name

Reply:

Bytes224
Data0x11Operation IDStatus code

Delete the directory called Directory name.

RFSV32_SET_ATT
Command:

Bytes22442 + n
Data0x22Operation IDSetClearFile name

Reply:

Bytes224
Data0x11Operation IDStatus 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
Command:

Bytes222 + n
Data0x23Operation IDFile name

Reply:

Bytes2244
Data0x11Operation IDStatus codeAttributes

Read the attributes for File name.

See RFSV32_READ_DIR for a description of the possible attribute values.

RFSV32_SET_MODIFIED
Command:

Bytes22442 + n
Data0x24Operation IDModified lowModified highFile name

Reply:

Bytes224
Data0x11Operation IDStatus 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
Command:

Bytes222 + n
Data0x25Operation IDFile name

Reply:

Bytes22444
Data0x11Operation IDStatus codeModified lowModified 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
Command:

Bytes222 + n
Data0x26Operation IDDirectory name

Reply:

Bytes224
Data0x11Operation IDStatus code

Change the current directory to Directory name.

RFSV32_SESSION_PATH
Command:

Bytes22
Data0x27Operation ID

Reply:

Bytes2242 + n
Data0x11Operation IDStatus codeDirectory name

Read the current directory.

RFSV32_READ_WRITE_FILE
Command:

Bytes22444
Data0x28Operation IDLengthDestination handleSource handle

Reply:

Bytes2244
Data0x11Operation IDStatus codeCopied

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

The reply contains the Copied number of bytes.

RFSV32_CREATE_FILE
Command:

Bytes2242 + n
Data0x29Operation IDModeFile name

Reply:

Bytes2244
Data0x11Operation IDStatus codeHandle

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

Bytes2242 + n
Data0x2aOperation IDModeFile name

Reply:

Bytes2244
Data0x11Operation IDStatus codeHandle

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

Bytes222 + n
Data0x2bOperation IDFile name

Reply:

Bytes224
Data0x11Operation IDStatus code

Check if File name exists.

RFSV32_LOCK
Command:

Bytes22444
Data0x2dOperation IDLengthOffsetHandle

Reply:

Bytes224
Data0x11Operation IDStatus 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
Command:

Bytes22444
Data0x2eOperation IDLengthOffsetHandle

Reply:

Bytes224
Data0x11Operation IDStatus 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
Command:

Bytes224442 + n
Data0x2fOperation IDUID 1UID 2UID 3File name

Reply:

Bytes2244
Data0x11Operation IDStatus codeHande

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

Bytes224
Data0x30Operation IDDrive

Reply:

Bytes2242 + n
Data0x11Operation IDStatus codeVolume 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
Command:

Bytes2242 + n
Data0x31Operation IDDriveVolume label

Reply:

Bytes224
Data0x11Operation IDStatus 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
Command:

Bytes222 + n2 + m
Data0x32Operation IDSource file nameDestination file name

Reply:

Bytes224
Data0x11Operation IDStatus code

Replace Destination file name with Source file name.

ClipBdServer

The ClipBdServer handles notification about changes to the C:\System\Data\Clpboard.cbd file that is used to hold the clipboard contents on EPOC devices. This enables CopyAnywhere style functionality to be implemented.

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

The ClipBdServer implements very few commands:
RCLIP_INIT
Command:

Bytes12
Data0x00Version

Reply:

Bytes12
Data0x00Version

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

Bytes1
Data0x04

Reply (delayed until the clipboard has changed):

Bytes1
Data0x00

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

Bytes11
Data0x080x00

Reply:

Bytes1
Data0x08

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

The clipboard file has a similar format to other EPOC data files, consisting of sections and linked lists. Only sufficient details are included here to read or write text. For a more complete description, including how objects and graphics are handled, see Frodo Looijaard's file format description at http://huizen.dds.nl/~frodol/psiconv/html/Index.html.
Text Only File
Bytes444441444n
DataUID 1UID 2UID 3UID 4Section table offsetSection table lengthSection typeSection offsetString lengthData

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
Some special characters are used within EPOC text. The following should be adequate to support manipulation of clipboard text:

EPOC CodeDescription
60x06New paragraph
70x07New line
80x08Hard page break
90x09Tab
100x0aUnbreakable tab
110x0bHard hyphen
120x0cSoft hyphen
150x0fVisible space
160x10Hard space

WPRT Server

The WPRT server allows EPOC device to print via the attached device. It provides relatively simple transfer of printer data grouped by page.

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

Most WPRT command frames generate a response frame.
WPRT_LEVEL
Command:

Bytes111
Data0x00Major versionMinor version

Reply:
Bytes111
DataStatus codeMajor versionMinor 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
Command:

Bytes1
Data0xf0

Reply:
Bytes114n
DataLast packetLast pagePage lengthData
or:

Bytes1n
DataLast packetData

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 packetDescription
0x2ANot the last packet
0xFFThis 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 packetDescription
0x2ANot the last page
0xFFThis 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
Command:

Bytes1
Data0xf1

Cancel the current print job.

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

WPRT_STOP
Command:

Bytes1
Data0xff

Terminate the WPRT server.

No reply is sent.

Print Data Format

Some of the data structures within the printer data have similarities with those of other EPOC data files, but there are also subtle (and not so subtle) differences. As with the clipboard file described above, Frodo Looijaard's file format description may be useful.

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

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

Bytes8
Data0xe8 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
Bytes14
Data0x00Section

Start of a major section of the page.

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

Section & 0x03Description
0x00Header
0x01Body
0x02Footer
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:

WPRT_END
Bytes1
Data0x01

End of the page.

WPRT_SET_DRAW_MODE
Bytes11
Data0x03Mode

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:

ModeDescriptionAction
0x01Use the inverse of the current screen colour (ignoring the pen and brush colours)~screen
0x02Bitwise xor the pen and brush colours with the current screen colourcolour ^ screen
0x03Invert the pen and brush colours and bitwise xor with the current screen colour~colour ^ screen
0x04Bitwise or the pen and brush colours with the current screen colourcolour | screen
0x05Bitwise or the pen and brush colours with the inverse of the current screen colourcolour | ~screen
0x08Bitwise and the pen and brush colours with the current screen colourcolour & screen
0x09Bitwise and the pen and brush colours with the inverse of the current screen colourcolour & ~screen
0x14Invert the pen and brush colours and bitwise or with the current screen colour.~colour | screen
0x15Invert the pen and brush colours and bitwise or with the inverse of the current screen colour~colour | ~screen
0x18Invert the pen and brush colours and bitwise and with the current screen colour~colour & screen
0x19Invert the pen and brush colours and bitwise and with the inverse of the current screen colour~colour & ~screen
0x20Use both the pen and brush colour as they arecolour
0x30Invert 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
Bytes14444
Data0x04LeftTopRightBottom

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
Bytes1
Data0x05

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
Bytes114
Data0x060x00Boolean

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
Bytes11 or 2n12444
Data0x07LengthFont faceScreen fontBase sizeStyleActual sizeBaseline

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 & 0x01BytesValue
01(n << 2) | 2
12(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 fontFont faceDescription
0x00SwissUsed for bullets, same as 0x02
0x01ArialProportional, sans serif
0x02Courier NewMonospaced
0x03Times New RomanProportional, 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:

StyleDescription
0x00000001Italic
0x00000002Bold
0x00000004Superscript
0x00000008Subscript

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
Bytes1
Data0x08

Discard the current font.

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

WPRT_SET_UNDERLINE_STYLE
Bytes11
Data0x09Enable

Control underlining.

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

EnableDescription
0x00Underlining disabled
0x01Underlining enabled

WPRT_SET_STRIKETHROUGH_STYLE
Bytes11
Data0x0aEnable

Control strikethrough.

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

EnableDescription
0x00Strikethrough disabled
0x01Strikethrough enabled

WPRT_LINE_FEED
Bytes144
Data0x0b??????

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
Bytes144
Data0x0c0x00 0x00 0x00 0x000x00 0x00 0x00 0x00

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
Bytes1111
Data0x0dRedGreenBlue

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:

RedGreenBlueDescription
0x000x000x00Black
0x550x550x55Dark grey
0xaa0xaa0xaaLight grey
0xff0xff0xffWhite

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
Bytes11
Data0x0eStyle

Set the pen style.

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

StyleDescriptionPattern
0x00The pen does not draw 
0x01A solid line-----------
0x02A dotted line. . . . . .
0x03A dashed line- - - - - -
0x04A line of alternating dashes and dots- . - . - .
0x05A 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
Bytes144
Data0x0fWidthHeight

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
Bytes1111
Data0x10RedGreenBlue

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
Bytes11
Data0x11Style

Set the brush style.

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

StyleDescription
0x00Null brush (no effect)
0x01Solid brush
0x02Patterned brush
0x03Vertical hatch brush
0x04Diagonal hatch brush (bottom left to top right)
0x05Horizontal hatch brush
0x06Rearward diagonal hatch brush (top left to bottom right)
0x07Square cross hatch (horizontal and vertical)
0x08Diamond cross hatch (both diagonals)

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

WPRT_PRIMITIVE_17
Bytes144
Data0x17LeftTop

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
Bytes14444
Data0x19Horizontal startVertical startHorizontal endVertical end

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
Bytes144
Data0x1b0x00 0x00 0x00 0x00???

The purpose of this primitive is not known.

WPRT_DRAW_ELLIPSE
Bytes14444
Data0x1fLeftTopRightBottom

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
Bytes14444
Data0x20LeftTopRightBottom

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
Bytes14Repeated fields:1
44
Data0x23VerticesHorizontalVerticalFill rule

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 ruleDescription
0x00Only fill areas with odd winding numbers
0x01Fill 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
Bytes144444444444444n
Data0x25LeftTopRightBottomData lengthData offsetPixel widthPixel heightRaw widthRaw heightDisplay mode0x00 0x00 0x00 0x000x00 0x00 0x00 0x00EncodingPixel data

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:

EncodingDescription
0x00000000Uncompressed
0x00000001Run Length Encoded (RLE)
0x00000000None
0x000000011bpp, black and white
0x000000022bpp, 4 greys
0x000000034bpp, 16 greys
0x000000048bpp, 256 greys
0x000000054bpp, 16 colours
0x000000068bpp, 256 colours
0x0000000716bpp, 64k colours
0x0000000832bpp, 16M colours
0x00000009RGB
0x0000000a4k colours

The Encoding indicates whether the Pixel data is compressed:

EncodingDescription
0x00000000Uncompressed
0x00000001Run Length Encoded (RLE)

The Pixel data contains the colour information for each dot within the bitmap.

If RLE compression has been used, as indicated by the Encoding, then this is organised as a sequence of marker/data pairs. A marker byte indicates the interpretation of the following data bytes:

MarkerDescription
0x00 to 0x7fSingle data byte follows, to be repeated Marker + 1 times
0x80 to 0xff0x100 - Marker bytes of uncompressed data follow

The Pixel data (after RLE decompression if required) is organised as a sequence of rows, from the top to the bottom of the image. Each row contains the colour of the pixels, packed as indicated by Display mode, with the least significant bits of each byte being the left-most pixel. Each row is padded with dummy pixels to be an exact multiple of 4 bytes long.

The bitmap data does not appear to include any palette information. For 1bpp black and white bitmaps the pixel values map to:

PixelRedGreenBlueDescription
00x000x000x00Black
10xff0xff0xffWhite

For 2bpp grey bitmaps the pixel values map to:

PixelRedGreenBlueDescription
00x000x000x00Black
10x550x550x55Dark grey
20xaa0xaa0xaaLight grey
30xff0xff0xffWhite

WPRT_DRAW_BITMAP_SRC
Bytes144444444444444n4444
Data0x26LeftTopRightBottomData lengthData offsetPixel widthPixel heightRaw widthRaw heightDisplay mode0x00 0x00 0x00 0x000x00 0x00 0x00 0x00EncodingPixel dataSource leftSource topSource rightSource bottom

Draw a bitmap in a rectangle from a source rectangle.

This is identical to WPRT_DRAW_BITMAP_RECT, other than the addition of sixteen extra bytes at the end. See the description of that primitive for an explanation of the common fields.

The Source left, Source top, Source right and Source bottom fields specify the rectangular section of the bitmap, specified in pixels from the top-left corner, that should be stretched to fit the destination rectangle.

WPRT_DRAW_TEXT
Bytes11 or 2n44
Data0x27LengthTextLeftBaseline

Plot a text label.

The Length field specifies the length in bytes of the following Text string. See WPRT_USE_FONT for a description of the encoding used.

The Text field is the text to be plotted.

The Left and Baseline fields specify the start position of the text baseline.

The text should be plotted using the current font and pen settings. The background should not be filled.

WPRT_DRAW_TEXT_JUSTIFIED
Bytes11 or 2n4444414
Data0x28LengthTextLeftTopRightBottomBaselineAlignmentMargin

Plot a text label.

The Length field specifies the length in bytes of the following Text string. See WPRT_USE_FONT for a description of the encoding used.

The Text field is the text to be plotted.

The Left, Top, Right and Bottom fields specify the rectangle that the text should be justified within.

The Baseline field is believed to encode the baseline position. However, acceptable results can be achieved by placing the baseline at a quarter of the way up the box, offset by the Baseline field of the WPRT_USE_FONT primitive.

The Alignment can be one of the following values:

AlignmentDescription
0x00Left align
0x01Centre align
0x02Right align

The Margin field specifies an offset for the justification position. This is measured from the left edge, except for right aligned text where is it measured from the right edge.

The rectangle should be filled using the current brush settings, or white if no brush colour has been selected. If a null brush is selected the the background should not be filled; the rectangle is for alignment only. The text should be plotted using the current font and pen settings, clipped to inside the rectangle.

GENCSERV Server

The Ericsson R380 includes a server that provides access to the phone's contacts database. Version 2.1 of the vCard specification is used, available from http://www.imc.org/pdi/vcard-21.txt.

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

Note that the server appears always to use NCP channel 0xFC or 0xFD. Attempting to connect using the channel it has allocated fails.

The details of the GENCSERV commands are poorly understood, so are presented here as the byte sequences that are sent and received within the NCP data frames. Note that sending the commands in the wrong sequence can cause the phone to crash, requiring the battery to be removed and refitted. This is likely to trigger a warning that the file system may be corrupt and should be reformatted.

Special Frames

Four special frames are used during initialisation and finalisation.
GENCSERV_INIT_1
Command:

Bytes12
Data0x000x01 0x01

Reply:

Bytes4
Data0x00 0x02 0x00 0x0b

This is the first command send during initialisation.

GENCSERV_INIT_2
Command:

Bytes123
Data0x010x0b 0x63 0x00 0x6d 0x00 0x63 0x00 0x73 0x00 0x65 0x00 0x33 0x00 0x32 0x00 0x2e 0x00 0x64 0x00 0x6c 0x00 0x6c 0x00

Reply:

Bytes9
Data0x00 0x2a 0x18 0x00 0x10 0x95 0x17 0x00 0x10

This is the third command sent during initialisation.

GENCSERV_FINALISE_1
Command:

Bytes1
Data0x02

Reply:

Bytes1
Data0x00

This is the fourth and final command sent during finalisation.

GENCSERV_INIT_3
Command:

Bytes1
Data0x04

Reply:

Bytes1
Data0x00

This is the second command sent during initialisation.

Command Frames

All command frames and their replies have start with a 0x03 byte followed by a reason code, and then nine bytes of constant data:

Bytes119
Data0x03Reason code0x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00

GENCSERV_INIT_4
Command:

Bytes119
Data0x030x000x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00

Reply:

Bytes119
Data0x030x000x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00

This is the fourth command sent during initialisation.

GENCSERV_DELETE
Command:

Bytes119n
Data0x030x060x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00vCards

Reply:

Bytes119n
Data0x030x060x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00vCards

Delete entries.

The vCards field of the command should contain one or more vCards consisting of just the VERSION and UID fields of the entries to delete. These can be discovered by first reading the entry using GENCSERV_READ.

The reply contains a copy of the data from the command.

GENCSERV_ADD
Command:

Bytes119n
Data0x030x070x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00vCards

Reply:

Bytes1194Repeated field:
4
Data0x030x070x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00CountIndex

Add new entries.

The vCards field contains one or more vCards to be added.

The Count field gives the number of entries actually added.

The Index fields give the indeces of the new entries; one for each entry added.

GENCSERV_MODIFY
Command:

Bytes119n
Data0x030x080x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00vCards

Reply:

Bytes1194Repeated field:
4
Data0x030x080x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00CountIndex

Modify existing entries.

The vCards field contains one or more vCards to be modified. These must contain the UID fields from the existing vCards, as returned by GENCSERV_READ.

The Count field gives the number of entries modified.

The Index fields give the indeces of the modified entries; one for each entry that was changed.

GENCSERV_FINALISE_2
Command:

Bytes119
Data0x030x090x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00

Reply:

Bytes1113
Data0x030x090x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00

This is the third command sent during finalisation.

GENCSERV_READ
Command:

Bytes1194Repeated field:
4
Data0x030x0e0x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00CountIndex

Reply:

Bytes119n
Data0x030x0e0x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00vCards

Read entries.

The Count field specifies the number of entries to read.

The Index fields give the indices of the entries to read. The available entries can be found using GENCSERV_INDEX.

The vCards field contains the vCards read.

GENCSERV_CHANGES
Command:

Bytes119444444
Data0x030x0f0x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00YearMonthDayHourMinuteSecond

Reply:

Bytes1194
Data0x030x0f0x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00Changes

Read the number of changes since a particular time.

The Year, Month, Day, Hour, Minute and Second fields specify the time to check against. This would normally be set to the time that the host last synchronized entries with the phone.

The Changes field gives the number of modifications that have been made since the specified time.

GENCSERV_INIT_5
Command:

Bytes1194
Data0x030x100x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x000x14 0x00 0x00 0x00

Reply:

Bytes1194
Data0x030x100x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00Done

This is the seventh command sent during initialisation.

The Ready field is returned as zero when the phone is ready. The sequence of commands GENCSERV_INIT_5, GENCSERV_INIT_7 and GENCSERV_RESET should be repeated in sequence until this happens.

GENCSERV_INDEX
Command:

Bytes1194
Data0x030x110x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00Type

Reply:

Bytes1194Repeated field:
4
Data0x030x110x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00CountIndex

List entries.

The Type field specifies the type of entries to return:

TypeDescription
0x00000000Current
0x00000003Deleted

The vCards field contains one or more vCards to be modified. These must contain the UID fields from the existing vCards, as returned by GENCSERV_READ.

The Count field gives the number of entries of the specified type.

The Index fields give the indeces of the entries; one for each entry found.

GENCSERV_FINALISE_3
Command:

Bytes119
Data0x030x120x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00

Reply:

Bytes1194
Data0x030x120x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x000x00 0x00 0x00 0x00

This is the second command sent during finalisation.

GENCSERV_INIT_6
Command:

Bytes119
Data0x030x150x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00

Reply:

Bytes1194
Data0x030x150x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x000x00 0x00 0x00 0x00

This is the fifth command sent during initialisation.

GENCSERV_INIT_7
Command:

Bytes119
Data0x030x190x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00

Reply:

Bytes119
Data0x030x190x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00

This is the eighth command send during initialisation.

GENCSERV_RESET
Command (initialisation):

Bytes119
Data0x030x1c0x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x00

Reply (initialisation):

Bytes1194
Data0x030x1c0x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x000xb4 0x04 0x00 0x00

Command (finalisation):

Bytes1194
Data0x030x1c0x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x000x14 0x00 0x00 0x00

Reply (finalisation):

Bytes1194
Data0x030x1c0x01 0x00 0x01 0x00 0x00 0x01 0x00 0x00 0x000xb8 0x04 0x00 0x00

This is the ninth command sent during initialisation, and the first command sent during finalisation.

Initialisation

The following sequence of commands need to be performed before any attempt is made to access the contacts:
  1. GENCSERV_INIT_1
  2. GENCSERV_INIT_3
  3. GENCSERV_INIT_2
  4. GENCSERV_INIT_4
  5. GENCSERV_INIT_6
  6. GENCSERV_LAST
  7. GENCSERV_INIT_5
  8. GENCSERV_INIT_7
  9. GENCSERV_RESET
The final three commands listed should be repeated until GENCSERV_INIT_5 returns ready.

Edit Operations

Entries can be read using GENCSERV_INDEX to find the indices and GENCSERV_READ to read the required entries. Entries can be deleted using GENCSERV_DELETE or changes written back with GENCSERV_MODIFY.

Adding a new entry with GENCSERV_ADD does not require the indices to be read first.

Finalisation

The following commands should be sent to cleanly close the contacts list before closing the server connection:
  1. GENCSERV_RESET
  2. GENCSERV_FINALISE_3
  3. GENCSERV_FINALISE_2
  4. GENCSERV_FINALISE_1

Error Codes

Many operations can return a status code. Zero always indicates success; any other value indicates a failure.

Different codes are used by SIBO and EPOC, although the NCP always uses the SIBO codes. The following tables indicate the closest mapping between the two sets of codes.

SIBO Error Codes

The following error codes may be returned by the SIBO servers.

SIBO codeSIBO nameEPOC equivalent
0E_SIBO_NONEE_EPOC_NONE
-1E_SIBO_GEN_FAILE_EPOC_GENERAL
-2E_SIBO_GEN_ARGE_EPOC_ARGUMENT
-3E_SIBO_GEN_OSE_EPOC_GENERAL
-4E_SIBO_GEN_NSUPE_EPOC_NOT_SUPPORTED
-5E_SIBO_GEN_UNDERE_EPOC_UNDERFLOW
-6E_SIBO_GEN_OVERE_EPOC_OVERFLOW
-7E_SIBO_GEN_RANGEE_EPOC_TOTAL_LOSS_OF_PRECISION
-8E_SIBO_GEN_DIVIDEE_EPOC_DIVIDE_BY_ZERO
-9E_SIBO_GEN_INUSEE_EPOC_IN_USE
-10E_SIBO_GEN_NOMEMORYE_EPOC_NO_MEMORY
-11E_SIBO_GEN_NOSEGMENTSE_EPOC_NO_MEMORY
-12E_SIBO_GEN_NOSEME_EPOC_NO_MEMORY
-13E_SIBO_GEN_NOPROCE_EPOC_NO_MEMORY
-14E_SIBO_GEN_OPENE_EPOC_ALREADY_EXISTS
-15E_SIBO_GEN_NOTOPENE_EPOC_NOT_FOUND
-16E_SIBO_GEN_IMAGEE_EPOC_CORRUPT
-17E_SIBO_GEN_RECEIVERE_EPOC_GENERAL
-18E_SIBO_GEN_DEVICEE_EPOC_BAD_DRIVER
-19E_SIBO_GEN_FSYSE_EPOC_DISMOUNTED
-20E_SIBO_GEN_STARTE_EPOC_NOT_READY
-21E_SIBO_GEN_NOFONTE_EPOC_GENERAL
-22E_SIBO_GEN_TOOWIDEE_EPOC_TOO_BIG
-23E_SIBO_GEN_TOOMANYE_EPOC_TOO_BIG
-32E_SIBO_FILE_EXISTE_EPOC_ALREADY_EXISTS
-33E_SIBO_FILE_NXISTE_EPOC_NOT_FOUND
-34E_SIBO_FILE_WRITEE_EPOC_WRITE
-35E_SIBO_FILE_READE_EPOC_ACCESS_DENIED
-36E_SIBO_FILE_EOFE_EPOC_EOF
-37E_SIBO_FILE_FULLE_EPOC_DISK_FULL
-38E_SIBO_FILE_NAMEE_EPOC_BAD_NAME
-39E_SIBO_FILE_ACCESSE_EPOC_ACCESS_DENIED
-40E_SIBO_FILE_LOCKEDE_EPOC_LOCKED
-41E_SIBO_FILE_DEVICEE_EPOC_NOT_READY
-42E_SIBO_FILE_DIRE_EPOC_PATH_NOT_FOUND
-43E_SIBO_FILE_RECORDE_EPOC_BAD_NAME
-44E_SIBO_FILE_RDONLYE_EPOC_ACCESS_DENIED
-45E_SIBO_FILE_INVE_EPOC_CORRUPT
-46E_SIBO_FILE_PENDINGE_EPOC_NOT_READY
-47E_SIBO_FILE_VOLUMEE_EPOC_BAD_NAME
-48E_SIBO_FILE_CANCELE_EPOC_CANCEL
-50E_SIBO_FILE_DISCE_EPOC_DISCONNECTED
-51E_SIBO_FILE_CONNECTE_EPOC_COULD_NOT_CONNECT
-52E_SIBO_FILE_RETRANE_EPOC_TIMED_OUT
-53E_SIBO_FILE_LINEE_EPOC_COMMS_LINE_FAIL
-54E_SIBO_FILE_INACTE_EPOC_TIMED_OUT
-55E_SIBO_FILE_PARITYE_EPOC_COMMS_PARITY
-56E_SIBO_FILE_FRAMEE_EPOC_COMMS_FRAME
-57E_SIBO_FILE_OVERRUNE_EPOC_COMMS_OVERRUN
-58E_SIBO_MDM_CONFAILE_EPOC_GENERAL
-59E_SIBO_MDM_BUSYE_EPOC_GENERAL
-60E_SIBO_MDM_NOANSE_EPOC_GENERAL
-61E_SIBO_MDM_BLACKLISTE_EPOC_GENERAL
-62E_SIBO_FILE_NOTREADYE_EPOC_NOT_READY
-63E_SIBO_FILE_UNKNOWNE_EPOC_UNKNOWN
-64E_SIBO_FILE_DIRFULLE_EPOC_DIR_FULL
-65E_SIBO_FILE_PROTECTE_EPOC_ACCESS_DENIED
-66E_SIBO_FILE_CORRUPTE_EPOC_CORRUPT
-67E_SIBO_FILE_ABORTE_EPOC_ABORT
-68E_SIBO_FILE_ERASEE_EPOC_GENERAL
-69E_SIBO_FILE_INVALIDE_EPOC_CORRUPT

EPOC Error Codes

The following error codes may be returned by the EPOC servers.

EPOC codeEPOC nameSIBO equivalent
0E_EPOC_NONEE_SIBO_NONE
-1E_EPOC_NOT_FOUNDE_SIBO_FILE_NXIST
-2E_EPOC_GENERALE_SIBO_GEN_FAIL
-3E_EPOC_CANCELE_SIBO_FILE_CANCEL
-4E_EPOC_NO_MEMORYE_SIBO_GEN_NOMEMORY
-5E_EPOC_NOT_SUPPORTEDE_SIBO_GEN_NSUP
-6E_EPOC_ARGUMENTE_SIBO_GEN_ARG
-7E_EPOC_TOTAL_LOSS_OF_PRECISIONE_SIBO_GEN_RANGE
-8E_EPOC_BAD_HANDLEE_SIBO_FILE_NXIST
-9E_EPOC_OVERFLOWE_SIBO_GEN_OVER
-10E_EPOC_UNDERFLOWE_SIBO_GEN_UNDER
-11E_EPOC_ALREADY_EXISTSE_SIBO_FILE_EXIST
-12E_EPOC_PATH_NOT_FOUNDE_SIBO_FILE_DIR
-13E_EPOC_DIEDE_SIBO_GEN_FAIL
-14E_EPOC_IN_USEE_SIBO_GEN_INUSE
-15E_EPOC_SERVER_TERMINATEDE_SIBO_GEN_FAIL
-16E_EPOC_SERVER_BUSYE_SIBO_GEN_TOOMANY
-17E_EPOC_COMPLETIONE_SIBO_GEN_FAIL
-18E_EPOC_NOT_READYE_SIBO_FILE_NOTREADY
-19E_EPOC_UNKNOWNE_SIBO_FILE_UNKNOWN
-20E_EPOC_CORRUPTE_SIBO_FILE_CORRUPT
-21E_EPOC_ACCESS_DENIEDE_SIBO_FILE_ACCESS
-22E_EPOC_LOCKEDE_SIBO_FILE_LOCKED
-23E_EPOC_WRITEE_SIBO_FILE_WRITE
-24E_EPOC_DISMOUNTEDE_SIBO_GEN_FSYS
-25E_EPOC_EOFE_SIBO_FILE_EOF
-26E_EPOC_DISK_FULLE_SIBO_FILE_FULL
-27E_EPOC_BAD_DRIVERE_SIBO_GEN_DEVICE
-28E_EPOC_BAD_NAMEE_SIBO_FILE_NAME
-29E_EPOC_COMMS_LINE_FAILE_SIBO_FILE_LINE
-30E_EPOC_COMMS_FRAMEE_SIBO_FILE_FRAME
-31E_EPOC_COMMS_OVERRUNE_SIBO_FILE_OVERRUN
-32E_EPOC_COMMS_PARITYE_SIBO_FILE_PARITY
-33E_EPOC_TIMEOUTE_SIBO_FILE_RETRAN
-34E_EPOC_COULD_NOT_CONNECTE_SIBO_FILE_CONNECT
-35E_EPOC_COULD_NOT_DISCONNECTE_SIBO_FILE_DISC
-36E_EPOC_DISCONNECTEDE_SIBO_FILE_DISC
-37E_EPOC_BAD_LIBRARY_ENTRY_POINTE_SIBO_GEN_FAIL
-38E_EPOC_BAD_DESCRIPTORE_SIBO_GEN_FAIL
-39E_EPOC_ABORTE_SIBO_FILE_ABORT
-40E_EPOC_TOO_BIGE_SIBO_FILE_FULL
-41E_EPOC_DIVIDE_BY_ZEROE_SIBO_GEN_DIVIDE
-42E_EPOC_BAD_POWERE_SIBO_GEN_FAIL
-43E_EPOC_DIR_FULLE_SIBO_FILE_DIRFULL

Character Sets

The SIBO variant of the protocol uses code page 850, but the EPOC variant uses the Windows ANSI (Windows code page 1252) character set. The following table lists the SIBO and EPOC character codes, together with the mapping used by the EPOC variant of the protocol to convert between the two character codes:

CodeSIBOEPOC
CharacterTo EPOCCharacterTo SIBO
00x00NUL (non-printable)00x00NUL (non-printable)00x00
10x01SOH (non-printable)10x01SOH (non-printable)10x01
20x02STX (non-printable)20x02STX (non-printable)20x02
30x03ETX (non-printable)30x03ETX (non-printable)30x03
40x04EOT (non-printable)40x04EOT (non-printable)40x04
50x05ENQ (non-printable)50x05ENQ (non-printable)50x05
60x06ACK (non-printable)60x06ACK (non-printable)60x06
70x07BEL (non-printable)70x07BEL (non-printable)70x07
80x08BS (non-printable)80x08BS (non-printable)80x08
90x09HT (non-printable)90x09HT (non-printable)90x09
100x0aNL (non-printable)100x0aNL (non-printable)100x0a
110x0bVT (non-printable)110x0bVT (non-printable)110x0b
120x0cNP (non-printable)120x0cNP (non-printable)120x0c
130x0dCR (non-printable)130x0dCR (non-printable)130x0d
140x0eSO (non-printable)140x0eSO (non-printable)140x0e
150x0fSI (non-printable)150x0fSI (non-printable)150x0f
160x10DLE (non-printable)160x10DLE (non-printable)160x10
170x11DC1 (non-printable)170x11DC1 (non-printable)170x11
180x12DC2 (non-printable)180x12DC2 (non-printable)180x12
190x13DC3 (non-printable)190x13DC3 (non-printable)190x13
200x14DC4 (non-printable)200x14DC4 (non-printable)200x14
210x15NAK (non-printable)210x15NAK (non-printable)210x15
220x16SYN (non-printable)220x16SYN (non-printable)220x16
230x17ETB (non-printable)230x17ETB (non-printable)230x17
240x18CAN (non-printable)240x18CAN (non-printable)240x18
250x19EM (non-printable)250x19EM (non-printable)250x19
260x1aSUB (non-printable)260x1aSUB (non-printable)260x1a
270x1bESC (non-printable)270x1bESC (non-printable)270x1b
280x1cFS (non-printable)280x1cFS (non-printable)280x1c
290x1dGS (non-printable)290x1dGS (non-printable)290x1d
300x1eRS (non-printable)300x1eRS (non-printable)300x1e
310x1fUS (non-printable)310x1fUS (non-printable)310x1f
320x20 Space320x20 Space320x20
330x21!Exclamation mark330x21!Exclamation mark330x21
340x22"Quotation mark340x22"Quotation mark340x22
350x23#Number sign350x23#Number sign350x23
360x24$Dollar sign360x24$Dollar sign360x24
370x25%Percent sign370x25%Percent sign370x25
380x26&Ampersand380x26&Ampersand380x26
390x27'Apostrophe390x27'Apostrophe390x27
400x28(Left parenthesis400x28(Left parenthesis400x28
410x29)Right parenthesis410x29)Right parenthesis410x29
420x2a*Asterisk420x2a*Asterisk420x2a
430x2b+Plus sign430x2b+Plus sign430x2b
440x2c,Comma440x2c,Comma440x2c
450x2d-Hyphen-minus450x2d-Hyphen-minus450x2d
460x2e.Full stop460x2e.Full stop460x2e
470x2f/Solidus470x2f/Solidus470x2f
480x300Digit zero480x300Digit zero480x30
490x311Digit one490x311Digit one490x31
500x322Digit two500x322Digit two500x32
510x333Digit three510x333Digit three510x33
520x344Digit four520x344Digit four520x34
530x355Digit five530x355Digit five530x35
540x366Digit six540x366Digit six540x36
550x377Digit seven550x377Digit seven550x37
560x388Digit eight560x388Digit eight560x38
570x399Digit nine570x399Digit nine570x39
580x3a:Colon580x3a:Colon580x3a
590x3b;Semicolon590x3b;Semicolon590x3b
600x3c<Less-than sign600x3c<Less-than sign600x3c
610x3d=Equals sign610x3d=Equals sign610x3d
620x3e>Greater-than sign620x3e>Greater-than sign620x3e
630x3f?Question mark630x3f?Question mark630x3f
640x40@Commercial at640x40@Commercial at640x40
650x41ALatin capital letter A650x41ALatin capital letter A650x41
660x42BLatin capital letter B660x42BLatin capital letter B660x42
670x43CLatin capital letter C670x43CLatin capital letter C670x43
680x44DLatin capital letter D680x44DLatin capital letter D680x44
690x45ELatin capital letter E690x45ELatin capital letter E690x45
700x46FLatin capital letter F700x46FLatin capital letter F700x46
710x47GLatin capital letter G710x47GLatin capital letter G710x47
720x48HLatin capital letter H720x48HLatin capital letter H720x48
730x49ILatin capital letter I730x49ILatin capital letter I730x49
740x4aJLatin capital letter J740x4aJLatin capital letter J740x4a
750x4bKLatin capital letter K750x4bKLatin capital letter K750x4b
760x4cLLatin capital letter L760x4cLLatin capital letter L760x4c
770x4dMLatin capital letter M770x4dMLatin capital letter M770x4d
780x4eNLatin capital letter N780x4eNLatin capital letter N780x4e
790x4fOLatin capital letter O790x4fOLatin capital letter O790x4f
800x50PLatin capital letter P800x50PLatin capital letter P800x50
810x51QLatin capital letter Q810x51QLatin capital letter Q810x51
820x52RLatin capital letter R820x52RLatin capital letter R820x52
830x53SLatin capital letter S830x53SLatin capital letter S830x53
840x54TLatin capital letter T840x54TLatin capital letter T840x54
850x55ULatin capital letter U850x55ULatin capital letter U850x55
860x56VLatin capital letter V860x56VLatin capital letter V860x56
870x57WLatin capital letter W870x57WLatin capital letter W870x57
880x58XLatin capital letter X880x58XLatin capital letter X880x58
890x59YLatin capital letter Y890x59YLatin capital letter Y890x59
900x5aZLatin capital letter Z900x5aZLatin capital letter Z900x5a
910x5b[Left square bracket910x5b[Left square bracket910x5b
920x5c\Reverse solidus920x5c\Reverse solidus920x5c
930x5d]Right square bracket930x5d]Right square bracket930x5d
940x5e^Circumflex accent940x5e^Circumflex accent940x5e
950x5f_Low line950x5f_Low line950x5f
960x60`Grave accent960x60`Grave accent960x60
970x61aLatin small letter A970x61aLatin small letter A970x61
980x62bLatin small letter B980x62bLatin small letter B980x62
990x63cLatin small letter C990x63cLatin small letter C990x63
1000x64dLatin small letter D1000x64dLatin small letter D1000x64
1010x65eLatin small letter E1010x65eLatin small letter E1010x65
1020x66fLatin small letter F1020x66fLatin small letter F1020x66
1030x67gLatin small letter G1030x67gLatin small letter G1030x67
1040x68hLatin small letter H1040x68hLatin small letter H1040x68
1050x69iLatin small letter I1050x69iLatin small letter I1050x69
1060x6ajLatin small letter J1060x6ajLatin small letter J1060x6a
1070x6bkLatin small letter K1070x6bkLatin small letter K1070x6b
1080x6clLatin small letter L1080x6clLatin small letter L1080x6c
1090x6dmLatin small letter M1090x6dmLatin small letter M1090x6d
1100x6enLatin small letter N1100x6enLatin small letter N1100x6e
1110x6foLatin small letter O1110x6foLatin small letter O1110x6f
1120x70pLatin small letter P1120x70pLatin small letter P1120x70
1130x71qLatin small letter Q1130x71qLatin small letter Q1130x71
1140x72rLatin small letter R1140x72rLatin small letter R1140x72
1150x73sLatin small letter S1150x73sLatin small letter S1150x73
1160x74tLatin small letter T1160x74tLatin small letter T1160x74
1170x75uLatin small letter U1170x75uLatin small letter U1170x75
1180x76vLatin small letter V1180x76vLatin small letter V1180x76
1190x77wLatin small letter W1190x77wLatin small letter W1190x77
1200x78xLatin small letter X1200x78xLatin small letter X1200x78
1210x79yLatin small letter Y1210x79yLatin small letter Y1210x79
1220x7azLatin small letter Z1220x7azLatin small letter Z1220x7a
1230x7b{Left curly bracket1230x7b{Left curly bracket1230x7b
1240x7c|Vertical line1240x7c|Vertical line1240x7c
1250x7d}Right curly bracket1250x7d}Right curly bracket1250x7d
1260x7e~Tilde1260x7e~Tilde1260x7e
1270x7fDEL (non-printable)1270x7fDEL (non-printable)1270x7f
1280x80ÇLatin capital letter C with cedilla1990xc7Euro sign1760xb0
1290x81üLatin small letter U with diaeresis2520xfc(undefined)1770xb1
1300x82éLatin small letter E with acute2330xe9Single low-9 quotation mark1780xb2
1310x83âLatin small letter A with circumflex2260xe2Latin small letter F with hook1590x9f
1320x84äLatin small letter A with diaeresis2280xe4Double low-9 quotation mark1800xb4
1330x85àLatin small letter A with grave2240xe0Horizontal ellipsis1850xb9
1340x86åLatin small letter A with ring above2290xe5Dagger50x05
1350x87çLatin small letter C with cedilla2310xe7Double dagger1870xbb
1360x88êLatin small letter E with circumflex2340xeaModifier letter circumflex accent1880xbc
1370x89ëLatin small letter E with diaeresis2350xebPer mille sign1910xbf
1380x8aèLatin small letter E with grave2320xe8Latin capital letter S with caron1920xc0
1390x8bïLatin small letter I with diaeresis2390xefSingle left-pointing angle quotation mark1930xc1
1400x8cîLatin small letter I with circumflex2380xeeLatin capital ligature oe1940xc2
1410x8dìLatin small letter I with grave2360xec(undefined)1950xc3
1420x8eÄLatin capital letter A with diaeresis1960xc4Latin capital letter Z with caron1970xc5
1430x8fÅLatin capital letter A with ring above1970xc5(undefined)2000xc8
1440x90ÉLatin capital letter E with acute2010xc9(undefined)2010xc9
1450x91æLatin small ligature AE2300xe6Left single quotation mark2020xca
1460x92ÆLatin capital ligature AE1980xc6Right single quotation mark2030xcb
1470x93ôLatin small letter O with circumflex2440xf4Left double quotation mark2040xcc
1480x94öLatin small letter O with diaeresis2460xf6Right double quotation mark2060xce
1490x95òLatin small letter O with grave2420xf2Bullet2540xfe
1500x96ûLatin small letter U with circumflex2510xfbEn dash2130xd5
1510x97ùLatin small letter U with grave2490xf9Em dash2050xcd
1520x98ÿLatin small letter Y with diaeresis2550xffSmall tilde2170xd9
1530x99ÖLatin capital letter O with diaeresis2140xd6Trade mark sign2180xda
1540x9aÜLatin capital letter U with diaeresis2200xdcLatin small letter S with caron2190xdb
1550x9bøLatin small letter O with stroke2480xf8Single right-pointing angle quotation mark2200xdc
1560x9c£Pound sign1630xa3Latin small ligature oe1790xb3
1570x9dØLatin capital letter O with stroke2160xd8(undefined)2230xdf
1580x9e×Multiplication sign2150xd7Latin small letter Z with caron2400xf0
1590x9fLatin small letter F with hook1310x83Latin capital letter Y with diaeresis2420xf2
1600xa0áLatin small letter A with acute2250xe1 No-break space2550xff
1610xa1íLatin small letter I with acute2370xed¡Inverted exclamation mark1730xad
1620xa2óLatin small letter O with acute2430xf3¢Cent sign1890xbd
1630xa3úLatin small letter U with acute2500xfa£Pound sign1560x9c
1640xa4ñLatin small letter N with tilde2410xf1¤Currency sign2070xcf
1650xa5ÑLatin capital letter N with tilde2090xd1¥Yen sign1900xbe
1660xa6ªFeminine ordinal indicator1700xaa¦Broken bar2210xdd
1670xa7ºMasculine ordinal indicator1860xba§Section sign2450xf5
1680xa8¿Inverted question mark1910xbf¨Diaeresis2490xf9
1690xa9®Registered sign1740xae©Copyright sign1840xb8
1700xaa¬Not sign1720xacªFeminine ordinal indicator1660xa6
1710xab½Vulgar fraction one half1890xbd«Left-pointing double angle quotation mark1740xae
1720xac¼Vulgar fraction one quarter1880xbc¬Not sign1700xaa
1730xad¡Inverted exclamation mark1610xa1­Soft hyphen1960xc4
1740xae«Left-pointing double angle quotation mark1710xab®Registered sign1690xa9
1750xaf»Right-pointing double angle quotation mark1870xbb¯Macron2380xee
1760xb0Light shade1280x80°Degree sign2480xf8
1770xb1Medium shade1290x81±Plus-minus sign2410xf1
1780xb2Dark shade1300x82²Superscript two2530xfd
1790xb3Box drawings light vertical1560x9c³Superscript three2520xfc
1800xb4Box drawings light vertical and left1320x84´Acute accent2390xef
1810xb5ÁLatin capital letter A with acute1930xc1µMicro sign2300xe6
1820xb6ÂLatin capital letter A with circumflex1940xc2Pilcrow sign2440xf4
1830xb7ÀLatin capital letter A with grave1920xc0·Middle dot2500xfa
1840xb8©Copyright sign1690xa9¸Cedilla2470xf7
1850xb9Box drawings double vertical and left1330x85¹Superscript one2510xfb
1860xbaBox drawings double vertical50x05ºMasculine ordinal indicator1670xa7
1870xbbBox drawings double down and left1350x87»Right-pointing double angle quotation mark1750xaf
1880xbcBox drawings double up and left1360x88¼Vulgar fraction one quarter1720xac
1890xbd¢Cent sign1620xa2½Vulgar fraction one half1710xab
1900xbe¥Yen sign1650xa5¾Vulgar fraction three quarters2430xf3
1910xbfBox drawings light down and left1370x89¿Inverted question mark1680xa8
1920xc0Box drawings light up and right1380x8aÀLatin capital letter A with grave1830xb7
1930xc1Box drawings light up and horizontal1390x8bÁLatin capital letter A with acute1810xb5
1940xc2Box drawings light down and horizontal1400x8cÂLatin capital letter A with circumflex1820xb6
1950xc3Box drawings light vertical and right1410x8dÃLatin capital letter A with tilde1990xc7
1960xc4Box drawings light horizontal1730xadÄLatin capital letter A with diaeresis1420x8e
1970xc5Box drawings light vertical and horizontal1420x8eÅLatin capital letter A with ring above1430x8f
1980xc6ãLatin small letter A with tilde2270xe3ÆLatin capital letter AE1460x92
1990xc7ÃLatin capital letter A with tilde1950xc3ÇLatin capital letter C with cedilla1280x80
2000xc8Box drawings double up and right1430x8fÈLatin capital letter E with grave2120xd4
2010xc9Box drawings double down and right1440x90ÉLatin capital letter E with acute1440x90
2020xcaBox drawings double up and horizontal1450x91ÊLatin capital letter E with circumflex2100xd2
2030xcbBox drawings double down and horizontal1460x92ËLatin capital letter E with diaeresis2110xd3
2040xccBox drawings double vertical and right1470x93ÌLatin capital letter I with grave2220xde
2050xcdBox drawings double horizontal1510x97ÍLatin capital letter I with acute2140xd6
2060xceBox drawings double vertical and horizontal1480x94ÎLatin capital letter I with circumflex2150xd7
2070xcf¤Currency sign1640xa4ÏLatin capital letter I with diaeresis2160xd8
2080xd0ðLatin small letter ETH2400xf0ÐLatin capital letter ETH2090xd1
2090xd1ÐLatin capital letter ETH2080xd0ÑLatin capital letter N with tilde1650xa5
2100xd2ÊLatin capital letter E with circumflex2020xcaÒLatin capital letter O with grave2270xe3
2110xd3ËLatin capital letter E with diaeresis2030xcbÓLatin capital letter O with acute2240xe0
2120xd4ÈLatin capital letter E with grave2000xc8ÔLatin capital letter O with circumflex2260xe2
2130xd5Latin small letter dotless I1500x96ÕLatin capital letter O with tilde2290xe5
2140xd6ÍLatin capital letter I with acute2050xcdÖLatin capital letter O with diaeresis1530x99
2150xd7ÎLatin capital letter I with circumflex2060xce×Multiplication sign1580x9e
2160xd8ÏLatin capital letter I with diaeresis2070xcfØLatin capital letter O with stroke1570x9d
2170xd9Box drawings light up and left1520x98ÙLatin capital letter U with grave2350xeb
2180xdaBox drawings light down and right1530x99ÚLatin capital letter U with acute2330xe9
2190xdbFull block1540x9aÛLatin capital letter U with circumflex2340xea
2200xdcLower half block1550x9bÜLatin capital letter U with diaeresis1540x9a
2210xdd¦Broken bar1660xa6ÝLatin capital letter Y with acute2370xed
2220xdeÌLatin capital letter I with grave2040xccÞLatin capital letter THORN2320xe8
2230xdfUpper half block1570x9dßLatin small letter sharp S2250xe1
2240xe0ÓLatin capital letter O with acute2110xd3àLatin small letter A with grave1330x85
2250xe1ßLatin small letter sharp S2230xdfáLatin small letter A with acute1600xa0
2260xe2ÔLatin capital letter O with circumflex2120xd4âLatin small letter A with circumflex1310x83
2270xe3ÒLatin capital letter O with grave2100xd2ãLatin small letter A with tilde1980xc6
2280xe4õLatin small letter O with tilde2450xf5äLatin small letter A with diaeresis1320x84
2290xe5ÕLatin capital letter O with tilde2130xd5åLatin small letter A with ring above1340x86
2300xe6µMicro sign1810xb5æLatin small letter AE1450x91
2310xe7þLatin small letter THORN2540xfeçLatin small letter C with cedilla1350x87
2320xe8ÞLatin capital letter THORN2220xdeèLatin small letter E with grave1380x8a
2330xe9ÚLatin capital letter U with acute2180xdaéLatin small letter E with acute1300x82
2340xeaÛLatin capital letter U with circumflex2190xdbêLatin small letter E with circumflex1360x88
2350xebÙLatin capital letter U with grave2170xd9ëLatin small letter E with diaeresis1370x89
2360xecýLatin small letter Y with acute2530xfdìLatin small letter I with grave1410x8d
2370xedÝLatin capital letter Y with acute2210xddíLatin small letter I with acute1610xa1
2380xee¯Macron1750xafîLatin small letter I with circumflex1400x8c
2390xef´Acute accent1800xb4ïLatin small letter I with diaeresis1390x8b
2400xf0­Soft hyphen1580x9eðLatin small letter ETH2080xd0
2410xf1±Plus-minus sign1770xb1ñLatin small letter N with tilde1640xa4
2420xf2Double low line1590x9fòLatin small letter O with grave1490x95
2430xf3¾Vulgar fraction three quarters1900xbeóLatin small letter O with acute1620xa2
2440xf4Pilcrow sign1820xb6ôLatin small letter O with circumflex1470x93
2450xf5§Section sign1670xa7õLatin small letter O with tilde2280xe4
2460xf6÷Division sign2470xf7öLatin small letter O with diaeresis1480x94
2470xf7¸Cedilla1840xb8÷Division sign2460xf6
2480xf8°Degree sign1760xb0øLatin small letter O with stroke1550x9b
2490xf9¨Diaeresis1680xa8ùLatin small letter U with grave1510x97
2500xfa·Middle dot1830xb7úLatin small letter U with acute1630xa3
2510xfb¹Superscript one1850xb9ûLatin small letter U with circumflex1500x96
2520xfc³Superscript three1790xb3üLatin small letter U with diaeresis1290x81
2530xfd²Superscript two1780xb2ýLatin small letter Y with acute2360xec
2540xfeBlack square1490x95þLatin small letter THORN2310xe7
2550xff No-break space1600xa0ÿLatin small letter Y with diaeresis1520x98

GNU Free Documentation License

Version 1.1, March 2000

Copyright © 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

0. Preamble

The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. Applicability and Definitions

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

2. Verbatim Copying

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. Copying in Quantity

If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. Modifications

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties - for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. Combining Documents

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

6. Collections of Documents

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. Aggregation with Independent Works

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

8. Translation

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

9. Termination

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10. Future Revisions of this License

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

Addendum: How to Use This License for Your Documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME.
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 the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License".

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.