Send Feedback

API Reference

This section defines the standard Application Programming Interface which all languages must support. If you're interested in porting Snarl support to another programming language, see the Porting page for further information.

• Datatypes
  
• The M_RESULT Enum
  
• snGetAppPath (V37)
  
• snGetGlobalMsg
  
• snGetIconsPath (V37)
  
• snGetSnarlWindow (V37)
  
• snGetVersion
  
• snGetVersionEx (V37)
  
• snHideMessage
  
• snIsMessageVisible
  
• snRegisterAlert (V37)
  
• snRegisterConfig
  
• snRegisterConfig2 (V37)
  
• snRevokeConfig
  
• snSetTimeout (V37)
  
• snShowMessage
  
• snShowMessageEx (V37)
  
• snUpdateMessage
  

As all programming languages give different (and sometimes conflicting) names to different datatypes we have decided to show syntax declarations in pseudo code. This allows them to be programming language agnostic and generally eases readability. The following table aims to explain the various datatypes used and to give equivalents for certain languages:

Additionally, the following table explains other mnemonics used:

A number of functions return a value within the M_RESULT enum. This enum is defined in the melon core objects type library (melon.tlb) and is reproduced here for reference. See the individual functions description for the specific meaning of the returned value.

int32 snGetGlobalMsg()

Returns the atom that corresponds to the "SnarlGlobalEvent" registered Windows message. This message is sent by Snarl when it is first starts and when it shuts down. See the Snarl startup and shutdown section for more information.

This function should always succeed as it either returns the value of the existing atom or, if it doesn't already exist, it will create it and then return its value. If for some reason registering the atom fails, this function will return zero.

str snGetAppPath()

Returns a fully qualified path to Snarl's installation folder. Typically this will be c:\program files\full phat products\snarl\ but it can of course be whatever the user specified when Snarl was installed. Also note that this is the location where Snarl is currently running from, which is not necessarily the installed location (although it would be very unusual for these to differ). The returned path will have a trailing backslash appended if necessary.

If Snarl is not running an empty string will be returned.

str snGetIconsPath()

Returns a fully-qualified path to Snarl's default icon location. This is currently snGetAppPath()\etc\icons\ although this may change in future releases of Snarl. The returned path will have a trailing backslash appended if necessary.

If Snarl is not running an empty string will be returned.

int32 snGetSnarlWindow()

Returns a handle to the current Snarl Dispatcher window, or zero if it wasn't found. This is the recommended way to test if Snarl is running or not.

bool snGetVersion(Major As *int16, Minor As *int16)

Checks if Snarl is currently running and, if it is, retrieves the major and minor release version numbers in Major and Minor respectively. Returns True if Snarl is running, False otherwise.

The major version number is represented by the integer part of the version number (so, for R1.6, this would be 1); the revision number is represented by the decimal part of the version number (for R1.6, this is 6).

Although this function has been superceded in V37 with snGetVersionEx(), you can still use this function to test for releases prior to V37. See Determining which version of Snarl is running for more information.

int32 snGetVersionEx()

Returns the Snarl system version number. This is an integer value which represents the system build number and can be used to identify the specific version of Snarl running. Of course, as this function is only available as of Snarl V37, if calling it returns zero (or an M_RESULT value) you should use snGetVersion() to determine which pre-V37 version of Snarl is installed.

As anecdotal information, the following table shows previous Snarl releases and their corresponding system version number:

bool snHideMessage(Id As int32)

Hides the notification specified by Id. Id is the value returned by snShowMessage() or snShowMessageEx() when the notification was initially created. This function returns True if the notification was successfully hidden or False otherwise (for example, the notification may no longer exist).

bool snIsMessageVisible(Id As int32)

Returns True if the notification specified by Id is still visible, or False if not. Id is the value returned by snShowMessage() or snShowMessageEx() when the notification was initially created.

M_RESULT snRegisterAlert(AppName as str, Class as str)

Registers an alert of Class for application AppName which must have previously been registered with either snRegisterConfig() or snRegisterConfig2(). Class is displayed in the Snarl Preferences panel so it should be people friendly ("My cool alert" as opposed to "my_cool_alert").

If AppName isn't registered you'll get M_NOT_FOUND returned. Other possible return values are M_FAILED if Snarl isn't running, M_TIMED_OUT if Snarl couldn't process the request quickly enough, or M_ALREADY_EXISTS if the alert has already been registered. If all went well, M_OK is returned.

M_RESULT snRegisterConfig(hWnd As int32, AppName as str, ReplyMsg As int32)

Registers an application's configuration interface with Snarl. AppName is the text that's displayed in the Applications list so it should be people friendly ("My cool app" rather than "my_cool_app"). Also, it really should match the name of the application as when a user runs an application called "MyCoolApp.exe" they'd expect to see that appear in the Applications list and not "Titanics Cruncher 1.1".

As of V37, if the user double-clicks the application's entry in the Preferences panel, one of two things can happen: if the window specified in hWnd has a title then it is simply displayed by Snarl - this is to maintain backwards compatability with previous releases of Snarl. If, however, the window has no title and ReplyMsg is non-zero then Snarl sends ReplyMsg to the window specified in hWnd with SNARL_SHOW_APP_UI in wParam.

Be sure to call RevokeConfig() when your application exits. If you fail to do this, your application will remain orphaned in Snarl's Preferences panel until the user quits Snarl.

M_RESULT snRegisterConfig2(hWnd As int32, AppName as str, ReplyMsg As int32, Icon as str)

Registers an application's configuration interface with Snarl. This function is identical to snRegisterConfig() except that Icon can be used to specify a PNG image which will be displayed against the application's entry in Snarl's Preferences panel.

Be sure to call RevokeConfig() when your application exits. If you fail to do this, your application will remain orphaned in Snarl's Preferences panel until the user quits Snarl.

bool snRevokeConfig(hWnd As int32)

Removes the application previously registered using snRegisterConfig() or snRegisterConfig2(). hWnd should be the same as that used during registration. Typically this is done as part of an application's shutdown procedure.

M_RESULT snSetTimeout(Id As int32, Timeout As int32)

Sets the timeout of existing notification Id to Timeout seconds. Id is the value returned by snShowMessage() or snShowMessageEx() when the notification was first created. If Timeout is zero the notification remains on screen until clicked by the user.

If everything went okay M_OK is returned. Other possible return values are M_FAILED if Snarl isn't running, M_TIMED_OUT if Snarl couldn't process the request quickly enough, or M_NOT_FOUND if the notification doesn't exist.

int32 snShowMessage(Title as str, Text as str, [Timeout As int32], [IconPath as str], [hWndReply As int32], [uReplyMsg As int32])

Displays a message with Title and Text. Timeout controls how long the message is displayed for (in seconds) (omitting this value means the message is displayed indefinately). IconPath specifies the location of a PNG image which will be displayed alongside the message text.

hWndReply and uReplyMsg identify the handle of a window and a Windows message respectively. If both are provided then uReplyMsg will be sent to hWndReply if the user right- or left-clicks the message, or the message times out. In each instance the wParam value of the message will be set to one of the following values:

int32 snShowMessageEx(Class as str, Title as str, Text as str, [Timeout As int32], [IconPath As String], [hWndReply As int32], [uReplyMsg As int32], [SoundFile as str])

Displays a notification. This function is identical to snShowMessage() except that Class specifies an alert previously registered with snRegisterAlert() and SoundFile can optionally specify a WAV sound to play when the notification is displayed on screen.

SoundFile can either be a filename to a specific sound to play, or it can represent a system sound. To play a system sound, prefix the name of the sound with a '+' symbol. For example, to play the default 'Mail Received' system sound, you would specify "+MailBeep" in SoundFile. System sounds are listed under HKEY_CURRENT_USER\AppEvents\EventLabels in the Registry. Note that if an existing sound is being played, the requested sound may not be played, although the notification will still be displayed.

If all goes well this function returns a value which uniquely identifies the new notification. Other possible return values are M_FAILED if Snarl isn't running, M_TIMED_OUT if Snarl couldn't process the request quickly enough, M_BAD_HANDLE or M_NOT_FOUND if the application isn't registered with Snarl or M_ACCESS_DENIED if the user has blocked the notification class within Snarl's preferences.

bool snUpdateMessage(Id As int32, Title as str, Text as str)

Changes the title and text in the message specified by Id to the values specified by Title and Text respectively. Id is the value returned by snShowMessage() or snShowMessageEx() when the notification was originally created. To change the timeout parameter of a notification, use snSetTimeout()