BotSense Protocol

Modules
	XML Message Set

Detailed Description

Intro

The transport mechanism of all messages flowing between the bsProxy server and the server's registered clients is TCP/IP. A client establishes communication with the server by making a connection request to the listening TCP port of the server (default port: 9195). If the server has client space, the connection is accepted and the communication is established.

Closing of the client's port automatically unregisters the client from the server.

There are two classes of messages:

• built-in server-terminated messages
• proxied device-terminated specific messages

Two different Message Exhange Patterns are supported:

• client request - server response
• server to client device-specific out-flow streaming

Message Structure

All requests and response messages contain an 8-byte header plus an optional message body. For server-terminated request/response messages, the RoadNarrows NetMsgs 8-bit Identifier-Type-Value field encoding format is used for all message bodies. All fields are big-endian. See the NetMsgs Package for more details. For device-terminated specific requests and responses, the message body is transparent to the server and, so, can be of any format defined by the application. However it is recommended that the application developer use the NetMsgs package for ease of building message code and for better run-time diagnostics and message tracing that is built into bsProxy.

Message Header

The 8-byte header (BSPROXY_MSG_HDR_LEN) contains 5 fields read by the server to determine how to dispatch and process the request. The header is formatted using the NetMsgs flat encoding with big-endian byte order of all values. Table 1 summarizes the header fields.

Field	Size	Description
m_hdrMagic	2	The start-of-message magic number BSPROXY_MSG_MAGIC. The magic number is required to start all messages. It may be used to resynchornize a message stream, i.e. anti-aliasing.
m_hdrTid	1	The request/response transaction id (tid). The client generates the tid for a request and the server copies the tid to the response header. The BotSense library libbotsense will automatically generate and match Tid's in a request-response sequence. See BotSense Transaction Id Attributes.
m_hdrVConn	1	The virtual connection handle. The value BSPROXY_VCONN_SERVER is reserved for server-terminated requests. All other values are for device-terminated specific requests and responses. See BotSense Handle Attributes.
m_hdrMsgId	2	The message identifier uniquely identifies the request and response messages within a virtual connection context. See BotSense Application-Specific Message Id Attributes. For server-terminated message ids see the bsProxyMsgs.h NetMsgs generated file.
m_hdrBodyLen	2	The length of the message body in bytes immediately following the header in the IP packet. If there is no message body, then this value should be set to 0 (zero).
Table 1: BotSense Message Header Format

Server-Terminated Messages

The set of request and response server-terminated messages are described below. Server-terminated messages provide the base set of services to manage proxied devices. Per each request message, libbotsense provids a functional interface. See the libotsense Man Pages for the full list of libbotsense functions. See XML Message Set for the server-terminated message specification.

For any request that fails, the bsProxy server will send a generic error response message (Standard Error Response Message). The library libbotsense will automatically interpret server error messages, logging the error, and returning the appropriate error code to the calling client function.

Get Version Messages

Get the version string of the bsProxy server.

Request MsgId:	BsProxyMsgIdReqGetVersion
Request Body:	None
Response MsgId:	BsProxyMsgIdRspGetVersion
Response Body:	BsProxyRspGetVersion_T
libbotsense Call:	bsServerReqGetVersion ()

Loopback Messages

Loopback character data sent by the client and loopbacked by the servier.

Request MsgId:	BsProxyMsgIdReqLoopback
Request Body:	BsProxyReqLoopback_T
Response MsgId:	BsProxyMsgIdRspLoopback
Response Body:	BsProxyRspLoopback_T
libbotsense Call:	bsServerReqLoopback ()

Set Diagnostic Logging Messages

Set the level of diagnostic logging performed by the server. The new level will override the current value set either during server startup or by servicing a previous 'set logging' request message. The diagnostic logging level has global server impact in that it effects the logging of the server and all virtual connection.

Request MsgId:	BsProxyMsgIdReqSetLogging
Request Body:	BsProxyReqSetLogging_T
Response MsgId:	BsProxyMsgIdRspOk
Response Body:	None
libbotsense Call:	bsServerReqSetLogging ()

Message Tracing Enable/Disable Messages

Enable/disable tracing of message packing/unpacking. The tracing only effects the specified virtual connection. Both the bsProxy server and the libbotsense library will print the tracing to stderr.

Request MsgId:	BsProxyMsgIdReqMsgTrace
Request Body:	BsProxyReqMsgTrace_T
Response MsgId:	BsProxyMsgIdRspOk
Response Body:	None
libbotsense Call:	bsServerReqMsgTrace ()

Open a Proxied Device Messages

Open a proxied device. The client specifies the proxied device, the interface protocol module, and any optional device-specific open parameters in a packed format. The server will return a new virtual connection handle.

Request MsgId:	BsProxyMsgIdReqDevOpen
Request Body:	BsProxyReqDevOpen_T
Response MsgId:	BsProxyMsgIdRspOk
Request Body:	BsProxyRspDevOpen_T
libbotsense Call:	bsServerReqOpenDev ()

Close a Proxied Device Messages

Close a proxied device. The virtual connection handle is no longer valid after the request is serviced.

Request MsgId:	BsProxyMsgIdReqDevClose
Request Body:	BsProxyReqDevClose_T
Response MsgId:	BsProxyMsgIdRspOk
Response Body:	None
libbotsense Call:	bsServerReqCloseDev ()

Get the List of Virtual Connections Messages

Get the server's list of virtual connection handles for this client.

Request MsgId:	BsProxyMsgIdReqGetVConnList
Request Body:	None
Response MsgId:	BsProxyMsgIdRspOk
Response Body:	BsProxyRspGetVConnList_T
libbotsense Call:	bsServerReqGetVConnList ()

Set Diagnostic Logging Messages

Get the server's information on the given virtual connection. The client specifies the virtual connection handle. The response message contains the details.

Request MsgId:	BsProxyMsgIdReqGetVConnInfo
Request Body:	BsProxyReqGetVConnInfo_T
Response MsgId:	BsProxyMsgIdRspOk
Response Body:	BsProxyRspGetVConnInfo_T
libbotsense Call:	bsServerReqGetVConnInfo ()

Standard Ok Response Message

The BotSense standard ok (success) response message. The message can be sent in response to either a server-terminated or a device-terminated request. The libotsense library will automatically intercept the ok message and return BS_OK to the calling client function.

Response MsgId:	BsProxyMsgIdRspOk
Response Body:	None

Standard Error Response Message

The BotSense standard error (failure) response message. The message can be sent in response to either a server-terminated or a device-terminated request. The response contains one of the BotSense Error Codes, plus an error string. The libotsense library will automatically intercept the error message, print the appropriate diagnostic, and return to the calling client function with the received error code.

Response MsgId:	BsProxyMsgIdRspErr
Response Body:	BsProxyRspErr_T