Synchronous Tunnel API

The Synchronous Tunnel API defines a platform-independent framing protocol to map between the stream based semantics of TCP/IP and a frame based semantics of synchronous communications. The API is defined in the C Language include file synctunneldef.h as a group of types and macros for encoding and decoding packets sent to and from the syncunnel server running on the PXS.

All packets transferred over TCP/IP between client and server begin with a 2-byte length field in network byte order (most significant byte first). The receiver decodes this field to determine how much additional data follows.

To send and receive data, the client can use the StnPacketStruct type. The data to be sent is copied into the data field of the structure, then the total packet length is encoded into the length field. For instance, to send 98 bytes of data, the client would do:

#include "synctunneldef.h"

StnPacketStruct packet;
int             length = 98;

memcpy(&packet.data, data, length);

stn_ENCODE_HEADER(&packet.header, length, 0);

length += sizeof(packet.header);

/* Send length bytes to the server */
send(sock, &packet, length, 0);

To receive a packet from the server, the client would do:

StnPacketStruct packet;
int             length = sizeof(packet.header);

/* Receive header into packet.header */
recv(sock, &packet.header, length, 0);

length = stn_GET_LENGTH(&packet.header);

/* Receive length additional bytes into packet.data */
recv(sock, &packet.data, length, 0);

The packet.data field will then contain length bytes of data from the packet.