kamailio/modules/dialog_ng/doc/dialog_ng_devel.xml

<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;

]>
<!-- Module Developer's Guide -->

<chapter>
	
    <title>&develguide;</title>
    <section>
        <title>Available Functions</title>

        <section>
            <title>
                <function moreinfo="none">register_dlgcb (dialog, type, cb, param, free_param_cb)</function>
            </title>
            <para>
		Register a new callback to the dialog.
            </para>
            <para>Meaning of the parameters is as follows:</para>
            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>struct dlg_cell* dlg</emphasis> - dialog to 
			register callback to. If maybe NULL only for DLGCB_CREATED callback
			type, which is not a per dialog type.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>int type</emphasis> - types of callbacks; more
			types may be register for the same callback function; only 
			DLGCB_CREATED must be register alone. Possible types:
                        <itemizedlist>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_LOADED</emphasis>
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_CREATED</emphasis> - called when a new 
				dialog is created - it's a global type (not associated to 
				any dialog)
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_FAILED</emphasis> - called when the dialog
				was negatively replied (non-2xx) - it's a per dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_CONFIRMED_NA</emphasis> - called when the
				dialog is confirmed (2xx replied) but the setup-concluding ACK
				message from the caller is yet pending - it's a per dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_CONFIRMED</emphasis> - called when the
				dialog is confirmed (2xx replied) and the setup-concluding ACK
				message from the caller has been seen - it's a per dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_REQ_WITHIN</emphasis> - called when the 
				dialog matches a sequential request (excluding setup-concluding
				ACK messages which are handled in DLGCB_CONFIRMED) - it's a per
				dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_TERMINATED</emphasis> - called when the 
				dialog is terminated via BYE - it's a per dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_TERMINATED_CONFIRMED</emphasis> -
				called when response to a BYE request is received - it's a
				per dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_EXPIRED</emphasis> - called when the 
				dialog expires without receiving a BYE - it's a per dialog 
				type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_EARLY</emphasis> - called when the
				dialog is created in an early state (18x replied) - it's
				a per dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_RESPONSE_FWDED</emphasis> - called when
				the dialog matches a reply to the initial INVITE request - it's
				a per dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_RESPONSE_WITHIN</emphasis> - called when
				the dialog matches a reply to a subsequent in dialog request
				- it's a per dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_MI_CONTEXT</emphasis> - called when the
				mi dlg_list_ctx command is invoked - it's a per dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_SPIRALED</emphasis> - called when the
				dialog matches a spiraling request - it's a per dialog type.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <emphasis>DLGCB_DESTROY</emphasis>
                                </para>
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>dialog_cb cb</emphasis> - callback function to be 
			called. Prototype is: 
                        <quote>void (dialog_cb) 
			(struct dlg_cell* dlg, int type, struct dlg_cb_params * params);
                        </quote>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>void *param</emphasis> - parameter to be passed to
			the callback function.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>param_free callback_param_free</emphasis> - 
			callback function to be called to free the param.
			Prototype is: 
                        <quote>void (param_free_cb) (void *param);</quote>
                    </para>
                </listitem>

            </itemizedlist>
        </section>

        <section>
            <title>
                <function moreinfo="none">terminate_dlg (str callid, str ftag, str ttag, hdrs)</function>
            </title>
            <para>
		Terminate a Dialog identified by callid, ftag and ttag in early or confirmed state.
            </para>
            <para>Meaning of parameters is as follows:</para>
            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>str* callid</emphasis> - callid of dialog to 
			terminate.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>str* ftag</emphasis> - from_tag of dialog to 
			terminate.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>str* ttag</emphasis> - to tag of dialog to 
			terminate.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>str* hdrs</emphasis> - string containg extra headers (full format) 
			to be added to the BYE requests of the dialog.
                    </para>
                </listitem>
            </itemizedlist>
        </section>

        <section>
            <title>
                <function moreinfo="none">lookup_terminate_dlg (unsigned int h_entry, unsigned int h_id, hdrs)</function>
            </title>
            <para>
		Terminate a Dialog identified by h_entry and h_id (similar to dlg_end_dlg command via XMLRPC).
            </para>
            <para>Meaning of parameters is as follows:</para>
            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>unsigned int h_entry</emphasis> - Number of the table, where to find the dialog
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>unsigned int h_id</emphasis> - Number of the entry in the table, where to find the dialog
			terminate.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>str* hdrs</emphasis> - string containg extra headers (full format) 
			to be added to the BYE requests of the dialog.
                    </para>
                </listitem>
            </itemizedlist>
        </section>
        
        <section>
            <title>
                <function moreinfo="none">set_dlg_var (dlg, key, val)</function>
            </title>
            <para>
		Add a variable to the dialog structure
            </para>
            <para>Meaning of parameters is as follows:</para>
            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>struct dlg_cell* dlg</emphasis> - dialog to 
			add to.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>str* key</emphasis> - Name of the variable.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>str* val</emphasis> - Value of the variable.
                    </para>
                </listitem>
            </itemizedlist>
        </section>
        
        <section>
            <title>
                <function moreinfo="none">get_dlg_var (dlg, key)</function>
            </title>
            <para>
		Retrieves a variable attached to the dialog structure
            </para>
            <para>Meaning of parameters is as follows:</para>
            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>struct dlg_cell* dlg</emphasis> - dialog to 
			get the variable from.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>str* key</emphasis> - Name of the variable.
                    </para>
                </listitem>
            </itemizedlist>
        </section>
        
        <section>
            <title>
                <function moreinfo="none">get_current_dialog ()</function>
            </title>
            <para>
		Get the current dialog for a message, if exists
            </para>
        </section>
        

    </section>

</chapter>