From WikiChip
Editing mirc/dynamic-link library
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
This page supports semantic in-text annotations (e.g. "[[Is specified as::World Heritage Site]]") to build structured and queryable content provided by Semantic MediaWiki. For a comprehensive description on how to use annotations or the #ask parser function, please have a look at the getting started, in-text annotation, or inline queries help pages.
Latest revision | Your text | ||
Line 2: | Line 2: | ||
mIRC allows programs to make calls to various '''dynamic-link libraries''' ('''DLL'''s) 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 mIRC script, so for intensive data processing a DLL would be more efficient. | mIRC allows programs to make calls to various '''dynamic-link libraries''' ('''DLL'''s) 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 mIRC script, so for intensive data processing a DLL would be more efficient. | ||
− | '''Note | + | '''Note''': mIRC also supports calling {{mIRC|COM}} objects, for calling non-standard DLLs. |
= Using a Dll = | = Using a Dll = | ||
Line 21: | Line 21: | ||
=== Parameters === | === Parameters === | ||
* '''<filename>''' - The filename for the dll you wish to use. | * '''<filename>''' - The filename for the dll you wish to use. | ||
− | * '''<procname>''' - The | + | * '''<procname>''' - The name of the function/procedure you wish to call. |
− | * '''[data]''' - The optional parameters for the function/procedure | + | * '''[data]''' - The optional parameters for the function/procedure. |
− | * '''<alias>''' - If you use | + | * '''<alias>''' - If you use $dllcall, it calls the function asynchronously, meaning that the code won't halt, $dllcall won't return a value. Instead, mIRC calls the specified <alias> when the function finishes. |
= Creating a Dll = | = Creating a Dll = | ||
Line 29: | Line 29: | ||
'''Note''': We won't deal with how to create a dll in details, the scripter here must be familiar with dll creation already. | '''Note''': We won't deal with how to create a dll in details, the scripter here must be familiar with dll creation already. | ||
− | + | The exported functions must have the following function prototype: | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
+ | <source lang="c">#include <windows.h> | ||
+ | int __stdcall funcName(HWND mWnd, HWND aWnd, char *data, char *parms, BOOL show, BOOL nopause);</source> | ||
* '''mWnd''' - The handle of the main mIRC window. | * '''mWnd''' - The handle of the main mIRC window. | ||
* '''aWnd''' - 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. | * '''aWnd''' - 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''' - This is a buffer you can write to if you want mIRC to perform a command or to return a value from a | + | * '''data''' - This is a buffer you can write to if you want mIRC to perform a command or to return a value from a $dll call (remember that $dllcall do not return a value by design even if you fill this buffer), |
* '''parms''' - For a better handling of command execution, this is a buffer which can be filled if you are filling the 'data' buffer with a command. mIRC will fill the variable $1- with this value, which you can include in the command in 'data'. The examples shows how to use it. | * '''parms''' - For a better handling of command execution, this is a buffer which can be filled if you are filling the 'data' buffer with a command. mIRC will fill the variable $1- with this value, which you can include in the command in 'data'. The examples shows how to use it. | ||
+ | |||
+ | '''Note''': Both 'data' and 'params' are allocated with the Line Length Limit of mIRC, 4150 bytes on mIRC 7.34 at the time of writting this. | ||
+ | |||
* '''show''' - This Bool value is FALSE if a dot '.' has been used to make the command (/.dll) quiet. | * '''show''' - This Bool value is FALSE if a dot '.' has been used to make the command (/.dll) quiet. | ||
* '''nopause''' - This Bool value is TRUE if mIRC is in a critical routine, meaning that you must not stop the processing in mIRC (long while loop for example). | * '''nopause''' - This Bool value is TRUE if mIRC is in a critical routine, meaning that you must not stop the processing in mIRC (long while loop for example). | ||
− | + | These functions must use the [[stdcall calling convention]]. (This is also the standard calling convention for all other Microsoft [[Win32 API]] functions.) | |
− | |||
− | |||
− | |||
− | |||
− | These functions must use the [[stdcall calling convention]]. (This is also the standard calling convention for all other | ||
=== Note on C++ Dll and stdcall === | === Note on C++ Dll and stdcall === | ||
− | If you are making a | + | If you are making a C++ dll, you need to use the extern "C" directive on all the function that you want to export (all the function called from mIRC including the LoadDll and UnloadDll routine), which indicates the function has "C" linkage as opposed to "C++". |
− | The interesting difference is that | + | The interesting difference is that C linkage does not use "mangling" when exporting your function, an operation which rename your functions with additional information to help the linking process. |
<source lang="c">extern "C" int __stdcall funcName(HWND mWnd, HWND aWnd, char *data, char *parms, BOOL show, BOOL nopause);</source> | <source lang="c">extern "C" int __stdcall funcName(HWND mWnd, HWND aWnd, char *data, char *parms, BOOL show, BOOL nopause);</source> | ||
Line 69: | Line 63: | ||
== Return value == | == Return value == | ||
− | The function returns an integer, this value indicates what mIRC | + | The function returns an integer, this value indicates what mIRC shoul do: |
* '''0''' - Means that mIRC should /halt processing. | * '''0''' - Means that mIRC should /halt processing. | ||
− | * '''1''' - Means that mIRC should continue processing | + | * '''1''' - Means that mIRC should continue processing. |
* '''2''' - Means that you have filled the 'data' variable with a command which mIRC should perform, you can also fill the "parms" variable with the parameters to use, if any. | * '''2''' - Means that you have filled the 'data' variable with a command which mIRC should perform, you can also fill the "parms" variable with the parameters to use, if any. | ||
* '''3''' - Means that the DLL has filled the data variable with the result that $dll() as an identifier should return. | * '''3''' - Means that the DLL has filled the data variable with the result that $dll() as an identifier should return. | ||
Line 80: | Line 74: | ||
== Keeping a Dll loaded == | == Keeping a Dll loaded == | ||
− | + | By default a DLL is unloaded immediately after you make the /dll or $dll()/$dllcall call. | |
− | You | + | You can keep a DLL loaded by including a LoadDll() routine in your DLL, which mIRC calls the first time you load the DLL: |
− | |||
− | |||
<source lang="C"> | <source lang="C"> | ||
Line 94: | Line 86: | ||
BOOL mKeep; | BOOL mKeep; | ||
BOOL mUnicode; | BOOL mUnicode; | ||
− | |||
− | |||
} LOADINFO;</source> | } LOADINFO;</source> | ||
− | * '''mVersion''' - Contains the mIRC version number in the low and high words. | + | * '''mVersion''' - Contains the mIRC version number in the low and high words. |
* '''mHwnd''' - Contains the window handle to the main mIRC window. | * '''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 | + | * '''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 mIRCs worked) |
− | * '''mUnicode''' - If set to true, indicates that | + | * '''mUnicode''' - If set to true, indicates that text is in unicode as opposed to ansi (default). This means the data passed from/to the dll is in utf16, the prototype of the function becomes: |
− | * | + | <source lang="c">int __stdcall funcName(HWND mWnd, HWND aWnd, wchar *data, wchar *parms, BOOL show, BOOL nopause);</source>Notice the difference for data and parms, which are now of the type wchar instead of char |
− | * | ||
== Unloading the Dll == | == Unloading the Dll == | ||
Line 159: | Line 148: | ||
{ | { | ||
//we fill data with a command we want mirc to execute | //we fill data with a command we want mirc to execute | ||
− | strcpy(data,"/echo -a | + | strcpy(data,"/echo -a é"); |
//we return 2 indicating mIRC should execute the command in 'data'. | //we return 2 indicating mIRC should execute the command in 'data'. | ||
return 2; | return 2; | ||
} | } | ||
+ | |||
extern "C" int __stdcall more_example(HWND mWnd, HWND aWnd, CHAR *data, char *parms, BOOL show, BOOL nopause) | extern "C" int __stdcall more_example(HWND mWnd, HWND aWnd, CHAR *data, char *parms, BOOL show, BOOL nopause) | ||
Line 178: | Line 168: | ||
strcpy(str,"$nick"); | strcpy(str,"$nick"); | ||
SendMessage(mWnd, WM_MEVALUATE, MAKEWPARAM(0, atoi(data)), 0); | SendMessage(mWnd, WM_MEVALUATE, MAKEWPARAM(0, atoi(data)), 0); | ||
− | strcpy(data,str) | + | strcpy(data,str), |
return 3; | return 3; | ||
} | } | ||
Line 200: | Line 190: | ||
BOOL mKeep; | BOOL mKeep; | ||
BOOL mUnicode; | BOOL mUnicode; | ||
− | |||
− | |||
} LOADINFO; | } LOADINFO; | ||
Line 212: | Line 200: | ||
extern "C" int __stdcall UnloadDll(int mTimeout) { | extern "C" int __stdcall UnloadDll(int mTimeout) { | ||
//if dll is unloaded because mIRC exit or dll -u is used, we clean up, otherwise we prevent the unloading by returning 0. | //if dll is unloaded because mIRC exit or dll -u is used, we clean up, otherwise we prevent the unloading by returning 0. | ||
− | if (mTimeout != 1) | + | if (mTimeout != 1) CloseHandle(file); |
− | |||
− | |||
− | |||
− | |||
return 0; | return 0; | ||
} | } | ||
</source> | </source> | ||
− | Use $dll(yourdll.dll,simple_example, | + | Use $dll(yourdll.dll,simple_example), which will return "simple string". |
− | Use $dll(yourdll.dll,average_example | + | Use $dll(yourdll.dll,average_example) or /dll yourdll.dll average_example, this will execute "/echo -a é" in mIRC 7.x, because the project is not unicode, the two bytes é are sent as ascii, mIRC 7.x will correctly decode that as utf8. On mIRC 6.x (you would need to remove the mUnicode variable in the LOADINFO structure), this would display the two bytes. |
If you set the mUnicode variable to TRUE on mIRC 7.x in the LoadDll function and if you set your project to use unicode (in visual studio: project properties > configuration properties > general > character set), this would correctly show the two bytes as well. | If you set the mUnicode variable to TRUE on mIRC 7.x in the LoadDll function and if you set your project to use unicode (in visual studio: project properties > configuration properties > general > character set), this would correctly show the two bytes as well. | ||
− | Use $dll(yourdll.dll,more_example | + | Use $dll(yourdll.dll,more_example) or /dll yourdll.dll more_example, this will fill $1- from data with the value from parms and execute the final "//echo -a test". |
Use $dll(yourdll.dll,from_event,$eventid) inside an event where $nick exists, this will use SendMessage() to evaluate $nick from the event context and fill data with that value, returned by $dll. | Use $dll(yourdll.dll,from_event,$eventid) inside an event where $nick exists, this will use SendMessage() to evaluate $nick from the event context and fill data with that value, returned by $dll. | ||
− | Use $dll(yourdll.dll,usingSM, | + | Use $dll(yourdll.dll,usingSM), which will use SendMessage() to execute a command in mIRC, it will also evaluate a line of code and return the result in $dll(). |
== Example 2 : Using GNU GCC on Windows (C) == | == Example 2 : Using GNU GCC on Windows (C) == | ||
Line 253: | Line 237: | ||
} | } | ||
</source> | </source> | ||
− | Use | + | Use dll "reverse.dll" reverse <text>. |
− | [[Category:mIRC | + | [[Category:mIRC]] |