OsipUA public API

Name

OsipUA public API -- The SIP user agent.

Synopsis


#include <osipua.h>


struct      OsipUA;
OsipUA*     osip_ua_new                     (ua_params_t *params);
void        osip_ua_set_ip4addr             (OsipUA *ua,
                                             char *ip4addr);
int         osip_ua_set_contact             (OsipUA *ua,
                                             char *contact);
int         osip_ua_add_alias               (OsipUA *ua,
                                             char *contact);
int         osip_ua_remove_alias            (OsipUA *ua,
                                             char *contact);
void        osip_ua_clean_alias             (OsipUA *ua);
int         (*OsipUASignalHandler)          (OsipCallLeg*,
                                             sip_t*,
                                             void*);
int         osip_ua_signal_connect          (OsipUA *ua,
                                             char *signal,
                                             int (*func) (OsipCallLeg *,sip_t *msg, void*));
int         osip_ua_set_outbound_proxy      (OsipUA *ua,
                                             char *proxy,
                                             char *passwd);
int         osip_ua_destroy                 (OsipUA *ua);

Description

The OsipUA object represents a SIP user agent. It can also be used for "endpoint servers" like conferencing servers or gateway servers. Once the user agent is created, then it is possible setup handlers for the application to be informed of the evolution of the call-legs managed by the user agent.

Details

struct OsipUA

struct OsipUA
{
	osip_t *config; /* the config structure driving the stack*/
	struct _OsipManager *manager;  /* the manager object that manages the stack on which the ua is running */
	contact_t *contact;  /* the user agent real identity, like machin@217.0.0.128 */
	list_t *alias;      /* list of alias like machin@www-db.research.bell-labs.com, including address of records */
	char *fromtag;          /* the from tag put in all from fields of the requests */

	char ua_ip4addr[IP4_SIZE];
	int ua_port;
	list_t call_list;  /* the list of call-legs managed by the user agent*/
	int max_calls;  /* the number of call of ua will process. If the limit is exceeded, it will answer BUSY HERE*/
	url_t *registrar;   /* sip url of a registrar. This is also the address of the proxy if the OSIPUA_USE_PROXY flag is set */
	char *reg_passwd;  /* the password used for registration*/
	unsigned int flags;
	#define OSIP_UA_USE_PROXY (0x0001)
	struct _MediaDesc *maudio;     /* a MediaDescriptor for audio*/
	struct _MediaDesc *mvideo;     /* a MediaDescriptor for video*/
	/*signals*/
	int (*invite)(OsipCallLeg *,sip_t *, void*);   /*INVITE*/
	int (*invite_accepted)(OsipCallLeg *,sip_t*, void*);   /*INVITE_ACCEPTED*/    /* called to signal that media sessions can start*/
	int (*bye)(OsipCallLeg *,sip_t*, void*);  /*BYE*/
	int  (*faillure)(OsipCallLeg *,sip_t*, void*);  /*FAILLURE*/
	int  (*informative)(OsipCallLeg *,sip_t*, void*);  /*various informations*/
	FILE *dbg;

  /* presence management infos */
  int presence_mode;   /* 200-> accept calls
			  486-> answer automatic 486 Busy
			  600-> 600 Busy Evrywhere
			  480-> answar automatic 480 Temporirily unavailable
		          302-> Moved temporarily
		          380-> Alternative service */
  int presence_delay;     /* a value in seconds to ba added to Retry-After
			  in 486 Busy or 480 Temporirily unavailable */
  char *presence_contact_url;   /* contain a sip-url for 302, 301, 380.
			  TO BE DONE: Can also contain an email instead of url!
			  */

};

The fields of the OsipUA structure should not be accessed directly.


osip_ua_new ()

OsipUA*     osip_ua_new                     (ua_params_t *params);

This function creates a user agent according to the parameters in params.


osip_ua_set_ip4addr ()

void        osip_ua_set_ip4addr             (OsipUA *ua,
                                             char *ip4addr);

Set or change the ip address of a user agent.


osip_ua_set_contact ()

int         osip_ua_set_contact             (OsipUA *ua,
                                             char *contact);

Set the official identity of the ua.


osip_ua_add_alias ()

int         osip_ua_add_alias               (OsipUA *ua,
                                             char *contact);

Add a new sip URI the user agent is supposed to respond. If an incoming request does not match the official contact or one of the uri in the alias list, then the ua answers 404 Not Found.


osip_ua_remove_alias ()

int         osip_ua_remove_alias            (OsipUA *ua,
                                             char *contact);

Remove a contact uri from the ua list of alias.


osip_ua_clean_alias ()

void        osip_ua_clean_alias             (OsipUA *ua);

ua: a user agent

Removes and free all alias contact from the user agent alias list.


OsipUASignalHandler ()

int         (*OsipUASignalHandler)          (OsipCallLeg*,
                                             sip_t*,
                                             void*);


osip_ua_signal_connect ()

int         osip_ua_signal_connect          (OsipUA *ua,
                                             char *signal,
                                             int (*func) (OsipCallLeg *,sip_t *msg, void*));

Setup a signal handler for one of the OsipUA signals: "INVITE" to be informed of new invites, "INVITE_ACCEPTED" to be informed of the acceptation of an outgoing invite, "FAILLURE" to be informed of the faillure of an outgoing request, "INFORMATIVE" to be informed a the progress of a call-leg.


osip_ua_set_outbound_proxy ()

int         osip_ua_set_outbound_proxy      (OsipUA *ua,
                                             char *proxy,
                                             char *passwd);

Set a default proxy to use with a user agent. All requests will be sent to the proxy.


osip_ua_destroy ()

int         osip_ua_destroy                 (OsipUA *ua);

Destroy a user agent.