plugins/plugin20.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <title>XChat 2.0 Plugin Interface</title>
   5 <style type="text/css">
   6 <!--
   7 body {
   8 font-family: sans-serif;
   9 background-color: #FFFBF0;
  10 }
  11 .cmd {
  12 background-color: #dddddd;
  13 color: #990066
  14 }
  15 .bbox {
  16 font-family: monospace;
  17 color: #fdfdfd;
  18 background-color: #000;
  19 border: 1px solid #00f;
  20 padding: 4px;
  21 text-align: left;
  22 margin-left: 32px;
  23 margin-right: 32px;
  24 }
  25 .box {
  26 background-color: #ddddee;
  27 border: 1px solid #000;
  28 padding: 4px;
  29 text-align: left;
  30 margin-left: 32px;
  31 margin-right: 32px;
  32 }
  33 -->
  34 </style>
  35 </head>
  36 <body bgcolor="#FFFBF0" text="#000" link="#607060" vlink="#607060" alink="#607060">
  37
  38 <h1>XChat 2.0 Plugin Interface</h1>
  39
  40 <small>
  41 <font size="-12">plugin20.html revision 2.86</font>
  42 <br>Latest version of this document is available at: <a href="http://xchat.org/docs/plugin20.html">http://xchat.org/docs/plugin20.html</a></small>
  43
  44 <h2>1. Documentation:</h2>
  45 <blockquote>
  46 <a href="#intro">1.0 Introduction</a>
  47 <br><a href="#sample">1.1 Sample plugin</a>
  48 <br><a href="#word">1.2 What is word and word_eol?</a>
  49 <br><a href="#lists">1.3 Lists and fields</a>
  50 <br><a href="#win32">1.4 Plugins on Windows (Win32)</a>
  51 <br><a href="#gui">1.5 Controlling the GUI</a>
  52 <br>&nbsp; <a href="#gui">1.5.1 Basic Control</a>
  53 <br>&nbsp; <a href="#menu">1.5.2 Custom Menu Items</a>
  54 <br>&nbsp; <a href="#tray">1.5.3 System Tray</a>
  55 <br><a href="#unicode">1.6 Handling UTF-8/Unicode strings</a>
  56 </blockquote>
  57
  58 <h2>2. Function reference:</h2>
  59 <blockquote>
  60 <a href="#xchat_hook_command">xchat_hook_command</a>
  61 <br><a href="#xchat_hook_fd">xchat_hook_fd</a>
  62 <br><a href="#xchat_hook_print">xchat_hook_print</a>
  63 <br><a href="#xchat_hook_server">xchat_hook_server</a>
  64 <br><a href="#xchat_hook_timer">xchat_hook_timer</a>
  65 <br><a href="#xchat_unhook">xchat_unhook</a>
  66 <br>
  67 <br><a href="#xchat_command">xchat_command</a>
  68 <br><a href="#xchat_commandf">xchat_commandf</a>
  69 <br><a href="#xchat_print">xchat_print</a>
  70 <br><a href="#xchat_printf">xchat_printf</a>
  71 <br><a href="#xchat_emit_print">xchat_emit_print</a>
  72 <br><a href="#xchat_send_modes">xchat_send_modes</a>
  73 <br>
  74 <br><a href="#xchat_find_context">xchat_find_context</a>
  75 <br><a href="#xchat_get_context">xchat_get_context</a>
  76 <br><a href="#xchat_get_info">xchat_get_info</a>
  77 <br><a href="#xchat_get_prefs">xchat_get_prefs</a>
  78 <br><a href="#xchat_set_context">xchat_set_context</a>
  79 <br>
  80 <br><a href="#xchat_nickcmp">xchat_nickcmp</a>
  81 <br><a href="#xchat_strip">xchat_strip</a>
  82 <br><a href="#xchat_free">xchat_free</a>
  83 <br>
  84 <br><a href="#lists">xchat_list_get</a>
  85 <br><a href="#lists">xchat_list_free</a>
  86 <br><a href="#lists">xchat_list_fields</a> (not documented yet)
  87 <br><a href="#lists">xchat_list_next</a>
  88 <br><a href="#lists">xchat_list_str</a>
  89 <br><a href="#lists">xchat_list_int</a>
  90 <br><a href="#lists">xchat_list_time</a>
  91 <br>
  92 <br><a href="#xchat_plugingui_add">xchat_plugingui_add</a> (not documented yet)
  93 <br><a href="#xchat_plugingui_remove">xchat_plugingui_remove</a> (not documented yet)
  94 </blockquote><br>
  95
  96 <h3><a name=intro>Introduction</a></h3>
  97 Plugins for XChat are written in C. The interface aims to keep 100%
  98 binary compatability. This means that if you upgrade XChat, you will
  99 not need to recompile your plugins, they'll continue to work. The
 100 interface doesn't depend on any structures and offsets, so compiler
 101 versions shouldn't have an impact either. The only real requirement of
 102 an XChat plugin, is that it define a "xchat_plugin_init" symbol. This
 103 is your entry point function, see the example below. You should make
 104 all your global variables and functions <i>static</i>, so that a symbol
 105 is not exported. There is no harm in exporting these symbols, but they
 106 are not necessary and only pollute the name-space. Plugins are compiled as shared objects
 107 (.so files), for example:
 108 <br><br>
 109 Most UNIX systems:<pre>
 110         gcc -Wl,--export-dynamic -Wall -O1 -shared -fPIC myplugin.c -o myplugin.so
 111 </pre>
 112 MacOSX:<pre>
 113         gcc -no-cpp-precomp -g -O2 -Wall -bundle -flat_namespace -undefined suppress -o myplugin.so myplugin.c
 114 </pre>
 115
 116 See the <a href="#win32">Windows section</a> on how to compile a plugin
 117 using visual studio.
 118 <p>
 119 All strings passed to and from plugins are encoded in UTF-8, regardless
 120 of locale. <a href="#unicode">What does this mean</a>?
 121 </p><br>
 122
 123 <h3><a name=sample>Sample plugin</a></h3>
 124 This simple plugin autoOps anyone who joins a channel you're in. It also
 125 adds a new command /AUTOOPTOGGLE, which can be used to turn the feature ON
 126 or OFF. Every XChat plugin must define an xchat_plugin_init function, this
 127 is the normal entry point. xchat_plugin_deinit is optional.
 128 <br>
 129 <div style="color: #ffffff; background-color: #111199;">
 130 <pre>
 131
 132 <font color="#00ff00">#include </font><font color="#00ffff">&quot;xchat-plugin.h&quot;</font>
 133
 134 <font color="#00ff00">#define PNAME </font><font color="#00ffff">&quot;AutoOp&quot;</font>
 135 <font color="#00ff00">#define PDESC </font><font color="#00ffff">&quot;Auto Ops anyone that joins&quot;</font>
 136 <font color="#00ff00">#define PVERSION </font><font color="#00ffff">&quot;0.1&quot;</font>
 137
 138 <font color="#ffa500"><b>static</b></font> xchat_plugin *ph;   <font color="#bebebe"><b>/*</b></font><font color="#bebebe"><b> plugin handle </b></font><font color="#bebebe"><b>*/</b></font>
 139 <font color="#ffa500"><b>static</b></font> <font color="#ffa500"><b>int</b></font> enable = <font color="#00ffff">1</font>;
 140
 141 <font color="#ffa500"><b>static</b></font> <font color="#ffa500"><b>int</b></font> join_cb(<font color="#ffa500"><b>char</b></font> *word[], <font color="#ffa500"><b>void</b></font> *userdata)
 142 {
 143    <font color="#ffff00">if</font> (enable)
 144       <font color="#bebebe"><b>/*</b></font><font color="#bebebe"><b> Op ANYONE who joins </b></font><font color="#bebebe"><b>*/</b></font>
 145       xchat_commandf(ph, <font color="#00ffff">&quot;OP </font><font color="#ff00ff">%s</font><font color="#00ffff">&quot;</font>, word[<font color="#00ffff">1</font>]);
 146    <font color="#bebebe"><b>/*</b></font><font color="#bebebe"><b> word[1] is the nickname, as in the Settings-&gt;Advanced-&gt;TextEvents window in xchat </b></font><font color="#bebebe"><b>*/</b></font>
 147
 148    <font color="#ffff00">return</font> XCHAT_EAT_NONE;  <font color="#bebebe"><b>/*</b></font><font color="#bebebe"><b> don't eat this event, xchat needs to see it! </b></font><font color="#bebebe"><b>*/</b></font>
 149 }
 150
 151 <font color="#ffa500"><b>static</b></font> <font color="#ffa500"><b>int</b></font> autooptoggle_cb(<font color="#ffa500"><b>char</b></font> *word[], <font color="#ffa500"><b>char</b></font> *word_eol[], <font color="#ffa500"><b>void</b></font> *userdata)
 152 {
 153    <font color="#ffff00">if</font> (!enable)
 154    {
 155       enable = <font color="#00ffff">1</font>;
 156       xchat_print(ph, <font color="#00ffff">&quot;AutoOping now enabled!</font><font color="#ff00ff">\n</font><font color="#00ffff">&quot;</font>);
 157    } <font color="#ffff00">else</font>
 158    {
 159       enable = <font color="#00ffff">0</font>;
 160       xchat_print(ph, <font color="#00ffff">&quot;AutoOping now disabled!</font><font color="#ff00ff">\n</font><font color="#00ffff">&quot;</font>);
 161    }
 162
 163    <font color="#ffff00">return</font> XCHAT_EAT_ALL;   <font color="#bebebe"><b>/*</b></font><font color="#bebebe"><b> eat this command so xchat and other plugins can't process it </b></font><font color="#bebebe"><b>*/</b></font>
 164 }
 165
 166 <font color="#ffa500"><b>void</b></font> xchat_plugin_get_info(<font color="#ffa500"><b>char</b></font> **name, <font color="#ffa500"><b>char</b></font> **desc, <font color="#ffa500"><b>char</b></font> **version, <font color="#ffa500"><b>void</b></font> **reserved)
 167 {
 168    *name = PNAME;
 169    *desc = PDESC;
 170    *version = PVERSION;
 171 }
 172
 173 <font color="#ffa500"><b>int</b></font> xchat_plugin_init(xchat_plugin *plugin_handle,
 174                       <font color="#ffa500"><b>char</b></font> **plugin_name,
 175                       <font color="#ffa500"><b>char</b></font> **plugin_desc,
 176                       <font color="#ffa500"><b>char</b></font> **plugin_version,
 177                       <font color="#ffa500"><b>char</b></font> *arg)
 178 {
 179    <font color="#bebebe"><b>/*</b></font><font color="#bebebe"><b> we need to save this for use with any xchat_* functions </b></font><font color="#bebebe"><b>*/</b></font>
 180    ph = plugin_handle;
 181
 182    <font color="#bebebe"><b>/*</b></font><font color="#bebebe"><b> tell xchat our info </b></font><font color="#bebebe"><b>*/</b></font>
 183    *plugin_name = PNAME;
 184    *plugin_desc = PDESC;
 185    *plugin_version = PVERSION;
 186
 187    xchat_hook_command(ph, <font color="#00ffff">&quot;AutoOpToggle&quot;</font>, XCHAT_PRI_NORM, autooptoggle_cb, <font color="#00ffff">&quot;Usage: AUTOOPTOGGLE, Turns OFF/ON Auto Oping&quot;</font>, <font color="#00ffff">0</font>);
 188    xchat_hook_print(ph, <font color="#00ffff">&quot;Join&quot;</font>, XCHAT_PRI_NORM, join_cb, <font color="#00ffff">0</font>);
 189
 190    xchat_print(ph, <font color="#00ffff">&quot;AutoOpPlugin loaded successfully!</font><font color="#ff00ff">\n</font><font color="#00ffff">&quot;</font>);
 191
 192    <font color="#ffff00">return</font> <font color="#00ffff">1</font>;       <font color="#bebebe"><b>/*</b></font><font color="#bebebe"><b> return 1 for success </b></font><font color="#bebebe"><b>*/</b></font>
 193 }
 194
 195 </pre>
 196 </div>
 197
 198 <h3><a name=word>What's word and word_eol?</a></h3>
 199
 200 They are arrays of strings. They contain the parameters the user entered
 201 for the particular command. For example, if you executed:
 202
 203 <pre>
 204 /command NICK hi there
 205
 206 word[1] is command
 207 word[2] is NICK
 208 word[3] is hi
 209 word[4] is there
 210
 211 word_eol[1] is command NICK hi there
 212 word_eol[2] is NICK hi there
 213 word_eol[3] is hi there
 214 word_eol[4] is there
 215 </pre>
 216 These arrays are simply provided for your convenience. You are NOT allowed
 217 to alter them. Both arrays are limited to 32 elements (index 31). word[0] and
 218 word_eol[0] are reserved and should not be read.
 219 <br><br><br>
 220 <h3><a name=lists>Lists and Fields</a></h3>
 221 Lists of information (DCCs, Channels, Userlist etc) can be retreived
 222 with xchat_list_get. All fields are READ ONLY and must be copied if
 223 needed for a long time after calling xchat_list_str. The types of lists and fields available are:
 224 <blockquote>
 225
 226 "channels" - list of channels, querys and their servers.
 227 <blockquote><table border=1>
 228 <tr bgcolor="#dddddd"><td>Name</td><td>Description</td><td>Type</td></tr>
 229 <tr><td>channel</td><td>Channel or query name</td><td>string</td></tr>
 230 <tr><td>chantypes</td><td>Channel types e.g. "#!&amp;"<br><small>(Added in version 2.0.9. Older versions will return NULL)</small></td><td>string</td>
 231 <tr><td>context</td><td>(xchat_context *) pointer. Can be used with xchat_set_context</td><td>string</td></tr>
 232 <tr><td>flags</td><td>Server/Channel Bits:<br>
 233 <table>
 234 <tr><td>Bit #</td><td>Value</td><td>Description</td></tr>
 235 <tr><td>0</td><td>1</td><td>Connected</td></tr>
 236 <tr><td>1</td><td>2</td><td>Connecting in Progress</td></tr>
 237 <tr><td>2</td><td>4</td><td>You are away</td></tr>
 238 <tr><td>3</td><td>8</td><td>End of MOTD (Login complete)</td></tr>
 239 <tr><td>4</td><td>16</td><td>Has WHOX (ircu)</td></tr>
 240 <tr><td>5</td><td>32</td><td>Has IDMSG (FreeNode)</td></tr>
 241 <tr><td>6</td><td>64</td><td>Hide Join/Part Messages</td></tr>
 242 <tr><td>7</td><td>128</td><td>unused (was Color Paste in old versions)</td></tr>
 243 <tr><td>8</td><td>256</td><td>Beep on Message</td></tr>
 244 <tr><td>9</td><td>512</td><td>Blink Tray</td></tr>
 245 <tr><td>10</td><td>1024</td><td>Blink Task Bar</td></tr>
 246 </table>
 247 <br><small>(Bits 0-5 added in 2.0.9. Bits 6-8 added in 2.6.6. Bit 9 added in 2.8.0. Bit 10 in 2.8.6)</small></td><td>int</td></tr>
 248 <tr><td>id</td><td>Unique server ID<br><small>(Added in version 2.0.8. Older versions will return -1)</small></td><td>int</td></tr>
 249 <tr><td>lag</td><td>Lag in milliseconds<br><small>(Added in version 2.6.8. Older versions will return -1)</small></td><td>int</td>
 250 <tr><td>maxmodes</td><td>Maximum modes per line<br><small>(Added in version 2.0.9. Older versions will return -1)</small></td><td>int</td>
 251 <tr><td>network</td><td>Network name to which this channel belongs<br><small>(Added in version 2.0.2. Older versions will return NULL)</small></td><td>string</td></tr>
 252 <tr><td>nickprefixes</td><td>Nickname prefixes e.g. "@+"<br><small>(Added in version 2.0.9. Older versions will return NULL)</small></td><td>string</td>
 253 <tr><td>nickmodes</td><td>Nickname mode chars e.g. "ov"<br><small>(Added in version 2.0.9. Older versions will return NULL)</small></td><td>string</td>
 254 <tr><td>queue</td><td>Number of bytes in the send-queue<br><small>(Added in version 2.6.8. Older versions will return -1)</small></td><td>int</td>
 255 <tr><td>server</td><td>Server name to which this channel belongs</td><td>string</td></tr>
 256 <tr><td>type</td><td>Type of context this is: 1-Server 2-Channel 3-Dialog<br><small>(Added in version 2.0.2. Older versions will return -1)</small></td><td>int</td></tr>
 257 <tr><td>users</td><td>Number of users in this channel<br><small>(Added in version 2.0.8. Older versions will return -1)</small></td><td>int</td></tr>
 258 </table>
 259 </blockquote>
 260
 261 "dcc" - list of DCC file transfers. Fields:
 262 <blockquote> <table border=1>
 263 <tr bgcolor="#dddddd"><td>Name</td><td>Description</td><td>Type</td></tr>
 264 <tr><td>address32</td><td>Address of the remote user (ipv4 address)</td><td>int</td></tr>
 265 <tr><td>cps</td><td>Bytes per second (speed)</td><td>int</td></tr>
 266 <tr><td>destfile</td><td>Destination full pathname</td><td>string</td></tr>
 267 <tr><td>file</td><td>File name</td><td>string</td></tr>
 268 <tr><td>nick</td><td>Nickname of person who the file is from/to</td><td>string</td></tr>
 269 <tr><td>port</td><td>TCP port number</td><td>int</td></tr>
 270 <tr><td>pos</td><td>Bytes sent/received</td><td>int</td></tr>
 271 <tr><td>poshigh</td><td>Bytes sent/received, high order 32 bits</td><td>int</td></tr>
 272 <tr><td>resume</td><td>Point at which this file was resumed (or zero if it was not resumed)</td><td>int</td></tr>
 273 <tr><td>resumehigh</td><td>Point at which this file was resumed, high order 32 bits</td><td>int</td></tr>
 274 <tr><td>size</td><td>File size in bytes, low order 32 bits (cast it to unsigned)</td><td>int</td></tr>
 275 <tr><td>sizehigh</td><td>File size in bytes, high order 32 bits</td><td>int</td></tr>
 276 <tr><td>status</td><td>DCC Status: 0-Queued 1-Active 2-Failed 3-Done 4-Connecting 5-Aborted</td><td>int</td></tr>
 277 <tr><td>type</td><td>DCC Type: 0-Send 1-Receive 2-ChatRecv 3-ChatSend</td><td>int</td></tr>
 278 </table>
 279 </blockquote>
 280
 281 "ignore" - current ignore list.
 282 <blockquote> <table border=1>
 283 <tr bgcolor="#dddddd"><td>Name</td><td>Description</td><td>Type</td></tr>
 284 <tr><td>mask</td><td>Ignore mask. .e.g: *!*@*.aol.com</td><td>string</td></tr>
 285 <tr><td>flags</td><td>Bit field of flags. 0=Private 1=Notice 2=Channel 3=Ctcp<br>
 286 4=Invite 5=UnIgnore 6=NoSave 7=DCC</td><td>int</td></tr>
 287 </table>
 288 </blockquote>
 289
 290 "notify" - list of people on notify.
 291 <blockquote> <table border=1>
 292 <tr bgcolor="#dddddd"><td>Name</td><td>Description</td><td>Type</td></tr>
 293 <tr><td>networks</td><td>Networks to which this nick applies. Comma separated. May be NULL.
 294 <br><small>(Added in version 2.6.8)</small></td><td>string</td></tr>
 295 <tr><td>nick</td><td>Nickname</td><td>string</td></tr>
 296 <tr><td>flags</td><td>Bit field of flags. 0=Is online.</td><td>int</td></tr>
 297 <tr><td>on</td><td>Time when user came online.</td><td>time_t</td></tr>
 298 <tr><td>off</td><td>Time when user went offline.</td><td>time_t</td></tr>
 299 <tr><td>seen</td><td>Time when user the user was last verified still online.</td><td>time_t</td></tr>
 300 </table>
 301 <small>The entire "notify" list was added in xchat 2.0.8. Fields are
 302 only valid for the context when xchat_list_get() was called
 303 (i.e. you get information about the user ON THAT ONE SERVER ONLY). You
 304 may cycle through the "channels" list to find notify information for every
 305 server.</small>
 306 </blockquote>
 307
 308 "users" - list of users in the current channel.
 309 <blockquote> <table border=1>
 310 <tr bgcolor="#dddddd"><td>Name</td><td>Description</td><td>Type</td></tr>
 311 <tr><td>away</td><td>Away status (boolean)<br><small>(Added in version 2.0.6. Older versions will return -1)</small></td><td>int</td></tr>
 312 <tr><td>lasttalk</td><td>Last time the user was seen talking<br><small>(Added in version 2.4.2. Older versions will return -1)</small></td><td>time_t</td></tr>
 313 <tr><td>nick</td><td>Nick name</td><td>string</td></tr>
 314 <tr><td>host</td><td>Host name in the form: user@host (or NULL if not known).</td><td>string</td></tr>
 315 <tr><td>prefix</td><td>Prefix character, .e.g: @ or +. Points to a single char.</td><td>string</td></tr>
 316 <tr><td>realname</td><td>Real name or NULL<br><small>(Added in version 2.8.6)</small></td><td>string</td></tr>
 317 <tr><td>selected</td><td>Selected status in the user list, only works for retrieving the user list of the focused tab<br><small>(Added in version 2.6.1. Older versions will return -1)</small></td><td>int</td></tr>
 318 </table>
 319 </blockquote>
 320
 321 </blockquote>
 322
 323 Example:
 324 <br>
 325 <pre>
 326    list = xchat_list_get(ph, <font color="#f800f8">&quot;dcc&quot;</font>);
 327    <font color="#a02828"><b>if</b></font>(list)
 328    {
 329       xchat_print(ph, <font color="#f800f8">&quot;--- DCC LIST ------------------</font><font color="#6858c8">\n</font><font color="#f800f8">&quot;</font>
 330                       <font color="#f800f8">&quot;File  To/From   KB/s   Position</font><font color="#6858c8">\n</font><font color="#f800f8">&quot;</font>);
 331
 332       <font color="#a02828"><b>while</b></font>(xchat_list_next(ph, list))
 333       {
 334          xchat_printf(ph, <font color="#f800f8">&quot;</font><font color="#6858c8">%6s</font><font color="#f800f8"> </font><font color="#6858c8">%10s</font><font color="#f800f8"> </font><font color="#6858c8">%.2f</font><font color="#f800f8">  </font><font color="#6858c8">%d</font><font color="#6858c8">\n</font><font color="#f800f8">&quot;</font>,
 335              xchat_list_str(ph, list, <font color="#f800f8">&quot;file&quot;</font>),
 336              xchat_list_str(ph, list, <font color="#f800f8">&quot;nick&quot;</font>),
 337              xchat_list_int(ph, list, <font color="#f800f8">&quot;cps&quot;</font>) / <font color="#f800f8">1024</font>,
 338              xchat_list_int(ph, list, <font color="#f800f8">&quot;pos&quot;</font>));
 339       }
 340
 341       xchat_list_free(ph, list);
 342    }
 343 </pre>
 344
 345 <br>
 346
 347 <h3><a name=win32>Plugins on Windows (Win32)</a></h3>
 348 Yes, it can be done. All you need is either
 349 <a href="http://msdn.microsoft.com/visualc/vctoolkit2003/">MSVC</a> (Visual Studio) or
 350 <a href="http://www.mingw.org">MINGW</a>, both these compilers are free to download.
 351 Simply compile your plugin as a DLL. You should have the following files:
 352
 353 <ul>
 354 <li><a href="http://xchat.org/docs/xchat-plugin.h">xchat-plugin.h</a> - Main Plugin header</li>
 355 <li>plugin.c - Your plugin, you need to write this one :)</li>
 356 <li>plugin.def - A simple text file containing the following:</li>
 357 </ul>
 358 <div class=box>
 359 EXPORTS<br>
 360 &nbsp; xchat_plugin_init<br>
 361 &nbsp; xchat_plugin_deinit<br>
 362 &nbsp; xchat_plugin_get_info<br>
 363 </div>
 364
 365 <br>Leave out <i>xchat_plugin_deinit</i> if you don't intend to define that
 366 function. Then, to compile, type this at your command prompt:<br><br>
 367 <div class=bbox>
 368 <font color="#00FF00">MSVC</font>
 369 <br>&nbsp;cl -O1 -MD -G5 -DWIN32 -c plugin.c<br>
 370 <br>&nbsp;link /DLL /out:plugin.dll /SUBSYSTEM:WINDOWS plugin.obj /def:plugin.def /base:0x00d40000
 371 <br><br>
 372 <font color="#00FF00">GCC (MINGW)</font>
 373 <br>&nbsp;gcc -Wall -Os -DWIN32 -c plugin.c<br>
 374 <br>&nbsp;dllwrap --def plugin.def --dllname plugin.dll plugin.o<br><br>
 375 </div>
 376 <br>For a complete example, have a look at the source code of the <a href="http://xchat.org/win32/testing/xcdns-src.zip">DNS Plugin</a>, which also contains a Makefile.
 377 <br><br>
 378 <font color=red>Caveat:</font> Plugins compiled on Win32 MUST have a
 379 global variable called <b>ph</b>, which is the plugin_handle, much like
 380 in the <a href="#sample">sample plugin</a> above.
 381 <br><br>
 382
 383 <h3><a name=gui>Controlling the GUI</a></h3>
 384 <p>
 385 A simple way to perform basic GUI functions is to use the /GUI command.
 386 You can execute this command through the input-box, or by calling
 387 xchat_command(ph, "GUI .....");.
 388 </p>
 389 <blockquote>
 390         <table border=0 cellpadding=4>
 391         <tr><td>GUI ATTACH</td><td>Same function as "Attach Window" in the XChat menu (new for 2.6.2).</td></tr>
 392         <tr><td>GUI DETACH</td><td>Same function as "Detach Tab" in the XChat menu (new for 2.6.2).</td></tr>
 393         <tr><td>GUI APPLY</td><td>Similar to clicking OK in the settings window. Execute this after /SET to activate GUI changes (new for 2.8.0)</td></tr>
 394         <tr><td>GUI COLOR <i>n</i></td><td>Change the tab color of the current context, where n is a number from 0 to 3.</td></tr>
 395         <tr><td>GUI FOCUS</td><td>Focus the current window or tab.</td></tr>
 396         <tr><td>GUI FLASH</td><td>Flash the taskbar button. It will flash only if the window isn't focused and will stop when it is focused by the user.</td></tr>
 397         <tr><td>GUI HIDE</td><td>Hide the main xchat window completely (this is used by the Systray plugin).</td></tr>
 398         <tr><td>GUI ICONIFY</td><td>Iconify (minimize to taskbar) the current xchat window.</td></tr>
 399         <tr><td>GUI MSGBOX <i>text</i></td><td>Displays a asynchronous message box with your text (new for 2.4.5).</td></tr>
 400         <tr><td>GUI SHOW</td><td>Show the main xchat window (if currently hidden).</td></tr>
 401         </table>
 402 </blockquote>
 403 <p>
 404 Note, the FLASH, ICONIFY and COLOR args were added in xchat 2.0.8, they
 405 will not work with previous versions.
 406 </p>
 407 <a name=menu>Starting from 2.4.5 you can add your own items to the menu bar. The menu command has this syntax</a>:
 408 <pre>
 409         MENU [-eX] [-i&lt;ICONFILE>] [-k&lt;mod>,&lt;key>] [-m] [-pX] [-rX,group] [-tX] {ADD|DEL} &lt;path> [command] [unselect command]</pre>
 410 For example:
 411 <pre>
 412         MENU -p5 ADD FServe
 413         MENU ADD "FServe/Show File List" "fs list"
 414         MENU ADD FServe/-
 415         MENU -k4,101 -t1 ADD "FServe/Enabled" "fs on" "fs off"
 416         MENU -e0 ADD "FServe/Do Something" "fs action"
 417 </pre>
 418 In the example above, it would be recommended to execute "MENU DEL FServe" inside your xchat_plugin_deinit function. The special item with name "-" will add a separator line.
 419 <br><br>
 420 Parameters and flags:
 421 <blockquote>
 422 <table border=1 cellpadding=4 rules=all>
 423 <tr><td>-eX</td><td>Set enable flag to X. -e0 for disable, -e1 for enable. This lets you create a disabled (shaded) item.</td></tr>
 424 <tr><td>-iFILE</td><td>Use an icon filename FILE (new for 2.8.0). Not supported for toggles or radio items.</td></tr>
 425 <tr><td>-k&lt;mod>,&lt;key></td><td>Specify a keyboard shortcut. "mod" is the modifier which is a bitwise OR of: 1-SHIFT 4-CTRL 8-ALT in decimal. "key" is the key value in decimal, e.g. -k5,101 would specify SHIFT-CTRL-E.</td></tr>
 426 <tr><td>-m</td><td>Specify that this label should be treated as <a href="http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html">Pango Markup</a> language. Since forward slash ("/") is already used in menu paths, you should replace closing tags with an ASCII 003 instead e.g.: xchat_command(ph, "MENU -m ADD \"&lt;b>Bold Menu&lt;\003b>\""); (new for 2.6.6).</td></tr>
 427 <tr><td>-pX</td><td>Specify a menu item's position number. e.g. -p5 will cause the item to be inserted in the 5th place. New for 2.8.0: If the position is a negative number, it will be used as an offset from the bottom/right-most item.</td></tr>
 428 <tr><td>-rX,group</td><td>Specify a radio menu item, with initial state X and a group name (new for 2.8.0). The group name should be the exact label of another menu item (without the path) that this item will be grouped with. For radio items, only a select command will be executed (no unselect command).</td></tr>
 429 <tr><td>-tX</td><td>Specify a toggle menu item with an initial state. -t0 for an "unticked" item and -t1 for a "ticked" item.</td></tr>
 430 </table>
 431 </blockquote>
 432
 433 If you want to change an item's toggle state or enabled flag,
 434 just ADD an item with exactly the same name and command and specify the -tX -eX parameters you need.
 435 <br><br>It's also possible to add items to XChat's existing menus, for example:<br>
 436 <pre>   MENU ADD "Settings/Sub Menu"
 437         MENU -t0 ADD "Settings/Sub Menu/My Setting" myseton mysetoff
 438 </pre>
 439 However, internal names and layouts of XChat's menu may change in the future, so use at own risk.
 440 <br><br>
 441 Here is an example of Radio items:
 442 <pre>   MENU ADD "Language"
 443         MENU -r1,"English" ADD "Language/English" cmd1
 444         MENU -r0,"English" ADD "Language/Spanish" cmd2
 445         MENU -r0,"English" ADD "Language/German" cmd3</pre>
 446 <br>
 447 From 2.8.0, you can also change menus other than the main one (i.e popup menus). Currently they are:
 448 <blockquote>
 449 <table border=1 cellpadding=4 rules=all>
 450 <tr bgcolor="#999999"><td>Root Name</td><td>Menu</td></tr>
 451 <tr><td>$TAB</td><td>Tab menu (right click a channel/query tab or treeview row)</td></tr>
 452 <tr><td>$TRAY</td><td>System Tray menu</td></tr>
 453 <tr><td>$URL</td><td>URL link menu</td></tr>
 454 <tr><td>$NICK</td><td>Userlist nick-name popup menu</td></tr>
 455 <tr><td>$CHAN</td><td>Menu when clicking a channel in the text area (since 2.8.4)</td></tr>
 456
 457 </table>
 458 </blockquote>
 459 <pre>
 460         Example: MENU -p0 ADD "$TAB/Cycle Channel" cycle
 461 </pre>
 462
 463 <br>
 464 <a name=tray>Starting from 2.8.0 you can manipulate XChat's system tray icon using the /TRAY command</a>:
 465 <pre>
 466  Usage:
 467  TRAY -f &lt;timeout> &lt;file1> [&lt;file2>] Flash tray between two icons. Leave off file2 to use default xchat icon.
 468  TRAY -f &lt;filename>                  Set tray to a fixed icon.
 469  TRAY -i &lt;number>                    Flash tray with an internal icon.
 470                                      <small>2=Message 5=Highlight 8=Private 11=File</small>
 471  TRAY -t &lt;text>                      Set the tray tooltip.
 472  TRAY -b &lt;title> &lt;text>              Set the tray balloon.
 473                                      <small>Supported on Windows from 2.8.1 and 2.8.2 on Linux (libnotify required on Linux).</small>
 474 </pre>
 475 Filenames can be ICO or PNG format. PNG format is supported on Linux/BSD and Windows XP (but requires installation of GDI+ on Windows 2000). Set a timeout of -1 to use XChat's default.
 476 <br><br>
 477
 478 <h3><a name=unicode>Handling UTF-8/Unicode strings</a></h3>
 479 <p>
 480 The XChat plugin API specifies that strings passed to and from xchat must be encoded in UTF-8.
 481 <br><br>
 482 What does this mean for the plugin programmer? You just have to be a little careful when
 483 passing strings obtained from IRC to system calls. For example, if you're writing a file-server
 484 bot, someone might message you a filename. Can you pass this filename directly to open()? Maybe!
 485 If you're lazy... The correct thing to do is to convert the string to "system locale encoding",
 486 otherwise your plugin will fail on non-ascii characters.
 487 <br><br>
 488 Here are examples on how to do this conversion on Unix and Windows. In this example, someone will
 489 CTCP you the message "SHOWFILE &lt;filename&gt;".
 490 <br><br>
 491 </p>
 492 <pre>
 493 static int ctcp_cb(char *word[], char *word_eol[], void *userdata)
 494 {
 495         if(strcmp(word[1], "SHOWFILE") == 0)
 496         {
 497                 get_file_name(nick, word[2]);
 498         }
 499
 500         return XCHAT_EAT_XCHAT;
 501 }
 502
 503 static void get_file_name(char *nick, char *fname)
 504 {
 505         char buf[256];
 506         FILE *fp;
 507
 508 <font color="#777777">  /* the fname is in UTF-8, because it came from the xchat API */</font>
 509 </pre><font color="#33aa44">#ifdef _WIN32</font><pre>
 510         wchar_t wide_name[MAX_PATH];
 511
 512 <font color="#777777">  /* convert UTF-8 to WIDECHARs (aka UTF-16LE) */</font>
 513         if (MultiByteToWideChar(CP_UTF8, 0, fname, -1, wide_name, MAX_PATH) < 1)
 514                 return;
 515
 516 <font color="#777777">  /* now we have WIDECHARs, so we can _wopen() or CreateFileW(). */
 517         /* _wfopen actually requires NT4, Win2000, XP or newer. */</font>
 518         fp = _wfopen(wide_name, "r");
 519 </pre><font color="#33aa44">#else</font><pre>
 520         char *loc_name;
 521
 522 <font color="#777777">  /* convert UTF-8 to System Encoding */</font>
 523         loc_name = g_filename_from_utf8(fname, -1, 0, 0, 0);
 524         if(!loc_name)
 525                 return;
 526
 527 <font color="#777777">  /* now open using the system's encoding */</font>
 528         fp = fopen(loc_name, "r");
 529         g_free(loc_name);
 530 </pre><font color="#33aa44">#endif</font><pre>
 531         if (fp)
 532         {
 533                 while (fgets (buf, sizeof(buf), fp))
 534                 {
 535 <font color="#777777">                  /* send every line to the user that requested it */</font>
 536                         xchat_commandf (ph, "QUOTE NOTICE %s :%s", nick, buf);
 537                 }
 538                 fclose (fp);
 539         }
 540 }
 541 </pre>
 542
 543
 544
 545 <br><br>
 546
 547 <h1>Functions</h1>
 548
 549 <h3><a class=cmd name="xchat_hook_command">&nbsp;xchat_hook_command()&nbsp;</a></h3>
 550 <b>Prototype:</b> xchat_hook *xchat_hook_command(xchat_plugin *ph, const char *name, int pri, xchat_cmd_cb *callb, const char *help_text, void *userdata);
 551 <br>
 552 <br><b>Description:</b> Adds a new /command. This allows your program to
 553 handle commands entered at the input box. To capture text without a "/" at
 554 the start (non-commands), you may hook a special name of "". i.e xchat_hook_command(ph, "", ...);.
 555 <br>
 556 Starting from version 2.6.8, commands hooked that begin with a period ('.') will be hidden in /HELP and /HELP -l.
 557 <br>
 558 <br><b>Arguments:</b>
 559 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 560 <br><b>name:</b> Name of the command (without the forward slash).
 561 <br><b>pri:</b> Priority of this command. Use XCHAT_PRI_NORM.
 562 <br><b>callb:</b> Callback function. This will be called when the user executes the given command name.
 563 <br><b>help_text:</b> String of text to display when the user executes /help for this command. May be NULL if you're lazy.
 564 <br><b>userdata:</b> Pointer passed to the callback function.</blockquote>
 565 <b>Returns:</b> Pointer to the hook. Can be passed to xchat_unhook.
 566 <br>
 567 <br><b>Example:</b>
 568 <blockquote>
 569 <pre>
 570 static int onotice_cb(char *word[], char *word_eol[], void *userdata)
 571 {
 572         if(word_eol[2][0] == 0)
 573         {
 574                 xchat_printf(ph, "Second arg must be the message!\n");
 575                 return XCHAT_EAT_ALL;
 576         }
 577
 578         xchat_commandf(ph, "NOTICE @%s :%s", xchat_get_info(ph, "channel"), word_eol[2]);
 579         return XCHAT_EAT_ALL;
 580 }
 581
 582 xchat_hook_command(ph, "ONOTICE", XCHAT_PRI_NORM, onotice_cb,
 583                    "Usage: ONOTICE &lt;message> Sends a notice to all ops", NULL);
 584 </pre>
 585 </blockquote>
 586 <br>
 587
 588 <h3><a class=cmd name="xchat_hook_fd">&nbsp;xchat_hook_fd()&nbsp;</a></h3>
 589 <b>Prototype:</b> xchat_hook *xchat_hook_fd(xchat_plugin *ph, int fd, int flags, xchat_fd_cb *callb, void *userdata);
 590 <br>
 591 <br><b>Description:</b> Hooks a socket or file descriptor. WIN32: Passing a pipe from MSVCR71, MSVCR80 or other variations is not supported at this time.
 592 <br>
 593 <br><b>Arguments:</b>
 594 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 595 <br><b>fd:</b> The file descriptor or socket.
 596 <br><b>flags:</b> One or more of XCHAT_FD_READ, XCHAT_FD_WRITE, XCHAT_FD_EXCEPTION, XCHAT_FD_NOTSOCKET. Use bitwise OR to combine them.
 597 XCHAT_FD_NOTSOCKET tells xchat that the provided <b>fd</b> is not a socket, but a "MSVCRT.DLL" pipe.
 598 <br><b>callb:</b> Callback function. This will be called when the socket is available for reading/writing or exception (depending on your chosen <b>flags</b>)
 599 <br><b>userdata:</b> Pointer passed to the callback function.</blockquote>
 600 <b>Returns:</b> Pointer to the hook. Can be passed to xchat_unhook.
 601 <br><br><br>
 602
 603 <h3><a class=cmd name="xchat_hook_print">&nbsp;xchat_hook_print()&nbsp;</a></h3>
 604 <b>Prototype:</b> <font color="#f8a400"><b>xchat_hook</b></font> *xchat_hook_print(<font color="#f8a400"><b>xchat_plugin</b></font> *ph, <font color="#f8a400"><b>const char</b></font> *name, <font color="#f8a400"><b>int</b></font> pri, <font color="#f8a400"><b>xchat_print_cb</b></font> *callb, <font color="#f8a400"><b>void</b></font> *userdata);
 605 <br>
 606 <br><b>Description:</b> Registers a function to trap any print events.
 607 The event names may be any available in the "Advanced > Text Events" window.
 608 There are also some extra "special" events you may hook using this function.
 609 Currently they are:<blockquote>
 610 "Open Context" - Called when a new xchat_context is created.
 611 <br>"Close Context" - Called when a xchat_context pointer is closed.
 612 <br>"Focus Tab" - Called when a tab is brought to front.
 613 <br>"Focus Window" - Called a toplevel window is focused, or the main
 614 tab-window is focused by the window manager.
 615 <br>"DCC Chat Text" - Called when some text from a DCC Chat arrives. It provides these elements in the word[] array:<blockquote>word[1] Address
 616 <br>word[2] Port
 617 <br>word[3] Nick
 618 <br>word[4] The Message
 619 </blockquote>
 620 "Key Press" - Called when some keys are pressed in the input-box (since 2.4.2). It provides these elements in the word[] array:<blockquote>word[1] Key Value
 621 <br>word[2] State Bitfield (shift, capslock, alt)
 622 <br>word[3] String version of the key
 623 <br>word[4] Length of the string (may be 0 for unprintable keys)
 624 </blockquote>
 625 </blockquote>
 626 <br><b>Arguments:</b>
 627 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 628 <br><b>name:</b> Name of the print event (as in Edit Event Texts Window).
 629 <br><b>pri:</b> Priority of this command. Use XCHAT_PRI_NORM.
 630 <br><b>callb:</b> Callback function. This will be called when this event name is printed.
 631 <br><b>userdata:</b> Pointer passed to the callback function.</blockquote>
 632 <b>Returns:</b> Pointer to the hook. Can be passed to xchat_unhook.
 633 <br>
 634 <br><b>Example:</b>
 635 <blockquote>
 636 <pre>
 637 static int youpart_cb(char *word[], void *userdata)
 638 {
 639         xchat_printf(ph, "You have left channel %s\n", word[3]);
 640         return XCHAT_EAT_XCHAT; /* dont let xchat do its normal printing */
 641 }
 642
 643 xchat_hook_print(ph, "You Part", XCHAT_PRI_NORM, youpart_cb, NULL);
 644 </pre>
 645 </blockquote>
 646 <br>
 647
 648 <h3><a class=cmd name="xchat_hook_server">&nbsp;xchat_hook_server()&nbsp;</a></h3>
 649 <b>Prototype:</b> xchat_hook *xchat_hook_server(xchat_plugin *ph, const char *name, int pri, xchat_serv_cb *callb, void *userdata);
 650 <br>
 651 <br><b>Description:</b> Registers a function to be called when a certain server event occurs. You can
 652 use this to trap PRIVMSG, NOTICE, PART, a server numeric etc... If you want to
 653 hook every line that comes from the IRC server, you may use the special name of "RAW LINE".
 654 <br>
 655 <br><b>Arguments:</b>
 656 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 657 <br><b>name:</b> Name of the server event.
 658 <br><b>pri:</b> Priority of this command. Use XCHAT_PRI_NORM.
 659 <br><b>callb:</b> Callback function. This will be called when this event is received from the server.
 660 <br><b>userdata:</b> Pointer passed to the callback function.</blockquote>
 661 <b>Returns:</b> Pointer to the hook. Can be passed to xchat_unhook.
 662 <br>
 663 <br><b>Example:</b>
 664 <blockquote>
 665 <pre>
 666 static int kick_cb(char *word[], char *word_eol[], void *userdata)
 667 {
 668         xchat_printf(ph, "%s was kicked from %s (reason=%s)\n", word[4], word[3], word_eol[5]);
 669         return XCHAT_EAT_NONE;  /* don't eat this event, let other plugins and xchat see it too */
 670 }
 671
 672 xchat_hook_server(ph, "KICK", XCHAT_PRI_NORM, kick_cb, NULL);
 673 </pre>
 674 </blockquote>
 675 <br>
 676
 677 <h3><a class=cmd name="xchat_hook_timer">&nbsp;xchat_hook_timer()&nbsp;</a></h3>
 678 <b>Prototype:</b> xchat_hook *xchat_hook_timer(xchat_plugin *ph, int timeout, xchat_timer_cb *callb, void *userdata);
 679 <br>
 680 <br><b>Description:</b> Registers a function to be called every "timeout" milliseconds.
 681 <br>
 682 <br><b>Arguments:</b>
 683 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 684 <br><b>timeout:</b> Timeout in milliseconds (1000 is 1 second).
 685 <br><b>callb:</b> Callback function. This will be called every "timeout" milliseconds.
 686 <br><b>userdata:</b> Pointer passed to the callback function.</blockquote>
 687 <b>Returns:</b> Pointer to the hook. Can be passed to xchat_unhook.
 688 <br>
 689 <br><b>Example:</b>
 690 <blockquote>
 691 <pre>
 692 static xchat_hook *myhook;
 693
 694 static int stop_cb(char *word[], char *word_eol[], void *userdata)
 695 {
 696         if(myhook != NULL)
 697         {
 698                 xchat_unhook(ph, myhook);
 699                 myhook = NULL;
 700                 xchat_print(ph, "Timeout removed!\n");
 701         }
 702
 703         return XCHAT_EAT_ALL;
 704 }
 705
 706 static int timeout_cb(void *userdata)
 707 {
 708         xchat_print(ph, "Annoying message every 5 seconds! Type /STOP to stop it.\n");
 709         return 1;       /* return 1 to keep the timeout going */
 710 }
 711
 712 myhook = xchat_hook_timer(ph, 5000, timeout_cb, NULL);
 713 xchat_hook_command(ph, "STOP", XCHAT_PRI_NORM, stop_cb, NULL, NULL);
 714 </pre><br>
 715 </blockquote>
 716
 717 <h3><a class=cmd name="xchat_unhook">&nbsp;xchat_unhook()&nbsp;</a></h3>
 718 <b>Prototype:</b> void *xchat_unhook(xchat_plugin *ph, xchat_hook *hook);
 719 <br>
 720 <br><b>Description:</b> Unhooks any hook registered with xchat_hook_print/server/timer/command. When plugins are unloaded, all of its hooks are automatically
 721 removed, so you don't need to call this within your xchat_plugin_deinit() function.
 722 <br>
 723 <br><b>Arguments:</b>
 724 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 725 <br><b>hook:</b> Pointer to the hook, as returned by xchat_hook_*.
 726 <br></blockquote>
 727 <b>Returns:</b> The userdata you originally gave to xchat_hook_*.
 728 <br><br>
 729
 730 <h3><a class=cmd name="xchat_command">&nbsp;xchat_command()&nbsp;</a></h3>
 731 <b>Prototype:</b> void xchat_command(xchat_plugin *ph, const char *command);
 732 <br>
 733 <br><b>Description:</b> Executes a command as if it were typed in xchat's input box.
 734 <br>
 735 <br><b>Arguments:</b>
 736 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 737 <br><b>command:</b> Command to execute, without the forward slash "/".
 738 <br><br>
 739 </blockquote>
 740
 741 <h3><a class=cmd name="xchat_commandf">&nbsp;xchat_commandf()&nbsp;</a></h3>
 742 <b>Prototype:</b> void xchat_commandf(xchat_plugin *ph, const char *format, ...);
 743 <br>
 744 <br><b>Description:</b> Executes a command as if it were typed in xchat's input box and provides string formating like printf.
 745 <br>
 746 <br><b>Arguments:</b>
 747 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 748 <br><b>format:</b> The format string.
 749 <br><br>
 750 </blockquote>
 751
 752 <h3><a class=cmd name="xchat_print">&nbsp;xchat_print()&nbsp;</a></h3>
 753 <b>Prototype:</b> void xchat_print(xchat_plugin *ph, const char *text);
 754 <br>
 755 <br><b>Description:</b> Prints some text to the current tab/window.
 756 <br>
 757 <br><b>Arguments:</b>
 758 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 759 <br><b>text:</b> Text to print. May contain mIRC color codes.
 760 <br><br>
 761 </blockquote>
 762
 763 <h3><a class=cmd name="xchat_printf">&nbsp;xchat_printf()&nbsp;</a></h3>
 764 <b>Prototype:</b> void xchat_printf(xchat_plugin *ph, const char *format, ...);
 765 <br>
 766 <br><b>Description:</b> Prints some text to the current tab/window and provides formating like printf.
 767 <br>
 768 <br><b>Arguments:</b>
 769 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 770 <br><b>format:</b> The format string.
 771 <br><br>
 772 </blockquote>
 773
 774 <h3><a class=cmd name="xchat_emit_print">&nbsp;xchat_emit_print()&nbsp;</a></h3>
 775 <b>Prototype:</b> int xchat_emit_print(xchat_plugin *ph, const char *event_name, ...);
 776 <br>
 777 <br><b>Description:</b> Generates a print event. This can be any
 778 event found in the Preferences > Advanced > Text Events window. The vararg parameter list
 779 MUST always be NULL terminated. Special care should be taken when calling this function
 780 inside a print callback (from xchat_hook_print), as not to cause endless recursion.
 781 <br>
 782 <br><b>Arguments:</b>
 783 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 784 <br><b>event_name:</b> Text event to print.
 785 <br><br>
 786 </blockquote>
 787 <b>Returns:</b> 1-Success 0-Failure.
 788 <br><br>
 789 <b>Example:</b>
 790 <pre>
 791 xchat_emit_print(ph, "Channel Message", "John", "Hi there", "@", NULL);
 792 </pre>
 793 <br><br>
 794
 795 <h3><a class=cmd name="xchat_send_modes">&nbsp;xchat_send_modes()&nbsp;</a><small>(new for 2.0.9)</small></h3>
 796 <b>Prototype:</b> void xchat_send_modes (xchat_plugin *ph, const char *targets[], int ntargets, int modes_per_line, char sign, char mode)
 797 <br>
 798 <br><b>Description:</b> Sends a number of channel mode changes to the current channel. For example, you can Op a whole
 799 group of people in one go. It may send multiple MODE lines if the request doesn't fit on one. Pass 0 for
 800 <b>modes_per_line</b> to use the current server's maximum possible. This function should only be called while
 801 in a channel context.
 802 <br>
 803 <br><b>Arguments:</b>
 804 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 805 <br><b>targets:</b> Array of targets (strings). The names of people whom the action will be performed on.
 806 <br><b>ntargets:</b> Number of elements in the array given.
 807 <br><b>modes_per_line:</b> Maximum modes to send per line.
 808 <br><b>sign:</b> Mode sign, '-' or '+'.
 809 <br><b>mode:</b> Mode char, e.g. 'o' for Ops.<br>
 810 </blockquote>
 811 <b>Example:</b> (Ops the three names given)
 812 <pre>
 813 const char *names_to_Op[] = {"John", "Jack", "Jill"};
 814 xchat_send_modes(ph, names_to_Op, 3, 0, '+', 'o');
 815 </pre>
 816 <br><br>
 817
 818 <h3><a class=cmd name="xchat_find_context">&nbsp;xchat_find_context()&nbsp;</a></h3>
 819 <b>Prototype:</b> xchat_context *xchat_find_context(xchat_plugin *ph, const char *servname, const char *channel);
 820 <br>
 821 <br><b>Description:</b> Finds a context based on a channel and servername. If servname is NULL, it finds any channel (or query) by the given name. If channel is NULL, it finds the front-most tab/window of the given servname. If NULL is given for both arguments, the currently focused tab/window will be returned.<br>
 822 Changed in 2.6.1. If servname is NULL, it finds the channel (or query) by the given name in the same server group as the current context. If that doesn't exists then find any by the given name.
 823 <br>
 824 <br><b>Arguments:</b>
 825 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 826 <br><b>servname:</b> Servername or NULL.
 827 <br><b>channel:</b> Channelname or NULL.
 828 <br>
 829 </blockquote>
 830 <b>Returns:</b> Context pointer (for use with xchat_set_context) or NULL.
 831 <br><br><br>
 832
 833 <h3><a class=cmd name="xchat_get_context">&nbsp;xchat_get_context()&nbsp;</a></h3>
 834 <b>Prototype:</b> xchat_context *xchat_get_context(xchat_plugin *ph);
 835 <br>
 836 <br><b>Description:</b> Returns the current context for your plugin. You can use this later with xchat_set_context.
 837 <br>
 838 <br><b>Arguments:</b>
 839 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 840 <br>
 841 </blockquote>
 842 <b>Returns:</b> Context pointer (for use with xchat_set_context).
 843 <br><br><br>
 844
 845 <h3><a class=cmd name="xchat_get_info">&nbsp;xchat_get_info()&nbsp;</a></h3>
 846 <b>Prototype:</b> const char *xchat_get_info(xchat_plugin *ph, const char *id);
 847 <br>
 848 <br><b>Description:</b> Returns information based on your current context.
 849 <br>
 850 <br><b>Arguments:</b>
 851 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 852 <br><b>id:</b> ID of the information you want. Currently supported IDs are (case sensitive):
 853         <blockquote>
 854         <table border=0>
 855         <tr><td width="18%">away</td><td>away reason or NULL if you are not away.</td></tr>
 856         <tr><td>channel</td><td>current channel name.</td></tr>
 857         <tr><td>charset</td><td>character-set used in the current context (since 2.4.2).</td></tr>
 858         <tr><td>event_text &lt;name></td><td>text event format string for <i>name</i> (since 2.8.2).</td></tr>
 859         <tr><td>gtkwin_ptr</td><td>(GtkWindow *) (since 2.8.9).</td></tr>
 860         <tr><td>host</td><td>real hostname of the server you connected to.</td></tr>
 861         <tr><td>inputbox</td><td>the input-box contents, what the user has typed (since 2.4.1).</td></tr>
 862         <tr><td>libdirfs</td><td>library directory. e.g. /usr/lib/xchat. The same directory used for auto-loading plugins (since 2.4.0).<small>This string isn't necessarily UTF-8, but local file system encoding.</small></td></tr>
 863         <tr><td>modes</td><td>channel modes, if known, or NULL (since 2.8.1).</td></tr>
 864         <tr><td>network</td><td>current network name or NULL.</td></tr>
 865         <tr><td>nick</td><td>your current nick name.</td></tr>
 866         <tr><td>nickserv</td><td>nickserv password for this network or NULL (since 2.4.3).</td></tr>
 867         <tr><td>server</td><td>current server name (what the server claims to be). NULL if you are not connected.</td></tr>
 868         <tr><td>topic</td><td>current channel topic.</td></tr>
 869         <tr><td>version</td><td>xchat version number.</td></tr>
 870         <tr><td>win_ptr</td><td>native window pointer. Unix: (GtkWindow *) Win32: HWND (since 2.6.0).</td></tr>
 871         <tr><td>win_status</td><td>window status: "active", "hidden" or "normal" (since 2.0.9).</td>
 872         <tr><td>xchatdir</td><td>xchat config directory, e.g.: /home/user/.xchat2 <small>This string is encoded in UTF-8, which means you _should_ convert it to "locale" encoding before using functions like open() or OpenFile(). For best <a href="#unicode">Unicode support</a> on Linux, convert this string using g_filename_from_utf8 and on Windows convert this string to UTF-16LE (wide) and use OpenFileW() etc.</small></td></tr>
 873         <tr><td>xchatdirfs</td><td>xchat config directory, e.g.: /home/user/.xchat2 (since 2.0.9).<small>This string is encoded in local file system encoding, making it ideal for direct use with functions like open() or OpenFile(). For real Unicode support on Windows, it's best not to use xchatdirfs, but xchatdir instead.</small></td></tr>
 874         </table>
 875         </blockquote>
 876 </blockquote>
 877 <b>Returns:</b> A string of the requested information, or NULL. This string must
 878 not be freed and must be copied if needed after the call to xchat_get_info.
 879 <br><br><br>
 880
 881 <h3><a class=cmd name="xchat_get_prefs">&nbsp;xchat_get_prefs()&nbsp;</a></h3>
 882 <b>Prototype:</b> int xchat_get_prefs(xchat_plugin *ph, const char *name, const char **string, int *integer);
 883 <br>
 884 <br><b>Description:</b> Provides xchat's setting information (that which is available through the /set command).
 885 A few extra bits of information are available that don't appear in the /set list, currently they are:
 886 <br>
 887 <blockquote>
 888         <table border=0 cellpadding=5>
 889         <tr><td width="18%">state_cursor</td><td>Current input-box cursor position (characters, not bytes). Since 2.4.2.</td></tr>
 890         <tr><td width="18%">id</td><td>Unique server id. Since 2.6.1.</td></tr>
 891         </table>
 892 </blockquote>
 893 <br><b>Arguments:</b>
 894 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 895 <br><b>name:</b> Setting name required.
 896 <br><b>string:</b> Pointer-pointer which to set.
 897 <br><b>integer:</b> Pointer to an integer to set, if setting is a Boolean or Integer type.
 898 </blockquote>
 899 <b>Returns:</b> 0-Failed 1-Returned a string 2-Returned an Integer 3-Returned a Boolean.
 900 <br><br><b>Example:</b>
 901 <blockquote>
 902 <pre>
 903 {
 904         int i;
 905         const char *str;
 906
 907         if (xchat_get_prefs (ph, "irc_nick1", &amp;str, &amp;i) == 1)
 908         {
 909                 xchat_printf (ph, "Current nickname setting: %s\n", str);
 910         }
 911 }</pre>
 912 </blockquote>
 913 <br><br>
 914
 915
 916 <h3><a class=cmd name="xchat_set_context">&nbsp;xchat_set_context()&nbsp;</a></h3>
 917 <b>Prototype:</b> int xchat_set_context(xchat_plugin *ph, xchat_context *ctx);
 918 <br>
 919 <br><b>Description:</b> Changes your current context to the one given.
 920 <br>
 921 <br><b>Arguments:</b>
 922 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 923 <br><b>ctx:</b> Context to change to (obtained with xchat_get_context or xchat_find_context).
 924 <br>
 925 </blockquote>
 926 <b>Returns:</b> 1 for success, 0 for failure.
 927 <br><br><br>
 928
 929 <h3><a class=cmd name="xchat_nickcmp">&nbsp;xchat_nickcmp()&nbsp;</a></h3>
 930 <b>Prototype:</b> int xchat_nickcmp(xchat_plugin *ph, const char *s1, const char *s2);
 931 <br>
 932 <br><b>Description:</b> Performs a nick name comparision, based on the current server connection. This might be a RFC1459 compliant string compare, or
 933 plain ascii (in the case of DALNet). Use this to compare channels and nicknames. The function works the same way as strcasecmp.
 934 <br>
 935 <br><b>Arguments:</b>
 936 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 937 <br><b>s1:</b> String to compare.
 938 <br><b>s2:</b> String to compare s1 to.
 939 <br>
 940 </blockquote>
 941 <b>Quote from RFC1459:</b>
 942 <blockquote>
 943   Because of IRC's scandanavian origin, the characters {}| are
 944    considered to be the lower case equivalents of the characters []\,
 945    respectively. This is a critical issue when determining the
 946    equivalence of two nicknames.
 947 </blockquote>
 948 <b>Returns:</b>
 949        An integer
 950        less than, equal to, or greater than zero if s1 is found,
 951        respectively, to be less than, to match, or be greater than s2.
 952 <br><br><br>
 953
 954 <h3><a class=cmd name="xchat_strip">&nbsp;xchat_strip()&nbsp;</a><small>(new for 2.4.2)</small></h3>
 955 <b>Prototype:</b> char *xchat_strip(xchat_plugin *ph, const char *str, int len, int flags);
 956 <br>
 957 <br><b>Description:</b> Strips mIRC color codes and/or text attributes (bold, underlined etc) from the given string and returns a newly allocated string.
 958 <br>
 959 <br><b>Arguments:</b>
 960 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 961 <br><b>str:</b> String to strip.
 962 <br><b>len:</b> Length of the string (or -1 for NULL terminated).
 963 <br><b>flags:</b> Bit-field of flags: 0-Strip mIRC colors, 1-Strip text attributes.
 964 <br>
 965 </blockquote>
 966 <b>Returns:</b>
 967 A newly allocated string or NULL for failure. You must free this string with xchat_free.
 968 <br><br><b>Example:</b>
 969 <blockquote>
 970 <pre>
 971 {
 972         char *new_text;
 973
 974         /* strip both colors and attributes by using the 0 and 1 bits (1 BITWISE-OR 2) */
 975         new_text = xchat_strip(ph, "\00312Blue\003 \002Bold!\002", -1, 1 | 2);
 976
 977         if(new_text)
 978         {
 979                 /* new_text should now contain only "Blue Bold!" */
 980                 xchat_printf(ph, "%s\n", new_text);
 981                 xchat_free(ph, new_text);
 982         }
 983 }</pre>
 984 </blockquote>
 985
 986 <br><br>
 987
 988 <h3><a class=cmd name="xchat_free">&nbsp;xchat_free()&nbsp;</a><small>(new for 2.4.2)</small></h3>
 989 <b>Prototype:</b> void xchat_free(xchat_plugin *ph, void *ptr);
 990 <br>
 991 <br><b>Description:</b> Frees a string returned by xchat_* functions. Currently only used to free strings from xchat_strip.
 992 <br>
 993 <br><b>Arguments:</b>
 994 <blockquote><b>ph:</b> Plugin handle (as given to xchat_plugin_init).
 995 <br><b>ptr:</b> Pointer to free.
 996 <br>
 997 </blockquote>
 998
 999 <br><br>
1000
1001 </body>
1002 </html>