Palm Reporter Protocol Description

Version 1.0

Table of Contents


1 Foreword

1.1 Context

This document describes the protocol that is used to send data from the Palm OS Emulator to the Palm Reporter, which is described in another document (see Reporter Guide.html). This protocol is implemented above TCP/IP. The sender side is implemented as a shared library that POSE will load dynamically when it needs it. Today that library is only available for Windows and is called PalmTrace.dll. This protocol is recognized by the version 1.x of the Reporter. You don't need to know how POSE communicates with the Reporter in order to use these tools.

1.2 Protocol overview

The data flows unidirectionally from PalmTrace to the Reporter. The connection / disconnection is initiated by POSE through PalmTrace's exported functions. Each trace corresponds to a single packet (message). TCP guarantees the reliable and ordered data transfer of these packets.


2 Message Format

2.1 Message structure

Each message begins with a fixed size header. The message body is a set of "parameters". Each parameter has a fixed size header. The parameter body structure varies, according to the type located in the parameter header. A special parameter type is used to mark the end of the message.

2.2 Message header

vvXXXXXXXXXXXXXX

vv Version of trace protocol (2 bytes: Major, Minor)

Version matching is done on the major only. It will be incremented whenever a change renders it incompatible with the Reporter. The current protocol version number is 1.0.

For this version, XX...XX = NNNNp0p1...pn

NNNN : total size of the message (including vvNNNN) (4 bytes)

pi : Message parameters

NNNN, as all 16 bits and 32 bits integer values are transmitted in network order (big-endian).

2.3 Parameter header

cnndd..dd

c : Parameter opcode (1 byte)

n : nn parameter data len (excluding cnn)

d..d: parameter data

User or platform-dependant parameters must be >=128 (bit 7 set). This will prevent collision with future parameters.

Each message must include at least parameters of types 1, 5 and 0, in this order.

2.4 Parameter body

Parameter type

Body data structure

Data length (bytes)

0 : End of message

None

0

1 : Attributes

XXRRK, with XX = module, RR= reserved, K = kind (0=text,1= text with line break,2=binary)

5

2 : Indentation level

X

1

3 : Process ID

XXXX

4

4 : Thread ID

XXXX

4

5 : Trace Data

Either Formatted text or binary data, depending on the message attributes

Variable

6 : Time stamp

XXXX

4

There can be several type 5 parameters (they will be concatenated upon reception), but restrictions apply: only the last can be of kind 1, and if the first parameter is of kind 2, all parameters in the message must be of the same type.


3.0 Advanced Considerations

3.1 Design choices

3.2 Limits