To create new wiki account, please join us on #znc at freenode and ask admins to create a wiki account for you. You can say thanks to spambots for this inconvenience.


From ZNC
< Modperl
Revision as of 16:37, 17 December 2011 by DarthGandalf (talk)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


  • oopish perl modules (man perlobj, also see
  • 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

Modperl built-in functions[edit]

NOTE $mod as referenced here is a reference to your module in which its being used, aside from that these functions are analagous for the same functions in C++

  • ZNC::AddTimer( $mod, $funcname, $description, $interval, $cycles )
  • ZNC::RemTimer( $mod, $funcname )
  • ZNC::PutModule( $line, $ident, $host )
  • ZNC::PutModNotice( $line, $ident, $host )
  • ZNC::PutIRC( $line )
  • ZNC::PutStatus( $line )
  • ZNC::PutUser( $line )
  • ZNC::PutTarget( $target, $line )

How to load a perl module[edit]

First you have to load modperl itself. This global module takes no arguments.

Read loading modules to learn more about loading modules.

Then you can load and unload perl modules via commands to *status:

/msg *status loadperlmod
/msg *status unloadperlmod
/msg *status reloadperlmod <some args>

You can also load perl modules via LoadPerlModule in znc.conf. Example:

<User foo>
    GM:LoadPerlModule =
    GM:LoadPerlModule = <some args>

Setting a Timer[edit]

Setting a timer is a little more classic perl. The method has similar arguments as the C++ code. Example:

sub Foo {
    ZNC::PutTarget( "#Fred", "Timer has been Reached!" );
# Note that $me, is a reference to your module ($me is similar to 'this' in a perl paradigm)
# This will set a timer to call Foo() in 60 seconds. It will only be called once.
ZNC::AddTimer( $me, "Foo", "My Foo Timer", 60, 1 );


Built-in Methods[edit]

  • ZNC::Connect( $mod, $host, $port, $timeout, $bEnableReadline, $bUseSSL )
  • ZNC::ConnectSSL( $mod, $host, $port, $timeout, $bEnableReadline, $bUseSSL )
  • ZNC::Listen( $mod, $port, $bindhost, $bEnableReadline, $bUseSSL )
  • ZNC::ListenSSL( $mod, $port, $bindhost, $bEnableReadline )

Note the following need an object to work. You should derive from ZNCSocket like in the example

  • ZNCSocket::new( $classname, $modobj, $fd ) fd can be undefined
  • ZNCSocket::AddSock( $me )
  • ZNCSocket::Connect( $me, $host, $port, $timeout, $bEnableReadline, $bUseSSL )
  • ZNCSocket::ConnectSSL( $me, $host, $port, $timeout, $bEnableReadline )
  • ZNCSocket::Write( $me, $data )
  • ZNCSocket::Close( $me )
  • ZNCSocket::SetTimeout( $me, $timeout )
  • ZNCSocket::Listen( $me, $port, $bindhost, $bEnableReadline, $bUseSSL )
  • ZNCSocket::ListenSSL( $me, $port, $bindhost, $bEnableReadline )

Callbacks and hooks[edit]

  • includes builtin sock support (see
  • can be used in two methods
    1. Directly in your module itself, the sock fd is passed around for your reference. The sock fd is ALWAYS the first argument
    2. Instantiate in a new perl class (as used in
  • 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