# OsipCallLeg private API

## Name

OsipCallLeg private API -- This is the OsipCallLeg api that is used inside the osipua library. This part of documentation should only concern osipua developpers.

## Synopsis

    #include <osipua.h>

    OsipDialog* osip_dialog_new_from_incoming_trn
                                                (transaction_t *trn);
    int         osip_dialog_send_request        (OsipDialog *call_leg,
                                                 sip_t *sipmsg);
    void        osip_dialog_ack                 (OsipDialog *call,
                                                 transaction_t *trn);
    void        osip_dialog_send_response       (OsipDialog *call,
                                                 transaction_t *trn,
                                                 sip_t *resp);
    void        osip_dialog_respond             (OsipDialog *call,
                                                 transaction_t *trn,
                                                 int code);
    void        osip_dialog_update_from_response
                                                (OsipDialog *call,
                                                 sip_t *resp);
    void        osip_dialog_release             (OsipDialog *call);
    int         osip_dialog_destroy             (OsipDialog *call);

## Description

## Details

### osip_dialog_new_from_incoming_trn ()

    OsipDialog* osip_dialog_new_from_incoming_trn
                                                (transaction_t *trn);

Create a new call-leg from an initial incoming request. The function assumes that there is no existing call-leg that match the new request. You should use #osip_dialog_find() to check this.

trn : | an incoming transaction
Returns : | a new call leg.

### osip_dialog_send_request ()

    int         osip_dialog_send_request        (OsipDialog *call_leg,
                                                 sip_t *sipmsg);

Sends a sip request. The transaction is created to wrap the request and to the list of transaction of call-leg call_leg.

call_leg : | a call-leg.
sipmsg : | a sip request.
Returns : | 0 if successfull.

### osip_dialog_ack ()

    void        osip_dialog_ack                 (OsipDialog *call,
                                                 transaction_t *trn);

This function generates and sends an ACK request that will end the transaction trn. Must never be called outside the osip callbacks.

call : | a call-leg.
trn : | a transaction part of the dialog.

### osip_dialog_send_response ()

    void        osip_dialog_send_response       (OsipDialog *call,
                                                 transaction_t *trn,
                                                 sip_t *resp);

Sends the response resp that will be part of the transaction trn, trn being part of the call-leg call.

call : | a call-leg
trn : | a transaction
resp : | a sip response

### osip_dialog_respond ()

    void        osip_dialog_respond             (OsipDialog *call,
                                                 transaction_t *trn,
                                                 int code);

This function creates a sip response in the context of the call-leg call for the last transaction and sends it automatically. A sdp body can be optionnaly appended to the response.

call : | a call-leg.
trn : |
code : | the code of the response.

### osip_dialog_update_from_response ()

    void        osip_dialog_update_from_response
                                                (OsipDialog *call,
                                                 sip_t *resp);

call : |
resp : |

### osip_dialog_release ()

    void        osip_dialog_release             (OsipDialog *call);

Release a dialog. You can't use it anymore, and the object will be destroyed by the stack when the last transaction of the call-leg will terminate, either by successfull completion or timeout.

call : |

### osip_dialog_destroy ()

    int         osip_dialog_destroy             (OsipDialog *call);

Destroy a call-leg and all data associated with it. BUT: this function should not be called directly. You should use osip_dialog_release instead to schedule the destruction of the call leg.

call : | a call-leg.
Returns : | 0.