# 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

`$status()`
Returns the status of the socket : 4=connected 3=listening 2=connecting 1=in dns call 0=disconnected
`$connectTimeout()`
Returns the value of the connect attempt timeout in milliseconds. This is the timeout after that a connection attempt will be considered as failed if the remote host is not responding. You can set it with $setConnectTimeout().
`$setConnectTimeout(<timeout>)`
Sets the connect timeout for this socket. <timeout> must be a positive value in milliseconds. The default timeout is 60000.
`$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 succesfully 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.

`$accept(<socketId>)`
This function can be called only from inside $incomingConnectionEvent(). <socketId> must be a newly created socket sub-class instance object. The passed object will be set up to handle the incoming connection and this object will remain in listening state (unless you explicitly close it). This function returns '1' in case of success and '0' in case of failure.
`$connectEvent()`
This function is called when a connection attempt has been succesfully completed. The socket is actually connected to $remoteIp() on $remotePort(). You can start writing data and you may expect $dataAvailableEvent() to be triggered.
`$incomingConnectionEvent()`
This function is called when an incoming connection arrives over a socket in listening state. You must call $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>)`
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. Please note that this function can't deal withi binary data: NULL characters are transformed to ASCII characters 255.
`$readHex(<length>)`
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. Returns the data encoded as hexadecimal digit string: this function can deal with binary data too.
`$write(<data>)`

Writes <data> to the socket.
This function can't deal with binary data (you can't send a NULL character)
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.
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.

`$writeHex(<hex_data>)`

Writes <data> to the socket.
<data> is expected to be a hexadecimal rappresentation of the bytes to be sent (two HEX characters for each byte). This means that the length of <hex_data> string must be a multiple of 2.
Returns the length of the actually decoded and sent data in bytes or -1 in case of error (the string was not a valid hexadecimla rappresentation).
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.
If you're going to delete this object just after the $writeHex 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.
`$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.

Index, Object Classes

KVIrc 3.2.0 Documentation
Generated by root at Thu Mar 9 08:43:54 2006