Developer Guide

 

Introduction

The Snarl API is very straightforward to use and has been designed to be as flexible as possible, allow you to get up and running irrespective of how you want to communicate with Snarl.  Snarl provides a number of different mechanisms that can be used to create notifications, including:

  • Using Windows Messages
  • Using various different TCP/IP socket-based protocols
  • Using higher level network protocols such as HTTP

There are also a number of libraries and helper modules for various programming languages that allow immediate “drop in” support for Snarl.

API Format

Most interaction with Snarl is performed using the “raw” API, which uses the following format:

<command>[?arg=value&arg=value&...]

For example, creating a notification is as simple as this:

notify?title=Hello, world!

There are command-line tools which let you issue raw API commands, either using the Windows Messaging system (for apps running on the same machine as Snarl), or a network protocol (for apps running on a different machine).

 

 

 

Integrating Snarl

 

The Basics

Creating Notifications

 

Registering Applications

 

Unregistering

 

Defining Events

 

 

 

Scheduling Notifications

Notifications can be submitted to be displayed at a later date.  To schedule a notification, use the due argument in the notify command, setting it to a date or time in the future (notifications submitted with a date or time in the past will be displayed immediately by Snarl).  Any date or time format that is recognised by .net can be used.

Raw

notify?...due=<date>

 

Snarl Framework 5

Notification.Schedule(DateTime when);

 

Advanced Topics

Callbacks

Snarl allows applications to receive user feedback on any notifications that are created.  By its own nature, Snarl works in an asynchronous way (an application creates a notification, then continues working while the user decides on how they want to respond to the notification) so the mechanism you use to create notifications has an impact on how callbacks work.  To allow the most flexibility, Snarl provides the following types of callback:

  • Static callbacks
  • Dynamic callbacks
  • Managed callback (V47 and above)

 

Static Callbacks

Static callbacks are the most straightforward to use, but are also slightly limited in what can be done with them.  A static callback is usually either a URL or a fully-qualified path (either local or remote) to an executable.  Some examples of static callbacks:

http://snarl.fullphat.net/
\\myserver\shared\callback.exe

Static callbacks are ideal for applications that do not need to (or cannot) respond to asynchronous replies from Snarl.  This might be because of the nature of the application (e.g. batch files cannot easily receive replies from Snarl), or some other reason.

To set a static callback, just specify the URL or file path in the callback parameter when creating a notification, for example:

notify?title=Hello, world!&callback=http://snarl.fullphat.net

Your application doesn’t need to handle the callback; when the user clicks the button on the notification, Snarl will process the callback automatically.

Callback Arguments

From V46 onwards, you can also specify separate command-line arguments using the callback-args parameter, so if you want to run “c:\clicked.bat” with arguments “12345” you can do the following:

notify?title=Hello, world!&callback=c:\clicked.bat&callback-args=12345

 

Dynamic Callbacks

Dynamic callbacks allow for more flexibility when it comes to responding to user feedback.  As the name suggests, a dynamic callback leaving the logic of handling how to respond to the callback to the application itself.  Dynamic callbacks are not supported by all transports so, if you’re using a library to communicate with Snarl, you should check to see if the library supports dynamic callbacks.  The Win32 and SNP 2.0+ transports support dynamic callbacks; SNP/HTTP does not support dynamic callbacks.

 

Managed Callbacks

Managed callbacks are a new feature coming in V47 of the API.  They apply to all transports, however are particularly suited to transports that do not support dynamic callbacks as they provide functionality similar to that provided by dynamic callbacks.

Managed callbacks use three new arguments, and the format is different, as follows:

Arguments

The following arguments can be used with managed callbacks:

  • callback-invoked – used when a notification is invoked (that is, the user clicks the button that appears on the notification)
  • callback-expired – used when a notification disappears without any user interaction
  • callback-dismissed – used when the user dismisses the notification (that is, the user clicks on the notification body itself)

Format

Callbacks must be formatted in two parts – the first part containing the command to perform; the second part containing some data:

command:data

Command can be one of:

  • url:
  • http-get:
  • http-post:
  • file:

Data is specific to the command.

url:

Performs a straightforward HTTP GET request to the specific URL.  This is akin to simply setting the callback parameter to “http://localhost:4444/callback/here”.  Example:

url:http://localhost:4444/callback/here

http-get:

Sends a HTTP GET request to the specific URL, but includes any data-* notification parameters in the query.  For example, if a notification is created with the following parameters:

data-text=Hello, world!
data-magic_number=23
data-special_guid=4c4f4542-0010-cafe-c00006

And the callback parameter is set to:

http-get:http://myserver.local/callback

Then the “myserver.local” web server will receive a HTTP GET request with the following URI:

/callback?data-text=Hello,%20world%21&data-magic_number=23&data-special_guid=
4c4f4542-0010-cafe-c00006

http-post:

Similar to http-get above, http-post performs a HTTP POST request to the specified URL, including any data-* notifications parameters as a JSON object in the request body.  For example, if a notification is created with the following parameters:

data-text=Hello, world!
data-magic_number=23
data-special_guid=4c4f4542-0010-cafe-c00006

And the callback parameter is set to:

http-post:http://myserver.local:4444/callback

Then the “myserver.local” web server running on port 4444 will receive a HTTP POST request with the following content:

{
    "data-text":"Hello, world!",
    "data-magic_number":"23",
    "data-special_guid":"4c4f4542-0010-cafe-c00006"
}

The Content-Type header will also be set to application/json.

Handling Different Types of Callback

Static callbacks only fire when a notification is invoked by the user.  This is usually when the user clicks on the button that appears on notifications with a callback set.  Dynamic callbacks include the type of feedback received, which can be:

  • The user invoked (clicked on the button) the notification
  • The notification expired naturally
  • The user dismissed the notification (clicking anywhere but on the button)
  • The user selected an option from the notification

For transports that do not support dynamic callbacks, it wasn’t possible to support feedback other than responding to the invoke action through the callback parameter.  From V47, there are two new parameters – callback-expired and callback-dismissed – which allows applications to supply a managed callback that will be called when a notification expires or is dismissed respectively.

For example, creating a notification with:

callback-invoked=url:http://myserver.local:4444/callback/was_clicked
callback-expired=url:http://myserver.local:4444/callback/expired
callback-dismissed=url:http://myserver.local:4444/callback/alert_me?user=bad_bad_person

Will cause different requests to be sent to “myserver.local” depending on how the user reacted to the notification.

Button Label

Snarl will usually choose the most appropriate text for the button that appears in the notification, however applications can also customise this text using the callback-label parameter.  This parameter can be used if either (or both) of callback and callback-invoked are defined.

Note that the label is limited to approximately 8 characters in size.