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