Developers‎ > ‎

Snarl Framework

Introduction

The Snarl Framework (SFW) provides an easy to use and all-encompassing library for communicating with Snarl.  NEEDS WORK.
  • Multi-language support: the SFW It is accessible from any language which supports ActiveX (COM) components;
  • It supports both local and remote notifications seamlessly;
  • Built-in notification style: The framework provides an engine which displays a basic notification if Snarl is not installed or running on the computer;
  • No dependencies: The SFW does not depend on any other libraries, run-times or frameworks, and thus supports platforms which Snarl doesn't support natively (for example, Windows 98 and NT4.0).  This allows you to build applications which can run on older versions of Windows and forward notifications to an instance of Snarl running on a supported version of Windows.
NEEDS WORK


Framework Overview

Downloading the Framework

The framework is called libsnarl-x-y.dll (where '-x-y' is the version of the framework).  Generally speaking, the framework is forwards compatible with newer versions of Snarl, but is unlikely to be backwards compatible.  The framework is included in the main Snarl installation, but can also be downloaded from here: https://sourceforge.net/projects/snarlwin/files/libSnarl/?

Setting Up

The Snarl Framework will work with any language which supports the creation of ActiveX/COM objects so languages such as .net, VB6, Delphi and VBscript.  Depending on the language you're using, you may need to create a reference to the Framework, in which case this will be either the Snarl Framework 2.5 type library or libsnarl-2-5.dll, depending on the requirements of the language.

Once your application is referencing the Snarl Framework, the next thing to do is create an instance of a SnarlApp object as this provides a link between your application and Snarl.  Again, how this is achieved depends on the programming language used.  For example, using VB6, the following is required:
 
Set myApp = New SnarlApp

Similarly VBscript requires the following:

Set myApp = CreateObject("libsnarl25.snarlapp")

Once a new SnarlApp object has been created, it needs to be initialised.  Most properties are optional; the following is the most basic requirement: 
 
With myApp
    .Signature = "test/my_test_app"
    .Title = "My Test App"

End With 

Registering

The application is now ready to register with Snarl.  To do that you can either call SnarlApp.Register, as follows:

myApp.Register

Or you can create a notification and display it, which will cause the application to register at the same time. 

Managing Classes

Notification classes are managed by the Classes object and assigned to an application via the SnarlApp.Classes property.  A new SnarlApp object doesn't create a Classes object by default, so this must be done before adding any classes to it.

The following code creates a new Classes object. adds a class to it and assigns it to the SnarlApp object created above:
 
Dim pClasses As Classes
 
    Set pClasses = New Classes
    pClasses.Add "1", "My class"
    myApp.Classes = pClasses
 
Note that once the application has registered with Snarl, any subsequent changes to the assigned Classes object are replicated immediately within Snarl.

Removing classes is unusual.


Managing Notifications

Blah 

Create

Update

Replace

Merge




Tidying Up

Before your application exits, you must call TidyUp().  This ensures any resources created by the framework are released and also manages unregistering your application.

Classes and Methods

Actions

Details here

Add()

void Add(str Label, str Command)

Adds an action.  Label is displayed in the notification's Actions menu; Command is either acted on by Snarl, or returned to the application as a callback, depending on the type of command specified.

Count()

int32 Count()

Returns the number of items in the object.

MakeEmpty()

void MakeEmpty()

Removes all entries from the object.

Remove()

Remove(int32 Index)

Removes the entry at 1-based Index from the object.


Classes

Details here

Add()

void Add(str Name, str Description, [bool Enabled = TRUE], [str DefaultTitle], [str DefaultText], [str DefaultIcon], [str DefaultCallback], [str DefaultDuration = -1], [str DefaultSound])

Adds a new class to the object.  Name is used to identify the class within Snarl; Description is used to identify the class to the end user.  If the class should be disabled by default, then Enabled should be set to FALSE, otherwise it can be omitted.

DefaultTitle, DefaultText, DefaultIcon, DefaultCallback, DefaultDuration and DefaultSound are used by Snarl if the corresponding element of any notification created using the class is not specified.

Count()

int32 Count()

Returns the number of items in the object.

MakeEmpty()

void MakeEmpty()

Removes all entries from the object.

Remove()

Remove(str Name)

Removes the class identified by Name from the object.


Notification

Details here

Add()

void Add(str Name, str Value, [bool UpdateIfExists = FALSE])

Adds a new custom argument called Name with Value to the notification.  If the argument already exists and UpdateIfExists is TRUE, the existing argument is changed to the new value, otherwise it is left the same.

Remove()

Remove(str Name)

Removes the custom argument identified by Name from the object.

Properties

Name Type Description
 ActionsActions An Actions object which contains the actions associated with the notification.  May be null. 
 CallbackScriptStringA path to a script file to be run when the user invokes (clicks) the notification. 
 CallbackScriptTypeStringThe type of script file defined above.  Can be either "VBscript" or "Jscript" 
 ClassString The notification class to use when displaying the notification.
 DefaultCallbackStringA path, URL, system command to execute when the user invokes (clicks) the notification 
 Durationint32The amount of time, in seconds, the notification should be displayed for.  To use the system default, set to -1
 IconStringAn image, URL that points to an image, Windows icon, or index of an icon in a resource file to use as the notification's icon 
 MergeUIDStringUID of notification to merge content with 
 Priorityint32 Urgency rating.  Use -1 to indicate low priority, 0 to indicate normal priority, and 1 to indicate high priority
 ReplaceUIDStringUID of notification to replace content with 
 TextStringNotification body text 
 TitleStringNotification title text 
 UIDStringUID to assign to the notification 


SnarlApp

Details here

Activated() Event

Remove(int32 Index)

Blah

GetEtcPath()

str GetEtcPath()

Returns the path of Snarl's user configuration folder.  Typically this is %APPDATA%/full phat/snarl/etc/

Hide()

STATUS_CODE Hide(str UID)

Attempts to forcibly remove the notification with the specified UID from the screen.  The return value will be SUCCESS or some error if the request failed.

IsSnarlInstalled()

bool IsSnarlInstalled()

Returns TRUE if Snarl is installed on the computer, FALSE otherwise.

IsSnarlRunning()

bool IsSnarlRunning()

Returns TRUE if Snarl is currently running, FALSE otherwise.

IsVisible()

STATUS_CODE IsVisible(str UID)

Returns SUCCESS if the notification specified by UID is still visible on-screen or ERROR_NOTIFICATION_NOT_FOUND if it isn't.

Don't rely too much on this: it's very easy for a race condition to occur whereby an application calls this function, receives a positive response (indicating the notification is still visible) and then performs some action based on this while in the meantime the notification has expired or been invoked by the user.  In practice, use of this function should be avoided.

MakePath()

str MakePath(str Path)

Helper function.  Ensures Path has a trailing backslash.

NotificationActionSelected() Event

void NotificationActionSelected(str UID, str Identifier)

Generated when the user selects an entry from a notification's Actions Menu.  UID indicates the notification itself; Identifier is the action's command.

NotificationClosed() Event

void NotificationClosed(str UID)

Generated when the notification identified by UID is closed by the user clicking on the notification's Close gadget.  Note that this event is not generated in response to a call to Hide().

NotificationExpired() Event

void NotificationExpired(str UID)

Generated when the notification identified by UID has disappeared because it's specified duration has elapsed and the user did not invoke it.

NotificationInvoked() Event

void NotificationInvoked(str UID))

Generated when the notification identified by UID has been invoked by the user clicking on the notification's main body (that is, anywhere other than the Close or Actions gadgets).

Quit() Event

void Quit()

Reserved for future use.

Register()

STATUS_CODE Register()

Registers the application with Snarl.  Before calling this function, ensure at least the Title and Signature properties have been completed.

Show()

STATUS_CODE Show(Notification Notification)

Requests Snarl displays Notification.  If the application hasn't already registered with Snarl, this will be done automatically by Show().

ShowAbout() Event

void ShowAbout()

Generated when the user clicks the Details button on the [Apps] page within Snarl's preferences.  This even is only generated if the Hint property is blank.

ShowConfig() Event

void ShowConfig()

Generated when the user clicks the Settings... button on the [Apps] page within Snarl's preferences.  This even is only generated if the ConfigTool property is blank.

SnarlLaunched() Event

void SnarlLaunched()

Generated when Snarl is launched.

SnarlQuit() Event

void SnarlQuit()

Generated when Snarl quits.

SnarlStarted() Event

void SnarlStarted()

Generated when Snarl's notification handling engine starts.  This happens when Snarl is first launched, and subsequently when resuming after the user has stopped the engine from Snarl's tray icon.

SnarlStopped() Event

void SnarlStopped()

Generated when Snarl's notification handling engine stops.  This happens when Snarl terminates, and also when the user stops the engine by selecting Stop Snarl from Snarl's tray icon menu.

SnarlVersion()

int32 SnarlVersion()

Returns the version number of Snarl's notification engine.  Snarl must be running for this function to succeed, otherwise the function will return zero.

TidyUp()

void TidyUp()

Unregisters the application with Snarl, if this hasn't already been done, and frees resources allocated to the application.

Unregister()

STATUS_CODE Unregister()

Unregisters the application from Snarl.

UserAway() Event

void UserAway()

Generated when Snarl detects the user has gone idle.

UserReturned() Event

void UserReturned()

Generated when Snarl detects the user has returned to their computer.

Properties

Name Type Description
 ClassesClasses A Classes object which defines the notification classes associated with the application.  May be null.
 ConfigToolStringA path to an external configuration tool which will be launched by Snarl when the user clicks the Configure... button against the application
 HintStringA string which is displayed when the user clicks the About... button 
 IconString An image, URL that points to an image, Windows icon, or index of an icon in a resource file to use as the application's icon
 IsConnectedBoolRead-only.  Indicates 
 IsDaemonBoolIf set to TRUE, indicates the application should be treated as a Snarl-Specific Application (SSA) and thus will appear in the Snarl Apps... menu
 LibRevisionInt16Identifies the revision of the Snarl Framework in use
 LibVersionInt16Identifies the version of the Snarl Framework in use
 RemoteComputerString 
 SignatureStringRequired: application signature 
 TitleStringRequired: application title
 

Enumerations

NOTIFICATION_PRIORITY

HIGH_PRIORITY    = 1
LOW_PRIORITY     = -1
NORMAL_PRIORITY  = 0

STATUS_CODE

SUCCESS                       = 0
ERROR_FAILED                  = 101
ERROR_UNKNOWN_COMMAND         = 102
ERROR_TIMED_OUT               = 103
ERROR_BAD_SOCKET              = 106
ERROR_BAD_PACKET              = 107
ERROR_INVALID_ARG             = 108
ERROR_ARG_MISSING             = 109
ERROR_SYSTEM                  = 110
ERROR_ACCESS_DENIED           = 121
ERROR_NOT_RUNNING             = 201
ERROR_NOT_REGISTERED          = 202
ERROR_ALREADY_REGISTERED      = 203
ERROR_CLASS_ALREADY_EXISTS    = 204
ERROR_CLASS_BLOCKED           = 205
ERROR_CLASS_NOT_FOUND         = 206
ERROR_NOTIFICATION_NOT_FOUND  = 207
ERROR_FLOODING                = 208
ERROR_DO_NOT_DISTURB          = 209
ERROR_COULD_NOT_DISPLAY       = 210
ERROR_AUTH_FAILURE            = 211
ERROR_DISCARDED               = 212
ERROR_NOT_SUBSCRIBED          = 213



Advanced Features

Blah


Handling Callbacks 

Blah, using VB6, the following is required:

 
Dim WithEvents myApp As SnarlApp



Using Actions

Blah
Actions object is one-use - once added to notification, adding and removing actions has no effect until next notification shown.

Network Notifications 

Blah 

Built-In Notification 

Blah
 
 
 



Tutorials

The follow tutorials use the Snarl Framework within Visual Basic 6, however it should be very easy to translate them into other programming languages.  The first tutorial builds a simple application in stages by adding functionality along the way; the second is a simple application which uses the Snarl Network Protocol to mimic sending messages from one machine to an instance of Snarl running on another.

The Super Simple Sample

Part 1 - The Basics

  • Create a new Standard EXE Project and name it "super_simple_sample"
  • Add a reference to "Snarl Framework 2.5 (V43)" by selecting Project > References and picking it from the list of available references
  • Inside the Form1 code module, navigate to the declarations area and enter the following:
Dim myApp As SnarlApp
  • Inside the Form1 code module, navigate to the Form_Load() procedure and enter the following code:
Set myApp = New SnarlApp

With myApp
    .Signature = "test/sfw_super_simple_sample"
    .Title = "Super Simple Sample"

End With

The above code creates a new instance of a SnarlApp object - this is the applications link with Snarl and what we'll use to create notifications with.  Before we can register with Snarl, we need to configurate the object a little.  The above is the absolute minimum required by Snarl for an application to be successfully registered.  Next, we'll create a notification.
  • Add a CommandButton to Form 1, double-click it to bring up the Command1_Click() procedure and enter the following code:
Dim pn As Notification

Set pn = New Notification
With pn
    .Title = "Hello, world!"
    .Text = "From the Super Simple Sample demo"
    .UID = "123456"

End With

myApp.Show pn

This creates a new Notification object, and configures it with the bare minium of information (in actual fact, the UID property is not mandatory but we'll refer to it later on).  The call to myApp.Show actually causes the notification to be displayed.

Don't be tempted to run the program just yet however - there's one very important step left.
  • Navigate to the Form_Unload() procedure and enter the following:
myApp.TidyUp

This is very important as otherwise the application will remain registered with Snarl after it has terminated and, as the Snarl Framework secures applications using passwords by default, re-running the application will not re-register it with Snarl.

Make sure Snarl is running, and then start the application.  Clicking on the "Command1" button should generate the following notification:


Part 2 - Adding a Class


 

Step 3 - 


PhatJet 3000x Printer Status App

Ficticious printer called the PhatJet 3000x.

Sends paper out, paper jammed, print complete notifications to a central server so technicians can visit printer if required.