| Introduction | API Reference | Porting | Example Code |
This guide refers to the version of Snarl currently in development. API definitions listed with a (V37) after the name relate to functions expected to be included in the next release of Snarl.
Adding Snarl support to your application is incredibly simple. No, really, it is. Generally speaking, if you're using a traditional programming language such as C, C++, C#, Delphi, Visual Basic, etc. then it's no more difficult than adding one or two more include files to your project.
Applications talk to Snarl by sending it a packet of information wrapped in either a SNARLSTRUCT or SNARLSTRUCTEX datatype (more on these later). The packet is then sent to the Snarl Dispatcher window using the Windows WM_COPYDATA message.
Of course, this is not particularly intuitive, so there is a formal API defined which wraps all this message passing into a set of easy to use functions. These functions are then made available for different programming languages as include files. At the time of writing, there are include files for C#, C++, Delphi, REALBasic and VisualBasic 5/6. There are a number of others in progress, including C, VB.net, Python and Ruby. If you'd like to have a go at including support for another programming language, see this page for more information.
Displaying a notification is very straightforward: simply call snShowMessage() specifying what you want displayed in the title and text areas. You can also specify a timeout interval (in seconds), an icon and provide a window handle and message that Snarl will send to it if the user right-clicks the message, acknowledges the message (by left-clicking it), or the timeout interval expires. These last two parameters are discussed in more detail later on.
Assuming snShowMessage() was successful, it will have returned a non-zero value. This value represents your notification's unique identifer which you can use to either update the title and text of the message, timeout period (Snarl V37 or newer) or hide the message without waiting for the user to acknowledge it. Use snUpdateMessage() to change the title or text, snSetTimeout() to alter the timeout value, or snHideMessage() hide an existing notification.
Applications can register with Snarl. Although not a mandatory requirement (applications can still create notifications without first registering with Snarl), application developers are encourage to register their application with Snarl. Starting with Snarl V37 (R1.6), registering has the following benefits:
To register your application with Snarl, call either snRegisterConfig() or, under V37, snRegisterConfig2(). The latter allows you to specify a PNG icon which Snarl displays in it's Applications list.
Typically, an application will register with Snarl during its start-up procedures. Once an application exits, it should revoke its registration with Snarl by calling snRevokeConfig(). This flow diagram shows the process in more detail:
Snarl V37 extends the functionality available to both applications which use Snarl to display notifications, and to the end user running Snarl through the use of alerts. These sit between the application and Snarl and provide an intuitive way for the user to manage which alerts an application displays.
Alerts are given a class name and are registered using snRegisterAlert(). As the class name is displayed in Snarl's configuration panel, it makes sense to give this a human-readable name - for example, "Low disk space", as opposed to "vol_spc_low".
Say, for example, you're writing an application which generates three specific types of alert: when disk space on a particular drive drops below a certain number of Megabytes, when processor utilisation is over 90% for more than 30 seconds, and when available physical memory drops below 100 Megabytes. Each of these events can now be declared as an individual alert class, these are then displayed in Snarl's configuration panel underneath the application's registration details. For example:
snRegisterConfig2 myWindow, "My Monitoring App", myReply, "my_app_icon.png" snRegisterAlert "My Monitoring App", "Disk space low" snRegisterAlert "My Monitoring App", "High processor utilization" snRegisterAlert "My Monitoring App", "Physical memory low"
This appears in the Snarl configuration panel as so:
The user can now choose which of the three alerts are displayed by Snarl and no extra configuration is required within the application itself.
This section is still in development
When Snarl first starts up it registers a global Windows message called 'SnarlGlobalEvent'. Once Snarl has completed its startup routine, it broadcasts this message to all top-level windows with the wParam parameter set to SNARL_LAUNCHED, applications that work with Snarl can detect this message and reconfigure themselves accordingly.
Similarly, when Snarl stops running it broadcasts the same message, but this time with wParam set to SNARL_QUIT. If an application has registered its user interface with Snarl, the message value that was registered at the time is also sent, again with wParam set to SNARL_QUIT.
There are two simple ways to detect if Snarl is running. If you're using V37 or later includes you can call snGetSnarlWindow(), which will return non-zero if Snarl is running, or zero if it isn't. Note that this function will still work even if an earlier version is installed on the user's computer as the method used by snGetSnarlWindow() is backwards compatible.
If you're forced to use pre-V37 includes you can call snGetVersion() and test the return value. It will be True if Snarl is running, or False if it isn't.
In some cases it may be useful to know which version of Snarl is installed on a user's computer. With the release of V37 (R1.6) there are two ways to check for this. The preferred way is to call snGetVersionEx(). This returns an integer value which indicates the system version of Snarl installed. Release 1.6 is system version 37, subsequent releases will have consecutively numbered system versions.
The other, less preferred, method is to call snGetVersion() and test the returned Major and Minor values. Prior to V37, this is the only method available.
Prior to V37, double-clicking an entry in Snarl's Applications list would cause the window which was registered to be displayed on-screen. While useful for applications which did not provide access to their own UI, this behaviour is not always desirable. Starting with V37, applications can prevent Snarl from displaying the window passed in snRegisterConfig() or snRegisterConfig2() by ensuring the window itself has no title.
If ReplyMsg specified in either of the above functions was non-zero, and the configuration window has no title, Snarl will send this message back to the configuration window with SNARL_SHOW_APP_UI in wParam.