-#ifndef SNARL_INTERFACE_V41

-#define SNARL_INTERFACE_V41

-

-#include <tchar.h>

-#include <windows.h>

-#include <cstdio>

-

-#ifndef SMTO_NOTIMEOUTIFNOTHUNG

- #define SMTO_NOTIMEOUTIFNOTHUNG 8

-#endif

-

-

-namespace Snarl {

- namespace V41 {

-

- static const LPCTSTR SnarlWindowClass = _T("w>Snarl");

- static const LPCTSTR SnarlWindowTitle = _T("Snarl");

-

- static const LPCTSTR SnarlGlobalMsg = _T("SnarlGlobalEvent");

- static const LPCTSTR SnarlAppMsg = _T("SnarlAppMessage");

-

- static const int SnarlPacketDataSize = 4096;

-

- // Enums put in own namespace, because ANSI C++ doesn't decorate enums with tagname :(

- namespace SnarlEnums {

-

- /// <summary>

- /// Global event identifiers.

- /// Identifiers marked with a '*' are sent by Snarl in two ways:

- /// 1. As a broadcast message (uMsg = 'SNARL_GLOBAL_MSG')

- /// 2. To the window registered in snRegisterConfig() or snRegisterConfig2()

- /// (uMsg = reply message specified at the time of registering)

- /// In both cases these values appear in wParam.

- ///

- /// Identifiers not marked are not broadcast; they are simply sent to the application's registered window.

- /// </summary>

- enum GlobalEvent

- {

- SnarlLaunched = 1, // Snarl has just started running*

- SnarlQuit = 2, // Snarl is about to stop running*

- SnarlAskAppletVer = 3, // (R1.5) Reserved for future use

- SnarlShowAppUi = 4 // (R1.6) Application should show its UI

- };

-

- /// <summary>

- /// Message event identifiers.

- /// These are sent by Snarl to the window specified in RegisterApp() when the

- /// Snarl Notification raised times out or the user clicks on it.

- /// </summary>

- enum MessageEvent

- {

- NotificationClicked = 32, // Notification was right-clicked by user

- NotificationCancelled = 32, // Added in V37 (R1.6) -- same value, just improved the meaning of it

- NotificationTimedOut = 33, //

- NotificationAck = 34, // Notification was left-clicked by user

- NotificationMenu = 35, // Menu item selected (V39)

- NotificationMiddleButton = 36, // Notification middle-clicked by user (V39)

- NotificationClosed = 37 // User clicked the close gadget (V39)

- };

-

- /// <summary>

- /// Error values returned by calls to GetLastError().

- /// </summary>

- enum SnarlStatus

- {

- Success = 0,

-

- ErrorFailed = 101, // miscellaneous failure

- ErrorUnknownCommand, // specified command not recognised

- ErrorTimedOut, // Snarl took too long to respond

-

- ErrorArgMissing = 109, // required argument missing

- ErrorSystem, // internal system error

-

- ErrorNotRunning = 201, // Snarl handling window not found

- ErrorNotRegistered, //

- ErrorAlreadyRegistered, // not used yet; RegisterApp() returns existing token

- ErrorClassAlreadyExists, // not used yet; AddClass() returns existing token

- ErrorClassBlocked,

- ErrorClassNotFound,

- ErrorNotificationNotFound

- };

-

- /// <summary>

- /// Application flags - features this app supports.

- /// </summary>

- enum AppFlags

- {

- AppDefault = 0,

- AppHasPrefs = 1,

- AppHasAbout = 2,

- AppIsWindowless = 0x8000

- };

-

- enum SnarlCommand

- {

- RegisterApp = 1,

- UnregisterApp,

- UpdateApp,

- SetCallback,

- AddClass,

- RemoveClass,

- Notify,

- UpdateNotification,

- HideNotification,

- IsNotificationVisible,

- LastError // deprecated but retained for backwards compatability

- };

- }

-

- struct SnarlMessage

- {

- SnarlEnums::SnarlCommand Command;

- LONG32 Token;

- BYTE PacketData[SnarlPacketDataSize];

- };

-

- static const DWORD WM_SNARLTEST = WM_USER + 237;

-

-

- // ------------------------------------------------------------------------

- /// SnarlInterface class definition

- // ------------------------------------------------------------------------

- class SnarlInterface {

- public:

- SnarlInterface();

- ~SnarlInterface();

-

- LPTSTR AllocateString(size_t n) { return new TCHAR[n]; }

- void FreeString(LPTSTR str) { delete [] str; str = NULL; }

- void FreeString(LPCTSTR str) { delete [] str; }

-

- /// <summary>Register application with Snarl.</summary>

- /// <returns>The application token or 0 on failure.</returns>

- /// <remarks>The application token is saved in SnarlInterface member variable, so just use return value to check for error.</remarks>

- LONG32 RegisterApp(LPCSTR signature, LPCSTR title, LPCSTR icon, HWND hWndReply = NULL, LONG32 msgReply = 0, SnarlEnums::AppFlags flags = SnarlEnums::AppDefault);

- LONG32 RegisterApp(LPCWSTR signature, LPCWSTR title, LPCWSTR icon, HWND hWndReply = NULL, LONG32 msgReply = 0, SnarlEnums::AppFlags flags = SnarlEnums::AppDefault);

-

- /// <summary>Unregister application with Snarl when application is closing.</summary>

- /// <returns>0 on failure.</returns>

- LONG32 UnregisterApp();

-

- /// <summary>Update information provided when calling RegisterApp.</summary>

- /// <returns>0 on failure.</returns>

- LONG32 UpdateApp(LPCSTR title = NULL, LPCSTR icon = NULL);

- LONG32 UpdateApp(LPCWSTR title = NULL, LPCWSTR icon = NULL);

-

- /// <summary>Add a notification class to Snarl.</summary>

- /// <returns>0 on failure.</returns>

- LONG32 AddClass(LPCSTR className, LPCSTR description, bool enabled = true);

- LONG32 AddClass(LPCWSTR className, LPCWSTR description, bool enabled = true);

-

- /// <summary>Remove a notification class added with AddClass().</summary>

- /// <returns>0 on failure.</returns>

- LONG32 RemoveClass(LPCSTR className, bool forgetSettings = false);

- LONG32 RemoveClass(LPCWSTR className, bool forgetSettings = false);

-

- /// <summary>Remove all notification classes in one call.</summary>

- /// <returns>0 on failure.</returns>

- LONG32 RemoveAllClasses(bool forgetSettings = false);

-

- /// <summary>Show a Snarl notification.</summary>

- /// <returns>Returns the notification token or 0 on failure.</returns>

- /// <remarks>You can use <see cref="GetLastMsgToken()" /> to get the last token.</remarks>

- LONG32 EZNotify(LPCSTR className, LPCSTR title, LPCSTR text, LONG32 timeout = -1, LPCSTR icon = NULL, LONG32 priority = 0, LPCSTR acknowledge = NULL, LPCSTR value = NULL);

- LONG32 EZNotify(LPCWSTR className, LPCWSTR title, LPCWSTR text, LONG32 timeout = -1, LPCWSTR icon = NULL, LONG32 priority = 0, LPCWSTR acknowledge = NULL, LPCWSTR value = NULL);

-

- /// <summary>

- /// Show a Snarl notification.

- /// This function requires that you write your own packet data.

- /// </summary>

- /// <returns>Returns the notification token or 0 on failure.</returns>

- /// <remarks>You can use <see cref="GetLastMsgToken()" /> to get the last token.</remarks>

- LONG32 Notify(LPCSTR className, LPCSTR packetData);

- LONG32 Notify(LPCWSTR className, LPCWSTR packetData);

-

- /// <summary>Update the text or other parameters of a visible Snarl notification.</summary>

- /// <returns>0 on failure.</returns>

- LONG32 EZUpdate(LONG32 msgToken, LPCSTR title = NULL, LPCSTR text = NULL, LONG32 timeout = -1, LPCSTR icon = NULL);

- LONG32 EZUpdate(LONG32 msgToken, LPCWSTR title = NULL, LPCWSTR text = NULL, LONG32 timeout = -1, LPCWSTR icon = NULL);

-

- /// <summary>

- /// Update the text or other parameters of a visible Snarl notification.

- /// This function requires that you write your own packet data.

- /// </summary>

- /// <returns>0 on failure.</returns>

- LONG32 Update(LONG32 msgToken, LPCSTR packetData);

- LONG32 Update(LONG32 msgToken, LPCWSTR packetData);

-

- /// <summary>Hide a Snarl notification.</summary>

- /// <returns>0 on failure.</returns>

- LONG32 Hide(LONG32 msgToken);

-

- /// <summary>Test if a Snarl notification is visible.</summary>

- /// <returns>Returns -1 if message is visible. 0 if not visible or if an error occured.</returns>

- LONG32 IsVisible(LONG32 msgToken);

-

- /// <summary>Get the last error from Snarl. Call after other functions return 0 to know why it failed.</summary>

- /// <returns>Returns one of the SnarlEnums::SnarlStatus values.</returns>

- SnarlEnums::SnarlStatus GetLastError();

-

- /// <summary>Get Snarl version, if it is running.</summary>

- /// <returns>Returns a number indicating Snarl version.</returns>

- LONG32 GetVersion();

-

- /// <summary>

- /// Get the path to where Snarl is installed.

- /// ** Remember to call <see cref="FreeString(LPCTSTR)" /> on the returned string !!!

- /// </summary>

- /// <returns>Returns the path to where Snarl is installed.</returns>

- /// <remarks>This is a V39 API method.</remarks>

- LPCTSTR GetAppPath();

-

- /// <summary>

- /// Get the path to where the default Snarl icons are located.

- /// <para>** Remember to call <see cref="FreeString(LPCTSTR)" /> on the returned string !!!</para>

- /// </summary>

- /// <returns>Returns the path to where the default Snarl icons are located.</returns>

- /// <remarks>This is a V39 API method.</remarks>

- LPCTSTR GetIconsPath();

-

- /// <summary>GetLastMsgToken() returns token of the last message sent to Snarl.</summary>

- /// <returns>Returns message token of last message.</returns>

- /// <remarks>This function is not in the official API!</remarks>

- LONG32 GetLastMsgToken() const;

-

- /// <summary>Check whether Snarl is running</summary>

- /// <returns>Returns true if Snarl system was found running.</returns>

- static BOOL IsSnarlRunning();

-

- /// <summary>

- /// Returns the value of Snarl's global registered message.

- /// Notes:

- /// Snarl registers SNARL_GLOBAL_MSG during startup which it then uses to communicate

- /// with all running applications through a Windows broadcast message. This function can

- /// only fail if for some reason the Windows RegisterWindowMessage() function fails

- /// - given this, this function *cannnot* be used to test for the presence of Snarl.

- /// </summary>

- /// <returns>A 16-bit value (translated to 32-bit) which is the registered Windows message for Snarl.</returns>

- static UINT Broadcast();

-

- /// <summary>Returns the global Snarl Application message (V39)</summary>

- /// <returns>Returns Snarl application registered message.</returns>

- static UINT AppMsg();

-

- /// <summary>Returns a handle to the Snarl Dispatcher window (V37)</summary>

- /// <returns>Returns handle to Snarl Dispatcher window, or zero if it's not found.</returns>

- /// <remarks>This is now the preferred way to test if Snarl is actually running.</remarks>

- static HWND GetSnarlWindow();

-

- private:

- /// <summary>Send message to Snarl.</summary>

- /// <returns>Return zero on failure.</returns>

- LONG32 Send(SnarlMessage msg);

-

- /// <summary>Convert a unicode string to UTF8</summary>

- /// <returns>Returns pointer to the new string - Remember to delete [] returned string !</returns>

- /// <remarks>Remember to delete [] returned string !!!</remarks>

- LPSTR WideToUTF8(LPCWSTR szWideStr);

-

- /// <summary>Pack data into the PackedData member field.</summary>

- /// <param name="data">Should always be a pointer to the PackedData field</param>

- /// <param name="format">The format string. Can be NULL or "" to just zero PackedData!</param>

- /// <param name="...">Variable number of objects to convert</param>

- void PackData(BYTE* data, LPCSTR format, ...);

-

- LONG32 appToken;

- LONG32 lastMsgToken;

- SnarlEnums::SnarlStatus localError;

-

- }; // class

-

- } // namespace V41

-} // namespace Snarl

-

-#endif // SNARL_INTERFACE_V41