Developers‎ > ‎

API Reference

Introduction

This document provides an in-depth guide to using the Snarl API.  It is mainly targeted at developers who wish to add low-level support for Snarl into their application, or those developers who are creating an intermediary library which provides Snarl support for a particular programming language or environment; however other developers may find certain sections - for example the Command Reference useful too.

The Transports section provides details about the built-in transports which Snarl supports, and how to interface directly with them; the Command Reference includes commands added to V43 API, which was released with Snarl R2.5.

First, a quick re-cap on the request structure:

Request Structure

Applications talk to Snarl by sending it a request.  A request is simply a command with zero or more arguments separated by ampersands, and each argument consists of a variable name and value separated by an equals sign.  If a command has arguments, the first argument is separated from the command by a question mark.  The following is an example request:

notify?app-sig=some/app&title=Hello, world!&text=This is a notification

A note on character escaping: Attempting to use ampersands and equals signs within arguments will be misinterpreted by Snarl as marker characters and result in (at best) a malformed notification appearing.  To avoid this, use double ampersands and double equals signs respectively (question marks do not need to be treated in the same way as Snarl is only concerned about the first question mark it finds within the request).  Snarl also supports the use of URL escaped characters, so "%20" would be translated by Snarl into a space character for example.

Transports

How the request is actually sent to Snarl depends on the transport that is used.  A transport is a low-level mechanism that handles the communication between the application and Snarl itself.  Transports are built directly into Snarl.

A transport can be likened to a device driver and an operating system kernel, with the application playing the part of the device, and Snarl playing the part of the kernel.  The transport thus has two parts to it: a logical part which defines the protocol used, and a physical part which translates the protocol into something Snarl can understand.

Like a device driver, a transport handler must be robust and efficient and, also like device drivers, they run at a privileged level of execution (in this case, running in Snarl's process space).

Currently, Snarl supports three transports:
  • Win32 IPC
  • Snarl Network Protocol (SNP)
  • Growl Notification Transport Protocol (GNTP)

Win32 IPC

The Win32 IPC transport uses Windows messages to direct the notification content from the application to Snarl.  Consequently, this transport can only be used for local-to-local communication, however it does support multi-user environments.

Read more about the Win32 IPC transport.

SNP

SNP is a TCP/IP based protocol which can direct notifications to both the local computer or to a remote computer.  This transport does not support multi-user environments.

Read more about SNP here.

GNTP

GNTP is a TCP/IP based protocol defined by the Growl notification application.  It follows a format similar to email MIME.  This transport does not support multi-user environments.

Read more about GNTP here.

Hybrid Transports

Bit about them here

SNP/HTTP

SNP/HTTP (SNP over HTTP) is an extension to SNP which allows applications to communicate with Snarl using HTTP.  This can be particularly useful for browser-based applications which do not have access to the local computer's IP sockets.  While not a transport in its own right, it acts in a very similar way to one by translating incoming HTTP requests and then passing them to Snarl using the Win32 IPC transport.

Read more about SNP/HTTP here.

Status Codes

All requests will return a status code, however different transports handle responses in different ways so reference should be made to the documentation for the transport you are using for details on how this is done.

A status code of zero indicates success.  The remaining codes are grouped into two categories:
  • Errors (100-299)
  • Events (300-399)

Errors

An error indicates the request itself couldn't be fully completed.  In some cases the error may be fatal; in other cases the reason may be less serious.  Errors are sub-divided into two groups: the first group (codes 100-199) deal with system and transport errors; the second group (200-299) covers application errors:

System and Transport Errors

NameCode Description
SNARL_ERROR_FAILED 101General failure of some sort 
SNARL_ERROR_UNKNOWN_COMMAND 102The command was not recognised 
SNARL_ERROR_TIMED_OUT 103Snarl took too long to respond
SNARL_ERROR_BAD_SOCKET 106 The communication socket was closed unexpectedly  
SNARL_ERROR_BAD_PACKET 107 Badly formed SNP request 
SNARL_ERROR_INVALID_ARG 108 An invalid parameter was provided 
SNARL_ERROR_ARG_MISSING 109 A required argument was missing    
SNARL_ERROR_SYSTEM 110 Internal system error 
SNARL_ERROR_ACCESS_DENIED 121The command was not allowed (applies to the Snarl Framework only)

Application Errors

Name Code Description
SNARL_ERROR_NOT_RUNNING201Snarl isn't running on the local (or, in the case of a network request, remote) computer 
SNARL_ERROR_NOT_REGISTERED202An attempt was made to create a notification before the application was registered 
SNARL_ERROR_ALREADY_REGISTERED203The application is already registered 
SNARL_ERROR_CLASS_ALREADY_EXISTS204The class specified is already registered 
SNARL_ERROR_CLASS_BLOCKED 205The user has disabled notifications from this class 
SNARL_ERROR_CLASS_NOT_FOUND206The specified class was not found 
SNARL_ERROR_NOTIFICATION_NOT_FOUND207The specified notification was not found 
SNARL_ERROR_FLOODING208The notification was not displayed as it would cause flooding of the display 
SNARL_ERROR_DO_NOT_DISTURB209The user has enabled Do Not Disturb mode 
SNARL_ERROR_COULD_NOT_DISPLAY210No enough screen space exists to display the notification 
SNARL_ERROR_AUTH_FAILURE211Password mismatch 
SNARL_ERROR_DISCARDED 212The notification was discarded, usually because the sending application was in the foreground 
SNARL_ERROR_NOT_SUBSCRIBED 213Subscriber does not exist 

Events

Event codes are used when Snarl notifies the sending that something has happened.  Typically this will be due to some element of user interaction, or lack thereof.  Each transport defines its own methods for communicating an event, and not all transports support events - hence the documentation for the particular transport in use should be consulted for further information.

Name Code Description
SNARL_NOTIFY_GONE301Reserved for future use 
SNARL_NOTIFY_CLICK 302Deprecated: notification was right-clicked
SNARL_NOTIFY_EXPIRED 303Notification timed out
SNARL_NOTIFY_INVOKED 304Notification was clicked by the user
SNARL_NOTIFY_MENU 305Deprecated: item was selected from the notification's menu
SNARL_NOTIFY_EX_CLICK 306Deprecated: user clicked the middle mouse button on the notification
SNARL_NOTIFY_CLOSED 307User clicked the notification's Close gadget 
SNARL_NOTIFY_ACTION 308User selected an action from the notification's Actions menu

Command Reference

Bit about commands here

addaction

Adds an action to an existing notification (deprecated).

Arguments

Parameter Requirement Description
app-sig Required  The application's signature. 
uid Required The notification's unique identifier
label  Required  The text to be displayed to the user in the Actions drop-down menu
cmd  Required  Command to be invoked by Snarl (see notes)
passwordOptionalPassword used during registration.

Return Value

Return value is SNARL_SUCCESS if the action was added successfully, SNARL_ERROR_MISSING_ARG if either label or cmd are missing, SNARL_ERROR_NOTIFICATION_NOT_FOUND if the notification wasn't found, or SNARL_ERROR_AUTH_FAILURE if an incorrect password was supplied.
 
Notes
  • This command is now deprecated; applications should use notify to add actions to notifications
  • The cmd argument can take one of three forms, as follows:
TypeFormatAction TakenExamples
Static callback  URL or path to file or folder  Specified file, folder or URL is launched by Snarl c:\my_batch_file.bat
http://www.getsnarl.info

Dynamic callback  @{identifier}  Snarl notifies the application with a SNARL_NOTIFY_ACTION callback, passing {identifier} back to the application @123456
@email::1a2b3c4d5e
System command  !{command} Invokes a pre-defined system command - see here for details of currently implemented commands.  !taskmgr 
  • The return value (and thus end result) is unpredictable if an action with the same command already exists.

addclass

Adds a notification class to a previously registered application.

Arguments

Parameter Requirement Description
app-sig Required  The application's signature used during registration.
id Required The identifier used by subsequent notifications.
passwordOptionalThe password used during registration.
name  Optional  The user-friendly name of the class.
enabled  Optional  Should be one if the class is to be enabled by default, or zero otherwise.  The default is one.
callback Optional  Default callback to be used if a notification created using this class does not specify one.
title  Optional  Default title to be used if a notification created using this class does not specify one.
text  Optional Default text to be used if a notification created using this class does not specify one.
icon  Optional  Default icon to be used if a notification created using this class does not specify one.
sound  Optional  Default sound to be used if a notification created using this class does not specify one.

Return Value

Returns SNARL_SUCCESS if the notification was successfully hidden (or removed from the missed list), SNARL_ERROR_NOT_REGISTERED if the application wasn't found, or SNARL_ERROR_AUTH_FAILURE if an incorrect password was supplied.

Notes
  • As of V43, you can use class-id in place of id and class-name in place of name
  • name is what the end user sees in Snarl's preferences window and thus should be more meaningful than the identifier.  If it is not specified, id is displayed instead




clearactions

Removes all actions associated with the specified notification.

Arguments

Parameter Requirement Description
app-sig Required  The application's signature.
uid  Required  The notification's unique identifier.
passwordOptionalPassword used during registration. 

Return Value

Returns SNARL_SUCCESS if the successfully removed, SNARL_ERROR_NOTIFICATION_NOT_FOUND if the notification wasn't found, or SNARL_ERROR_AUTH_FAILURE if an incorrect password was supplied.

Notes
  • Consideration should be taken when using this command as it will undoubtedly be confusing for an end-user if the actions assigned to a notification are removed while it is still visible on-screen.


clearclasses

Removes all classes associated with a particular application.

Arguments

Parameter Requirement Description
app-sig Required  The application's signature.
password Optional  Password used during registration. 

Return Value

Returns SNARL_SUCCESS if the successfully removed, SNARL_ERROR_NOT_REGISTERED if the application wasn't found, or SNARL_ERROR_AUTH_FAILURE if an incorrect password was supplied.

Notes
  • This is a more convenient way of doing 
    remclass?app-sig=some/app&all=1


hello

Effectively a no-op.  It can be useful however to:
  • Confirm Snarl is running
  • Confirm Snarl is accepting notifications via the appropriate transport
  • Determine which version of Snarl is running.
Arguments

None.

Return Value

Returns the version number of Snarl.


hide

Removes the specified notification from the screen or missed list.

Arguments

Parameter Requirement Description
app-sig Required  The application's signature.
uid Required The notification's unique identifier.
passwordOptional Password used during registration.

Return Value

Returns SNARL_SUCCESS if the notification was successfully hidden (or removed from the missed list), SNARL_ERROR_NOTIFICATION_NOT_FOUND if the notification wasn't found, or SNARL_ERROR_AUTH_FAILURE if an incorrect password was supplied.

Notes
  • Consideration should be given to the circumstances around programmatically removing a notification.  See the following blog post for more information.



isvisible

Indicates whether or not the specified notification is still visible on-screen.

Arguments

ParameterRequirementDescription
app-sigRequired The application's signature.
uidRequiredThe notification's unique identifier.
passwordOptional Password used during registration.

Return Value

Returns SNARL_SUCCESS if the notification is still visible, SNARL_ERROR_NOTIFICATION_NOT_FOUND if the notification wasn't found, or SNARL_ERROR_AUTH_FAILURE if an incorrect password was supplied.

Notes
  • This action is of limited use as there exists the possibility that the notification will be visible when it is called, but will then immediately disappear (either due to it expiring, the user clicking it, or some other reason).  Consequently, although the request completed successfully, the actual result is invalid.  For this reason, applications should avoid relying on any value returned by this action.



notify

Displays a notification.

Arguments

ParameterRequirementDescription
app-sigRequired The application's signature used during registration.



passwordOptionalThe password used during registration.
id Optional The identifier of the class to use.
title Optional Notification title.
textOptional Notification body text.
timeout Optional The amount of time, in seconds, the notification should remain on screen.
icon OptionalThe icon to use, see the notes below for details of supported formats.
icon-base64 Optional Base64-encoded bytes to be used as the icon.
sound Optional The path to a sound file to play. 
callback Optional Callback to be invoked when the user clicks on the main body area of the notification.
uid OptionalA unique identifier for the notification so the sending application can track events related to it and update it if required. 
priorityOptionalThe urgency of the notification, 1 indicates high priority; -1 indicates low priority; 0 indicates normal priority, see Priorities in the Developer Guide for more information on how Snarl deals with different priorities. 
sensitivityOptionalThe sensitivity of the notification.  See the Sensitivity section in the Developer Guide for more information. 
replace-uidOptionalThe uid of an existing notification to replace. 
merge-uidOptionalThe uid of an existing notification to merge the content of this notification with.  
value-percentOptionalA decimal percent value to be included with the notification.  Certain styles can display this value as a meter or other visual representation.  See Custom Values in the Developer Guide for more information. 
action Optional An action to add to the notification, see Actions in the Developer Guide for more information.
logOptionalIf set to "0", the notification is not logged in the missed list or history.

Return Value

Returns a token (positive integer) if the notification was created successfully (not that it may not be displayed on screen depending on how the user has configured Snarl to respond), SNARL_ERROR_NOT_REGISTERED if the application wasn't found, or SNARL_ERROR_AUTH_FAILURE if an incorrect password was supplied.

Notes
  • Although individually optional, at least one of title, text and icon must be supplied for the command to succeed;
  • A timeout of zero means the notification should remain on screen until the user dismisses it (behaviour commonly referred to as "sticky"); a timeout of -1 (the default) indicates the notification should user the default duration - this is the recommended practice;
  • icon can be a fully qualified path to an image on a local or remote filesystem, a URL, a standard Snarl icon (if prefixed with '!') or an HICON (if prefixed with '#').  If no icon is provided, Snarl will attempt to use the application's own icon - see the Icons section in the Developer Guide for more information;
  • icon-base64 allows icon data to be included with the notification, which can be useful if the notification is being sent from one computer to another computer.  If both icon and icon-base64 are supplied, icon will take precedence;
  • If id is not specified, the notification will be displayed using the All/Other Notifications class;
  • If any of title, text, timeout, callback or sound are not supplied, then the corresponding class default will be used, if it exists;
  • sound can be a WAV or MP3 file, or (if prefixed with an exclamation mark) a Windows system sound;
  • callback is invoked when the user clicks the body area of the notification (any part of the notification not covered by a gadget); however, applications should consider using actions in preference to the callback feature of notifications, see the Notification Guidelines section in the Developer Guide for more information;
  • Any number of action arguments may be included within a single notify request.  See Actions in the Developer Guide for more details;
  • Depending on the state of the user at the time the notification appears, Snarl may alter the priority or timeout values of the notification before displaying it.  Consequently, these values should be considered as recommendations from the sending application but no more than that;
  • uid can be used to uniquely identify the notification after it has been displayed by Snarl, for example to update its content, replace it or merge additional content in.  The uid is also included in an event generated by the notification;
  • Support for value- arguments depends on the particular style used to display the notification.  See Custom Values in the Developer Guide for more information;
  • The log command is useful for applications which generate transient notifications which are of no use to the users from a historical perspective.  Such notifications could include an hourly reminder or the changing of the currently playing music track.  However, generally speaking, it's good practice to allow the user to decide which notifications should be logged.  It should be noted that, as of Snarl V45, all notifications are written to APP_DATA\full phat\snarl\snarl_log.txt, irrespective of the user's preferences and the value of this argument.


register

Registers an application with Snarl.

Arguments

Parameter Requirement Description
app-sig Required  The application's signature  
uid Required The notification's unique identifier
title  Required  The application's name 
icon  Optional  The icon to use - see notes for more details 
reply-to  Optional  Win32 transport only: the handle to a window (HWND) which Snarl should post events to 
reply-with  Optional  Win32 transport only: the message Snarl should use to post to the reply-to Window  
passwordOptionalPassword used during registration
keep-alive OptionalPrevent application from being removed during garbage collection

Notes
  • title is the actual name of the application which is displayed when the application first registers with Snarl and also appears in the applications list within Snarl's preferences UI. Unlike the signature, it does not need to be unique (however, logic dictates it should be);
  • icon can be a fully qualified path to an image on a local or remote filesystem, a URL, a standard Snarl icon (if prefixed with '!') or an HICON (if prefixed with '#').  If no icon is provided, Snarl will attempt to use the application's own icon - see the Icons section in the Developer Guide for more information;
  • reply-with and reply-to are both optional but one cannot be specified without the other.  These parameters apply to the Win32 transport only - see the documentation on this transport for more information;
  • From release 2.5.1 onwards, Snarl will periodically check for applications which appear to be orphaned - that is, an application which has registered but the process which registered it no longer exists.  For some environments, especially script and command-line ones, this can create a situation where a process launches to register an application, but then disappears once the command has been carried out.  To prevent such a registration from being automatically removed during the garbage collection, use keep-alive=1 when registering.  Your application must unregister itself manually and must (if it uses one) manage the registration password correctly;
  • Applications may also use reg instead of register, it does exactly the same thing.
Return Value

Return value is greater than zero if the application was successfully registered, SNARL_ERROR_ARG_MISSING if any of the required arguments are missing, or SNARL_ERROR_AUTH_FAILURE if Snarl detects a re-registration without a matching password.


remclass

Removes a particular notification class from a registered application.

Arguments

Parameter Requirement Description
app-sig Required  The application's signature  
password Optional  Password used during registration 
id  Optional  The identifier of the class to remove 
all  Optional  If 1, removes all classes associated with the specified application 

Return Value

Return value is SNARL_SUCCESS if the class was removed okay, SNARL_ERROR_CLASS_NOT_FOUND if the specified class doesn't exist, SNARL_ERROR_NOT_REGISTERED if the application wasn't found, SNARL_ERROR_ARG_MISSING if neither all nor id is supplied, or SNARL_ERROR_AUTH_FAILURE if an incorrect password was supplied.


subscribe

Subscribes to all notifications or notifications from specific applications.  Any number of app-sig entries can be provided and these applications need not already be registered with Snarl.  At present password is optional, however it is good practice to supply a strong password and it is likely the requirement for a password will be mandatory in future revisions of the API.

Arguments

Parameter Requirement Description
app-sig Optional Zero or more signatures of applications to subscribe to.  If no signatures are supplied, notifications from all applications will be received. 
password Optional  Password used for the subscription. 


Return Value

Clients can issue any number of further subscribe requests, however they must supply the same password each time otherwise the request will fail with SNARL_ERROR_AUTH_FAILURE.

Notes
  • Requires Snarl V43;
  • This action can only be issued via SNP 3.0; attempting to send it via an other transport protocol will result in a SNARL_ERROR_BAD_SOCKET response.

test

Displays a notification if Snarl is running in Debug Mode.

Arguments

None.

Return Value

Returns SNARL_SUCCESS if Snarl is running in debug mode and the test notification was displayed sucessfully, SNARL_UNKNOWN_COMMAND if Snarl is running but is not in debug mode and  otherwise.

unregister

Unregisters the specified application.

Arguments

Parameter Requirement Description
app-sig Required  The application's signature. 
password Optional  Password used during registration 

Return Value

Returns SNARL_SUCCESS if the application was unregistered okay, SNARL_ERROR_NOT_REGISTERED if the application wasn't found, or SNARL_ERROR_AUTH_FAILURE if an incorrect password was supplied.

Notes
  • Applications may also use unreg instead of unregister, it does exactly the same thing.

updateapp

Updates specific details about an already registered application.

Notes
    This action is deprecated.


    update

    Updates the content of an existing on-screen notification.

    Notes
      This action is deprecated.  Instead, applications should re-issue a notify command using the same UID - if the notification is still visible on-screen, it will be updated, otherwise a new notification will be created.


      version

      Effectively a no-op.  It can be useful however to:
      • Confirm Snarl is running;
      • Confirm Snarl is accepting notifications via the appropriate transport medium;
      • Determine which version of Snarl is running.
      Arguments

      None.

      Return Value

      Returns the system version number of Snarl.