Difference between revisions of "GeometryServiceNetworkProtocol"

From BRL-CAD
(Flesh out Data a bit.)
(Fixed headline)
Line 12: Line 12:
 
----
 
----
  
==GSNet Msg (Visual) Breakdown==
+
=GSNet Msg (Visual) Breakdown=
 
[[Image:GSNetMsgBreakdown.png|520x373px]]
 
[[Image:GSNetMsgBreakdown.png|520x373px]]
  
 
----
 
----
  
==GSNet Msg==
+
=GSNet Msg Description=
===Header===
+
==Header==
 
The header of the GSNet Msg contains the information necessary for quickly determining authenticity, type and length.  Geometry Service's network library, libNetwork, is built upon BRL-CAD's networking library: libPKG.  This causes the header byte layout to look like this:
 
The header of the GSNet Msg contains the information necessary for quickly determining authenticity, type and length.  Geometry Service's network library, libNetwork, is built upon BRL-CAD's networking library: libPKG.  This causes the header byte layout to look like this:
 
<br /><br />
 
<br /><br />
Line 57: Line 57:
  
  
====libPKG Part====
+
===libPKG Part===
 
Due to some C and C++ incompatibilities, the libPKG "Type" parameter is used as "Magic2" in the GSNet Protocol.  This is due to libPKG's need for each network connection to have a callback table that maps NetMsg types to pointers to the appropriate NetMsg handler function.  The GSNetwork library uses a publish/subscription scheme to route NetMsg.  LibPKG strips off the libPKG header before calling the appropriate callback function, thus making per class deserialization extremely complex.  To address these issues, the GSNetwork library routes NetMsg based on the "GS Msg Type" parameter rather than the "libPKG Type" parameter.
 
Due to some C and C++ incompatibilities, the libPKG "Type" parameter is used as "Magic2" in the GSNet Protocol.  This is due to libPKG's need for each network connection to have a callback table that maps NetMsg types to pointers to the appropriate NetMsg handler function.  The GSNetwork library uses a publish/subscription scheme to route NetMsg.  LibPKG strips off the libPKG header before calling the appropriate callback function, thus making per class deserialization extremely complex.  To address these issues, the GSNetwork library routes NetMsg based on the "GS Msg Type" parameter rather than the "libPKG Type" parameter.
 
<br /><br />
 
<br /><br />
Line 80: Line 80:
 
* '''Length:''' 4 byte integer that represents the number of bytes in the message from the end of this value to the end.
 
* '''Length:''' 4 byte integer that represents the number of bytes in the message from the end of this value to the end.
 
<br /><br />
 
<br /><br />
====GSNet Part====
+
===GSNet Part===
  
 
* '''MsgType:''' 2 byte integer value that tells what type of message this is.
 
* '''MsgType:''' 2 byte integer value that tells what type of message this is.
Line 89: Line 89:
 
----
 
----
  
===Data===
+
==Data==
 
----
 
----
The Data load of a NetMsg is, obivously, the important and unique part.  Data Loads can be as small as zero (In the case of a TypeOnlyMsg) or many kilobytes long.
+
The Data load of a NetMsg is, obivously, the important and unique part.  Data Loads can be as small as zero (in the case of a TypeOnlyMsg) or many kilobytes long.
  
 
Here is a list of [[NetMsgTypes|NetMsg types]] and here is a list of [[Common NetMsg Exchanges]].
 
Here is a list of [[NetMsgTypes|NetMsg types]] and here is a list of [[Common NetMsg Exchanges]].

Revision as of 15:01, 26 January 2011


GSNet
The Geometry Service Network (GSNet) Protocol is a TCP/IP based protocol designed to facilitate socketed communications between Geometry Service Nodes on a network. A Geometry Service Node is defined as any softwares that supports communication via the GSNet Protocol.



GSNet Msg (Visual) Breakdown

GSNetMsgBreakdown.png


GSNet Msg Description

Header

The header of the GSNet Msg contains the information necessary for quickly determining authenticity, type and length. Geometry Service's network library, libNetwork, is built upon BRL-CAD's networking library: libPKG. This causes the header byte layout to look like this:

Element Length Value
Magic1 int16 (2 Bytes) Always 0x41FE
Magic2 int16 (2 Bytes) Always 0x5309
MessageLength int32 (4 bytes)
MsgType int16 (2 bytes)
MessageUUID String (Variable bytes)
HasRegardingUUID Boolean (1 byte)
RegardingMessageUUID String (Variable bytes)


libPKG Part

Due to some C and C++ incompatibilities, the libPKG "Type" parameter is used as "Magic2" in the GSNet Protocol. This is due to libPKG's need for each network connection to have a callback table that maps NetMsg types to pointers to the appropriate NetMsg handler function. The GSNetwork library uses a publish/subscription scheme to route NetMsg. LibPKG strips off the libPKG header before calling the appropriate callback function, thus making per class deserialization extremely complex. To address these issues, the GSNetwork library routes NetMsg based on the "GS Msg Type" parameter rather than the "libPKG Type" parameter.

Table showing modifications described above:

libPKG element GSNet element
Magic Magic01
Type Magic02
Length Length
  • Magic01: 2 bytes of data designed to ensure integrity of data and mark NetMsg starting point.
  • Magic02: 2 bytes of data designed to ensure integrity of data and mark NetMsg starting point.
  • Length: 4 byte integer that represents the number of bytes in the message from the end of this value to the end.



GSNet Part

  • MsgType: 2 byte integer value that tells what type of message this is.
  • MessageUUID: Standard UUID for this message. Currently stored as a string.
  • HasRegardingUUID: Boolean flag that indicates whether there is a Regarding UUID or not.
  • RegardingMessageUUID: Standard UUID that indicates this NetMsg is a response to another NetMsg.

Data


The Data load of a NetMsg is, obivously, the important and unique part. Data Loads can be as small as zero (in the case of a TypeOnlyMsg) or many kilobytes long.

Here is a list of NetMsg types and here is a list of Common NetMsg Exchanges.