From WikiChip
Difference between revisions of "mirc/commands/dll"
< mirc‎ | commands

m (Bot: Adding a template)
 
(22 intermediate revisions by 6 users not shown)
Line 1: Line 1:
The '''/dll command''' can be used to call an [[exported function]] from [[DLL]] with the specified parameters.
+
{{mirc title|/dll Command}}
 
+
The '''/dll command''' can be used to call an exported function from a DLL with the specified parameters.
== Prototype ==
 
The exported function must have the following function prototype:
 
 
 
<source lang="c">#include <windows.h>
 
int funcName(HWND mWnd, HWND aWnd, char *data, char *parms, BOOL show, BOOL nopause);</source>
 
 
 
'''Note:''' These functions must use the [[stdcall calling convention]]. (This is also the standard calling convention for all other Microsoft [[Win32 API]] functions.)
 
  
 
== Synopsis ==
 
== Synopsis ==
 
  /dll <libName.dll> <funcName> [data]
 
  /dll <libName.dll> <funcName> [data]
 +
/dll -m <callback> <libName.dll> <funcName> [data]
 
  /dll -u <libName.dll>
 
  /dll -u <libName.dll>
  
 
== Switches ==
 
== Switches ==
 
* '''-u''' - Unload the given loaded library.
 
* '''-u''' - Unload the given loaded library.
 +
* '''-m''' - Call the procname in a new thread and call the alias <callback> when finished
 +
 +
'''Note''': if you pass only a filename, (for example "test.dll", instead of /folder/test.dll or c:\fullpath\test.dll), /dll -u will begin with N=1 looking into the whole list of dlls for a match between $nopath($dll(Nth)) instead of looking into $mircdir only or looking in $mircdir first.
  
 
== Parameters ==
 
== Parameters ==
Line 21: Line 18:
 
* '''[data]''' - The data to pass to that function.
 
* '''[data]''' - The data to pass to that function.
  
== Example ==
+
Note: If the path or filename contains a space, <libName.dll> MUST be enclosed in doublequotes.
<syntaxhighlight lang="mIRC">/*
+
 
  gcc -c -O3 reverse.c
+
== Examples ==
  gcc -shared --export-all-symbols -o reverse.dll -O3 reverse.o
 
  
  reverse.c:
+
Look at the {{mIRC|dll|dll}} article to see how to use a dll as well as how to create them.
  
  #include <windows.h>
+
silently fails if $dll(1) contains a space:
  #include <string.h>
+
<pre>//if ($dll(1)) dll -u $dll(1)</pre>
 
+
works whether or not $dll(1) contains a space:
  int __attribute__((stdcall))
+
<pre>//if ($dll(1)) dll -u $qt($dll(1))</pre>
  reverse(HWND mWnd, HWND aWnd, char *data, char *parms, BOOL show, BOOL nopause)
 
  {
 
      char *l = *data ? data + strlen(data) - 1 : data;
 
      char *p = parms;
 
      while ((*p++ = *l--));
 
      strcpy(data, "/echo -s ");
 
      strcat(data+8, parms);
 
      return 2;
 
  }
 
*/
 
  
; /reverse This is an example!
+
if $dll(1) is $mircdir $+ subdir\foo.dll and $dll(2) is $mircdir $+ foo.dll
; !elpmaxe na si sihT
+
"/dll -u foo.dll" matches the 1st index matching $nopath(foo.dll), so it removes subdir\foo.dll unless that were loaded last. But "/dll -u $qt($dll(2))" removes the foo.dll not located in the subdir.
Alias reverse {
 
  dll "reverse.dll" reverse $1-
 
}</syntaxhighlight>
 
  
 +
<pre>//dll foo.dll no_such_function | echo -a test</pre>
 +
If foo.dll does not exist, the script halts with an error, and the echo does not display. If foo.dll does exist but the function does not exist, /dll displays an error to status window, but the script continues executing the echo. It also loads foo.dll even if the function doesn't exist, and remains loaded in memory if the .dll's initialization routine sets mKeep=$true. See the $dll article for keeping the .dll loaded after execution, and for keeping the .dll past 10 minutes of idle time.
  
== Compatibility ==
+
While $dll(foo,function,) returns a 3rd parameter even if it's $null, "/dll foo.dll" does not require parm3.
Added: mIRC v5.6
 
  
Added On: 03/06/99
+
Using
 +
<pre>/dll file.dll function string</pre>
 +
used for loading a dll is roughly equivalent to
 +
<pre>noop $dll(file.dll,function,string)</pre>
  
<small>Note: Individual switches were not taken into consideration.</small>
+
== Compatibility ==
 +
{{mIRC compatibility|5.6}}
  
 
== See also ==
 
== See also ==
* [[List of commands - mIRC|List of commands]]
+
* {{mIRC|$dll}}
* [[List of identifiers - mIRC|List of identifiers]]
+
* {{mIRC|$dllcall}}
* [[$dll identifier - mIRC|$dll]]
+
* {{mIRC|sendmessage}}
{{mIRC command list}}
 
 
 
[[Category:MIRC commands]]
 

Latest revision as of 16:34, 2 May 2023

The /dll command can be used to call an exported function from a DLL with the specified parameters.

Synopsis[edit]

/dll <libName.dll> <funcName> [data]
/dll -m <callback> <libName.dll> <funcName> [data]
/dll -u <libName.dll>

Switches[edit]

  • -u - Unload the given loaded library.
  • -m - Call the procname in a new thread and call the alias <callback> when finished

Note: if you pass only a filename, (for example "test.dll", instead of /folder/test.dll or c:\fullpath\test.dll), /dll -u will begin with N=1 looking into the whole list of dlls for a match between $nopath($dll(Nth)) instead of looking into $mircdir only or looking in $mircdir first.

Parameters[edit]

  • <libName.dll> - The name and path of the dynamic link library (DLL) file.
  • <funcName> - The name of the exported function to call
  • [data] - The data to pass to that function.

Note: If the path or filename contains a space, <libName.dll> MUST be enclosed in doublequotes.

Examples[edit]

Look at the dll article to see how to use a dll as well as how to create them.

silently fails if $dll(1) contains a space:

//if ($dll(1)) dll -u $dll(1)

works whether or not $dll(1) contains a space:

//if ($dll(1)) dll -u $qt($dll(1))

if $dll(1) is $mircdir $+ subdir\foo.dll and $dll(2) is $mircdir $+ foo.dll "/dll -u foo.dll" matches the 1st index matching $nopath(foo.dll), so it removes subdir\foo.dll unless that were loaded last. But "/dll -u $qt($dll(2))" removes the foo.dll not located in the subdir.

//dll foo.dll no_such_function | echo -a test

If foo.dll does not exist, the script halts with an error, and the echo does not display. If foo.dll does exist but the function does not exist, /dll displays an error to status window, but the script continues executing the echo. It also loads foo.dll even if the function doesn't exist, and remains loaded in memory if the .dll's initialization routine sets mKeep=$true. See the $dll article for keeping the .dll loaded after execution, and for keeping the .dll past 10 minutes of idle time.

While $dll(foo,function,) returns a 3rd parameter even if it's $null, "/dll foo.dll" does not require parm3.

Using

/dll file.dll function string

used for loading a dll is roughly equivalent to

noop $dll(file.dll,function,string)

Compatibility[edit]

Added: mIRC v5.6
Added on: 03 Jun 1999
Note: Unless otherwise stated, this was the date of original functionality.
Further enhancements may have been made in later versions.


See also[edit]