# 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;
    	// to_t *to;
    	// call_id_t *callid;
    	// int local_cseq;
    	// int remote_cseq;
    	int status;
    	url_t *registrar;
    	/*
    	 * * GRS
    	 * * from and to are not enough if (for example) the far end proxy server <        * gets out of the loop and you end up communicating directly with the
    	 * * end system.  Your from and to remain constant, but you need to
    	 * * know who the "real" peer is for request URIs and to send the UDP
    	 * * packets to the right place.
    	 * *
    	 * * this could be handled in one of two ways - the "peer" field could
    	 * * stay null unless its valid, or we could always initialize it to
    	 * * be the same as the to field.  Simon, I'll leave that up to you.
    	 */
    	/* AMD: this can be acheived by the dialog.h API in oSIP */
    	dialog_t *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.