Snarl Integration Guide NOT IN USE


Content goes here...

Setting Up

Irrespective of which language or method you use to communicate with Snarl, the basic request structure is the same, as follows:


command indicates what Snarl should do; with the remainder of the request being specific to the command.  The various commands and their associated arguments are defined in the API reference.

Character Escaping

Attempting to use '&' or '=' characters intended for display will be misinterpreted by the request parser as marker characters and result in (at best) a malformed request.  To avoid this, and to allow display of '&' and '=' characters within notifications, use '&&' and '==' to represent a printable '&' and '=' respectively.  Question marks do not need to be escaped as Snarl is only interested in the first question mark it finds within the request.

Additionally, Snarl also supports the use of URL escaped characters so "%20" translates into a space character, for example.

Registering with Snarl

The first thing your application should do is register with Snarl.  It can do this at any time, although it must register before attempting to send any notifications.  The most common method is to register as part of the application's initialisation process, however it is recommended that the application registers each time it generates a notification - this avoids issues which can occur if Snarl is unloaded and then reloaded after the application has registered.


register?app-sig=app/acme-test&title=Test Application

Application Signatures

Application signatures must be unique to the individual application.  Consequently, the recommendation is to follow the Internet Media type (also known as  MIME content type) format as defined in IETF RFC 2046, specifically one that includes the application vendor's name, for example:


Note that the supplied signature must not contain spaces - you'll get a SNARL_ERROR_INVALID_ARG if it does.


Passwords are used to prevent other applications from attempting to create notifications by masquerading as a previously registered application.  The recommendation is that the password should be generated dynamically by the application on launch and should use a string of randomly generated alphanumeric characters.  Many libraries and helper modules include macros for doing exactly this.

Note: if an application fails to unregister with Snarl when it exits, Snarl will treat subsequent registrations as re-registrations and therefore the application must use the same password as it did on it's previous registration otherwise an error will occur.

Adding Classes

Content goes here...

Creating Notifications

Content goes here...


Content goes here...

Static Callbacks

Content goes here...

Dynamic Callbacks

Content goes here...

System Callbacks

Content goes here...


Content goes here...

Notification Guidelines

In order to maintain a consistent appearance, your application should follow these guidelines:

Keep the Title and Text short: Notifications appear at random times and, as such, the user will want to be able to digest the meaning of the notification as quickly as possible.  Titles should be kept as short as possible, typically no more than 4 words; the notification text may be longer but should still be as concise as possible.  If you need to pass a lot of information to the user, consider using a static callback or action which will direct the user to a document that contains it.

Avoid programmatically hiding notifications:
The Hide command should be avoided as it is impossible for your application to tell whether the user has been able to fully digest the notification content.  The only time Hide may be of use is if the event the notification is alerting the user to no longer exists (for example, a "power disconnected" notification when the power supply has been restored).

Avoid high-priority notifications: Generally speaking the user should be left to determine which notifications constitute high-priority status.  When deciding whether a notification should be displayed as high priority or not you should consider the context your notification will be displayed in and that, although you may feel the notification requires urgent from the user, the user may disagree.

Status Codes

All Snarl API calls return a signed 32-bit integer.  This value can indicate one of two things:
  • An error.  If the value is negative, this will be the error number.
  • Success.  If the value is zero or greater, this indicates the call completed successfully.  If the value is greater than zero, the call completed successfully and returned some data.  The meaning of the returned value will be specific to the API call.
The defined status codes are as follows:



libSnarl using VBScript

Paste the following into a text file, save it as "register.vbs" and double-click it.

Now paste the following into a text file, save it as "unregister.vbs" and double-click it.