                           ************************************
                           ** Armathan multiserver by a_dude **
                           ************************************




- How to contact me
- What is this mIRC add-on for
- How do I install it
- How do I uninstall it
- How do I launch it once installed
- What are the commands + how do I connect + troubleshootings upon connection
- What are the extra-features (tab "options" and "pos" of the Multiserver Setup)
- How can I change the colours of the messages
- Main troubleshootings
- How can I use my own aliases and popups
- Implementing the DCC send/get




How to contact me ?
-------------------

For any kind of comment (bug reports, add-on completely sucked, sluggish, worse
coding ever, etc ...), send a mail to armathan@hotmail.com

Or you can find me most of the time on the IrCQNet network (servers irc01.icq.com, 
irc02.icq.com, irc03.icq.com, irc04.icq.com, irc05.icq.com) on channel #web

By the time this add-on is released, it may not yet be case, but you will also find
me on the Cyberchat network (server filo.ebicom.net), room #cyberchat and #the_lounge

Take a look at www.armathan.cjb.net to see more add-ons and a full script I developped.

And thanks to all the people in #web like rockchick, pammy, LeeLee and some others who
dared to test the dodgy beta versions of this add-on ;-)



What is this mIRC add-on for ?
------------------------------

With this add-on, you can connect to as much servers as you want with only 
one mIRC open at a time.  The servers doesn't have to be part of the same network.

This add-on has been developped on mIRC v5.71 (www.mirc.com), but I think that it 
will work without problems with version 5.70

If at the end of the day, you think "but hey, that looks almost like mIRC, so what ?", 
well, that means  I archieved my goal  :-)



How do I install it ?
---------------------

Unzip the file "multiserver.zip" to any folder you want : to be absolutely sure that 
there won't be any problem, better choose a path where there are no spaces in the names 
of the folders, like "c:\chat\add-ons\multiserver" or "d:\mIRC\scripts\multiserver".

Next, launch mIRC and in the command line (where you type your text) of any window, 
type one of the two following command :
1) /load -rs path\multiserversetup.mrc 
--> path is the directory where you unzipped the file "multiserver.zip"
--> Ex : /load -rs c:\mIRC\multiserver\multiserversetup.mrc

2) //load -rs $findfile(drive,multiserversetup.mrc,1) 
--> drive is c:\ or d:\ or etc (where you unzipped the file "multiserver.zip")
--> Ex : //load -rs $findfile(c:\,multiserversetup.mrc,1) 

Answer "Yes" when asked to run initialization commands (if you answer "No", the script
won't be installed !). 



How do I uninstall it ?
------------------------

Type "/uninstall multiserver" (without the quotes), the files will be unloaded and the 
created variables erased.



How do I launch it once installed ?
-----------------------------------
 
Choose the item "Multiserver" in the status popup or else in the "commands" menu 
("commands" could be another name if it had been modified by another script).
Or type "/multiserver" (without the quotes).



What are the commands + how do I connect + troubleshootings upon connection ?
-----------------------------------------------------------------------------

It's all the same as the regular mIRC (read the mIRC help if you want to learn more about
them) : click on the tab "cmds" in the Multiserver Setup to see a list of the supported 
commands.  The most important commands that are not implemented are : 
- DCC send (but DCC chat is implemented) 
- /ignore command : that would have taken too much processing to remember all the addresses.

When you connect, be sure to fill in a valid email address in the form whatever@you.like
If the server needs an Identd, go to the tab "options" and enable "Ident Server"
The server list is based on your "servers.ini" file. Either choose a server in the list or
fill in manually its name.

Normally, if your are on a proxy (or bouncer or even V-host perhaps) on your main mIRC, you
shouldn't have problems connecting via the multiserver (--> it will be your real address !).
If you have problems connecting : : disconnect from you main mIRC, bring up the multiserver 
and connect on it (that will be on your real address) then reconnect with your main mIRC 
through the proxy (or bouncer).

If your main mIRC disconnect, you will still remain connected to the the servers you 
connected to with the multiserver.



What are the extra-features (tab "options" and "pos" of the Multiserver Setup) ?
-------------------------------------------------------------------------------

Anti-flood :
You read it like this : if a max of 5 ping replies (or received notices, etc) in less than
10 seconds (the interval), ignore following ping replies (or received notices, etc) during
60 seconds.
The "except" field : those are names that will not trigger a flood, typically services
like Nickserv, Memoserv, Chanserv, bots, etc

Anti-spam :
To block the opening of a private window if the message contain one of the words you spe-
fied.  If you already have a private chat window with someone, that anti-spam measure
isn't 	applied (in order words, the person whom you chat with can say "visit that site
at www.visit-me.com" without the message being blocked ...).


Notify and sound:
The notify is based on the normal mIRC nottify list and sound is like the normal feature, 
when someone plays a sound, it will be played if you got it in your "sounds" folder.  
You have also the command /sound to play a wav/midi file yourself.

Remember window positions :
In the status/channel/private chat popup, you have an entry "remember position" : everytime
you close that window, the position and size is saved for next you open it.  You can remove
the windows in the tab "pos".

Nickserv and Chanserv :
Support of these services with the status/channel popups (+ possibility to add your own 
popups).

Note : 
There is no userinfo/clientinfo/time/version ctcp replies.
Only a ping reply is sent on request.



How can I change the colours of the messages ?
----------------------------------------------

The add-on use the standard colours : click on the icon 'colours' in the mIRC toolbar
"Highlight text" : the colour for your own nickname when you talk
"Info text" and "Info2 text" : for various server messages



Main troubleshootings ?
-----------------------

1) Connection :
When you connect, be sure to fill in a valid email address in the form whatever@you.like
If the server needs an Identd, go to the tab "options" and enable "Ident Server"
The server list is based on your "servers.ini" file.

Normally, if your are on a proxy (or bouncer or even V-host perhaps) on your main mIRC, you
shouldn't have problems connecting via the multiserver (--> it will be your real address !).
If you have problems connecting : : disconnect from you main mIRC, bring up the multiserver 
and connect on it (that will be on your real address) then reconnect with your main mIRC 
through the proxy (or bouncer).


2) DCC chat, you can't establish a DCC connection : 
Your main mIRC shouldn't be on a bouncer or proxy, it should be your real IP : you may have
your main mIRC connected through a proxy/bouncer and your multiserver on your real IP (like
explained on point 1) but you won't be able to DCC chat.



How can I use my own aliases and popups ?
-----------------------------------------

Read the explanations under the tab "popups" in the Multiserver Setup.
Put your adapted popups in the file "multiserverpopup.mrc" and your aliases in the file
"multiserveralias.mrc".  There are already some popups and an anti-flood alias, just 
follow the examples ...

There is support for Nickserv and Chanserv with the status/channel popups.

Here under, same explanations as in the tab "popups" : 


All the add-ons and popups of the regular mIRC are not applied on the multiserver.
You need to adapt them in order to use them : change the commands to multiserver commands, 
copy and rename the aliases, copy and replace the normal popups elsewhere.  
You need to know at least how to edit popups.


Popups
******
Copy the normal popups you want to the file "multiserverpopup.mrc" in the remotes section.
If it's a channel popup, copy it inside the first "menu @Multi.#* {    }"
If it's a nicklist popup, copy it inside the second "menu @Multi.#* {  }"
If it's a private chat popup, copy it inside "menu @Multi.* {  }"
If it's a status popup, copy it inside "menu @Multi.status.* { }"
Read the comment written above each section of the menu items.

You then have to adapt the new popup so it can work in the multiserver environment : 
conversion of commands/alias and a slight different syntax.

A general rule is to replace the normal commands by the same commands prefixed by the 
word "multi." and every reference to the channel (like # or $active) needs to be replaced 
by $multi.chan

If it's a channel popup, you need to enclose the name of the popup inside $chanpop( ).
If it's a nicklist popup, you need to enclose the name of the popup inside $nicklist( ).
If it's a private chat popup, you need to enclose the name of the popup inside $querypop( ).

Just follow the examples of the existing popups.

For example :
1) "slap:/me slaps $1 with a trout" which is a nicklist popup becomes :
$nicklist(slap):multi.me slaps $1 with a trout

2) "present:/msg # here is a present for $1 !!" is a nicklist popup becomes :
$nicklist(present):multi.msg $multi.chan here is a present for $1 !!"

3) "channel greeting:/me greets everybody in here !" which is a channel popup becomes :
$chanpop(channel greeting):multi.me greets everybody in here !"

4) "hello love:msg $active hello my dear $1 !" which is a private chat popup becomes
$querypop(hello love):multi.msg $multi.chan hello my dear $multi.chan
(--> in that case, also replace $1 with $multi.chan)

See below for a list of the normal commands and their equivalent for the multiserver.


Aliases
*******
If you encounter aliases while converting popups, you need to adapt those as well.

Example :
"hello greeting:hello # $1" is the normal popup and 'hello' is the called alias :
alias hello {
msg $1 HELLO $2
msg $1 Hello hello $2 !!
}

Copy and rename the alias 'hello' in the file "multiserveralias.mrc" in the remote section.
Copy the popup inside "menu @Multi.#* {   }" in the file "multiserverpopup.mrc".
Convert commands.

Final result :
$listbox(hello greeting):multi.hello $multi.chan $1" is the new popup and 'multi.hello' 
is the renamed alias :
alias multi.hello {
multi.msg $1 HELLO $2
multi.msg $1 Hello hello $2 !!
}


You can also create your normal ones and execute them with the command /name_alias



Two equivalents identifiers
***************************

$me --> $multi.me.nick
# or $active --> $multi.chan



List of the equivalents of the normal commands
**********************************************
Replace all the normal commands you encounter by the following ones for conversion :
! Only in aliases and in popups ! Type the normal commands when executed on the command 
line.


/ame --> multi.ame <msg>
/amsg --> multi.amsg <msg>
/away --> multi.away <msg>
/dcc chat --> multi.dcc.chat <nick>
/echo --> multi.echo <msg>
/invite --> multi.invite <chan> <nick>
/join --> multi.join <chan> 
/ctcp --> multi.ctcp <nick> <msg>
/kick --> multi. kick <chan> <nick>
/me --> multi.me <msg>
/msg --> multi.msg <msg>
/msg --> multi.msg.silent <nick> <msg> : use this one when you need to do a 
	"/msg nickserv help" for example (the msg won't be displayed in the 
	window as a normal msg)
/mode --> multi.mode <chan|nick> <mode>
/nick --> multi.nick <new nick>
/notice --> multi.notice <nick> <msg>
/notify --> multi.notify <nick>
/ping --> multi.ping <nick|chan>
/query --> multi.query <nick> <msg>
/sound --> multi.sound <nick|chan> <sound>
/topic --> multi.topic <chan><topic>
/who --> multi.who <chan|nick>
/whois --> multi.whois <nick>
/whowas --> multi.whowas <nick>

If you want to use in your aliases an IRC (!!!) command not listed here, use 
"multi.quote <command> <parameter>" (<parameter> being optionnal)




How to implement the DCC send/get ? (Note : DCC chat is already implemented)
----------------------------------------------------------------------------

This feature was not implemented because I'm too lazy   :-)
In fact, my full script is almost ready (multiserver is part of it) and I want to move on
something else now ... quite franckly, scripting saturation has kicked it ...
You should know how to work with sockets if you wish to script that DCC feature.
To know more about the DCC protocol, go to http://www.undernet.org/documents/dccinfo.html

Please implement the code in the "multiserverdcc.mrc" file.


*** DCC send ***

You need to initiate the DCC connection : first sending a message so that the other side 
can react to the request before actually sending a file.

For the request, you have to write to the "right" socket, let's take the example of you 
being connected to the server irc.icq.com :
- status window will be @Multi.status.irc.icq.com
- channel window #x will @Multi.#w.irc.icq.com
- private chat window will be @Multi.someone.irc.icq.com

--> as you see, the name of the windows are always of the type @Multi.name.server
--> the name of socket to write to is "multiserver.server" and for the "server", just parse
    the name of the active window : $gettok($active, 3-,46) to retrieve the tokens after 
    the @Multi.name

So, to initiate the DCC send, you will to do :
1) Choose a free port to listen to on which you will get the acknowledgement that the DCC
   request has been accepted
2) Send a message to nick for a DCC send request
3) Code :
  alias dcc.send { 
    var %dcc.nick.send = $1
    var %dcc.file.send = $nopath($2)
    var %dcc.file.size = $file($2).size
    var %port.dcc = $rand(1024,9999)
    while ($portfree(%port.dcc) == $false) { %port.dcc = $rand(1024,9999) }
    var %dcc.listen.send = DCC.listen.send. $+ $1 $+ . $+ %port.dcc
    socklisten %dcc.listen.send %port.dcc
    var %sock.dcc.send = multiserver. $+ $gettok($active,3-,46)
    sockwrite -tn %sock.dcc.send PRIVMSG %dcc.nick.send :DCC SEND %dcc.file.send $longip($ip) %port.dcc  %dcc.file.size $+ 
  }

  The alias would be called like "dcc.send John c:\blah\crap.txt" --> better use a dialog
  so that the user can browse in his directories.

  Of course, a window like the DCC send/get of the normal mIRC that shows the progress of
  the transfer should be created as well.

4) Once the other side has accepted the request, you give a new name to a socket that you
   will use to accept the connection and then you close the listening socket.  
   For the rest, up to you :-)  



*** DCC get ***

The other side will send you a DCC get request.  In the beginning of the file 
"multiserverdcc.mrc", there is the following alias :

alias initiate.DCC { 
  var %DCC.par = $remove($1-,)

  if ($gettok(%DCC.par,8,32) isnum) && ($gettok(%DCC.par,9,32) isnum) && ($gettok(%DCC.par,6,32) == chat) { 
    etc etc etc
    }

  if  ($gettok(%DCC.par,6,32) == send) { 
    echo $colour(info2) -a *** $gettok(%DCC.par,1,32) - $gettok($rem.double($gettok(%DCC.par,2,32)),1,33) tried to DCC you the file $gettok(%DCC.par, 7,32) (DCC get not implemented) *** 
    }
}

The first "if" is for the DCC chat, the second "if" is for the DCC get.  The incoming
message looks like :
blah.irc.com :nick_sender!~host@address PRIVMSG nick_receiver :DCC SEND mirc.ini 3588236357 4171 6703

(the "var %DCC.par = $remove($1-,)" gets rid of the special token)

3588236357 is the foreign IP --> use $longip() to convert it
4171 is the foreign listening port
6703 is the size of the file mirc.ini

Well, you have all know : create a accept/reject DCC get dialog, then open a socket with 
those values, create a DCC get progress window, etc ...