NAME

       Net::SIP::Debug - debugging of Net::SIP

SYNOPSIS

         use Net::SIP::Debug '1';
         use Net::SIP::Debug qw( Net::SIP*=0 Registrar=1 );
         Net::SIP::Debug->level(1);

         perl -MNet::SIP::Debug=1 app.pl

DESCRIPTION

       Provides debugging support for Net::SIP.  Debugging can be enabled/disabled globally or
       per package and optional per subpackage.

       It provides support for different debugging levels, e.g.  the higher the level, the more
       debugging is done.  The following levels are used:

       •   1 - Debug messages for users.

       •   2 - Includes short SIP packet dumps of incoming and outgoing data.

       •   5 - Includes detailed SIP packet dumps for incoming and outgoing data.

       •   10 - Includes information about call flow, e.g. why packets get dropped etc.

       •   50 - Detailed debugging for programmers using Net::SIP.

       •   100 - Detailed debugging for core developers of Net::SIP.

CLASS METHODS

       import ( @ARGS )
           Extracts everything from arguments given to "use" which might be usable by level and
           forwards rest to Exporter.

           If the argument is a reference to a subroutine it will be used for showing the debug
           message instead of printing it to STDERR.  In this case the usual prefixes incl the
           time will not be added (useful for forwarding debug to syslog).

       level ( @ARGS )
           Enables/disables debugging depending on @ARGS. @ARGS might contain the following
           specifications:

           NUMBER  NUMBER will be interpreted as the debugging level.  It's used in debug etc to
                   print only debug message which a level lower or equal to NUMBER.

           PACKAGE Enables debugging for package PACKAGE. PACKAGE might be a fully qualified
                   package (e.g. "Net::SIP::Registrar") or the "Net" or "Net::SIP" might be
                   omitted ("Registrar"). If a "*" is added the debugging will also be enabled
                   for subpackages, e.g.  "Endpoint*" will enable debugging for
                   Net::SIP::Endpoint and Net::SIP::Endpoint::Context too.

           PACKAGE=NUMBER
                   Similar to the previous item, but this sets debugging level to NUMBER for the
                   specified packages and thus can also be used to selectively disable debugging
                   for some packages.

           If @ARGS is empty it will return the debugging level for the package which called this
           method (the first package in the caller stack which is not Net::SIP::Debug itself).

       set_prefix ( PREFIX )
           Sets prefix used for debug messages to PREFIX. Default prefix is 'DEBUG:' but for
           instance for forking applications it might be useful to change this to "DEBUG($$):" or
           similar.

SUBROUTINES

       DEBUG|debug ( [ LEVEL ],( MESSAGE | FMT,@ARG ))
           If debugging is enabled it will print debugging info to STDERR.  If multiple arguments
           are given to the function they will be fed into sprintf to create a single message.

           If the first argument looks like a number (see looks_like_number in Scalar::Util) it
           will be interpreted as the debug level for this message, e.g. if it is higher than the
           user specified debug level the message will not be printed.

           The MESSAGE (or the result from "sprintf(FMT,@ARG)") will be prefixed by the caller
           package, the caller function and the line from which DEBUG was called. In front of the
           prefix the current time (as float time_t) and the string "DEBUG:" will be added.

           If the message consists of multiple lines each line will be prefixed by the prefix and
           all but the first line will also have a TAB added between prefix and message data.

           The function is by default exported as DEBUG and can by exported as debug too.

       DEBUG_DUMP ( [ LEVEL ], @DATA )
           Will call debug with the output from Data::Dumpers Dumper if debugging is enabled. If
           @DATA has more than one item it will be fed as reference into Dumper, otherwise only
           the single item will be fed to Dumper.  For the meaning of LEVEL see debug.

           This function is exported by default.

       stacktrace ( MESSAGE | FMT,@ARG )
           Uses the arguments in debug, but instead of writing a debug message to STDERR it will
           be used in Carp::longmess.  Returns string with stacktrace.

       LEAK_TRACK ( REF )
           This is used internally for tracking leaks. It will rebless REF into a new class which
           behaves like the old one. Calls of LEAK_TRACK and DESTROY on this class will be
           tracked and shown. If Devel::Peek can be loaded it will Dump information about the REF
           on each call to LEAK_TRACK.

           Exported by default.

exported Variables

       $DEBUG
           This variable is set to false if all kind of debugging is disabled.  This variable is
           exported by default. It should not be changed.  It is intended to be used as a quick
           check to save expensive calls of debugging functions if no debugging will be used
           anyway, i.e.:

               $DEBUG && DEBUG(...)