kamailio/modules_s/xlog/README

1. Xlog Module

Elena-Ramona Modroiu

   Voice Sistem

   Copyright © 2003 FhG FOKUS
   Revision History
   Revision $Revision$ $Date$
     __________________________________________________________________

   1.1. Overview
   1.2. Implemented Specifiers
   1.3. Parameters

        1.3.1. buf_size (integer)

   1.4. Functions

        1.4.1. xlog(level, format)
        1.4.2. xdbg(format)

   1.5. Module API

        1.5.1. Functions

              1.5.1.1. int xbind(xl_api_t *xl_api)
              1.5.1.2. int xparse(char *s, xl_elog_p *el)
              1.5.1.3. int shm_xparse(char *s, xl_elog_p *el)
              1.5.1.4. int xparse2(char *s, xl_elog_p *el, xl_parse_cb cb)

              1.5.1.5. int shm_xparse2(char *s, xl_elog_p *el, xl_parse_cb
                      cb)

              1.5.1.6. xfree(xl_elog_p el)
              1.5.1.7. shm_xfree(xl_elog_p el)
              1.5.1.8. int xprint(struct sip_msg* msg, xl_elog_p el, char
                      *buf, int *len)

              1.5.1.9. str *xnulstr()

1.1. Overview

   This module provides the possibility to print user formatted log or
   debug messages from SER scripts, similar to printf function but now a
   specifier is replaced with a part of the SIP request. Section 1.2,
   "Implemented Specifiers" shows what can be printed out.

1.2. Implemented Specifiers

     * %% : '%'
     * %br : request's first branch
     * %bR : request's all branches
     * %ci : call-id
     * %cs : cseq
     * %ct : contact header
     * %Cxy : color printing based on escape sequences (x - foreground
       color, y - background color). The values for colors: x - default
       color of the terminal; s - Black; r - Red; g - Green; y - Yellow; b
       - Blue; p - Purple; c - Cyan; w - White
     * %ds : destination set
     * %fu : 'From' uri
     * %ft : 'From' tag
     * %Hn : host's hostname (if system hostname is FQDN, part before
       first .)
     * %Hd : host's domain (if system hosntame is FQDN, part behind first
       .)
     * %Hf : host's FQDN hostname
     * %Hi : host's IP address
     * %mb : whole SIP message buffer
     * %mf : flags set for current SIP request
     * %mi : SIP message id
     * %ml : SIP message length
     * %mx : SIP message id (in hex notation)
     * %nh : message's next hop
     * %pp : process id (pid)
     * %px : process id (pid) (in hex notation)
     * %rm : request's method
     * %ru : request's r-uri
     * %rr : reply's reason
     * %rs : reply's status
     * %rt : 'Refer-To' uri
     * %Ri : IP address of the interface where the request has been
       received
     * %Rp : received port
     * %si : IP source address
     * %sp : source port
     * %tu : 'To' uri
     * %tt : 'To' tag
     * %Ts : unix time stamp
     * %Tf : string formatted time
     * %Tx : unix time stamp (in hex notation)
     * %ua : User agent header field
     * %uq : unique id (per SER's process) - to make really unique id use
       %uq-%px-%mx or %uq-%px-%Tx
     * %{name[N]} : print the body of the Nth header identified by 'name'.
       If [N] is omitted then the body of the first header is printed. The
       first header is got when N=0, for the second N=1, a.s.o. To print
       the last header of that type, use -1, no other negative values are
       supported now. No white spaces are allowed inside the specifier
       (before }, before or after {, [, ] symbols). When N='*', all
       headers of that type are printed.
       The module should identify most of compact header names (the ones
       recognized by ser which should be all at this moment), if not, the
       compact form has to be specified explicitely. It is recommended to
       use dedicated specifiers for headers (e.g., %ua for user agent
       header), if they are available -- they are faster.
     * %<name[N]> : print the value of AVP optionally %indexed by the [N]
       value It uses AVPs subindexing, e.g. if you don't specify subindex
       and there are more AVPs with the same name, the result is NULL. To
       specify first AVP use [1], negative values are indexes counted
       backward through the list.
     * %@select.framework[N].value : print the value of select framework
       call. For detailed info what calls are available see select
       framework documentation (and modules documentation, as modules can
       extend select framework calls).
     * %| or %(space) : end of %@select.framework identifier. If you need
       to concatenate select framework call and another non-whitespace
       literal, you need to explicitelly set the end of the select
       framework identifier.
       E.g. %@ruri.user%|@%@ruri.host converts all featured request uri
       into user@host form only.

1.3. Parameters

   Revision History
   Revision $Revision$ $Date$

1.3.1. buf_size (integer)

   Maximum size of the log message.

   Default value is 4096.

   Example 1. Set buf_size parameter
...
modparam("xlog", "buf_size", 8192)
...

1.4. Functions

   Revision History
   Revision $Revision$ $Date$

1.4.1.  xlog(level, format)

   Print a formated message using LOG function.

   Meaning of the parameters is as follows:
     * level - The level that will be used in LOG function. It can be:
          + L_ALERT
          + L_CRIT
          + L_ERR
          + L_WARN
          + L_NOTICE
          + L_INFO
          + L_DBG
       What really matters is the third letter of the value.
     * format - The formatted string to be printed.

   Example 2. xlog usage
...
xlog("L_ERR", "time [%Tf] method <%rm> r-uri <%ru> 2nd via <%{via[1]}>\n");
...

1.4.2.  xdbg(format)

   Print a formatted message using DBG function.

   Meaning of the parameters is as follows:
     * format - The formatted string to be printed.

   Example 3. xdbg usage
...
xdbg("time [%Tf] method <%rm> r-uri <%ru>\n");
...

1.5. Module API

   Revision History
   Revision $Revision$ $Date$

1.5.1. Functions

1.5.1.1.  int xbind(xl_api_t *xl_api)

   Bind to the xlog module API.

   Meaning of the parameters is as follows:
     * xl_api - structure that the xlog module functions are bind to. The
       functions can be executed as xl_api.xparse(), xl_api.xprint()...

   Return value: 0 - success, <0 - error.

1.5.1.2.  int xparse(char *s, xl_elog_p *el)

   Parse an xl-formatted string in private memory.

   Meaning of the parameters is as follows:
     * s - string to be parsed.
     * el - returned xl-lib list.

   Return value: 0 - success, <0 - error.

1.5.1.3.  int shm_xparse(char *s, xl_elog_p *el)

   Parse an xl-formatted string in shared memory. See xparse() function
   for details.

1.5.1.4.  int xparse2(char *s, xl_elog_p *el, xl_parse_cb cb)

   Parse an xl-formatted string in private memory. This function is able
   to identify regular expression back references, for example \1, \2,
   \3... When a back reference is found the callback function is called
   that is supposed to farther parse the back reference and fill in the
   xl_elog structure.

   Meaning of the parameters is as follows:
     * s - string to be parsed.
     * el - returned xl-lib list.
     * cb - callback function for parsing the regular expression back
       references.

   The prototype of the callback function is: typedef int (*xl_parse_cb)
   (str *s, int shm, xl_elog_p el);

   Parameters of the callback function:
     * s - regular expression back reference to be parsed (without the
       leading '\' character).
     * shm - indicates whether or not shared memory needs to be used. (1:
       shared memory, 0: private memory)
     * el - pointer to the xl-lib list item that is supposed to be filled
       in.

   Return value: 0 - success, <0 - error.

1.5.1.5.  int shm_xparse2(char *s, xl_elog_p *el, xl_parse_cb cb)

   Parse an xl-formatted string in shared memory supporting regular
   expression back references. See xparse2() function for details.

1.5.1.6.  xfree(xl_elog_p el)

   Free the xl-lib list allocated by xparse() or xparse2().

   Meaning of the parameters is as follows:
     * el - xl-lib list to be freed.

1.5.1.7.  shm_xfree(xl_elog_p el)

   Free the xl-lib list allocated by shm_xparse() or shm_xparse2().

   Meaning of the parameters is as follows:
     * el - xl-lib list to be freed.

1.5.1.8.  int xprint(struct sip_msg* msg, xl_elog_p el, char *buf, int *len)

   Evaluate the xl-formatted string and print the result into a buffer.

   Meaning of the parameters is as follows:
     * msg - SIP message pointer.
     * el - xl-lib list to be evaluated.
     * buf - pre-allocated buffer that is filled in with the result.
     * len - length of the printed string. len needs to be set to the
       maximum length of the result buffer before calling this function.

   Return value: 0 - success, <0 - error.

1.5.1.9.  str *xnulstr()

   Return the string "<null>".