# $EPIC: connect_function.txt,v 1.2 2006/07/24 07:11:25 sthalik Exp $
======Synopsis:======
 $connect(<host> <port> [family])

======Technical:======
   * If the <host> argument is omitted the empty string is returned.
   * If the <port> argument is omitted the empty string is returned.
   * If the <host> argument does not resolve to a known Internet hostname, an error is output and the empty string is returned.
   * If a TCP connection to host <host> on port <port> cannot be opened, an error is output and the empty string is returned.
   * If the connection is established, then **/ON DCC_RAW "<fd> <host> E <port>"** will be thrown before this function returns.  <fd> is an integer by which you can refer to this connection with /dcc raw and /msg.
   * The return value of this function is a small integer suitable for use with /[[DCC]] [[dcc RAW|RAW]] and /[[MSG]].
   * The optional [family] argument can be 4, 6, v4, or v6 to specify usage of IPv4 or IPv6.

======Practical:======
This function will let you open up a TCP socket to any host/port.  You
can send messages to the connection using the return value as the key 
argument to [[DCC]] [[DCC RAW|RAW]] and [[MSG]].  You will receive messages from the 
connection via /[[ON]] [[on DCC_RAW|DCC_RAW]] "<fd> <host> D <data>".

======Returns:======
A number to be used for communication with an open TCP connection,
or the empty string if an error occurs.

======Examples:======
A complete example of opening up a connection to the local SMTPd,
sending a command, receiving responses, and cleaning up afterwards.

<file>
alias mailcheck {
  @ :host = [127.0.0.1]
  @ :port = 25

  on ^dcc_raw "% $host D *" {
    echo ======-- Incoming! --====== $2-
  }
  on ^dcc_lost "% RAW $host" {
    on dcc_raw -"% $2 D"
    on dcc_lost -$*
  }

  @ :fd = connect($host $port)
  msg =$fd QUIT
}
</file>

======History:======
This function first appeared in ircII-2.2pre3