# socket class

A Ipv4/Ipv6 TCP socket

Inherits
object
Description
This class provides a standard TCP/IP socket functionality. It can be used either for connecting to a remote host or to listening for incoming connections. If the KVIrc executable has been compiled with the IPV6 protocol support, this socket also supports it.
Functions

`<integer or string> $status(<asString:boolean>)`
Returns the status of the socket : 0=Unconnected 1=HostLookUp 2=Connecting 3=Connected 4=Bound 5=Closing 6=Listening
`$connect(<host>,<port>)`

Attempts a connection to <host> on port <port>.
<host> can be a numeric internet address (either Ipv4 or Ipv6 (if supported)) or a hostname.
If a hostname is used, a DNS lookup is performed (the socket enters the "dns call" state).
This function returns 1 if the connect attempt can be successfully initiated, 0 otherwise.
In fact, this function returns 0 only if the supplied <port> parameter is invalid or the socket is in an incoherent state (already connected or listening): for a newly created socket and with a valid <port> number you can safely ignore the return value.
Please note that the connection is asynchronous: when this function returns the socket is NOT connected: it has just initiated the connect attempt and you will be notified of the attempt result by an asynchronous event call: in case of failure, $connectFailedEvent() will be called, in case of succes, $connectEvent() will be called.

`$listen([<port>[,<interface>[,<force_ipv6>]]])`

Attempts to listen on the specified <port> and <interface>.
If <port> is not passed it is assumed to be 0, if <interface> is not passed, it is assumed to be "any interface" (INADDR_ANY).
Port 0 means that the kernel should choose a "random" port to listen on.
If the <interface> is recognized as IPV6 address, and IPV6 is supported, the socket listens in IPV6 mode. If <interface> is an empty string and <force_ipv6> is 1 the socket listens on "any ipv6 interface".
This function returns '1' in case of success and '0' in case of failure.
On some systems listening in the IPV6 namespace allows to accept also IPV4 connections (this includes linux but not windows afaik).
When an incoming connection will arrive, $incomingConnectionEvent() will be called.

`$connectedEvent()`
This function is called when a connection attempt has been successfully completed. The socket is actually connected to $remoteip() on $remoteport(). You can start writing data and you may expect $dataavailableevent() to be triggered.
`$incomingConnectionEvent(<socket:h_object>)`
This function is called when an incoming connection arrives over a socket in listening state. You must return 1 if you to terminad this incoming connectioncall $accept() passing a newly created socket object to accept and handle the connection. If you don't call $accept() the incoming connection will be automatically terminated.
`$connectFailedEvent(<reason>)`
This function is called when a connection attempt fails for some reason. <reason> contains the error string. This function may be called only between a call to $connect() and the $connectevent().
`$disconnectEvent([error])`
This function is called when a connection is terminated either cleanly or because of an error. [error] is an empty string in case of a "clean" termination (connection closed by the remote host) or is a message describing the socket error that caused the connection to be interrupted.
`$dataAvailableEvent(<data_length>)`
This function is called when some data is available to be read: the <data_length> parameter specifies the length of the available data in bytes. You can use one of the $read* functions to obtain the data
`$read(<length>[,<hobject>])`
Reads at most <length> bytes of data from the socket. If <length> is anything "outside" the available data range (<length> < 0 or <length> > available_data_length), this function returns all the available data. By default this function can deal ascii data only: NULL characters are transformed to ASCII characters 255. You can pass a memorybuffer object to read binary data.
`$write(<data, array,files or hobject>[,length])`

Writes <data> to the socket.
This function can deal with binary data passing a memorybuffer object
Please note that when this function finishes it does not mean that the data has reached the remote end.
Basically it does not even mean that the data has been sent to the remote host.
The data is enqueued for sending and will be sent as soon as possible.
Using an array you can pass bytes or data string like this: @$write($array($(0xff),$(0xff),$(0xff),$(0xff),"This is an example")); If you're going to delete this object just after the $write call, you should call $close() just before delete to ensure the data delivery.

`$close()`

Resets this socket state: kills any pending or active connection. After a close() call the socket may be used for a new connection.
If there is an active connection, there is a last attempt to flush the pending outgoing data.
You don't need to call $close() if you delete the socket: KVIrc will reset the socket state automatically and free the memory. But if you want to ensure data delivery after a $write call sequece and just before a delete, $close() is the only chance to do it.

`$remoteIp()`
Returns the IP address of the remote end of this socket. The return value is meaningful only if the socket is in connected or connecting state.
`$setProtocol(<protocol>)`
Let KVIrc use TCP or UDP protocol
`$remotePort()`
Returns the port of the remote end of this socket. The return value is meaningful only if the socket is in connected or connecting state.
`$localIp()`
Returns the IP address of the local end of this socket. The return value is meaningful only if the socket is in connected, listening or connecting state.
`$localPort()`
Returns the port of the local end of this socket. The return value is meaningful only if the socket is in connected, listening or connecting state.

Examples

    // Server socket: listen 8080 port and answer to requests (multi-threaded)
    class("webserver","socket")
    {
        function incomingConnectionEvent()
        {
            // incoming connection socket passed by the framework
            %socket = $0
            debug "Webserver incoming Conection from: %socket->$remoteIp : %socket->$remotePort"
            %socket->$write("HTTP/1.0 200 OK\n\n<html><head></head><body><h1>KVIrc Webserver</h1></body></html>\n")
            // tells KVIrc no need this socket anymore
            return $true()
        }
        function constructor()
        {
            debug listen @$listen(8080, "127.0.0.1")
        }
    }
    // finally start webserver
    %WebS = $new(webserver)

    // Client socket - go to google and grab request header

    class("httprequest","socket")
    {
        function errorEvent()
        {
            // the connection to the server failed
            debug  "Connection failed: "$0
            delete $$
        }
        function disconnectedEvent()
        {
            // connection has been closed
            debug  "Connection is closed"
            delete $$
        }
        function destructor()
        {
            // if the socket is still open close it
            if(@$status() == "Connected") @$close()
        }
        function stateChangedEvent()
        {
            debug socket state $0
        }
        function dataAvailableEvent()
        {
            // reading the received data
            debug reading $0 bytes
            %newdata  = @$read($0)
            debug data:  %newdata
            // close and delete the socket
            @$close()
            delete $$
        }
        function constructor()
        {
            // connect to the server
            @$connect("www.google.com",80)
        }
        function connectedEvent()
        {
            // connection is complete
            // send a request to receive the headers only from http://www.google.com/
            debug connected
            debug written bytes @$write("HEAD / HTTP/1.1\r\nHost: www.google.de\r\nConnection: Close\r\nUser-Agent: KVIrc socket\r\n\r\n") on socket;
        }
    }
    %Temp = $new(httprequest)

Index, Object Classes

KVIrc 4.2.0.6190 Documentation
Generated by portbuild at Mon Aug 12 12:09:14 2013