Snarl Network Protocol

SNP 1.0

The Snarl Network Protocol is designed to allow applications to connect to and communicate with an instance of Snarl running on a remote computer. It is TCP-based and is designed to be fairly 'human-readable' in a similar way to protocols such as HTTP. The basic process of communication is as follows:

The client application will create a TCP connection to port 9887 on the computer where Snarl is running (127.0.0.1 can be used if a connection to the local computer is required). The client then issues commands to Snarl and Snarl will send a reply back to the client to indicate success or otherwise.

Command Packet

All communication from a client to Snarl takes the form of a command packet. The packet is constructed as follows:

data=value#?data=value

A packet is terminated with a Carriage Return and Line Feed pair (typically referred to as CR/LF). Once Snarl receives the end of packet marker it processes the request. Each request must begin with an SNP header, which is used to identify the type and version of the packet being sent. The header for SNP 1.0 looks thus:

type=SNP#?version=1.0

In addition to the header, the packet must also contain an action item and an app item. The former describes the action being requested; the latter identifies the application the action refers to. There are currently four actions defined: register, unregister, add_class and notification. Depending on the action item, other parameters may be required.

Response Packet

Assuming the connection to Snarl succeeded, the client application will receive a reply at its local TCP port. The reply takes the form of:

SNP/version/return_code/description

version indicates the version of the server, return_code is an integer which represents the result of the previous command. This will be zero for success, or a non-zero value if an error occurred - see the Return Codes section for more details; description is a human-readable translation of the return code.

A success response looks thus:

SNP/1.0/0/OK

And an error response looks thus:

SNP/1.0/202/Application is not registered

Registering with Snarl

The first action an application should perform is to register itself. This is done using the register action. The app parameter should be used to specify the name of the application, as follows:

type=SNP#?version=1.0#?action=register#?app=Just Testing...

Adding a Class

Once an application is successfully registered, it should add at least one class. This isn't mandatory but adding classes allows the end user (and you) greater control over the notifications your application displays. Adding a class is done using the add_class action. The required app parameter should be used to specify the name of the application as it was specified during registration. One further parameter - class - is required and defines the name of the class being added. An additional parameter - title - is optional and will be used as the 'friendly' class name if specified.

Example:

type=SNP#?version=1.0#?action=add_class#?app=Just Testing...#?class=1#?title=A classy class

Displaying a Notification

To display a notification, use the notification action. The following parameters must also be specified: class - the name of an existing class; title - the notification title; text - the notification text, and timeout - the number of seconds the notification should be displayed for (or zero if it should be sticky).

Example:

type=SNP#?version=1.0#?action=notification#?app=Just Testing...#?class=1#?title=Hello#?text=World!#?timeout=10

Unregistering with Snarl

The last action an application should perform is to unregister itself. This is done using the unregister action. The app parameter should be used to specify the name of the application which was used during registration, as follows:

type=SNP#?version=1.0#?action=unregister#?app=Just Testing...

A Worked Example

The best way to test this is to try it. Fourtunately, this is easy using the HyperTerminal application which comes with Windows.