=====================================================================
Smirc.dll v1.0.2
---------------------------------------------------------------------
Author  : twig*
Website : www.genscripts.net
Date    : 18th July 2007
Email   : twigboy@tpg.com.au
=====================================================================



Contents:
---------------------------------------------------------------------
1. How to use
2. Version history
3. Credits



=====================================================================
1. How to use:
---------------------------------------------------------------------
 Smirc.dll relies on a 3rd party application called Snarl in order
 to work. It can be downloaded from http://www.fullphat.net

 The DLL must be accessible from your mIRC directory for the
 following functions to work.

 I am currently waiting for the Snarl API to be improved before
 implementing additional functionality. Some DLL calls are not
 documented because the API for them are flaky and do not function
 correctly.

 Most successful calls are prefixed with S_OK. If S_ERR is returned,
 the remainder of the value will detail the nature of the error.

 Example          : S_ERR Snarl not running.


 -----------
 Smirc
 -----------
 Displays a Snarl notification. A unique ID is returned for the
 notification for further manipulation.

 Data format      : S_OK [MSG_ID]
 Parameters       : $dll(smirc.dll, Smirc, [DURATION] -[FLAGS] [MESSAGE] $chr(9) [TITLE] $chr(9) [IMAGE_ICON])
  - duration      = Timeout duration (in seconds) of message.
                    Use 0 for no timeout. (Required parameter)
  - flags         = Flags to specify which parameters are given.
                    This is a required parameter.

                    Supported flags are 'c', 't' and 'i'.

                    'c' will send a signal mIRC when the
                    notification is clicked and/or closed.
  - message       = Message text for the notification. (Required parameter)
  - title         = Title text for the notification.
                    (Required parameter if 't' flag specified)
  - icon          = File to use for the notification icon.
                    Icon files can be either ICO, BMP, PNG or JPG.
                    (Required parameter if 'i' flag specified)

 Examples
 //echo -a $dll(smirc.dll, Smirc, 3 - message text)
 //echo -a $dll(smirc.dll, Smirc, 3 -c this message will trigger a Smirc signal)
 //echo -a $dll(smirc.dll, Smirc, 0 -t this message has a title $chr(9) title text)
 //echo -a $dll(smirc.dll, Smirc, 0 -i this message has an icon $chr(9) F:\Icons\Swirl.ico)
 //echo -a $dll(smirc.dll, Smirc, 0 -ti this message has both title text and icon $chr(9) title texto! $chr(9) F:\Icons\Swirl.ico)
 //echo -a $dll(smirc.dll, Smirc, 0 -tic this notification will trigger a callback, display a message containin both title text and icon $chr(9) title texto! $chr(9) F:\Icons\Swirl.ico)

 Notes
 - I'm not sure what other filetypes work for the icon file. The
   Snarl API did not specify any.
 - Also, the icon file currently doesn't support icon library
   files such as ICL or EXE.
 - The icon file parameter MUST be absolute path and filename as
   it is not processed by mIRC or the DLL.
   Snarl processes the file specified on its own accord.


 -----------
 HideMessage
 -----------
 Hides the notification with the ID specified.

 Data format      : S_OK Message hidden.
 Parameters       : $dll(smirc.dll, HideMessage, [MSG_ID])
  - msg_id        = The unique ID from 'Smirc' is used to determine
                    which notification is hidden. (Required parameter)

 Examples
 //echo -a $dll(smirc.dll, HideMessage, 693)

 Notes
  - The returned data format may change.


 -----------
 IsSnarl
 -----------
 Determines if Snarl is currently running. There is a bug in the
 SnarlAPI which causes it to return $true even though Snarl has
 been manually stopped from the preferences panel.

 Data format      : $true

 Example
 //echo -a $dll(smirc.dll, IsSnarl, .)


 -----------
 IsVisible
 -----------
 Determines if a message is visible or not.

 Data format      : $true
 Parameters       : $dll(smirc.dll, IsVisible, [MSG_ID])
  - msg_id        = The unique ID from 'Smirc' is used to determine
                    which notification is queried. (Required parameter)

 Example
 //echo -a $dll(smirc.dll, IsVisible, 695)


 -----------
 SnarlVersion
 -----------
 Retrieves the version of Snarl which is active.

 Example
 //echo -a $dll(smirc.dll, SnarlVersion, .)


 -----------
 UpdateMessage
 -----------
 Updates a Snarl notification.

 Data format      : S_OK Message updated.
 Parameters       : $dll(smirc.dll, UpdateMessage, [MSG_ID] -[FLAGS] [MESSAGE] $chr(9) [TITLE] $chr(9) [IMAGE_ICON])
  - msg_id        = The unique ID from 'Smirc' is used to determine
                    which notification is updated. (Required parameter)
  - flags         = Flags to specify which parameters are given.
                    Supported flags are 't' and 'i'. (Required parameter)
  - message       = Message text for the notification. (Required parameter)
  - title         = Title text for the notification. (Required
                    parameter if 't' flag specified)
  - icon          = File to use for the notification icon. Icon files can
                    Icon files can be either ICO, BMP, PNG or JPG.
                    (Required parameter if 'i' flag specified)

 Examples
 //echo -a $dll(smirc.dll, UpdateMessage, 373 -m message text)
 //echo -a $dll(smirc.dll, UpdateMessage, 684 -t this message has a title $chr(9) title text)
 //echo -a $dll(smirc.dll, UpdateMessage, 685 -i this message has an icon $chr(9) F:\Icons\Swirl.ico)
 //echo -a $dll(smirc.dll, UpdateMessage, 686 -ti this message has both title text and icon $chr(9) title texto! $chr(9) F:\Icons\Swirl.ico)

 Notes
 - Both message and title parameters are applied to the notification,
   regardless if the parameters are specified or not. This is a limitation
   of the Snarl API and a request has been put in to change this behaviour.
 - The returned data format may change.


 -----------
 Version
 -----------
 Retrieves the version for Smirc.dll.

 Example
 //echo -a $dll(smirc.dll, Version, .)


 -----------
 Smirc Signal
 -----------
 A signal from Smirc.dll to mIRC to determine user interaction with notifications.

 In order to receive a signal message, you must call the 'Smirc'
 function with the -c flag set.

 Parameters       : Smirc [ID] [ACTION]
  - ID            = The unique notification ID returned from the 'Smirc' function.
                    This is used to determine which notification this signal is for.
  - ACTION        = The action the user has taken in regards to the notification.
                    Values can be either 'closed' (left click), 'rclick', 'timeout'
                    and 'unknown'.

 Examples
 ON *:SIGNAL:Smirc: {
   if ($2 == rclick) {
     echo 3 -a you have right clicked on notification $1
   }
 }



2. Version updates:
---------------------------------------------------------------------
 v1.0.2 (18/07/2007)
 -----------
 - Fixed S_OK and S_ERR being duplicated in 'Smirc' function.
 - Added callback signals when -c flag is specified.

 v1.0.1 (09/07/2007)
 -----------
 - Added alot more functionality (UpdateMessage, SnarlVersion, IsSnarl,
   HideMessage and IsVisible)
 - Changed /Smirc syntax to support icon and be more flexible
 - Updated SnarlAPI interface to v37
 - Added the source files.
 - Fixed documentation so examples work.

 v1.00 (05/07/2007)
 -----------
 - Initial private release.


3. Credits:
---------------------------------------------------------------------
 - #genscripts crew
 - Chris Peel for creating Snarl
 - Brian Hartvigsen for writing the Snarl C++ interface files
 - dJabba for testing and providing a template for the readme.txt