# OsipCallLeg public API

## Name

OsipCallLeg public API --

## Synopsis

    #include <osipua.h>

    struct      OsipDialog;
    struct      RegistrationCtxt;
    OsipDialog* osip_dialog_new                 (struct _OsipUA *ua);
    int         osip_dialog_invite              (OsipDialog *call_leg,
                                                 char *callee,
                                                 char *body_mime);
    void        osip_dialog_accept_invite       (OsipDialog *call_leg,
                                                 transaction_t *trn);
    int         osip_dialog_bye                 (OsipDialog *call_leg);
    int         osip_dialog_register            (OsipDialog *call_leg,
                                                 RegistrationCtxt *ctxt);
    int         osip_dialog_unregister          (OsipDialog *call,
                                                 RegistrationCtxt *ctxt);
    void        osip_dialog_release             (OsipDialog *call);

## Description

## Details

### struct OsipDialog

    struct OsipDialog {

    	from_t *from;
    	int status;
    	url_t *registrar;
    	dialog_t *dialog;
    	char *received;	/* ip address of the originator */
    	char *localip;	/* local ip address to use for this dialog*/
    	/* transactions associated with call-leg */
    	transaction_t *inc_invite_tr;
    	transaction_t *out_invite_tr;
    	transaction_t *inc_bye_tr;
    	transaction_t *out_bye_tr;
    	transaction_t *inc_cancel_tr;
    	transaction_t *out_cancel_tr;
    	transaction_t *out_register_tr;

    	/* list_t incoming_transactions; */
    	/* list_t outgoing_transactions; */

    	struct _RegistrationCtxt *reg_context;	/* the registration context if a registration is occuring */
    	int inv_auth_count;
    	int reg_auth_count;
    	int resp180_count;
    	unsigned int tag_set:1;
    	unsigned int padding:31;

    	struct _OsipUA *ua;	/* the ua object that manages the call */
    	list_t body_contexts;	/* the active body contexts */
    	void *data;
    };

### struct RegistrationCtxt

    struct RegistrationCtxt {

    	char *registrar;   /* name or address of the registrar */
    	char *address_of_record;   /* can be NULL, in which case calleg->from is used */
    	char *password;
            int cseq_number;
            char *callid_number;
    	int expires;
    	int action; 	/* perhaps deprecated ...*/
    #define REGISTER_ACTION_PROXY 0
    #define REGISTER_ACTION_REDIRECT 1
    #define REGISTER_ACTION_ANY 2
    	int ref_count;  /* private, don 't touch it ! */
    } ;

### osip_dialog_new ()

    OsipDialog* osip_dialog_new                 (struct _OsipUA *ua);

Creates a new OsipDialog object managed by the user agent ua.

ua : | an existing user agent.
Returns : | a new call leg.

### osip_dialog_invite ()

    int         osip_dialog_invite              (OsipDialog *call_leg,
                                                 char *callee,
                                                 char *body_mime);

Sends an invite to callee.

call_leg : | a call-leg.
callee : | the URI of the person to invite.
body_mime : |
Returns : | 0 if the invite was sent, a negative value if not.

### osip_dialog_accept_invite ()

    void        osip_dialog_accept_invite       (OsipDialog *call_leg,
                                                 transaction_t *trn);

On reception of the 200 Ok for invite, then the osipua library calls the "INVITE" signal handler. Then the user can choose to accept the call using this function. If the user wants to reject the call, then it should call osip_dialog_bye().

call_leg : |
trn : | a transaction initiated by INVITE from a remote client.

### osip_dialog_bye ()

    int         osip_dialog_bye                 (OsipDialog *call_leg);

Sends a bye and ends the call-leg.

call_leg : | a call-leg.
Returns : | 0 if the bye was sent, a negative value if not.

### osip_dialog_register ()

    int         osip_dialog_register            (OsipDialog *call_leg,
                                                 RegistrationCtxt *ctxt);

Sends a REGISTER request to a registrar.

call_leg : | a call-leg.
ctxt : |
Returns : | 0 if the REGISTER was sent, a negative value if not.

### osip_dialog_unregister ()

    int         osip_dialog_unregister          (OsipDialog *call,
                                                 RegistrationCtxt *ctxt);

Sends a REGISTER request to a registrar with a expire=0, so that the registration is cancelled. Warning: the ctxt structure may be changed. Do not rely on it to make a new registration.

call : | a call-leg.
ctxt : | a registration context that has been used to make a previous registration.
Returns : | 0 if the REGISTER was sent, a negative value if not.

### 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 : | a dialog.