JANOS Help System: [Commands] [Topics] [Tech Support] [Printable Manual] [Search]
JMP Protocol DESCRIPTION There are two methods of achieving a JMP protocol connection. Both provide access to the full capabilities of the protocol. WEBSOCKET A WebSocket connection creates a full-duplex communications channel as would be available by direct connection to a TCP port but using the HTTP or HTTPS mechanism. This enables direct interaction between a website and JANOS. By default a WebSocket channel supports the JMP protocol. This is how the JNIOR WebUI performs tasks such as are available through the Folders, Console and Syslog tabs. Websocket has been standardized by the IETF https://www.ietf.org/ as RFC 6455 https://tools.ietf.org/html/rfc6455 . The JNIOR WebUI is installed by the file /flash/www/config.zip and in particular the JavaScript file comm.js in that library handles the Websocket communications. You are free to use that source code as reference or to incorporate any part of it in your custom website. Note that the JMP protocol requires a login. This is critical as the protocol is very powerful. When a website login to the JNIOR is successful (or if the login is disabled) a Session Cookie is generated. This is passed when a related HTTP connection is elevated to Websocket. It then is accepted as a valid login credential providing seamless operation. PROTOCOL PORT By default a connection to TCP Port 9220 provides direct access to the JMP protocol. In this case there is a special wrapper that must be used in transporting the JSON messages. One of the issues in using JSON in communications protocols stems from the lack of message length information. In the absence of a length the communications driver must count open '{' and close '}' curly braces in order to ascertain when an entire structure has been read from the channel. This is complicated by the fact that curly braces may appear in string data and those must be ignored. The algorithm, while not complicated, is an annoyance. The JMP connection uses a wrapper that conveys a message length. Once a successful connection is made to the JMP Server port, messages may be exchanged. With one exception all messages conform to the JSON format using the ASCII printable character set. The high-level message format must be as follows. This forms the message wrapper which is a 2-element JSON Array construct. [ length , object ] Where length defines the exact size of the object in bytes excluding leading and trailing white-space if any. Leading and trailing white-space, which can include newline characters, may be present surrounding both the length value and the object. Here object must be a fully formed and valid JSON Object beginning with '{' and ending with '}' curly braces. Both these curly braces and any characters in between are included in the length value. The leading '[' opening square bracket, ',' comma, and trailing ']' closing square bracket are required. The opening and closing JSON Object curly braces are also verified. If there is any violation to this format the message will be simply ignored. There is no response or indication of error. All bytes outside of the square brackets are ignored as well. A valid parsing strategy would be as follows: * Read and ignore bytes up to a '[' opening square bracket * Read and ignore white-space characters (space, tab, newline, etc.) * Accumulate a decimal length (must be digits 0-9, the result must be >= 2) * Read and ignore white-space * Read and confirm the presence of the ',' comma * Read and ignore white space * Extract the JSON Object of precise length defined by the numeric value * Read and ignore white-space * Read and confirm the ']' closing square bracket (no other character is acceptable) * Confirm that the JSON object is properly enclosed by '{' and '}' curly braces * Process the JSON object and repeat This wrapper is not used by the Websocket connection since Websocket already includes message length information. EXAMPLE All TCP/IP Port 9220 communications utilize the 2-element JSON Array format for conveying valid JSON Objects. This is not used in WebSocket communications. In describing JMP protocol Messages the 2-element JSON Array format will be assumed. We will only show the enclosed JSON Objects. To initialize communications the client should send a blank or empty message. The following is acceptable. { "Message":"" } This message properly formatted for JMP Port 9220 would be transmitted as follows. [14,{"Message":""}] The connection will proceed depending on the authentication requirements established by configuration and the client environment for the connection. NOTES It is important to note that the TCP/IP connection is a streaming channel and one or more network packets may be required to convey an entire message. Similarly a packet may include the final bytes of one message and those beginning the next. A reliable implementation will buffer incoming data until an entire message is received. Once the message is processed it is removed from the buffer leaving any additional data which will be required to form the message that follows. JMP is not Master-Slave. Many requests do solicit a response but not all. There are also unsolicited messages produced by the server. These alert the client to I/O changes as well as many other events. The protocol allows you to specify any amount of META data with your request. That data is echoed in the associated response. This can be used to maintain synchronization between request and response. It is a very flexible means of synchronization and can be used to convey, for example, detailed processing instructions for the response. SEE ALSO HELP Topics: SECURITY, JMP, JSON [/flash/manpages/protocol.hlp:25]