Create listen socket

From Botnix

create_listen_socket

r = main::create_listen_socket(id,module,host,port,use_v6)

Create a socket, which is inserted into the bot's socket engine. The socket created is a 'listening' socket which accepts new connections. The module and callback parameters indicate the module name to call back when socket activity occurs, the module being the perl object '$self' parameter. The id can be any arbitary text which your module can use to identify the socket.

The host and port are locally available hostnames and ports which the socket is to be bound to. If the host:port set is already in use, this function will fail by returning 0.

If you want to bind to all available interfaces, use undef as the hostname, and to allow the operating system to select a port for you, use undef as the port number. If use_v6 is declared, and IPV6 is supported by your system, then the socket bound to will be an IPV6 socket, otherwise it will be an IPV4 (the standard protocol currently used on the internet at this time). This parameter is included here, and not in the create_socket call simply because when the host parameter is not defined, there is no other way to diffrentiate between binding an IPV4 and an IPV6 socket.

The function socket_new in your module will be called when a new connection is attempted on the socket, as shown in the following example:

sub socket_new {
        my($self,$listener,$newsock,$paddr) = @_;
        # our new socket is "newsock". We should store this so
        # we can do something with it later
}

When this function is called, a new socket (identical in operation to a socket created using create_socket) will be created whos id is given in $newsock. Data will come in on this socket id, causing your module's socket_callback event to be called in an identical manner as sockets created using create_socket, as shown in the example below:

sub socket_callback {
        my ($self,$id) = @_;
        my $result = main::read_socket($id);
        $telnets{$id}{in} += length($result);
        if ($result eq "") {
                main::lprint("telnet Connection '$id' failed") if $main::debug;
                main::delete_socket($id);
                main::lprint("Deleted socket") if $main::debug;
                delete $telnets{$id};
                return;
        } else {
                chomp($result);
                $result =~ s/(\r|\n)//g;
                if ($result eq "") { return };
                main::lprint("telnet Data on '$id': '$result'") if $main::debug;  

        ...

        }
}

Once you are finished with a socket you MUST delete it with main::delete_socket as shown above. this will transparently close the file descriptor for you. This function returns the file descriptor allocated, or 0 if it fails. You should avoid direct access to the file descriptor wherever possible.

For a good working example of these socket calls, please see the modules modules/irc/dcc.pm and modules/irc/telnet.pm