Send Feedback

Porting Snarl

You may be in the wrong place. If you're looking to include support for Snarl in your application and support for the programming language you're using already exists then you need the API Reference instead. If, however, you're looking to add direct support for Snarl to a programming language that's not already supported, then keep on reading...

• Introduction
  
• Developing Language-Specific Code
  
• Constants
  
• Structures
  
• Low-Level Command Reference
  
• Helper Functions
  

Introduction

Snarl is managed by requests sent a specific window (known as the Dispatcher window in this guide). Almost all interaction with Snarl takes place through the use of a COPYDATASTRUCT sent via the WM_COPYDATA message to the Dispatcher window. (There are a number of API functions which don't use this method, these are described in more detail in Helper Functions below). The COPYDATASTUCT encapsulates a special structure which is used to transmit request data to Snarl. There are currently two special structures defined - SNARLSTRUCT and SNARLSTRUCTEX - which are described in more detail in the Structures section.

This way of working has been chosen to allow Snarl to be as flexible as possible when it comes to supporting different programming languages. As all the core functionality is provided through the use of Windows message handling functionality, any programming language which can access the Win32 API can communicate with Snarl.

Almost all Snarl functionality is managed through the use of these two structures, using the Cmd parameter to specify what to do and the rest of the structure to provide command-specific information. While this is a very flexible, it is not very intuitive, and for programming languages that use String types, converting to byte arrays can lead to compatability issues.

Developing Language-Specific Code

• A set of Constants
  
• Two Structures
  
• A set of Low-Level Commands
  
• A number of Helper Functions
  

Constants

All language specific include files must include a number of constants. These can be defined either as an Enum (if the language supports such things), or a physical (hard-coded) values. Note that all undefined constant values are reserved for future use - if you feel you need a particular constant defining for some specific purpose, please raise a request with the Snarl Development Team in the first instance.

The SNARL_COMMANDS Enumeration

These are the current defined commands for V37 and previous versions. Standard commands (those which use a SNARLSTRUCT type) run from 1 to 31 (1F in hex), although only those from 1 to 10 (0x0A) are currently defined. Extended commands (which use a SNARLSTRUCTEX type) run from 32 (0x20) to 63 (0x3F) although only one - SNARL_EX_SHOW - is currently defined:

SNARL_SHOW = 1
SNARL_HIDE = 2
SNARL_UPDATE = 3
SNARL_IS_VISIBLE = 4
SNARL_GET_VERSION = 5
SNARL_REGISTER_CONFIG_WINDOW = 6
SNARL_REVOKE_CONFIG_WINDOW = 7
SNARL_REGISTER_ALERT = 8
SNARL_REVOKE_ALERT = 9
SNARL_REGISTER_CONFIG_WINDOW_2 = 10
SNARL_EX_SHOW = 32

The WM_SNARLTEST Message

This was introduced in V37 (Snarl R1.6) and is designed for use only when developing an include file. It's purpose is to indicate a successful connection to Snarl without requiring a SNARLSTRUCT. This message should be sent directly to the Snarl Dispatcher window - if Snarl is running, it will display a notification to indicate the message was received successfully.

WM_SNARLTEST is defined as follows:

const WM_SNARLTEST = WM_USER + 237

To send this message, use either the Win32 SendMessage() or SendMessageTimeout() functions. If Snarl displays the notification successfully it will return -1. In addition to simply displaying a notification, setting wParam to 1 means Snarl will display whatever you specify in lParam.

Global Event Identifiers

There are four global events currently identified, as follows:

const SNARL_LAUNCHED = 1
const SNARL_QUIT = 2
const SNARL_ASK_APPLET_VER = 3 // introduced in V36
const SNARL_SHOW_APP_UI = 4 // introduced in V37

Notification Event Identifiers

These values are sent to the window specified in snShowMessage() or snShowMessageEx(), as follows:

const SNARL_NOTIFICATION_CLICKED = 32
const SNARL_NOTIFICATION_TIMED_OUT = 33
const SNARL_NOTIFICATION_ACK = 34
const SNARL_NOTIFICATION_CANCELLED = SNARL_NOTIFICATION_CLICKED // introduced in V37

Other Constants

The following is used to register Snarl's global message:

const SNARL_GLOBAL_MSG = "SnarlGlobalEvent"

Structures

There are two structures currently defined (actually, there is one base structure and another structure which extends it). The structure used is determined by the command being sent. Further structures may be defined in future releases of Snarl, although it's expected that SNARLSTRUCTEX should be flexible enough to cover any future requirments. The two structures are defined below using pseudo code, see here for an explanation of the types used:

SNARLSTRUCT

struct SNARLSTRUCT {
   Cmd As SNARL_COMMANDS
   Id As int32
   Timeout As int32
   LngData2 As int32
   Title As Byte(1024)
   Text As Byte(1024)
   Icon As Byte(1024)
}

SNARLSTRUCTEX

struct SNARLSTRUCTEX {
   pss As SNARLSTRUCT
   Class As Byte(1024)
   Extra As Byte(1024)
   Extra2 As Byte(1024)
   Reserved1 As int32
   Reserved2 As int32
}

As can be seen, SNARLSTRUCTEX is just a SNARLSTRUCT with some extra fields attached. Whenever a command is received Snarl assumes it is a SNARLSTRUCT, retrieves the Cmd value and uses this to determine whether it is an extended command or not.

Low-Level Command Reference

SNARL_EX_SHOW (V36)

Parameters

Return Value

.

SNARL_GET_VERSION

Parameters

Return Value

.

SNARL_GET_VERSION_EX (V37)

Parameters

Return Value

.

SNARL_HIDE

Parameters

Return Value

.

SNARL_IS_VISIBLE

Parameters

Return Value

.

SNARL_REGISTER_ALERT (V37)

Parameters

Return Value

.

SNARL_REGISTER_CONFIG_WINDOW

Parameters

Return Value

.

SNARL_REGISTER_CONFIG_WINDOW_2 (V37)

Parameters

Return Value

.

SNARL_REVOKE_ALERT (V37)

Parameters

Return Value

.

SNARL_REVOKE_CONFIG_WINDOW

Parameters

Return Value

.

SNARL_SET_TIMEOUT

Parameters

Return Value

.

SNARL_SHOW

Parameters

Return Value

.

SNARL_UPDATE

Parameters

Return Value

.

Helper Functions

snGetAppPath()

Synopsis

str snGetAppPath()

Parameters

None

Return Value

A string value containing the path to where Snarl is currently running from. Snarl records this path in a Static class child window within the Dispatcher window. To retrieve the value, use the following pesudo code:

hWnd = snGetSnarlWindow()
If hWnd <> 0 Then
  hWndPath = FindWindowEx(hWnd, 0, "static", NULLSTRING)
  If hWndPath <> 0 Then
    result = GetWindowText(hWndPath, some_string, length_of(some_string) + 1)
    If result > 0 Then
      snGetAppPath = LeftStr(some_string, result)
    End If
  End If
End If

snGetGlobalMsg()

Synopsis

int32 snGetGlobalMsg()

Parameters

None

Return Value

This function should return the result of RegisterWindowMessage() with SNARL_GLOBAL_MSG as the parameter.

snGetIconsPath()

Synopsis

str snGetIconsPath()

Parameters

None

Return Value

Assuming snGetAppPath() succeeds, this function should return the result of that with etc\icons\ appended to it, otherwise it should return an empty string.

The trailing slash must be appended to the string.

snGetSnarlWindow()

Synopsis

int32 snGetSnarlWindow()

Parameters

None

Return Value

A handle to the Snarl Dispatcher window. This can be achieved by calling FindWindow() specifying NULL in lpClassName and "Snarl" in lpWindowName.