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.
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/?
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:
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:
.Signature = "test/my_test_app"
.Title = "My Test App"
The application is now ready to register with Snarl. To do that you can either call SnarlApp.Register, as follows:
Or you can create a notification and display it, which will cause the application to register at the same time.
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:
Set pClasses =
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.
Before your application exits, you must call TidyUp(). This ensures any resources created by the framework are released and also manages unregistering your application.
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.
Returns the number of items in the object.
Removes all entries from the object.
Removes the entry at 1-based Index from the object.
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.
Returns the number of items in the object.
Removes all entries from the object.
Removes the class identified by Name from the object.
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.
Removes the custom argument identified by Name from the object.
|Name ||Type ||Description|
| Actions||Actions ||An Actions object which contains the actions associated with the notification. May be null. |
| CallbackScript||String||A path to a script file to be run when the user invokes (clicks) the notification. |
| CallbackScriptType||String||The type of script file defined above. Can be either "VBscript" or "Jscript" |
| Class||String ||The notification class to use when displaying the notification.|
| DefaultCallback||String||A path, URL, system command to execute when the user invokes (clicks) the notification |
| Duration||int32||The amount of time, in seconds, the notification should be displayed for. To use the system default, set to -1|
| Icon||String||An 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 |
| MergeUID||String||UID of notification to merge content with |
| Priority||int32 ||Urgency rating. Use -1 to indicate low priority, 0 to indicate normal priority, and 1 to indicate high priority|
| ReplaceUID||String||UID of notification to replace content with |
| Text||String||Notification body text |
| Title||String||Notification title text |
| UID||String||UID to assign to the notification |
Returns the path of Snarl's user configuration folder. Typically this is %APPDATA%/full phat/snarl/etc/
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.
Returns TRUE if Snarl is installed on the computer, FALSE otherwise.
Returns TRUE if Snarl is currently running, FALSE otherwise.
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.
Helper function. Ensures Path has a trailing backslash.
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.
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().
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.
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).
Reserved for future use.
Registers the application with Snarl. Before calling this function, ensure at least the Title and Signature properties have been completed.
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().
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.
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.
Generated when Snarl is launched.
Generated when Snarl quits.
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.
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.
Returns the version number of Snarl's notification engine. Snarl must be running for this function to succeed, otherwise the function will return zero.
Unregisters the application with Snarl, if this hasn't already been done, and frees resources allocated to the application.
Unregisters the application from Snarl.
Generated when Snarl detects the user has gone idle.
Generated when Snarl detects the user has returned to their computer.
|Name ||Type ||Description|
| Classes||Classes ||A Classes object which defines the notification classes associated with the application. May be null.|
| ConfigTool||String||A path to an external configuration tool which will be launched by Snarl when the user clicks the Configure... button against the application|
| Hint||String||A string which is displayed when the user clicks the About... button |
| Icon||String ||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|
| IsConnected||Bool||Read-only. Indicates |
| IsDaemon||Bool||If set to TRUE, indicates the application should be treated as a Snarl-Specific Application (SSA) and thus will appear in the Snarl Apps... menu|
| LibRevision||Int16||Identifies the revision of the Snarl Framework in use|
| LibVersion||Int16||Identifies the version of the Snarl Framework in use|
| RemoteComputer||String |
| Signature||String||Required: application signature |
| Title||String||Required: application title|
HIGH_PRIORITY = 1
LOW_PRIORITY = -1
NORMAL_PRIORITY = 0
SUCCESS = 0
ERROR_FAILED = 101
ERROR_UNKNOWN_COMMAND = 102
ERROR_ACCESS_DENIED = 121
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_DO_NOT_DISTURB = 209
ERROR_COULD_NOT_DISPLAY = 210
ERROR_NOT_SUBSCRIBED = 213
Blah, using VB6, the following is required:
Dim WithEvents myApp As
Actions object is one-use - once added to notification, adding and removing actions has no effect until next notification shown.
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:
- Inside the Form1 code module, navigate to the Form_Load() procedure and enter the following code:
Set myApp = New SnarlApp
.Signature = "test/sfw_super_simple_sample"
.Title = "Super Simple Sample"
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
.Title = "Hello, world!"
.Text = "From the Super Simple Sample demo"
.UID = "123456"
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:
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.