TM :: Callback hooks

Caution: most of the callbacks work with shmem-ized messages which you can no more change (e.g., lumps are fixed). Most reply-processing callbacks are also called from a mutex, which may cause deadlock if you are not careful. Also, reply callbacks may pass the value of FAKED_REPLY messages, which is a non-dereferencable pointer indicating that no message was received and a timer hit instead.

All callbacks excepting the TMCB_REQUEST_IN are associates to a transaction. It means they will be run only when the event will hint the transaction the callbacks were register for. TMCB_REQUEST_IN is a global callback - it means it will be run for all transactions.

--------------------------------

TMCB_REQUEST_IN -- a brand-new request was received and is about to establish transaction; it is not yet cloned and lives in pkg mem -- your last chance to mangle it before it gets shmem-ized (then, it's read-only); it's called from HASH_LOCK, so be careful. It is guaranteed not to be a retransmission. The transactional context is mostly incomplete -- this callback is called in very early stage before the message is shmem-ized (so that you can work with it).

TMCB_RESPONSE_IN -- a brand-new reply was received which matches an existing transaction. It may or may not be a retransmission.

TMCB_RESPONSE_PRE_OUT -- a final reply is about to be sent out (either local or proxied); you cannnot change the reply, but it is usefull to update your state before putting the reply on the network and to avoid any races (receiving an ACK before updating with the status of the reply)

TMCB_RESPONSE_OUT -- a final reply was sent out (either local or proxied) -- there is nothing more you can change from the callback, it is good for accounting-like uses.

Note:

: the message passed to callback may also have value FAKED_REPLY (like other reply callbacks) which indicates a pseudo_reply caused by a timer. Check for this value before deferring -- you will cause a segfault otherwise. Check for t->uas.request validity too if you need it ... locally initiated UAC transactions set it to 0.

TMCB_ON_FAILURE_RO -- called on receipt of a reply or timer; it means all branches completed with a failure; the callback function MUST not change anything in the transaction (READONLY) that's a chance for doing ACC or stuff like this

TMCB_ON_FAILURE -- called on receipt of a reply or timer; it means all branches completed with a failure; that's a chance for example to add new transaction branches

TMCB_RESPONSE_FWDED -- called when a reply is about to be forwarded; it is called after a message is received but before a message is sent out: it is called when the decision is made to forward a reply; it is parametrized by pkg message which caused the transaction to complete (which is not necessarily the same which will be forwarded). As forwarding has not been executed and may fail, there is no guarantee a reply will be successfully sent out at this point of time.

Note:

: TMCB_REPLY_ON_FAILURE and TMCB_REPLY_FWDED are called from reply mutex which is used to deterministically process multiple replies received in parallel. A failure to set the mutex again or stay too long in the callback may result in deadlock.

: the reply callbacks will not be evoked if "silent C-timer hits". That's a feature to clean transactional state from a proxy quickly -- transactions will then complete statelessly. If you wish to disable this feature, either set the global option "noisy_ctimer" to 1, or set t->noisy_ctimer for selected transaction.

TMCB_E2EACK_IN -- called when an ACK belonging to a proxied INVITE transaction completed with 200 arrived. Note that because it can be only dialog-wise matched, only the first transaction occurrence will be matched with spirals. If record-routing is not enabled, you will never receive the ACK and the callback will never be triggered.

TMCB_REQUEST_FWDED -- request is being forwarded out. It is called before a message is forwarded and it is your last chance to change its shape.

TMCB_LOCAL_COMPLETED -- final reply for localy initiated transaction arrived. Message may be FAKED_REPLY.

IMPORTANT NOTES:

1) that callbacks MUST be installed before forking (callback lists do not live in shmem and have no access protection), i.e., at best from mod_init functions.

2) the callback's param MUST be in shared memory and will NOT be freed by TM; you must do it yourself from the callback function if necessary.