quick modperl tutorial and examples

git-svn-id: https://znc.svn.sourceforge.net/svnroot/znc/trunk@389 726aef4b-f618-498e-8847-2d620e286838

docs/Example.pm

@@ -0,0 +1,31 @@
+package Example;
+use strict;
+
+#
+# Create a constructor for the module
+sub new
+{
+	my ( $classname ) = @_;
+	my $self = {};
+
+	bless( $self, $classname );
+
+	return( $self );
+}
+
+#
+# we're going to hook this call back
+sub OnChanMsg
+{
+	my ( $me, $nick, $chan, $msg ) = @_;
+	ZNC::PutTarget( $chan, "WTF!?, you said [$msg]\n" );
+	return( ZNC::CONTINUE );
+}
+
+sub OnShutdown
+{
+	my ( $me ) = @_;
+}
+
+1;
+

docs/ExampleWithSock.pm

@@ -0,0 +1,95 @@
+package SampleSock;
+use base 'ZNCSocket';
+
+sub OnConnect
+{
+	my ( $me ) = @_;
+	ZNC::PutTarget( $me->{SamChan}, "I have FD [$me->{fd}]" );
+}
+
+sub OnReadLine
+{
+	my ( $me, $line ) = @_;
+	$line =~ s/\r?\n$//;
+
+	ZNC::PutTarget( $me->{SamChan}, "I have a line [$line]" );
+	$me->Write( "WHAAAAA!?\n" );
+}
+
+sub OnSockDestroy
+{
+	my ( $me ) = @_;
+	ZNC::PutTarget( $me->{SamChan}, "Ahhhh we be closed :(" );
+}
+
+sub OnSockDestroy
+{
+	ZNC::PutTarget( $me->{SamChan}, "destructor called, he wants his money back" );
+}
+
+sub OnNewSock
+{
+	my ( $me, $newfd ) = @_;
+	ZNC::PutTarget( $me->{SamChan}, "new created fd $newfd" );
+	my $obj = new SampleSock( $me->{modobj}, $newfd );
+	$obj->{SamChan} = $me->{SamChan};
+	$obj->AddSock();
+}
+
+1;
+
+package ExampleWithSock;
+use strict;
+
+sub new
+{
+	my ( $classname ) = @_;
+	my $self = {};
+
+	bless( $self, $classname );
+
+	print STDERR "WOOOF!\n";
+
+	return( $self );
+}
+
+sub OnChanMsg
+{
+	my ( $me, $nick, $chan, $msg ) = @_;
+	$nick =~ s/^(.+?)!.*/$1/;
+
+	ZNC::PutTarget( $chan, "$nick, you said [$msg]?" );
+
+	if ( $msg =~ /^go\s+(.+?)\s+(.+)/i )
+	{
+		my $obj = new SampleSock( $me );
+		$obj->{SamChan} = $chan;
+		if ( $obj->Connect( $1, $2, 10, 1 ) )
+		{
+			$obj->AddSock();
+		}
+	}
+	elsif ( $msg =~ /^listen\s+([0-9]+)/ )
+	{
+		my $obj = new SampleSock( $me );
+		$obj->{SamChan} = $chan;
+		if ( $obj->Listen( $1, "", 1 ) )
+		{
+			$obj->AddSock();
+		}
+		else
+		{
+			ZNC::PutTarget( $chan, "Failed to setup listener!" );
+		}
+	}
+
+	return( ZNC::CONTINUE );
+}
+
+sub OnShutdown
+{
+	print STDERR "HERE I AM!!!!!\n";
+}
+
+1;
+

docs/PerlMods.txt

@@ -0,0 +1,41 @@
+Requires the global module g_modperl.so
+
+- oopish perl modules (man perlobj, also see Example.pm)
+- Has all the same callbacks as c++ code, with the same arguments
+- special destructor should be used instead of perl DESTROY
+	- OnShutdown, reason for this is during that destructor the user object
+	  inside g_modperl is available for use
+
+
+
+- Builting Sockets -
+- includes builtin sock support (see ExampleWithSocks.pm)
+- can be used two methods
+	- method one is directly in your module itself, the sock fd is passed
+	  around for your reference. The sock fd is ALWAYS the first argument
+	- method two is to instantiate in a new perl class (as used in
+	  ExampleWithSocks.pm)
+
+- methods receiving callbacks are:
+	- OnSockDestroy() -- when this sock is being destroyed
+	- OnConnect( iParentFD ) -- called on the inbound/outbound socket, if this 
+	  is created from a listening socket, iParentFD will be > -1
+	- OnConnectionFrom( sRemoteHost, iRemotePort ) -- called on the listening 
+	  socket when an inbound connection is coming in. If you return anything but
+	  ZNC::CONTINUE, the connection will be denied.
+	- OnError( iErrorNum ) -- called when an error occurs. errno.h contains valid 
+	  error codes
+	- OnConnectionRefused() -- called when an outbound connection is refused
+	- OnTimeout() -- called when a connection times out
+	- OnDisconnect() -- called when a connection is closed
+	- ReadData( data, len ) -- called when data comes in, len contains the length
+	  of the data being sent in
+	- ReadLine( line ) -- called when a line (ended by \n) comes down. You must
+	  enable readline when the socket is creatd (via connect or listen)
+	
+	NOTE: all of the socket stuff is a basic wrapper around Csocket, and full
+	documentation can be found at http://csocket.net/docs/annotated.html
+	
+
+
+