GNAP Protocol Overview
Goto: Documentation Home
GNAP (Generic Network Access Protocol) is a binary communcation protocol designed to be a mixture of lightweight, flexible and easy for clients to process (GNAP is processed on 8bit industrial micros). While at times GNAP may seem strange, it is very easy and efficient for high volume servers.
The GNAP binary protocol is based around a series of Packets where each packet has an 8 byte header.
The first 4 bytes of the packet header define the payload inside the packet, such as a request for information or updates to data. This is called the packet type.
The second 4 bytes of the header define the overall length of the packet and it's payload. This length includes the 8 bytes for the header, so lengths will never be less than 8 bytes.
The contents and encoding of the packet (the payload) are left to each packet type to define. Most packets use the standardised field encoding shown in the diagram. With this encoding, the payload consists of a byte stream, where the sequence of the bytes conveys both the information contained in the payload and the encoding used.
The GNAP binary protocol can operate as both a broadcast protocol (typically using UDP broadcasts) or point to point (typically over TCP connections).
The binary GNAP protocol can be easily converted into XML, with a few exceptions and limitations. In fact, most servers operate on the binary protocol as it is easier and faster to process, and simply convert to and from XML formats to communicate to end clients. This allows remote clients, such as Web Browsers using XML to read and write from a GDS server.
The GNAP packet header becomes the enclosing XML tag.
| For example, the binary packet (shown stylised) | PINB 314 19,test |
| Converts to | <PINB><f19>test</f19></PINB> |
All payload fields, which are always numerically identified in binary GNAP, as called 'f Field-Number', such as Field 19 being called f19 in XML. The XML convertor does not generate "attributes" (although it may do so in the future)
XML packets are typically read and written to/from a URL on a Web Server. These URLs match the packet type to be processed. To read a pinboard (packet type PINB), you can encode the request onto the URL /GNAP/PINB. In HTTP, you can request either GET or POST transactions, depending on what packet type you are requesting.
For example, the IDQY packet (identification query), is sent to the URL /GNAP/IDQY and the GDS server may response with an IDRP (identification response) XML Packet. (Security note, not all GDS Servers will answer this request, and Server Admins can also manually set fields to any value they wish)
When writing data with XML packets, the field names are changed to include the format of the data. This is required as the convertor receiving an XML packet needs to generate the correct binary format. These binary formats do not store all data in "text-strings" like XML, and the convertor needs to be told explicitly which binary format should be used. In practice, this is very easy to use for XML authors, as the documentation of a packet simply gives the read and write field names independently.
As XML is primarily a text based system, binary data cannot be sent over XML packets easily.
Several GNAP packet types, such as SCRB, SCRM and other encrypted formats cannot be used. Other controls are needed to ensure link level security for XML.