DLL Support

The /dll and $dll() features allow you to make calls to DLLs designed to work with mIRC. The main reason you would want to do this is that processing information in a DLL can be far faster than doing so in a script, so for intensive data processing a DLL would be more efficient.

Note that mIRC also supports calling COM objects, for calling non-standard DLLs.

Warning: do not use DLLs from sources you do not trust. See the Accepting Files section for information on the dangers of accepting and using files from the internet.

 /dll <filename> <procname> [data]

 $dll(filename, procname, data)

 $dllcall(filename, alias, procname, data)

The above open a DLL, call the procname routine, and send it the specified data. The only difference is that $dll() can return a value, like all other identifiers.

$dllcall() is multi-threaded so it will not halt the script and will call the specified alias once the call returns.

Technical notes

This section contains technical information for programmers who want to create DLLs for use with mIRC.

The routine in the DLL being called must be of the form:

int __stdcall procname(HWND mWnd, HWND aWnd, TCHAR *data, TCHAR *parms, BOOL show, BOOL nopause)

mWnd is the handle to the main mIRC window.

aWnd is the handle of the window in which the command is being issued, this might not be the currently active window if the command is being called by a remote script.

data is the information that you wish to send to the DLL. On return, the DLL can fill this variable with the command it wants mIRC to perform if any.

parms is filled by the DLL on return with parameters that it wants mIRC to use when performing the command that it returns in the data variable.

show is FALSE if the . prefix was specified to make the command quiet, or TRUE otherwise.

nopause is TRUE if mIRC is in a critical routine and the DLL must not do anything that pauses processing in mIRC, eg. the DLL should not pop up a dialog.

The DLL can return an integer to indicate what it wants mIRC to do:

 0 means that mIRC should /halt processing

 1 means that mIRC should continue processing

 2 means that it has filled the data variable with a command which it wants mIRC to perform, and has filled parms with the parameters to use, if any, when performing the command.

 3 means that the DLL has filled the data variable with the result that $dll() as an identifier should return.

Note: You may need to create a .def file with the procedure names exported when compiling your DLL.

Keeping a DLL Loaded after a call

By default a DLL is unloaded immediately after you make the /dll or $dll() call. You can keep a DLL loaded by including a LoadDll() routine in your DLL, which mIRC calls the first time you load the DLL:

 void __stdcall LoadDll(LOADINFO*);

 typedef struct {

   DWORD  mVersion;

   HWND   mHwnd;

   BOOL   mKeep;

   BOOL   mUnicode;

   DWORD mBeta;

   DWORD mBytes;

 } LOADINFO;

mVersion contains the mIRC version number in the low and high words.

mHwnd contains the window handle to the main mIRC window.

mKeep is set to TRUE by default, indicating that mIRC will keep the DLL loaded after the call. You can set mKeep to FALSE to make mIRC unload the DLL after the call (which is how previous versions of mIRC worked).

mUnicode indicates that strings are Unicode as opposed to ANSI.

mBeta contains the mIRC beta version number, for public betas.

mBytes specifies the maximum number of bytes (not characters) allowed in the data and parms variables.

Note: For backward compatibility reasons, the default format is ANSI, however Unicode is generally recommended for new DLLs.

Unloading a DLL

You can unload a loaded DLL by using the -u switch:

 /dll -u <filename>

You can browse the list of loaded DLLs by using:

 $dll(N/filename)   returns the Nth loaded DLL

mIRC will automatically unload a DLL if it is not used for ten minutes, or when mIRC exits.

You can also define an UnloadDll() routine in your DLL which mIRC will call when unloading a DLL to allow it to clean up.

 int __stdcall UnloadDll(int mTimeout);

 The mTimeout value can be:

   0   UnloadDll() is being called due to a DLL being unloaded with /dll -u.

   1   UnloadDll() is being called due to a DLL not being used for ten minutes. The UnloadDll() routine can return 0 to keep the DLL loaded, or 1 to allow it to be unloaded.

   2   UnloadDll() is being called due to a DLL being unloaded when mIRC exits.