Snarl Network Protocol (SNP)

Introduction

The Snarl Network Protocol (SNP) provides simple access to both local and remote instances of Snarl via TCP.  As it is a network protocol, neither the sending or receiving computers need to be running Snarl, or even Windows for that matter; so long as a connection can be made, applications will be able to send notifications.

Communication Overview

Prior to Snarl R4.0, communication took place using TCP on specific ports, depending on the variation of the protocol used.  Starting with Snarl R4.0, communication can take place over any valid TCP port using any variation of SNP.  It should be noted however, that applications – especially older ones – may still expect communication to occur across a specific port.

Typically it is down to the client to manage the connection and terminate it when no further communication is required, however in some cases Snarl may terminate the connection.

The communication process is as follows:

  1. Client creates a socket
  2. Client connects to Snarl running on a remote computer
  3. Client sends a request to Snarl
  4. Client receives a reply from Snarl
  5. Steps 3 and 4 repeat until either the client or Snarl ends the connection

Callback events and notifications forwarded as the result of a subscription will also be received by the client.

The client may choose to create a new socket for each request, or re-use an existing socket (preferred, as it saves on resources).  If the client is expecting to handle callbacks then it must ensure the socket remains open at least until the callback is received, or is no longer required.  If a client has subscribed for notifications from a remote computer, it must leave the socket open in order to receive notifications sent by the remote computer.

Message Structure

A SNP message consists of:

  • A header;
  • Some content;
  • A terminator.

The header, content and terminator vary depending on the version of the protocol used.

Message Types

Two types of message are currently defined:

  • Request
  • Response

Request Message

A SNP request is sent from a client (which may be Snarl, but will more likely be an application) to a computer running Snarl, and is usually a request for Snarl to take some form of action.  Notifications forwarded from one computer to another are also considered requests, as the source computer is requesting the destination computer to consider the notification content for action.

Response Message

A SNP response is received by a client from a remote instance of Snarl in response to the previous request.  The response will typically indicate the result (success or failure) of a previous request and may provide further information (for example, extended error information in the case of a failure) depending on the nature of the request.

Protocol Versions

SNP 1

SNP 1 covers two variations: 1.0 and 1.1.  See the documentation here for more details.  SNP 1 is no longer in development and is considered deprecated, however it will continue to be supported by Snarl for the time being.

SNP 2

SNP 2 built on SNP 1 by using a more traditional URL format for each request.  A SNP 2.0 request begins with “snp://” and ends with a single 0x0D (CR, \r) character.  SNP 2.0 is also extensible in that you can issue any Snarl API command using the protocol.  See the documentation here for more details.

Although SNP 2.0 is considered deprecated, Snarl will continue to support it for the foreseeable future.

SNP 3

SNP 3 is the current preferred variation of SNP.  SNP 3 is a slightly more complex protocol from a formatting perspective, but does allow for more advanced features compared to SNP 2 such as subscribing to, and forwarding of, notifications.  Both SNP 2 and SNP 3 are still considered viable protocols.  Read more about SNP 3 here.

SNP 3 documentation.

SNP 4

SNP 4.0 is currently in development.  We welcome ideas and suggestions on the definition of this version.

SNP/HTTP

SNP/HTTP began as a browser-based variant of SNP 2.0 and remains supported by Snarl to this day.  It is currently under development as a more structured RESTful-based API that applications can use to target Snarl in a more structured and extensible way.  Read more – and contribute – to the development of SNP/HTTP here.  You can find out more about the current version of SNP/HTTP on the SNP 2.0 page.