$Revision: 1.2 $
$Date: 2005/08/24 13:24:35 $

# TM Module API

There are applications which would like to generate SIP transactions without too big involvement in SIP stack, transaction management, etc. An example of such an application is sending instant messages from a website. To address needs of such apps, SER accepts requests for new transactions via fifo pipes too. If you want to enable this feature, start FIFO server with configuration option.

fifo="/tmp/ser_fifo"

Then, an application can easily launch a new transaction by writing a transaction request to this named pipe. The request must follow very simple format, which is

     :t_uac_from:[<file_name>]\n
     <method>\n
     <sender's uri>\n
     <dst uri>\n
     <CR_separated_headers>\n
     <body>\n
     .\n
     \n

(Filename is to where a report will be dumped. ser assumes /tmp as file's directory.)

Note the the request write must be atomic, otherwise it might get intermixed with writes from other writers. You can easily use it via Unix command-line tools, see the following example:

    [jiri@bat jiri]$ cat > /tmp/ser_fifo
    :t_uac_from:xxx
    MESSAGE
    sip:sender@iptel.org
    sip:mrx@iptel.org
    header:value
    foo:bar
    bznk:hjhjk
    p_header: p_value

    body body body
    yet body
    end of body
    .

or cat test/transaction.fifo > /tmp/ser_fifo

## Defines

- ACK_TAG enables stricter matching of acknowledgments including to-tags. Without it, to-tags are ignored. It is disabled by default for two reasons:

  - It eliminates an unlikely race condition in which transaction's to-tag is being rewritten by a 200 OK whereas an ACK is being looked up by to-tag.

  - It makes UACs happy who set wrong to-tags.

  It should not make a difference, as there may be only one negative reply sent upstream and 200/ACKs are not matched as they constitute another transaction. It will make no difference at all when the new magic cookie matching is enabled anyway.

- CANCEL_TAG similarly enables strict matching of CANCELs including to-tags--act of mercy to UACs, who screw up the to-tags (however, it still depends on how forgiving the downstream UAS is). Like with ACK_TAG, all this complex transactions matching goes with RFC3261's magic cookie away anyway.

## Functions

### `register_tmcb(cb_type, cb_func)`

For programmatic use only--register a function to be called back on an event. See t_hooks.h for more details.

Meaning of the parameters is as follows:

- cb_type - Callback type.

- cb_func - Callback function.

### `load_tm(*import_structure)`

For programmatic use only--import exported TM functions. See the acc module for an example of use.

Meaning of the parameters is as follows:

- import_structure - Pointer to the import structure.