Snarl Integration Guide NOT IN USE

Introduction

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?parameter=value&parameter=value&...

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.

Example

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:

application/x-vnd-acme.my_test_app

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

Passwords

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...

Callbacks

Content goes here...

Static Callbacks

Content goes here...

Dynamic Callbacks

Content goes here...

System Callbacks

Content goes here...

Actions

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:

SNARL_ERROR_FAILED101 
SNARL_ERROR_UNKNOWN_COMMAND102 
SNARL_ERROR_TIMED_OUT103 
SNARL_ERROR_BAD_SOCKET106 
SNARL_ERROR_BAD_PACKET107 
SNARL_ERROR_INVALID_ARG108 
SNARL_ERROR_ARG_MISSING109 
SNARL_ERROR_SYSTEM110 
SNARL_ERROR_ACCESS_DENIED 121 
SNARL_ERROR_NOT_RUNNING201 
SNARL_ERROR_NOT_REGISTERED202 
SNARL_ERROR_CLASS_BLOCKED 205 
SNARL_ERROR_CLASS_NOT_FOUND 206 
SNARL_ERROR_NOTIFICATION_NOT_FOUND207 
SNARL_ERROR_FLOODING208 
SNARL_ERROR_DO_NOT_DISTURB 209 
SNARL_ERROR_COULD_NOT_DISPLAY 210 
SNARL_ERROR_AUTH_FAILURE 211 
SNARL_ERROR_DISCARDED 212 
SNARL_ERROR_NOT_SUBSCRIBED 213 


Examples


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.