From 3034f9480369cb8083cd625b358354b4618cd985 Mon Sep 17 00:00:00 2001 From: Benny Prijono Date: Sat, 17 Jun 2006 04:08:30 +0000 Subject: Modifications all over the place, but mainly only to update Doxygen documentation git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@515 74dad513-b988-da41-8d7b-12977e46ad98 --- pjsip/include/pjsip-simple/evsub.h | 3 +- pjsip/include/pjsip-simple/evsub_msg.h | 10 +- pjsip/include/pjsip-simple/iscomposing.h | 13 + pjsip/include/pjsip-simple/pidf.h | 1 + pjsip/include/pjsip-simple/presence.h | 4 + pjsip/include/pjsip-simple/xpidf.h | 1 + pjsip/include/pjsip-ua/sip_inv.h | 73 +- pjsip/include/pjsip-ua/sip_regc.h | 39 +- pjsip/include/pjsip-ua/sip_xfer.h | 18 +- pjsip/include/pjsip/sip_auth.h | 12 +- pjsip/include/pjsip/sip_auth_msg.h | 170 ++- pjsip/include/pjsip/sip_auth_parser.h | 55 +- pjsip/include/pjsip/sip_config.h | 62 +- pjsip/include/pjsip/sip_dialog.h | 29 +- pjsip/include/pjsip/sip_endpoint.h | 27 +- pjsip/include/pjsip/sip_errno.h | 17 + pjsip/include/pjsip/sip_event.h | 14 +- pjsip/include/pjsip/sip_module.h | 86 +- pjsip/include/pjsip/sip_msg.h | 255 +--- pjsip/include/pjsip/sip_parser.h | 65 +- pjsip/include/pjsip/sip_private.h | 15 - pjsip/include/pjsip/sip_resolve.h | 16 +- pjsip/include/pjsip/sip_tel_uri.h | 12 + pjsip/include/pjsip/sip_transaction.h | 23 +- pjsip/include/pjsip/sip_transport.h | 53 +- pjsip/include/pjsip/sip_transport_loop.h | 21 + pjsip/include/pjsip/sip_transport_udp.h | 19 +- pjsip/include/pjsip/sip_types.h | 32 +- pjsip/include/pjsip/sip_ua_layer.h | 31 +- pjsip/include/pjsip/sip_uri.h | 113 +- pjsip/include/pjsip/sip_util.h | 19 +- pjsip/include/pjsip_simple.h | 3 +- pjsip/include/pjsua-lib/pjsua.h | 2237 +++++++++++++++++------------- 33 files changed, 2044 insertions(+), 1504 deletions(-) (limited to 'pjsip/include') diff --git a/pjsip/include/pjsip-simple/evsub.h b/pjsip/include/pjsip-simple/evsub.h index 0bcd63a9..4eb2ae1c 100644 --- a/pjsip/include/pjsip-simple/evsub.h +++ b/pjsip/include/pjsip-simple/evsub.h @@ -30,6 +30,7 @@ /** * @defgroup PJSIP_EVENT_NOT SIP Event Notification (RFC 3265) Module * @ingroup PJSIP_SIMPLE + * @brief Core Event Subscription framework, used by presence, call transfer, etc. * @{ * * This module provides the implementation of SIP Extension for SIP Specific @@ -430,7 +431,7 @@ PJ_DECL(pjsip_evsub*) pjsip_tsx_get_evsub(pjsip_transaction *tsx); * Set event subscription's module data. * * @param sub The event subscription. - * @param index The module id. + * @param mod_id The module id. * @param data Arbitrary data. */ PJ_DECL(void) pjsip_evsub_set_mod_data( pjsip_evsub *sub, unsigned mod_id, diff --git a/pjsip/include/pjsip-simple/evsub_msg.h b/pjsip/include/pjsip-simple/evsub_msg.h index 4f4a9b92..3f464ddb 100644 --- a/pjsip/include/pjsip-simple/evsub_msg.h +++ b/pjsip/include/pjsip-simple/evsub_msg.h @@ -26,6 +26,7 @@ #include /** + * @defgroup PJSIP_EVENT_HDRS Additional Header Fields * @ingroup PJSIP_EVENT_NOT * @{ */ @@ -41,7 +42,9 @@ PJ_BEGIN_DECL */ typedef struct pjsip_event_hdr { + /** Standard header fields. */ PJSIP_DECL_HDR_MEMBER(struct pjsip_event_hdr); + pj_str_t event_type; /**< Event name. */ pj_str_t id_param; /**< Optional event ID parameter. */ pjsip_param other_param; /**< Other parameter. */ @@ -66,11 +69,12 @@ typedef pjsip_generic_array_hdr pjsip_allow_events_hdr; /** * Create a new Allow-Events header. * - * @param pool. The pool. + * @param pool The pool. * * @return Allow-Events header. */ -PJ_DECL(pjsip_allow_events_hdr*) pjsip_allow_events_hdr_create(pj_pool_t *pool); +PJ_DECL(pjsip_allow_events_hdr*) +pjsip_allow_events_hdr_create(pj_pool_t *pool); /** @@ -78,7 +82,9 @@ PJ_DECL(pjsip_allow_events_hdr*) pjsip_allow_events_hdr_create(pj_pool_t *pool); */ typedef struct pjsip_sub_state_hdr { + /** Standard header fields. */ PJSIP_DECL_HDR_MEMBER(struct pjsip_sub_state_hdr); + pj_str_t sub_state; /**< Subscription state. */ pj_str_t reason_param; /**< Optional termination reason. */ int expires_param; /**< Expires param, or -1. */ diff --git a/pjsip/include/pjsip-simple/iscomposing.h b/pjsip/include/pjsip-simple/iscomposing.h index b5544ea4..428c1251 100644 --- a/pjsip/include/pjsip-simple/iscomposing.h +++ b/pjsip/include/pjsip-simple/iscomposing.h @@ -26,6 +26,15 @@ #include #include +/** + * @defgroup PJSIP_ISCOMPOSING Message Composition Indication (RFC 3994) + * @ingroup PJSIP_SIMPLE + * @brief Support for Indication of Message Composition (RFC 3994) + * @{ + * + * This implements message composition indication, as described in + * RFC 3994. + */ PJ_BEGIN_DECL @@ -113,6 +122,10 @@ PJ_DECL(pj_status_t) pjsip_iscomposing_parse( pj_pool_t *pool, int *p_refresh ); +/** + * @} + */ + PJ_END_DECL diff --git a/pjsip/include/pjsip-simple/pidf.h b/pjsip/include/pjsip-simple/pidf.h index 1b57c5d2..ccd844ce 100644 --- a/pjsip/include/pjsip-simple/pidf.h +++ b/pjsip/include/pjsip-simple/pidf.h @@ -32,6 +32,7 @@ PJ_BEGIN_DECL /** * @defgroup PJSIP_SIMPLE_PIDF PIDF/Presence Information Data Format (RFC 3863) * @ingroup PJSIP_SIMPLE + * @brief Support for PIDF/Presence Information Data Format (RFC 3863) * @{ * * This file provides tools for manipulating Presence Information Data diff --git a/pjsip/include/pjsip-simple/presence.h b/pjsip/include/pjsip-simple/presence.h index f8d63527..ee2805f4 100644 --- a/pjsip/include/pjsip-simple/presence.h +++ b/pjsip/include/pjsip-simple/presence.h @@ -34,6 +34,7 @@ PJ_BEGIN_DECL /** * @defgroup PJSIP_SIMPLE_PRES SIP Extension for Presence (RFC 3856) * @ingroup PJSIP_SIMPLE + * @brief Support for SIP Extension for Presence (RFC 3856) * @{ * * This module contains the implementation of SIP Presence Extension as @@ -67,6 +68,9 @@ PJ_DECL(pj_status_t) pjsip_pres_init_module(pjsip_endpoint *endpt, PJ_DECL(pjsip_module*) pjsip_pres_instance(void); +/** + * Maximum presence status info. + */ #define PJSIP_PRES_STATUS_MAX_INFO 8 /** diff --git a/pjsip/include/pjsip-simple/xpidf.h b/pjsip/include/pjsip-simple/xpidf.h index c5736c54..17938fd6 100644 --- a/pjsip/include/pjsip-simple/xpidf.h +++ b/pjsip/include/pjsip-simple/xpidf.h @@ -31,6 +31,7 @@ PJ_BEGIN_DECL /** * @defgroup PJSIP_SIMPLE_XPIDF XPIDF/Presence Information Data Format * @ingroup PJSIP_SIMPLE + * @brief Support for XPIDF/Presence Information Data Format * @{ * * This is an old presence data format as described in: diff --git a/pjsip/include/pjsip-ua/sip_inv.h b/pjsip/include/pjsip-ua/sip_inv.h index cdc8b8f9..e07ba79a 100644 --- a/pjsip/include/pjsip-ua/sip_inv.h +++ b/pjsip/include/pjsip-ua/sip_inv.h @@ -19,21 +19,73 @@ #ifndef __SIP_INVITE_SESSION_H__ #define __SIP_INVITE_SESSION_H__ +/** + * @file sip_inv.h + * @brief INVITE sessions + */ + + #include #include +/** + * @defgroup PJSIP_HIGH_UA User Agent Library + * @ingroup PJSIP + * @brief Mid-level User Agent Library. + * + * This is the high level user agent library, which consists of: + * - @ref PJSIP_INV, to encapsulate INVITE sessions and SDP + * negotiation in the session, + * - @ref PJSUA_REGC, high level client registration API, and + * - @ref PJSUA_XFER. + * + * More detailed information is explained in + * PJSIP Developer's Guide + * PDF document, and readers are encouraged to read the document to + * get the concept behind dialog, dialog usages, and INVITE sessions. + * + * The User Agent Library is implemented in pjsip-ua static + * library. + */ + +/** + * @defgroup PJSIP_INV INVITE Session + * @ingroup PJSIP_HIGH_UA + * @brief Provides INVITE session management. + * @{ + * + * The INVITE session uses the @ref PJSIP_DIALOG framework to manage + * the underlying dialog, and is one type of usages that can use + * a particular dialog instance (other usages are event subscription, + * discussed in @ref PJSIP_EVENT_NOT). The INVITE session manages + * the life-time of the session, and also manages the SDP negotiation. + * + * Application must link with pjsip-ua static library to use this API. + * + * More detailed information is explained in + * PJSIP Developer's Guide + * PDF document, and readers are encouraged to read the document to + * get the concept behind dialog, dialog usages, and INVITE sessions. + * + * The INVITE session does NOT manage media. If application wants to + * use API that encapsulates both signaling and media in a very easy + * to use API, it can use @ref PJSUA_LIB for this purpose. + */ + PJ_BEGIN_DECL -typedef enum pjsip_inv_state pjsip_inv_state; +/** + * @see pjsip_inv_session + */ typedef struct pjsip_inv_session pjsip_inv_session; -typedef struct pjsip_inv_callback pjsip_inv_callback; + /** * This enumeration describes invite session state. */ -enum pjsip_inv_state +typedef enum pjsip_inv_state { PJSIP_INV_STATE_NULL, /**< Before INVITE is sent or received */ PJSIP_INV_STATE_CALLING, /**< After INVITE is sent */ @@ -42,14 +94,14 @@ enum pjsip_inv_state PJSIP_INV_STATE_CONNECTING, /**< After 2xx is sent/received. */ PJSIP_INV_STATE_CONFIRMED, /**< After ACK is sent/received. */ PJSIP_INV_STATE_DISCONNECTED, /**< Session is terminated. */ -}; +} pjsip_inv_state; /** * This structure contains callbacks to be registered by application to * receieve notifications from the framework about various events in * the invite session. */ -struct pjsip_inv_callback +typedef struct pjsip_inv_callback { /** * This callback is called when the invite sesion state has changed. @@ -118,7 +170,9 @@ struct pjsip_inv_callback */ void (*on_media_update)(pjsip_inv_session *inv_ses, pj_status_t status); -}; + +} pjsip_inv_callback; + /** @@ -187,7 +241,7 @@ struct pjsip_inv_session * occurences of events in invite sessions. * * @param endpt The endpoint instance. - * @param callback Callback structure. + * @param cb Callback structure. * * @return PJ_SUCCESS on success, or the appropriate error code. */ @@ -310,7 +364,7 @@ PJ_DECL(pj_status_t) pjsip_inv_verify_request( pjsip_rx_data *rdata, * in rdata. The invite session needs to inspect the * received request to see if the request contains * features that it supports. - * @param sdp If application has determined its media capability, + * @param local_sdp If application has determined its media capability, * it can specify this capability in this argument. * If SDP is received in the initial INVITE, the UAS * capability specified in this argument doesn't have to @@ -563,6 +617,9 @@ PJ_DECL(const char *) pjsip_inv_state_name(pjsip_inv_state state); PJ_END_DECL +/** + * @} + */ #endif /* __SIP_INVITE_SESSION_H__ */ diff --git a/pjsip/include/pjsip-ua/sip_regc.h b/pjsip/include/pjsip-ua/sip_regc.h index d86c330e..a071fcc1 100644 --- a/pjsip/include/pjsip-ua/sip_regc.h +++ b/pjsip/include/pjsip-ua/sip_regc.h @@ -26,18 +26,22 @@ #include #include -//#include -PJ_BEGIN_DECL /** - * @defgroup PJSUA_REGC SIP Registration Client - * @ingroup PJSUA + * @defgroup PJSUA_REGC Client Registration + * @ingroup PJSIP_HIGH_UA + * @brief High Layer API for performing client registration. * @{ - * \brief - * API for performing registration for user agent. + * + * This provides API for performing client registration. Application must + * link with pjsip-ua static library to use this API. + */ + +PJ_BEGIN_DECL + /** Typedef for client registration data. */ typedef struct pjsip_regc pjsip_regc; @@ -56,15 +60,15 @@ typedef struct pjsip_regc pjsip_regc; */ struct pjsip_regc_cbparam { - pjsip_regc *regc; - void *token; - int code; - pj_status_t status; - pj_str_t reason; - pjsip_rx_data *rdata; - int contact_cnt; - int expiration; - pjsip_contact_hdr *contact[PJSIP_REGC_MAX_CONTACT]; + pjsip_regc *regc; /**< Client registration structure. */ + void *token; /**< Arbitrary token. */ + pj_status_t status; /**< Error status. */ + int code; /**< SIP status code received. */ + pj_str_t reason; /**< SIP reason phrase received. */ + pjsip_rx_data *rdata; /**< The complete received response. */ + int expiration;/**< Next expiration interval. */ + int contact_cnt;/** #include +/** + * @defgroup PJSUA_XFER Call Transfer + * @ingroup PJSIP_HIGH_UA + * @brief Provides call transfer functionality. + * @{ + * + * This implements call transfer functionality to INVITE sessions. The call + * transfer functionality uses SIP Event Subscription framework for + * managing call transfer status. + * + * Application must link with pjsip-ua AND pjsip-simple static + * libraries to use call transfer functionality. + */ PJ_BEGIN_DECL @@ -168,8 +181,11 @@ PJ_DECL(pj_status_t) pjsip_xfer_send_request( pjsip_evsub *sub, pjsip_tx_data *tdata); - PJ_END_DECL +/** + * @} + */ + #endif /* __PJSIP_XFER_H__ */ diff --git a/pjsip/include/pjsip/sip_auth.h b/pjsip/include/pjsip/sip_auth.h index 7a8eb610..b049e1c4 100644 --- a/pjsip/include/pjsip/sip_auth.h +++ b/pjsip/include/pjsip/sip_auth.h @@ -29,14 +29,20 @@ PJ_BEGIN_DECL +/** + * @addtogroup PJSIP_AUTH Authentication Framework + * @ingroup PJSIP_CORE + * @brief Client and server side authentication framework. + */ /** - * @defgroup PJSIP_AUTH_API Authorization API's + * @defgroup PJSIP_AUTH_API Authentication API's * @ingroup PJSIP_AUTH + * @brief Structures and functions to perform authentication. * @{ */ -/* Length of digest string. */ +/** Length of digest string. */ #define PJSIP_MD5STRLEN 32 @@ -80,6 +86,7 @@ struct pjsip_cred_info */ typedef struct pjsip_cached_auth_hdr { + /** Standard list member */ PJ_DECL_LIST_MEMBER(struct pjsip_cached_auth_hdr); pjsip_method method; /**< To quickly see the method. */ @@ -100,6 +107,7 @@ typedef struct pjsip_cached_auth_hdr */ typedef struct pjsip_cached_auth { + /** Standard list member */ PJ_DECL_LIST_MEMBER(struct pjsip_cached_auth); pj_str_t realm; /**< Realm. */ diff --git a/pjsip/include/pjsip/sip_auth_msg.h b/pjsip/include/pjsip/sip_auth_msg.h index 81d6cd09..d73946bc 100644 --- a/pjsip/include/pjsip/sip_auth_msg.h +++ b/pjsip/include/pjsip/sip_auth_msg.h @@ -24,21 +24,23 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_MSG_AUTHORIZATION Header Field: Authorization and Proxy-Authorization - * @brief Authorization and Proxy-Authorization header field. - * @ingroup PJSIP_MSG + * @addtogroup PJSIP_MSG_HDR * @{ */ /** - * Common credential. + * Common credential structure represents common credential fields + * present in Authorization/Proxy-Authorization header. */ struct pjsip_common_credential { - pj_str_t realm; - pjsip_param other_param; + pj_str_t realm; /**< Credential's realm. */ + pjsip_param other_param; /**< Other parameters. */ }; +/** + * @see pjsip_common_credential + */ typedef struct pjsip_common_credential pjsip_common_credential; @@ -48,19 +50,22 @@ typedef struct pjsip_common_credential pjsip_common_credential; */ struct pjsip_digest_credential { - pj_str_t realm; - pjsip_param other_param; - pj_str_t username; - pj_str_t nonce; - pj_str_t uri; - pj_str_t response; - pj_str_t algorithm; - pj_str_t cnonce; - pj_str_t opaque; - pj_str_t qop; - pj_str_t nc; + pj_str_t realm; /**< Realm of the credential */ + pjsip_param other_param; /**< Other parameters. */ + pj_str_t username; /**< Username parameter. */ + pj_str_t nonce; /**< Nonce parameter. */ + pj_str_t uri; /**< URI parameter. */ + pj_str_t response; /**< Response digest. */ + pj_str_t algorithm; /**< Algorithm. */ + pj_str_t cnonce; /**< Cnonce. */ + pj_str_t opaque; /**< Opaque value. */ + pj_str_t qop; /**< Quality of protection. */ + pj_str_t nc; /**< Nonce count. */ }; +/** + * @see pjsip_digest_credential + */ typedef struct pjsip_digest_credential pjsip_digest_credential; /** @@ -69,14 +74,17 @@ typedef struct pjsip_digest_credential pjsip_digest_credential; */ struct pjsip_pgp_credential { - pj_str_t realm; - pjsip_param other_param; - pj_str_t version; - pj_str_t signature; - pj_str_t signed_by; - pj_str_t nonce; + pj_str_t realm; /**< Realm. */ + pjsip_param other_param; /**< Other parameters. */ + pj_str_t version; /**< Version parameter. */ + pj_str_t signature; /**< Signature parameter. */ + pj_str_t signed_by; /**< Signed by parameter. */ + pj_str_t nonce; /**< Nonce parameter. */ }; +/** + * @see pjsip_pgp_credential + */ typedef struct pjsip_pgp_credential pjsip_pgp_credential; /** @@ -85,16 +93,24 @@ typedef struct pjsip_pgp_credential pjsip_pgp_credential; */ struct pjsip_authorization_hdr { + /** Standard header fiends. */ PJSIP_DECL_HDR_MEMBER(struct pjsip_authorization_hdr); + + /** Authorization scheme. */ pj_str_t scheme; + + /** Type of credentials, depending on the scheme. */ union { - pjsip_common_credential common; - pjsip_digest_credential digest; - pjsip_pgp_credential pgp; + pjsip_common_credential common; /**< Common fields. */ + pjsip_digest_credential digest; /**< Digest credentials. */ + pjsip_pgp_credential pgp; /**< PGP credentials. */ } credential; }; +/** + * @see pjsip_authorization_hdr. + */ typedef struct pjsip_authorization_hdr pjsip_authorization_hdr; /** SIP Proxy-Authorization header shares the same structure as SIP @@ -104,36 +120,34 @@ typedef struct pjsip_authorization_hdr pjsip_proxy_authorization_hdr; /** * Create SIP Authorization header. - * @param pool Pool where memory will be allocated from. - * @return SIP Authorization header. + * @param pool Pool where memory will be allocated from. + * @return SIP Authorization header. */ -PJ_DECL(pjsip_authorization_hdr*) pjsip_authorization_hdr_create(pj_pool_t *pool); +PJ_DECL(pjsip_authorization_hdr*) +pjsip_authorization_hdr_create(pj_pool_t *pool); /** * Create SIP Proxy-Authorization header. - * @param pool Pool where memory will be allocated from. - * @return SIP Proxy-Authorization header. + * @param pool Pool where memory will be allocated from. + * @return SIP Proxy-Authorization header. */ -PJ_DECL(pjsip_proxy_authorization_hdr*) pjsip_proxy_authorization_hdr_create(pj_pool_t *pool); +PJ_DECL(pjsip_proxy_authorization_hdr*) +pjsip_proxy_authorization_hdr_create(pj_pool_t *pool); /** - * @} - */ - -/** - * @defgroup PJSIP_WWW_AUTH Header Field: Proxy-Authenticate and WWW-Authenticate - * @brief Proxy-Authenticate and WWW-Authenticate. - * @ingroup PJSIP_MSG - * @{ + * This structure describes common fields in authentication challenge + * headers (WWW-Authenticate and Proxy-Authenticate). */ - struct pjsip_common_challenge { - pj_str_t realm; - pjsip_param other_param; + pj_str_t realm; /**< Realm for the challenge. */ + pjsip_param other_param; /**< Other parameters. */ }; +/** + * @see pjsip_common_challenge + */ typedef struct pjsip_common_challenge pjsip_common_challenge; /** @@ -142,16 +156,19 @@ typedef struct pjsip_common_challenge pjsip_common_challenge; */ struct pjsip_digest_challenge { - pj_str_t realm; - pjsip_param other_param; - pj_str_t domain; - pj_str_t nonce; - pj_str_t opaque; - int stale; - pj_str_t algorithm; - pj_str_t qop; + pj_str_t realm; /**< Realm for the challenge. */ + pjsip_param other_param; /**< Other parameters. */ + pj_str_t domain; /**< Domain. */ + pj_str_t nonce; /**< Nonce challenge. */ + pj_str_t opaque; /**< Opaque value. */ + int stale; /**< Stale parameter. */ + pj_str_t algorithm; /**< Algorithm parameter. */ + pj_str_t qop; /**< Quality of protection. */ }; +/** + * @see pjsip_digest_challenge + */ typedef struct pjsip_digest_challenge pjsip_digest_challenge; /** @@ -160,14 +177,17 @@ typedef struct pjsip_digest_challenge pjsip_digest_challenge; */ struct pjsip_pgp_challenge { - pj_str_t realm; - pjsip_param other_param; - pj_str_t version; - pj_str_t micalgorithm; - pj_str_t pubalgorithm; - pj_str_t nonce; + pj_str_t realm; /**< Realm for the challenge. */ + pjsip_param other_param; /**< Other parameters. */ + pj_str_t version; /**< PGP version. */ + pj_str_t micalgorithm; /**< micalgorithm parameter. */ + pj_str_t pubalgorithm; /**< pubalgorithm parameter. */ + pj_str_t nonce; /**< Nonce challenge. */ }; +/** + * @see pjsip_pgp_challenge + */ typedef struct pjsip_pgp_challenge pjsip_pgp_challenge; /** @@ -176,33 +196,51 @@ typedef struct pjsip_pgp_challenge pjsip_pgp_challenge; */ struct pjsip_www_authenticate_hdr { + /** Standard header fields. */ PJSIP_DECL_HDR_MEMBER(struct pjsip_www_authenticate_hdr); + + /** Authentication scheme */ pj_str_t scheme; + + /** This union contains structures that are only relevant + depending on the value of the scheme being used. + */ union { - pjsip_common_challenge common; - pjsip_digest_challenge digest; - pjsip_pgp_challenge pgp; + pjsip_common_challenge common; /**< Common fields. */ + pjsip_digest_challenge digest; /**< Digest challenge. */ + pjsip_pgp_challenge pgp; /**< PGP challenge. */ } challenge; }; +/** + * WWW-Authenticate header. + */ typedef struct pjsip_www_authenticate_hdr pjsip_www_authenticate_hdr; + +/** + * Proxy-Authenticate header. + */ typedef struct pjsip_www_authenticate_hdr pjsip_proxy_authenticate_hdr; /** * Create SIP WWW-Authenticate header. - * @param pool Pool where memory will be allocated from. - * @return SIP WWW-Authenticate header. + * + * @param pool Pool where memory will be allocated from. + * @return SIP WWW-Authenticate header. */ -PJ_DECL(pjsip_www_authenticate_hdr*) pjsip_www_authenticate_hdr_create(pj_pool_t *pool); +PJ_DECL(pjsip_www_authenticate_hdr*) +pjsip_www_authenticate_hdr_create(pj_pool_t *pool); /** * Create SIP Proxy-Authenticate header. - * @param pool Pool where memory will be allocated from. - * @return SIP Proxy-Authenticate header. + * + * @param pool Pool where memory will be allocated from. + * @return SIP Proxy-Authenticate header. */ -PJ_DECL(pjsip_proxy_authenticate_hdr*) pjsip_proxy_authenticate_hdr_create(pj_pool_t *pool); +PJ_DECL(pjsip_proxy_authenticate_hdr*) +pjsip_proxy_authenticate_hdr_create(pj_pool_t *pool); /** * @} diff --git a/pjsip/include/pjsip/sip_auth_parser.h b/pjsip/include/pjsip/sip_auth_parser.h index 3a214bef..73e9a82a 100644 --- a/pjsip/include/pjsip/sip_auth_parser.h +++ b/pjsip/include/pjsip/sip_auth_parser.h @@ -28,18 +28,14 @@ PJ_BEGIN_DECL -/** - * @defgroup PJSIP_AUTH_PARSER_MODULE Authorization Parser Module - * @ingroup PJSIP_AUTH - * @{ - */ - /** * Initialize and register authorization parser module. * This will register parser handler for various Authorization related headers * such as Authorization, WWW-Authenticate, Proxy-Authorizization, and * Proxy-Authenticate headers. * + * This function is called automatically by the main SIP parser. + * * @return PJ_SUCCESS or the appropriate status code. */ PJ_DECL(pj_status_t) pjsip_auth_init_parser(void); @@ -50,36 +46,25 @@ PJ_DECL(pj_status_t) pjsip_auth_init_parser(void); PJ_DECL(void) pjsip_auth_deinit_parser(); -extern const pj_str_t pjsip_USERNAME_STR, - pjsip_REALM_STR, - pjsip_NONCE_STR, - pjsip_URI_STR, - pjsip_RESPONSE_STR, - pjsip_ALGORITHM_STR, - pjsip_DOMAIN_STR, - pjsip_STALE_STR, - pjsip_QOP_STR, - pjsip_CNONCE_STR, - pjsip_OPAQUE_STR, - pjsip_NC_STR, - pjsip_TRUE_STR, - pjsip_FALSE_STR, - pjsip_DIGEST_STR, - pjsip_PGP_STR, - pjsip_MD5_STR, - pjsip_AUTH_STR; -/* -extern const pj_str_t pjsip_QUOTED_TRUE_STR, - pjsip_QUOTED_FALSE_STR, - pjsip_QUOTED_DIGEST_STR, - pjsip_QUOTED_PGP_STR, - pjsip_QUOTED_MD5_STR, - pjsip_QUOTED_AUTH_STR; -*/ -/** - * @} - */ +extern const pj_str_t pjsip_USERNAME_STR, /**< "username" string const. */ + pjsip_REALM_STR, /**< "realm" string const. */ + pjsip_NONCE_STR, /**< "nonce" string const. */ + pjsip_URI_STR, /**< "uri" string const. */ + pjsip_RESPONSE_STR, /**< "response" string const. */ + pjsip_ALGORITHM_STR,/**< "algorithm" string const. */ + pjsip_DOMAIN_STR, /**< "domain" string const. */ + pjsip_STALE_STR, /**< "stale" string const. */ + pjsip_QOP_STR, /**< "qop" string const. */ + pjsip_CNONCE_STR, /**< "cnonce" string const. */ + pjsip_OPAQUE_STR, /**< "opaque" string const. */ + pjsip_NC_STR, /**< "nc" string const. */ + pjsip_TRUE_STR, /**< "true" string const. */ + pjsip_FALSE_STR, /**< "false" string const. */ + pjsip_DIGEST_STR, /**< "digest" string const. */ + pjsip_PGP_STR, /**< "pgp" string const. */ + pjsip_MD5_STR, /**< "md5" string const. */ + pjsip_AUTH_STR; /**< "auth" string const. */ PJ_END_DECL diff --git a/pjsip/include/pjsip/sip_config.h b/pjsip/include/pjsip/sip_config.h index 593e539a..23575766 100644 --- a/pjsip/include/pjsip/sip_config.h +++ b/pjsip/include/pjsip/sip_config.h @@ -19,8 +19,43 @@ #ifndef __PJSIP_SIP_CONFIG_H__ #define __PJSIP_SIP_CONFIG_H__ +/** + * @file sip_config.h + * @brief Compile time configuration. + */ #include +/** + * @defgroup PJSIP PJSIP Library Collection + */ + +/** + * @defgroup PJSIP_CORE Core SIP Library + * @ingroup PJSIP + * @brief The core framework from which all other SIP components depends on. + * + * The PJSIP Core library only provides transport framework, event + * dispatching/module framework, and SIP message representation and + * parsing. It doesn't do anything usefull in itself! + * + * If application wants the stack to do anything usefull at all, + * it must registers @ref PJSIP_MOD to the core library. Examples + * of modules are @ref PJSIP_TRANSACT and @ref PJSUA_UA. + */ + +/** + * @defgroup PJSIP_BASE Base Types + * @ingroup PJSIP_CORE + * @brief Basic PJSIP types and configurations. + */ + +/** + * @defgroup PJSIP_CONFIG Compile Time Configuration + * @ingroup PJSIP_BASE + * @brief PJSIP compile time configurations. + * @{ + */ + /** * Specify maximum transaction count in transaction hash table. * Default value is 16*1024 @@ -76,6 +111,14 @@ #endif +/** + * Maximum packet length. + */ +#ifndef PJSIP_MAX_PKT_LEN +# define PJSIP_MAX_PKT_LEN 1500 +#endif + + /* Endpoint. */ #define PJSIP_MAX_TIMER_COUNT (2*PJSIP_MAX_TSX_COUNT + 2*PJSIP_MAX_DIALOG_COUNT) @@ -84,7 +127,6 @@ /* Transport related constants. */ -#define PJSIP_MAX_PKT_LEN 1500 #define PJSIP_POOL_RDATA_LEN 4000 #define PJSIP_POOL_RDATA_INC 4000 #define PJSIP_POOL_LEN_TRANSPORT 512 @@ -141,22 +183,22 @@ //#define PJSIP_T1_TIMEOUT 15000 //#define PJSIP_T2_TIMEOUT 60000 -/* T1 timeout value. */ +/** Transaction T1 timeout value. */ #if !defined(PJSIP_T1_TIMEOUT) # define PJSIP_T1_TIMEOUT 500 #endif -/* T2 timeout value. */ +/** Transaction T2 timeout value. */ #if !defined(PJSIP_T2_TIMEOUT) # define PJSIP_T2_TIMEOUT 4000 #endif -/* Completed timer for non-INVITE */ +/** Transaction completed timer for non-INVITE */ #if !defined(PJSIP_T4_TIMEOUT) # define PJSIP_T4_TIMEOUT 5000 #endif -/* Completed timer for INVITE */ +/** Transaction completed timer for INVITE */ #if !defined(PJSIP_TD_TIMEOUT) # define PJSIP_TD_TIMEOUT 32000 #endif @@ -166,7 +208,7 @@ * Authorization */ -/* +/** * If this flag is set, the stack will keep the Authorization/Proxy-Authorization * headers that are sent in a cache. Future requests with the same realm and * the same method will use the headers in the cache (as long as no qop is @@ -182,7 +224,7 @@ # define PJSIP_AUTH_HEADER_CACHING 1 #endif -/* +/** * If this flag is set, the stack will proactively send Authorization/Proxy- * Authorization header for next requests. If next request has the same method * with any of previous requests, then the last header which is saved in @@ -203,7 +245,7 @@ # define PJSIP_AUTH_AUTO_SEND_NEXT 1 #endif -/* +/** * Support qop="auth" directive. * This option also requires client to cache the last challenge offered by * server. @@ -215,6 +257,10 @@ #endif +/** + * @} + */ + #include diff --git a/pjsip/include/pjsip/sip_dialog.h b/pjsip/include/pjsip/sip_dialog.h index c365a8d5..e796b0a3 100644 --- a/pjsip/include/pjsip/sip_dialog.h +++ b/pjsip/include/pjsip/sip_dialog.h @@ -31,6 +31,30 @@ #include #include + +/** + * @defgroup PJSIP_DIALOG Base Dialog + * @ingroup PJSIP_UA + * @brief The base dialog framework to support dialog usages. + * @{ + * + * The base dialog framework provides management for base dialog + * properties such as From header, To header, CSeq + * sequencing, Call-ID header, Contact header management, + * dialog route-set management, and common authentication. + * This basic dialog functionality will be shared by all dialog + * usages of a particular dialog. + * + * More detailed information is explained in + * PJSIP Developer's Guide + * PDF document, and readers are encouraged to read the document to + * get the concept behind dialog, dialog usages, and INVITE sessions. + * + * Application MUST initialize the user agent layer module by calling + * #pjsip_ua_init_module() before using any of the dialog API, and link + * the application with with pjsip-core library. + */ + PJ_BEGIN_DECL @@ -54,7 +78,10 @@ typedef struct pjsip_dlg_party */ enum pjsip_dialog_state { + /** Dialog is not established. */ PJSIP_DIALOG_STATE_NULL, + + /** Dialog has been established (probably early) */ PJSIP_DIALOG_STATE_ESTABLISHED, }; @@ -86,7 +113,7 @@ struct pjsip_dialog pjsip_user_agent *ua; /**< User agent instance. */ pjsip_endpoint *endpt; /**< Endpoint instance. */ - /* The dialog set. */ + /** The dialog set which this dialog belongs (opaque type). */ void *dlg_set; /* Dialog's session properties. */ diff --git a/pjsip/include/pjsip/sip_endpoint.h b/pjsip/include/pjsip/sip_endpoint.h index f25c7493..e6632042 100644 --- a/pjsip/include/pjsip/sip_endpoint.h +++ b/pjsip/include/pjsip/sip_endpoint.h @@ -27,18 +27,18 @@ #include #include -PJ_BEGIN_DECL - /** - * @defgroup PJSIP SIP Stack Core - * Implementation of core SIP protocol stack processing. + * @defgroup PJSIP_CORE_CORE At the Very Core + * @ingroup PJSIP_CORE + * @brief The very core of PJSIP. */ +PJ_BEGIN_DECL + /** - * @defgroup PJSIP_ENDPT SIP Endpoint - * @ingroup PJSIP - * @brief - * Representation of SIP node instance. + * @defgroup PJSIP_ENDPT Endpoint + * @ingroup PJSIP_CORE_CORE + * @brief The master, owner of all objects * * SIP Endpoint instance (pjsip_endpoint) can be viewed as the master/owner of * all SIP objects in an application. It performs the following roles: @@ -286,7 +286,7 @@ PJ_DECL(pj_status_t) pjsip_endpt_create_tdata( pjsip_endpoint *endpt, * * Note: at the moment we don't have implementation of RFC 3263 yet! * - * @param resolver The resolver engine. + * @param endpt The endpoint instance. * @param pool The pool to allocate resolver job. * @param target The target specification to be resolved. * @param token A user defined token to be passed back to callback function. @@ -418,6 +418,11 @@ PJ_DECL(void) pjsip_endpt_dump( pjsip_endpoint *endpt, pj_bool_t detail ); +/** + * @} + */ + + /** * Log an error. */ @@ -436,10 +441,6 @@ PJ_DECL(void) pjsip_endpt_log_error( pjsip_endpoint *endpt, PJ_LOG(4,expr); \ } while (0) -/** - * @} - */ - /* * Internal functions. */ diff --git a/pjsip/include/pjsip/sip_errno.h b/pjsip/include/pjsip/sip_errno.h index 4fc9d4bd..83557cb7 100644 --- a/pjsip/include/pjsip/sip_errno.h +++ b/pjsip/include/pjsip/sip_errno.h @@ -19,10 +19,22 @@ #ifndef __PJSIP_SIP_ERRNO_H__ #define __PJSIP_SIP_ERRNO_H__ +/** + * @file sip_errno.h + * @brief PJSIP Specific Error Code + */ + #include PJ_BEGIN_DECL +/** + * @defgroup PJSIP_CORE_ERRNO PJSIP Specific Error Code + * @ingroup PJSIP_BASE + * @brief PJSIP specific error constants. + * @{ + */ + /* * PJSIP error codes occupies 170000 - 219000, and mapped as follows: * - 170100 - 170799: mapped to SIP status code in response msg. @@ -382,4 +394,9 @@ PJ_BEGIN_DECL PJ_END_DECL + +/** + * @} + */ + #endif /* __PJSIP_SIP_ERRNO_H__ */ diff --git a/pjsip/include/pjsip/sip_event.h b/pjsip/include/pjsip/sip_event.h index caac953f..5dc9d457 100644 --- a/pjsip/include/pjsip/sip_event.h +++ b/pjsip/include/pjsip/sip_event.h @@ -27,8 +27,9 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_EVENT SIP Event - * @ingroup PJSIP + * @defgroup PJSIP_EVENT Event + * @ingroup PJSIP_CORE_CORE + * @brief Representation of events as they are distributed among modules. * @{ */ #include @@ -64,8 +65,7 @@ typedef enum pjsip_event_id_e /** - * \struct - * \brief Event descriptor to fully identify a SIP event. + * This structure describe event descriptor to fully identify a SIP event. * * Events are the only way for a lower layer object to inform something * to higher layer objects. Normally this is achieved by means of callback, @@ -85,8 +85,8 @@ struct pjsip_event */ pjsip_event_id_e type; - /* - * The event body. + /** + * The event body as union, which fields depends on the event type. * By convention, the first member of each struct in the union must be * the pointer which is relevant to the event. */ @@ -216,7 +216,7 @@ struct pjsip_event /** * Get the event string from the event ID. * @param e the event ID. - * @notes defined in sip_util.c + * @note defined in sip_util.c */ PJ_DEF(const char *) pjsip_event_str(pjsip_event_id_e e); diff --git a/pjsip/include/pjsip/sip_module.h b/pjsip/include/pjsip/sip_module.h index 94e3002c..ef13e278 100644 --- a/pjsip/include/pjsip/sip_module.h +++ b/pjsip/include/pjsip/sip_module.h @@ -29,16 +29,26 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_MOD SIP Modules - * @ingroup PJSIP + * @defgroup PJSIP_MOD Modules + * @ingroup PJSIP_CORE_CORE + * @brief Modules are the primary means to extend PJSIP! * @{ + * Modules are the primary means to extend PJSIP. Without modules, PJSIP + * would not know how to handle messages, and will simply discard all + * incoming messages. + * + * Modules are registered by creating and initializing #pjsip_module + * structure, and register the structure to PJSIP with + * #pjsip_endpt_register_module(). + * + * The PJSIP Developer's Guide + * has a thorough discussion on this subject, and readers are encouraged + * to read the document for more information. */ /** - * Module registration structure, which is passed by the module to the - * endpoint during the module registration process. This structure enables - * the endpoint to query the module capability and to further communicate - * with the module. + * The declaration for SIP module. This structure would be passed to + * #pjsip_endpt_register_module() to register the module to PJSIP. */ struct pjsip_module { @@ -46,12 +56,16 @@ struct pjsip_module PJ_DECL_LIST_MEMBER(struct pjsip_module); /** - * Module name. + * Module name to identify the module. + * + * This field MUST be initialized before registering the module. */ pj_str_t name; /** - * Module ID. + * Module ID. Application must initialize this field with -1 before + * registering the module to PJSIP. After the module is registered, + * this field will contain a unique ID to identify the module. */ int id; @@ -59,11 +73,15 @@ struct pjsip_module * Integer number to identify module initialization and start order with * regard to other modules. Higher number will make the module gets * initialized later. + * + * This field MUST be initialized before registering the module. */ int priority; /** - * Pointer to function to be called to initialize the module. + * Optional function to be called to initialize the module. This function + * will be called by endpoint during module registration. If the value + * is NULL, then it's equal to returning PJ_SUCCESS. * * @param endpt The endpoint instance. * @return Module should return PJ_SUCCESS to indicate success. @@ -71,23 +89,29 @@ struct pjsip_module pj_status_t (*load)(pjsip_endpoint *endpt); /** - * Pointer to function to be called to start the module. + * Optional function to be called to start the module. This function + * will be called by endpoint during module registration. If the value + * is NULL, then it's equal to returning PJ_SUCCESS. * * @return Module should return zero to indicate success. */ pj_status_t (*start)(void); /** - * Pointer to function to be called to deinitialize the module before - * it is unloaded. + * Optional function to be called to deinitialize the module before + * it is unloaded. This function will be called by endpoint during + * module unregistration. If the value is NULL, then it's equal to + * returning PJ_SUCCESS. * * @return Module should return PJ_SUCCESS to indicate success. */ pj_status_t (*stop)(void); /** - * Pointer to function to be called to deinitialize the module before - * it is unloaded. + * Optional function to be called to deinitialize the module before + * it is unloaded. This function will be called by endpoint during + * module unregistration. If the value is NULL, then it's equal to + * returning PJ_SUCCESS. * * @param mod The module. * @@ -96,7 +120,7 @@ struct pjsip_module pj_status_t (*unload)(void); /** - * Called to process incoming request. + * Optional function to be called to process incoming request message. * * @param rdata The incoming message. * @@ -107,7 +131,7 @@ struct pjsip_module pj_bool_t (*on_rx_request)(pjsip_rx_data *rdata); /** - * Called to processed incoming response. + * Optional function to be called to process incoming response message. * * @param rdata The incoming message. * @@ -118,7 +142,8 @@ struct pjsip_module pj_bool_t (*on_rx_response)(pjsip_rx_data *rdata); /** - * Called to process outgoing request. + * Optional function to be called when transport layer is about to + * transmit outgoing request message. * * @param tdata The outgoing request message. * @@ -129,7 +154,8 @@ struct pjsip_module pj_status_t (*on_tx_request)(pjsip_tx_data *tdata); /** - * Called to process outgoing response message. + * Optional function to be called when transport layer is about to + * transmit outgoing response message. * * @param tdata The outgoing response message. * @@ -140,8 +166,9 @@ struct pjsip_module pj_status_t (*on_tx_response)(pjsip_tx_data *tdata); /** - * Called when this module is acting as transaction user for the specified - * transaction, when the transaction's state has changed. + * Optional function to be called when this module is acting as + * transaction user for the specified transaction, when the + * transaction's state has changed. * * @param tsx The transaction. * @param event The event which has caused the transaction state @@ -157,10 +184,29 @@ struct pjsip_module */ enum pjsip_module_priority { + /** + * This is the priority used by transport layer. + */ PJSIP_MOD_PRIORITY_TRANSPORT_LAYER = 8, + + /** + * This is the priority used by transaction layer. + */ PJSIP_MOD_PRIORITY_TSX_LAYER = 16, + + /** + * This is the priority used by the user agent and proxy layer. + */ PJSIP_MOD_PRIORITY_UA_PROXY_LAYER = 32, + + /** + * This is the priority used by the dialog usages. + */ PJSIP_MOD_PRIORITY_DIALOG_USAGE = 48, + + /** + * This is the recommended priority to be used by applications. + */ PJSIP_MOD_PRIORITY_APPLICATION = 64, }; diff --git a/pjsip/include/pjsip/sip_msg.h b/pjsip/include/pjsip/sip_msg.h index df764152..0f01c06b 100644 --- a/pjsip/include/pjsip/sip_msg.h +++ b/pjsip/include/pjsip/sip_msg.h @@ -20,7 +20,7 @@ #define __PJSIP_SIP_MSG_H__ /** - * @file sip_msg.h + * @file pjsip/sip_msg.h * @brief SIP Message Structure. */ @@ -31,8 +31,9 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_MSG SIP Message Structure - * @ingroup PJSIP + * @defgroup PJSIP_MSG Messaging Elements + * @ingroup PJSIP_CORE + * @brief Various SIP message elements such as methods, headers, URIs, etc. * @{ */ @@ -154,8 +155,8 @@ PJ_DECL(int) pjsip_method_cmp( const pjsip_method *m1, const pjsip_method *m2); /////////////////////////////////////////////////////////////////////////////// /** - * @defgroup PJSIP_MSG_HDR Header Fields General Structure. - * @brief General Header Fields Structure. + * @defgroup PJSIP_MSG_HDR Header Fields + * @brief Declarations for various SIP header fields. * @ingroup PJSIP_MSG * @{ */ @@ -461,8 +462,8 @@ PJ_DECL(const pj_str_t*) pjsip_get_status_text(int status_code); /////////////////////////////////////////////////////////////////////////////// /** - * @addtogroup PJSIP_MSG_MEDIA Media Type - * @brief Media type definitions and manipulations. + * @addtogroup PJSIP_MSG_MEDIA Media/MIME Type + * @brief Media/MIME type declaration and manipulations. * @ingroup PJSIP_MSG * @{ */ @@ -654,7 +655,7 @@ PJ_DECL(pjsip_msg_body*) pjsip_msg_body_create( pj_pool_t *pool, /////////////////////////////////////////////////////////////////////////////// /** * @defgroup PJSIP_MSG_MSG Message Structure - * @brief Message structure and operations. + * @brief SIP message (request and response) structure and operations. * @ingroup PJSIP_MSG * @{ */ @@ -845,9 +846,7 @@ PJ_DECL(pj_ssize_t) pjsip_msg_print(const pjsip_msg *msg, /////////////////////////////////////////////////////////////////////////////// /** - * @addtogroup PJSIP_MSG_HDR_GEN Header Field: Generic - * @brief Generic header field which contains header name and value. - * @ingroup PJSIP_MSG + * @addtogroup PJSIP_MSG_HDR * @{ */ @@ -904,17 +903,8 @@ pjsip_generic_string_hdr_init( pj_pool_t *pool, const pj_str_t *hvalue); -/** - * @} - */ /////////////////////////////////////////////////////////////////////////////// -/** - * @addtogroup PJSIP_MSG_HDR_GEN_INT Header Field: Generic Integer - * @brief Generic header field which contains header name and value. - * @ingroup PJSIP_MSG - * @{ - */ /** * Generic SIP header, which contains hname and a string hvalue. @@ -964,26 +954,25 @@ PJ_DECL(pjsip_generic_int_hdr*) pjsip_generic_int_hdr_init( pj_pool_t *pool, const pj_str_t *hname, int value ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_GENERIC_LIST Header Field: Generic string list. - * @brief Header with list of strings separated with comma - * @ingroup PJSIP_MSG - * @{ - */ /** Maximum elements in the header array. */ #define PJSIP_GENERIC_ARRAY_MAX_COUNT 32 +/** + * Generic array of string header. + */ typedef struct pjsip_generic_array_hdr { + /** Standard header fields. */ PJSIP_DECL_HDR_MEMBER(struct pjsip_generic_array_hdr); - unsigned count; /**< Number of elements. */ - pj_str_t values[PJSIP_GENERIC_ARRAY_MAX_COUNT]; /**< Elements. */ + + /** Number of tags/elements. */ + unsigned count; + + /**< Tags/elements. */ + pj_str_t values[PJSIP_GENERIC_ARRAY_MAX_COUNT]; + } pjsip_generic_array_hdr; /** @@ -1018,17 +1007,8 @@ PJ_DECL(pjsip_generic_array_hdr*) pjsip_generic_array_hdr_init(pj_pool_t *pool, const pj_str_t *hname); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_ACCEPT Header Field: Accept - * @brief Accept header field. - * @ingroup PJSIP_MSG - * @{ - */ + /** Accept header. */ typedef pjsip_generic_array_hdr pjsip_accept_hdr; @@ -1061,16 +1041,11 @@ PJ_DECL(pjsip_accept_hdr*) pjsip_accept_hdr_create(pj_pool_t *pool); PJ_DECL(pjsip_accept_hdr*) pjsip_accept_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ /////////////////////////////////////////////////////////////////////////////// + /** - * @defgroup PJSIP_MSG_HDR_ALLOW Header Field: Allow - * @brief Allow header field. - * @ingroup PJSIP_MSG - * @{ + * Allow header. */ typedef pjsip_generic_array_hdr pjsip_allow_hdr; @@ -1102,17 +1077,8 @@ PJ_DECL(pjsip_allow_hdr*) pjsip_allow_hdr_create(pj_pool_t *pool); PJ_DECL(pjsip_allow_hdr*) pjsip_allow_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_CID Header Field: Call-ID - * @brief Call-ID header field. - * @ingroup PJSIP_MSG - * @{ - */ + /** * Call-ID header. */ @@ -1151,17 +1117,8 @@ PJ_DECL(pjsip_cid_hdr*) pjsip_cid_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_CLEN Header Field: Content-Length - * @brief Content-Length header field. - * @ingroup PJSIP_MSG - * @{ - */ /** * Content-Length header. */ @@ -1197,17 +1154,7 @@ PJ_DECL(pjsip_clen_hdr*) pjsip_clen_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_CSEQ Header Field: CSeq - * @brief CSeq header field. - * @ingroup PJSIP_MSG - * @{ - */ /** * CSeq header. */ @@ -1243,17 +1190,7 @@ PJ_DECL(pjsip_cseq_hdr*) pjsip_cseq_hdr_create( pj_pool_t *pool ); PJ_DECL(pjsip_cseq_hdr*) pjsip_cseq_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_CONTACT Header Field: Contact - * @brief Contact header field. - * @ingroup PJSIP_MSG - * @{ - */ /** * Contact header. * In this library, contact header only contains single URI. If a message has @@ -1296,17 +1233,8 @@ PJ_DECL(pjsip_contact_hdr*) pjsip_contact_hdr_create( pj_pool_t *pool ); PJ_DECL(pjsip_contact_hdr*) pjsip_contact_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_CTYPE Header Field: Content-Type - * @brief Content-Type header field. - * @ingroup PJSIP_MSG - * @{ - */ /** * Content-Type. */ @@ -1342,17 +1270,7 @@ PJ_DECL(pjsip_ctype_hdr*) pjsip_ctype_hdr_create( pj_pool_t *pool ); PJ_DECL(pjsip_ctype_hdr*) pjsip_ctype_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_EXPIRES Header Field: Expires - * @brief Expires header field. - * @ingroup PJSIP_MSG - * @{ - */ /** Expires header. */ typedef pjsip_generic_int_hdr pjsip_expires_hdr; @@ -1387,17 +1305,8 @@ PJ_DECL(pjsip_expires_hdr*) pjsip_expires_hdr_init( pj_pool_t *pool, int value ); -/** - * @} - */ /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_FROMTO Header Field: From/To - * @brief From and To header field. - * @ingroup PJSIP_MSG - * @{ - */ /** * To or From header. */ @@ -1468,30 +1377,23 @@ PJ_DECL(pjsip_to_hdr*) pjsip_to_hdr_init( pj_pool_t *pool, /** * Convert the header to a From header. * - * @param pool The pool. - * @return "From" header. + * @param hdr The generic from/to header. + * @return "From" header. */ PJ_DECL(pjsip_from_hdr*) pjsip_fromto_hdr_set_from( pjsip_fromto_hdr *hdr ); /** * Convert the header to a To header. * - * @param pool The pool. - * @return "To" header. + * @param hdr The generic from/to header. + * @return "To" header. */ PJ_DECL(pjsip_to_hdr*) pjsip_fromto_hdr_set_to( pjsip_fromto_hdr *hdr ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// /** - * @defgroup PJSIP_MSG_HDR_MAX_FORWARDS Header Field: Max-Forwards - * @brief Max-Forwards header field. - * @ingroup PJSIP_MSG - * @{ + * Max-Forwards header. */ typedef pjsip_generic_int_hdr pjsip_max_fwd_hdr; @@ -1525,17 +1427,10 @@ pjsip_max_fwd_hdr_create(pj_pool_t *pool, int value); PJ_DECL(pjsip_max_fwd_hdr*) pjsip_max_fwd_hdr_init( pj_pool_t *pool, void *mem, int value ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// /** - * @defgroup PJSIP_MSG_HDR_MIN_EXPIRES Header Field: Min-Expires - * @brief Min-Expires header field. - * @ingroup PJSIP_MSG - * @{ + * Min-Expires header. */ typedef pjsip_generic_int_hdr pjsip_min_expires_hdr; @@ -1570,18 +1465,8 @@ PJ_DECL(pjsip_min_expires_hdr*) pjsip_min_expires_hdr_init( pj_pool_t *pool, void *mem, int value ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_ROUTING Header Field: Record-Route/Route - * @brief Record-Route and Route header fields. - * @ingroup PJSIP_MSG - * @{ - */ /** * Record-Route and Route headers. */ @@ -1589,7 +1474,7 @@ typedef struct pjsip_routing_hdr { PJSIP_DECL_HDR_MEMBER(struct pjsip_routing_hdr); /**< Generic header fields. */ pjsip_name_addr name_addr; /**< The URL in the Route/Record-Route header. */ - pjsip_param other_param; /** Other parameter. */ + pjsip_param other_param; /**< Other parameter. */ } pjsip_routing_hdr; /** Alias for Record-Route header. */ @@ -1665,16 +1550,9 @@ PJ_DECL(pjsip_rr_hdr*) pjsip_routing_hdr_set_rr( pjsip_routing_hdr *r ); */ PJ_DECL(pjsip_route_hdr*) pjsip_routing_hdr_set_route( pjsip_routing_hdr *r ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// /** - * @defgroup PJSIP_MSG_HDR_REQUIRE Header Field: Require - * @brief Require header field. - * @ingroup PJSIP_MSG - * @{ + * Require header. */ typedef pjsip_generic_array_hdr pjsip_require_hdr; @@ -1704,17 +1582,10 @@ PJ_DECL(pjsip_require_hdr*) pjsip_require_hdr_create(pj_pool_t *pool); PJ_DECL(pjsip_require_hdr*) pjsip_require_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// /** - * @defgroup PJSIP_MSG_HDR_RETRY_AFTER Header Field: Retry-After - * @brief Retry-After header field. - * @ingroup PJSIP_MSG - * @{ + * Retry-After header. */ typedef pjsip_generic_int_hdr pjsip_retry_after_hdr; @@ -1744,16 +1615,9 @@ PJ_DECL(pjsip_retry_after_hdr*) pjsip_retry_after_hdr_init( pj_pool_t *pool, int value ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// /** - * @defgroup PJSIP_MSG_HDR_SUPPORTED Header Field: Supported - * @brief Supported header field. - * @ingroup PJSIP_MSG - * @{ + * Supported header. */ typedef pjsip_generic_array_hdr pjsip_supported_hdr; @@ -1778,16 +1642,9 @@ PJ_DECL(pjsip_supported_hdr*) pjsip_supported_hdr_create(pj_pool_t *pool); PJ_DECL(pjsip_supported_hdr*) pjsip_supported_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ - /////////////////////////////////////////////////////////////////////////////// /** - * @defgroup PJSIP_MSG_HDR_UNSUPPORTED Header Field: Unsupported - * @brief Unsupported header field. - * @ingroup PJSIP_MSG - * @{ + * Unsupported header. */ typedef pjsip_generic_array_hdr pjsip_unsupported_hdr; @@ -1812,18 +1669,7 @@ PJ_DECL(pjsip_unsupported_hdr*) pjsip_unsupported_hdr_create(pj_pool_t *pool); PJ_DECL(pjsip_unsupported_hdr*) pjsip_unsupported_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ - - /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_VIA Header Field: Via - * @brief Via header field. - * @ingroup PJSIP_MSG - * @{ - */ /** * SIP Via header. * In this implementation, Via header can only have one element in each header. @@ -1865,18 +1711,7 @@ PJ_DECL(pjsip_via_hdr*) pjsip_via_hdr_create( pj_pool_t *pool ); PJ_DECL(pjsip_via_hdr*) pjsip_via_hdr_init( pj_pool_t *pool, void *mem ); -/** - * @} - */ - - /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_WARNING Header Field: Warning - * @brief Warning header field. - * @ingroup PJSIP_MSG - * @{ - */ /** * SIP Warning header. * In this version, Warning header is just a typedef for generic string @@ -1917,25 +1752,7 @@ pjsip_warning_hdr_create_from_status( pj_pool_t *pool, const pj_str_t *host, pj_status_t status); -/** - * @} - */ - -/** - * @bug Once a header is put in the message, the header CAN NOT be put in - * other list. Solution: - * - always clone header in the message. - * - create a list node for each header in the message. - */ - - /////////////////////////////////////////////////////////////////////////////// -/** - * @defgroup PJSIP_MSG_HDR_UNIMP Unimplemented Header Fields - * @brief Unimplemented header fields. - * @ingroup PJSIP_MSG - * @{ - */ /** Accept-Encoding header. */ typedef pjsip_generic_string_hdr pjsip_accept_encoding_hdr; diff --git a/pjsip/include/pjsip/sip_parser.h b/pjsip/include/pjsip/sip_parser.h index b2e49694..b9e752f0 100644 --- a/pjsip/include/pjsip/sip_parser.h +++ b/pjsip/include/pjsip/sip_parser.h @@ -31,8 +31,9 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_PARSER SIP Message Parser - * @ingroup PJSIP + * @defgroup PJSIP_PARSER Parser + * @ingroup PJSIP_MSG + * @brief Message and message elements parsing. * @{ */ @@ -66,6 +67,7 @@ extern int PJSIP_SYN_ERR_EXCEPTION; */ typedef struct pjsip_parser_err_report { + /** Standard header fields. */ PJ_DECL_LIST_MEMBER(struct pjsip_parser_err_report); int except_code; /**< Error exception (e.g. PJSIP_SYN_ERR_EXCEPTION) */ int line; /**< Line number. */ @@ -134,6 +136,7 @@ PJ_DECL(pj_status_t) pjsip_register_hdr_parser( const char *hname, * * @param hname The header name registered. * @param hshortname The short header name registered, or NULL. + * @param fptr Previously registered function to parse the header. * * @return zero if unregistration was successfull. */ @@ -185,7 +188,7 @@ PJ_DECL(pj_status_t) pjsip_unregister_uri_parser( const char *scheme, */ PJ_DECL(pjsip_uri*) pjsip_parse_uri( pj_pool_t *pool, char *buf, pj_size_t size, - unsigned option); + unsigned options); /** * Parse a packet buffer and build a full SIP message from the packet. This @@ -237,6 +240,7 @@ PJ_DECL(pjsip_msg *) pjsip_parse_rdata( char *buf, pj_size_t size, * * @param buf The input buffer, which must be NULL terminated. * @param size The buffer size. + * @param is_datagram Put non-zero if transport is datagram oriented. * @param msg_size [out] If message is valid, this parameter will contain * the size of the SIP message (including body, if any). * @@ -278,19 +282,26 @@ PJ_DECL(void*) pjsip_parse_hdr( pj_pool_t *pool, const pj_str_t *hname, * a newline (as in SIP message) or ampersand mark (as in URI). This separator * however is optional for the last header. * - * @param pool the pool. - * @param buf the input text to parse. - * @param size the text length. - * @param hlist the header list to store the parsed headers. This list must - * have been initialized before calling this function. - * @return zero if successfull, or -1 if error is encountered. Upon error, - * the \a hlist argument MAY contain successfully parsed headers. + * @param pool the pool. + * @param input the input text to parse. + * @param size the text length. + * @param hlist the header list to store the parsed headers. + * This list must have been initialized before calling + * this function. + * @return zero if successfull, or -1 if error is encountered. + * Upon error, the \a hlist argument MAY contain + * successfully parsed headers. */ PJ_DECL(pj_status_t) pjsip_parse_headers( pj_pool_t *pool, char *input, pj_size_t size, pj_list *hlist ); +/** + * @} + */ + + /* * Various specification used in parsing, exported here as extern for other * parsers. @@ -316,20 +327,22 @@ extern pj_cis_t /* * Various string constants. */ -extern const pj_str_t pjsip_USER_STR, - pjsip_METHOD_STR, - pjsip_TRANSPORT_STR, - pjsip_MADDR_STR, - pjsip_LR_STR, - pjsip_SIP_STR, - pjsip_SIPS_STR, - pjsip_TEL_STR, - pjsip_BRANCH_STR, - pjsip_TTL_STR, - pjsip_PNAME_STR, - pjsip_Q_STR, - pjsip_EXPIRES_STR, - pjsip_TAG_STR; +extern const pj_str_t pjsip_USER_STR, /**< "user" string constant. */ + pjsip_METHOD_STR, /**< "method" string constant */ + pjsip_TRANSPORT_STR, /**< "transport" string const. */ + pjsip_MADDR_STR, /**< "maddr" string const. */ + pjsip_LR_STR, /**< "lr" string const. */ + pjsip_SIP_STR, /**< "sip" string constant. */ + pjsip_SIPS_STR, /**< "sips" string constant. */ + pjsip_TEL_STR, /**< "tel" string constant. */ + pjsip_BRANCH_STR, /**< "branch" string constant. */ + pjsip_TTL_STR, /**< "ttl" string constant. */ + pjsip_RECEIVED_STR, /**< "received" string const. */ + pjsip_Q_STR, /**< "q" string constant. */ + pjsip_EXPIRES_STR, /**< "expires" string constant. */ + pjsip_TAG_STR, /**< "tag" string constant. */ + pjsip_RPORT_STR; /**< "rport" string const. */ + /* * Parser utilities. @@ -346,10 +359,6 @@ void pjsip_concat_param_imp( pj_str_t *param, pj_pool_t *pool, const pj_str_t *pname, const pj_str_t *pvalue, int sepchar); void pjsip_parse_end_hdr_imp ( pj_scanner *scanner ); -/** - * @} - */ - PJ_END_DECL #endif /* __PJSIP_SIP_PARSER_H__ */ diff --git a/pjsip/include/pjsip/sip_private.h b/pjsip/include/pjsip/sip_private.h index 80417906..6c741bbe 100644 --- a/pjsip/include/pjsip/sip_private.h +++ b/pjsip/include/pjsip/sip_private.h @@ -26,21 +26,6 @@ #include -PJ_BEGIN_DECL - -/** - * @defgroup PJSIP_PRIVATE Private structures and functions (PJSIP internals) - * @ingroup PJSIP - * @{ - */ - - - -/** - * @} - */ - -PJ_END_DECL #endif /* __PJSIP_PRIVATE_I_H__ */ diff --git a/pjsip/include/pjsip/sip_resolve.h b/pjsip/include/pjsip/sip_resolve.h index b9fbe0d5..3ebface3 100644 --- a/pjsip/include/pjsip/sip_resolve.h +++ b/pjsip/include/pjsip/sip_resolve.h @@ -32,9 +32,14 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_RESOLVE SIP Server Resolver - * @ingroup PJSIP + * @defgroup PJSIP_RESOLVE Server Resolution + * @ingroup PJSIP_TRANSPORT + * @brief Framework to resolve SIP servers based on RFC 3263. * @{ + * This is the server resolution framework, which is modelled after + * RFC 3263 - Locating SIP Servers document. The server resolution + * framework is asynchronous; callback will be called once the server + * address has been resolved (successfully or with errors). */ /** @@ -42,12 +47,10 @@ PJ_BEGIN_DECL */ #define PJSIP_MAX_RESOLVED_ADDRESSES 8 -typedef struct pjsip_server_addresses pjsip_server_addresses; - /** * The server addresses returned by the resolver. */ -struct pjsip_server_addresses +typedef struct pjsip_server_addresses { /** Number of address records. */ unsigned count; @@ -66,7 +69,8 @@ struct pjsip_server_addresses } entry[PJSIP_MAX_RESOLVED_ADDRESSES]; -}; +} pjsip_server_addresses; + /** * The type of callback function to be called when resolver finishes the job. diff --git a/pjsip/include/pjsip/sip_tel_uri.h b/pjsip/include/pjsip/sip_tel_uri.h index 5ade09c6..22a13052 100644 --- a/pjsip/include/pjsip/sip_tel_uri.h +++ b/pjsip/include/pjsip/sip_tel_uri.h @@ -26,6 +26,13 @@ #include +/** + * @addtogroup PJSIP_TEL_URI tel URI Scheme + * @ingroup PJSIP_URI + * @brief Support for "tel:" URI scheme. + * @{ + */ + PJ_BEGIN_DECL @@ -68,4 +75,9 @@ PJ_DECL(int) pjsip_tel_nb_cmp(const pj_str_t *nb1, const pj_str_t *nb2); PJ_END_DECL +/** + * @} + */ + + #endif /* __PJSIP_TEL_URI_H__ */ diff --git a/pjsip/include/pjsip/sip_transaction.h b/pjsip/include/pjsip/sip_transaction.h index 895487dd..1f44e7b6 100644 --- a/pjsip/include/pjsip/sip_transaction.h +++ b/pjsip/include/pjsip/sip_transaction.h @@ -31,9 +31,28 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_TRANSACT SIP Transaction + * @defgroup PJSIP_TRANSACT Transaction Layer * @ingroup PJSIP + * @brief Provides statefull message processing. + * + * This module provides stateful processing to incoming or outgoing SIP + * messages. + * Before performing any stateful operations, application must register the + * transaction layer module by calling #pjsip_tsx_layer_init_module(). + * + * Application should link with pjsip-core library to + * use the transaction layer. + */ + +/** + * @defgroup PJSIP_TRANSACT_TRANSACTION Transaction + * @ingroup PJSIP_TRANSACT + * @brief Transaction instance for all types of SIP transactions. * @{ + * The pjsip_transaction describes SIP transaction, and is used for + * both INVITE and non-INVITE, UAC or UAS. Application must register the + * transaction layer module with #pjsip_tsx_layer_init_module() before + * performing any stateful operations. */ /** @@ -257,7 +276,7 @@ PJ_DECL(pj_status_t) pjsip_tsx_create_key( pj_pool_t *pool, * @param code The status code to report. */ PJ_DECL(pj_status_t) pjsip_tsx_terminate( pjsip_transaction *tsx, - int st_code ); + int code ); /** diff --git a/pjsip/include/pjsip/sip_transport.h b/pjsip/include/pjsip/sip_transport.h index ce256f09..2adcea01 100644 --- a/pjsip/include/pjsip/sip_transport.h +++ b/pjsip/include/pjsip/sip_transport.h @@ -34,12 +34,17 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_TRANSPORT SIP Transport - * @ingroup PJSIP + * @defgroup PJSIP_TRANSPORT Transport + * @ingroup PJSIP_CORE + * @brief This is the transport framework. * - * This is the low-level transport layer. Application normally won't need to - * use this function, but instead can use transaction or higher layer API to - * send and receive messages. + * The transport framework is fully extensible. Please see + * PJSIP Developer's Guide PDF + * document for more information. + * + * Application MUST register at least one transport to PJSIP before any + * messages can be sent or received. Please see @ref PJSIP_TRANSPORT_UDP + * on how to create/register UDP transport to the transport framework. * * @{ */ @@ -137,8 +142,8 @@ PJ_DECL(const char*) pjsip_transport_get_type_name(pjsip_transport_type_e t); */ typedef struct pjsip_rx_data_op_key { - pj_ioqueue_op_key_t op_key; - pjsip_rx_data *rdata; + pj_ioqueue_op_key_t op_key; /**< ioqueue op_key. */ + pjsip_rx_data *rdata; /**< rdata associated with this */ } pjsip_rx_data_op_key; @@ -303,9 +308,18 @@ PJ_DECL(char*) pjsip_rx_data_get_info(pjsip_rx_data *rdata); */ typedef struct pjsip_tx_data_op_key { + /** ioqueue pending operation key. */ pj_ioqueue_op_key_t key; + + /** Transmit data associated with this key. */ pjsip_tx_data *tdata; + + /** Arbitrary token (attached by transport) */ void *token; + + /** Callback to be called when pending transmit operation has + completed. + */ void (*callback)(pjsip_transport*,void*,pj_ssize_t); } pjsip_tx_data_op_key; @@ -376,6 +390,8 @@ struct pjsip_tx_data /** Transport manager internal. */ void *token; + + /** Callback to be called when this tx_data has been transmitted. */ void (*cb)(void*, pjsip_tx_data*, pj_ssize_t); /** Transport information, only valid during on_tx_request() and @@ -592,18 +608,18 @@ typedef struct pjsip_tpfactory pjsip_tpfactory; */ struct pjsip_tpfactory { - /* This list is managed by transport manager. */ + /** This list is managed by transport manager. */ PJ_DECL_LIST_MEMBER(struct pjsip_tpfactory); - pj_pool_t *pool; - pj_lock_t *lock; + pj_pool_t *pool; /**< Owned memory pool. */ + pj_lock_t *lock; /**< Lock object. */ - pjsip_transport_type_e type; - char type_name[8]; - unsigned flag; + pjsip_transport_type_e type; /**< Transport type. */ + char type_name[8]; /**< Type string name. */ + unsigned flag; /**< Transport flag. */ - pj_sockaddr local_addr; - pjsip_host_port addr_name; + pj_sockaddr local_addr; /**< Bound address. */ + pjsip_host_port addr_name; /**< Published name. */ /** * Create new outbound connection. @@ -628,7 +644,7 @@ struct pjsip_tpfactory * Register a transport factory. * * @param mgr The transport manager. - * @param factory Transport factory. + * @param tpf Transport factory. * * @return PJ_SUCCESS if listener was successfully created. */ @@ -637,6 +653,11 @@ PJ_DECL(pj_status_t) pjsip_tpmgr_register_tpfactory(pjsip_tpmgr *mgr, /** * Unregister factory. + * + * @param mgr The transport manager. + * @param tpf Transport factory. + * + * @return PJ_SUCCESS is sucessfully unregistered. */ PJ_DECL(pj_status_t) pjsip_tpmgr_unregister_tpfactory(pjsip_tpmgr *mgr, pjsip_tpfactory *tpf); diff --git a/pjsip/include/pjsip/sip_transport_loop.h b/pjsip/include/pjsip/sip_transport_loop.h index 3cc2af86..9ef5768b 100644 --- a/pjsip/include/pjsip/sip_transport_loop.h +++ b/pjsip/include/pjsip/sip_transport_loop.h @@ -19,8 +19,26 @@ #ifndef __PJSIP_TRANSPORT_LOOP_H__ #define __PJSIP_TRANSPORT_LOOP_H__ + +/** + * @file sip_transport_loop.h + * @brief + * Loopback transport (for debugging) + */ + + #include +/** + * @defgroup PJSIP_TRANSPORT_LOOP Loop Transport + * @ingroup PJSIP_TRANSPORT + * @brief Loopback transport (for testing purposes). + * @{ + * The loopback transport simply bounce back outgoing messages as + * incoming messages. This feature is used mostly during automated + * testing, to provide controlled behavior. + */ + PJ_BEGIN_DECL /** @@ -120,6 +138,9 @@ PJ_DECL(pj_status_t) pjsip_loop_set_delay( pjsip_transport *tp, PJ_END_DECL +/** + * @} + */ #endif /* __PJSIP_TRANSPORT_LOOP_H__ */ diff --git a/pjsip/include/pjsip/sip_transport_udp.h b/pjsip/include/pjsip/sip_transport_udp.h index 886f18c6..7cf8f553 100644 --- a/pjsip/include/pjsip/sip_transport_udp.h +++ b/pjsip/include/pjsip/sip_transport_udp.h @@ -1,4 +1,4 @@ -/* $Id: $ */ +/* $Id$ */ /* * Copyright (C) 2003-2006 Benny Prijono * @@ -19,10 +19,24 @@ #ifndef __PJSIP_TRANSPORT_UDP_H__ #define __PJSIP_TRANSPORT_UDP_H__ +/** + * @file sip_transport_udp.h + * @brief SIP UDP Transport. + */ + #include PJ_BEGIN_DECL +/** + * @defgroup PJSIP_TRANSPORT_UDP UDP transport + * @ingroup PJSIP_TRANSPORT + * @brief API to create and register UDP transport. + * @{ + * The functions below are used to create UDP transport and register + * the transport to the framework. + */ + /** * Start UDP transport. * @@ -67,5 +81,8 @@ PJ_DECL(pj_status_t) pjsip_udp_transport_attach(pjsip_endpoint *endpt, PJ_END_DECL +/** + * @} + */ #endif /* __PJSIP_TRANSPORT_UDP_H__ */ diff --git a/pjsip/include/pjsip/sip_types.h b/pjsip/include/pjsip/sip_types.h index 53035529..8ca8a041 100644 --- a/pjsip/include/pjsip/sip_types.h +++ b/pjsip/include/pjsip/sip_types.h @@ -19,16 +19,39 @@ #ifndef __PJSIP_SIP_TYPES_H__ #define __PJSIP_SIP_TYPES_H__ + +/* + * My note: Doxygen PJSIP and PJSIP_CORE group is declared in + * sip_config.h + */ + +/** + * @file sip_types.h + * @brief Basic PJSIP types. + */ + #include #include /** - * Opaque data structure for transports (sip_transport.h). + * @addtogroup PJSIP_BASE + */ + +/* @defgroup PJSIP_TYPES Basic Data Types + * @ingroup PJSIP_BASE + * @brief Basic data types. + * @{ + */ + + + +/** + * Forward declaration for SIP transport. */ typedef struct pjsip_transport pjsip_transport; /** - * Opaque data type for transport manager (sip_transport.h). + * Forward declaration for transport manager. */ typedef struct pjsip_tpmgr pjsip_tpmgr; @@ -217,5 +240,10 @@ PJ_DECL(pj_status_t) pjsip_exception_to_status(int exception_id); */ #define PJSIP_THROW_SPEC(list) + +/** + * @} + */ + #endif /* __PJSIP_SIP_TYPES_H__ */ diff --git a/pjsip/include/pjsip/sip_ua_layer.h b/pjsip/include/pjsip/sip_ua_layer.h index 4c62bec6..ca6db080 100644 --- a/pjsip/include/pjsip/sip_ua_layer.h +++ b/pjsip/include/pjsip/sip_ua_layer.h @@ -29,20 +29,34 @@ PJ_BEGIN_DECL /** - * @defgroup PJSUA SIP User Agent Stack + * @defgroup PJSIP_UA Base User Agent Layer/Common Dialog Layer + * @ingroup PJSIP + * @brief Dialog management. + * + * This module provides basic dialog management, which is used by higher + * layer dialog usages such as INVITE sessions and SIP Event Subscription + * framework (RFC 3265). Application should link with pjsip-core + * library to use this base UA layer. The base UA layer module is initialized + * with #pjsip_ua_init_module(). */ /** * @defgroup PJSUA_UA SIP User Agent Module - * @ingroup PJSUA + * @ingroup PJSIP_UA + * @brief Provides dialog management. * @{ - * \brief - * User Agent manages the interactions between application and SIP dialogs. + * + * Application MUST initialize the user agent layer module by calling + * #pjsip_ua_init_module() before using any of the dialog API, and link + * the application with with pjsip-core library. */ /** User agent initialization parameter. */ typedef struct pjsip_ua_init_param { + /** Callback to be called when the UA layer detects that outgoing + * dialog has forked. + */ pjsip_dialog* (*on_dlg_forked)(pjsip_dialog *first_set, pjsip_rx_data *res); } pjsip_ua_init_param; @@ -90,6 +104,11 @@ PJ_DEF(void) pjsip_ua_dump(pj_bool_t detail); PJ_DECL(pjsip_endpoint*) pjsip_ua_get_endpt(pjsip_user_agent *ua); +/** + * @} + */ + + /* * Internal (called by sip_dialog.c). */ @@ -100,10 +119,6 @@ PJ_DECL(pj_status_t) pjsip_ua_unregister_dlg(pjsip_user_agent *ua, pjsip_dialog *dlg ); -/** - * @} - */ - PJ_END_DECL diff --git a/pjsip/include/pjsip/sip_uri.h b/pjsip/include/pjsip/sip_uri.h index 6973c524..e5bc4180 100644 --- a/pjsip/include/pjsip/sip_uri.h +++ b/pjsip/include/pjsip/sip_uri.h @@ -33,9 +33,15 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_URL URL Structures - * @brief SIP Url, tel: Url, and generic URI. + * @defgroup PJSIP_URI URI + * @brief URI types and manipulations. * @ingroup PJSIP_MSG + */ + +/** + * @addtogroup PJSIP_URI_PARAM URI Parameter Container + * @ingroup PJSIP_URI + * @brief Generic parameter elements container. * @{ */ @@ -118,6 +124,17 @@ PJ_DECL(pj_ssize_t) pjsip_param_print_on(const pjsip_param *param_list, const pj_cis_t *pvalue_unres, int sep); +/** + * @} + */ + +/** + * @defgroup PJSIP_URI_GENERIC Generic URI + * @ingroup PJSIP_URI + * @brief Generic representation for all types of URI. + * @{ + */ + /** * URI context. */ @@ -221,45 +238,6 @@ struct pjsip_uri (pj_strnicmp2(pjsip_uri_get_scheme(url), "tel", 3)==0) -/** - * SIP and SIPS URL scheme. - */ -typedef struct pjsip_sip_uri -{ - pjsip_uri_vptr *vptr; /**< Pointer to virtual function table.*/ - pj_str_t user; /**< Optional user part. */ - pj_str_t passwd; /**< Optional password part. */ - pj_str_t host; /**< Host part, always exists. */ - int port; /**< Optional port number, or zero. */ - pj_str_t user_param; /**< Optional user parameter */ - pj_str_t method_param; /**< Optional method parameter. */ - pj_str_t transport_param; /**< Optional transport parameter. */ - int ttl_param; /**< Optional TTL param, or -1. */ - int lr_param; /**< Optional loose routing param, or zero */ - pj_str_t maddr_param; /**< Optional maddr param */ - pjsip_param other_param; /**< Other parameters grouped together. */ - pjsip_param header_param; /**< Optional header parameter. */ -} pjsip_sip_uri; - - -/** - * SIP name-addr, which typically appear in From, To, and Contact header. - * The SIP name-addr contains a generic URI and a display name. - */ -typedef struct pjsip_name_addr -{ - /** Pointer to virtual function table. */ - pjsip_uri_vptr *vptr; - - /** Optional display name. */ - pj_str_t display; - - /** URI part. */ - pjsip_uri *uri; - -} pjsip_name_addr; - - /** * Generic function to get the URI scheme. * @param uri the URI object. @@ -326,6 +304,58 @@ PJ_INLINE(void*) pjsip_uri_clone( pj_pool_t *pool, const void *uri ) } + +/** + * @} + */ + +/** + * @defgroup PJSIP_SIP_URI SIP URI Scheme and Name address + * @ingroup PJSIP_URI + * @brief SIP URL structure ("sip:" and "sips:") + * @{ + */ + + +/** + * SIP and SIPS URL scheme. + */ +typedef struct pjsip_sip_uri +{ + pjsip_uri_vptr *vptr; /**< Pointer to virtual function table.*/ + pj_str_t user; /**< Optional user part. */ + pj_str_t passwd; /**< Optional password part. */ + pj_str_t host; /**< Host part, always exists. */ + int port; /**< Optional port number, or zero. */ + pj_str_t user_param; /**< Optional user parameter */ + pj_str_t method_param; /**< Optional method parameter. */ + pj_str_t transport_param; /**< Optional transport parameter. */ + int ttl_param; /**< Optional TTL param, or -1. */ + int lr_param; /**< Optional loose routing param, or zero */ + pj_str_t maddr_param; /**< Optional maddr param */ + pjsip_param other_param; /**< Other parameters grouped together. */ + pjsip_param header_param; /**< Optional header parameter. */ +} pjsip_sip_uri; + + +/** + * SIP name-addr, which typically appear in From, To, and Contact header. + * The SIP name-addr contains a generic URI and a display name. + */ +typedef struct pjsip_name_addr +{ + /** Pointer to virtual function table. */ + pjsip_uri_vptr *vptr; + + /** Optional display name. */ + pj_str_t display; + + /** URI part. */ + pjsip_uri *uri; + +} pjsip_name_addr; + + /** * Create new SIP URL and initialize all fields with zero or NULL. * @param pool The pool. @@ -344,6 +374,7 @@ PJ_DECL(pjsip_sip_uri*) pjsip_sips_uri_create( pj_pool_t *pool ); /** * Initialize SIP URL (all fields are set to NULL or zero). * @param url The URL. + * @param secure Create sips URI? */ PJ_DECL(void) pjsip_sip_uri_init(pjsip_sip_uri *url, int secure); diff --git a/pjsip/include/pjsip/sip_util.h b/pjsip/include/pjsip/sip_util.h index eaa4bc03..d2b46be1 100644 --- a/pjsip/include/pjsip/sip_util.h +++ b/pjsip/include/pjsip/sip_util.h @@ -25,8 +25,9 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_ENDPT SIP Endpoint - * @ingroup PJSIP + * @defgroup PJSIP_ENDPT_STATELESS Message Creation and Stateless Operations + * @ingroup PJSIP_CORE_CORE + * @brief Utilities to create various messages and base function to send messages. * @{ */ @@ -238,6 +239,10 @@ typedef struct pjsip_send_state * * @param endpt The endpoint instance. * @param tdata The transmit data to be sent. + * @param token Arbitrary token to be given back on the callback. + * @param cb Optional callback to notify transmission status (also + * gives chance for application to discontinue retrying + * sending to alternate address). * * @return PJ_SUCCESS, or the appropriate error code. */ @@ -349,6 +354,16 @@ PJ_DECL(pj_status_t) pjsip_endpt_respond_stateless(pjsip_endpoint *endpt, const pjsip_hdr *hdr_list, const pjsip_msg_body *body); +/** + * @} + */ + +/** + * @defgroup PJSIP_TRANSACT_UTIL Stateful Operations + * @ingroup PJSIP_TRANSACT + * @brief Utility function to send requests/responses statefully. + * @{ + */ /** * This composite function creates and sends response statefully for the diff --git a/pjsip/include/pjsip_simple.h b/pjsip/include/pjsip_simple.h index fd7c41ae..97af4bc4 100644 --- a/pjsip/include/pjsip_simple.h +++ b/pjsip/include/pjsip_simple.h @@ -18,7 +18,8 @@ */ /** - * @defgroup PJSIP_SIMPLE SIP Event, Instant Messaging and Presence Extension (SIMPLE) + * @defgroup PJSIP_SIMPLE Event and Presence Framework + * @ingroup PJSIP */ /** diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h index 65e0cc72..90ba0f42 100644 --- a/pjsip/include/pjsua-lib/pjsua.h +++ b/pjsip/include/pjsua-lib/pjsua.h @@ -19,6 +19,12 @@ #ifndef __PJSUA_H__ #define __PJSUA_H__ +/** + * @file pjsua.h + * @brief PJSUA API. + */ + + /* Include all PJSIP core headers. */ #include @@ -41,64 +47,138 @@ #include +/** + * @defgroup PJSUA_LIB PJSUA API + * @ingroup PJSIP + * @brief Very high level API for constructing SIP UA applications. + * @{ + * + * PJSUA API is very high level API for constructing SIP user agent + * applications. It wraps together the signaling and media functionalities + * into an easy to use call API, provides account management, buddy + * management, presence, instant messaging, along with multimedia + * features such as conferencing, file streaming, local playback, + * voice recording, and so on. + * + * Application must link with pjsua-lib to use this API. In addition, + * this library depends on the following libraries: + * - pjsip-ua, + * - pjsip-simple, + * - pjsip-core, + * - pjmedia, + * - pjmedia-codec, + * - pjlib-util, and + * - pjlib, + * + * so application must also link with these libraries as well. + * + * @section root_using_pjsua_lib Using PJSUA API + * + * Please refer to @ref using_pjsua_lib on how to use PJSUA API. + */ + PJ_BEGIN_DECL -/** - * Max buddies in buddy list. - */ -#ifndef PJSUA_MAX_BUDDIES -# define PJSUA_MAX_BUDDIES 256 -#endif +/** Forward declaration */ +typedef struct pjsua_media_config pjsua_media_config; -/** - * Max simultaneous calls. +/***************************************************************************** + * BASE API */ -#ifndef PJSUA_MAX_CALLS -# define PJSUA_MAX_CALLS 32 -#endif - /** - * Max ports in the conference bridge. - */ -#ifndef PJSUA_MAX_CONF_PORTS -# define PJSUA_MAX_CONF_PORTS 254 -#endif + * @defgroup PJSUA_LIB_BASE Base API + * @ingroup PJSUA_LIB + * @brief Basic application creation/initialization, logging configuration, etc. + * @{ + * + * The base PJSUA API controls PJSUA creation, initialization, and startup, and + * also provides various auxiliary functions. + * + * @section using_pjsua_lib Using PJSUA Library + * + * @subsection creating_pjsua_lib Creating PJSUA + * + * Before anything else, application must create PJSUA by calling #pjsua_create(). + * This, among other things, will initialize PJLIB, which is crucial before + * any PJLIB functions can be called. + * + * @subsection init_pjsua_lib Initializing PJSUA + * + * After PJSUA is created, application can initialize PJSUA by calling + * #pjsua_init(). This function takes several configuration settings in the + * argument, so application normally would want to set these configuration + * before passing them to #pjsua_init(). + * + * Sample code to initialize PJSUA: + \code + pjsua_config ua_cfg; + pjsua_logging_config log_cfg; + pjsua_media_config media_cfg; -/** - * Maximum accounts. - */ -#ifndef PJSUA_MAX_ACC -# define PJSUA_MAX_ACC 8 -#endif + // Initialize configs with default settings. + pjsua_config_default(&ua_cfg); + pjsua_logging_config_default(&log_cfg); + pjsua_media_config_default(&media_cfg); + // At the very least, application would want to override + // the call callbacks in pjsua_config: + ua_cfg.cb.on_incoming_call = ... + ua_cfg.cb.on_call_state = .. + ... -/** - * Maximum proxies in account. - */ -#ifndef PJSUA_ACC_MAX_PROXIES -# define PJSUA_ACC_MAX_PROXIES 8 -#endif + // Customize other settings (or initialize them from application specific + // configuration file): + ... -/** - * Default registration interval. - */ -#ifndef PJSUA_REG_INTERVAL -# define PJSUA_REG_INTERVAL 55 -#endif + // Initialize pjsua + status = pjsua_init(&ua_cfg, &log_cfg, &media_cfg); + if (status != PJ_SUCCESS) { + pjsua_perror(THIS_FILE, "Error initializing pjsua", status); + return status; + } + .. + \endcode + * + * @subsection other_init_pjsua_lib Other Initialization + * + * After PJSUA is initialized with #pjsua_init(), application will normally + * need/want to perform the following tasks: + * + * - create SIP transport with #pjsua_transport_create(). Please see + * @ref PJSUA_LIB_TRANSPORT section for more info. + * - create one or more SIP accounts with #pjsua_acc_add() or + * #pjsua_acc_add_local(). Please see @ref PJSUA_LIB_ACC for more info. + * - add one or more buddies with #pjsua_buddy_add(). Please see + * @ref PJSUA_LIB_BUDDY section for more info. + * - optionally configure the sound device, codec settings, and other + * media settings. Please see @ref PJSUA_LIB_MEDIA for more info. + * + * + * @subsection starting_pjsua_lib Starting PJSUA + * + * After all initializations have been done, application must call + * #pjsua_start() to start PJSUA. This function will check that all settings + * are properly configured, and apply default settings when it's not, or + * report error status when it is unable to recover from missing setting. + * + * Most settings can be changed during run-time. For example, application + * may add, modify, or delete accounts, buddies, or change media settings + * during run-time. + */ -/** Account identification */ -typedef int pjsua_acc_id; +/** Constant to identify invalid ID for all sorts of IDs. */ +#define PJSUA_INVALID_ID (-1) /** Call identification */ typedef int pjsua_call_id; -/** SIP transport identification */ -typedef int pjsua_transport_id; +/** Account identification */ +typedef int pjsua_acc_id; /** Buddy identification */ typedef int pjsua_buddy_id; @@ -113,1188 +193,1223 @@ typedef int pjsua_recorder_id; typedef int pjsua_conf_port_id; -/** Constant to identify invalid ID for all sorts of IDs. */ -#define PJSUA_INVALID_ID (-1) + +/** + * Maximum proxies in account. + */ +#ifndef PJSUA_ACC_MAX_PROXIES +# define PJSUA_ACC_MAX_PROXIES 8 +#endif /** - * Account configuration. + * Logging configuration. */ -typedef struct pjsua_acc_config +typedef struct pjsua_logging_config { - /** - * The full SIP URL for the account. The value can take name address or - * URL format, and will look something like "sip:account@serviceprovider". - * - * This field is mandatory. - */ - pj_str_t id; - - /** - * This is the URL to be put in the request URI for the registration, - * and will look something like "sip:serviceprovider". - * - * This field should be specified if registration is desired. If the - * value is empty, no account registration will be performed. + /** + * Log incoming and outgoing SIP message? Yes! */ - pj_str_t reg_uri; + pj_bool_t msg_logging; - /** - * Optional URI to be put as Contact for this account. It is recommended - * that this field is left empty, so that the value will be calculated - * automatically based on the transport address. + /** + * Input verbosity level. Value 5 is reasonable. */ - pj_str_t contact; + unsigned level; /** - * Number of proxies in the proxy array below. + * Verbosity level for console. Value 4 is reasonable. */ - unsigned proxy_cnt; + unsigned console_level; - /** - * Optional URI of the proxies to be visited for all outgoing requests - * that are using this account (REGISTER, INVITE, etc). Application need - * to specify these proxies if the service provider requires that requests - * destined towards its network should go through certain proxies first - * (for example, border controllers). - * - * These proxies will be put in the route set for this account, with - * maintaining the orders (the first proxy in the array will be visited - * first). + /** + * Log decoration. */ - pj_str_t proxy[PJSUA_ACC_MAX_PROXIES]; + unsigned decor; - /** - * Optional interval for registration, in seconds. If the value is zero, - * default interval will be used (PJSUA_REG_INTERVAL, 55 seconds). + /** + * Optional log filename. */ - unsigned reg_timeout; + pj_str_t log_filename; - /** - * Number of credentials in the credential array. + /** + * Optional callback function to be called to write log to + * application specific device. This function will be called for + * log messages on input verbosity level. */ - unsigned cred_count; + void (*cb)(int level, const char *data, pj_size_t len); - /** - * Array of credentials. If registration is desired, normally there should - * be at least one credential specified, to successfully authenticate - * against the service provider. More credentials can be specified, for - * example when the requests are expected to be challenged by the - * proxies in the route set. - */ - pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; -} pjsua_acc_config; +} pjsua_logging_config; /** - * Call this function to initialize account config with default values. + * Use this function to initialize logging config. * - * @param cfg The account config to be initialized. + * @param cfg The logging config to be initialized. */ -PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg) +PJ_INLINE(void) pjsua_logging_config_default(pjsua_logging_config *cfg) { pj_memset(cfg, 0, sizeof(*cfg)); - cfg->reg_timeout = PJSUA_REG_INTERVAL; + cfg->msg_logging = PJ_TRUE; + cfg->level = 5; + cfg->console_level = 4; + cfg->decor = PJ_LOG_HAS_SENDER | PJ_LOG_HAS_TIME | + PJ_LOG_HAS_MICRO_SEC | PJ_LOG_HAS_NEWLINE; +} + +/** + * Use this function to duplicate logging config. + * + * @param pool Pool to use. + * @param dst Destination config. + * @param src Source config. + */ +PJ_INLINE(void) pjsua_logging_config_dup(pj_pool_t *pool, + pjsua_logging_config *dst, + const pjsua_logging_config *src) +{ + pj_memcpy(dst, src, sizeof(*src)); + pj_strdup_with_null(pool, &dst->log_filename, &src->log_filename); } /** - * Account info. Application can query account info by calling - * #pjsua_acc_get_info(). + * Application callbacks. */ -typedef struct pjsua_acc_info +typedef struct pjsua_callback { - /** - * The account ID. - */ - pjsua_acc_id id; - /** - * Flag to indicate whether this is the default account. - */ - pj_bool_t is_default; - - /** - * Account URI + * Notify application when invite state has changed. + * Application may then query the call info to get the + * detail call states. */ - pj_str_t acc_uri; + void (*on_call_state)(pjsua_call_id call_id, pjsip_event *e); - /** - * Flag to tell whether this account has registration setting - * (reg_uri is not empty). + /** + * Notify application on incoming call. */ - pj_bool_t has_registration; + void (*on_incoming_call)(pjsua_acc_id acc_id, pjsua_call_id call_id, + pjsip_rx_data *rdata); /** - * An up to date expiration interval for account registration session. + * Notify application when media state in the call has changed. + * Normal application would need to implement this callback, e.g. + * to connect the call's media to sound device. */ - int expires; + void (*on_call_media_state)(pjsua_call_id call_id); /** - * Last registration status code. If status code is zero, the account - * is currently not registered. Any other value indicates the SIP - * status code of the registration. + * Notify application on call being transfered. + * Application can decide to accept/reject transfer request + * by setting the code (default is 200). When this callback + * is not defined, the default behavior is to accept the + * transfer. */ - pjsip_status_code status; + void (*on_call_transfered)(pjsua_call_id call_id, + const pj_str_t *dst, + pjsip_status_code *code); /** - * String describing the registration status. + * Notify application when registration status has changed. + * Application may then query the account info to get the + * registration details. */ - pj_str_t status_text; + void (*on_reg_state)(pjsua_acc_id acc_id); /** - * Presence online status for this account. + * Notify application when the buddy state has changed. + * Application may then query the buddy into to get the details. */ - pj_bool_t online_status; + void (*on_buddy_state)(pjsua_buddy_id buddy_id); /** - * Buffer that is used internally to store the status text. + * Notify application on incoming pager (i.e. MESSAGE request). + * Argument call_id will be -1 if MESSAGE request is not related to an + * existing call. */ - char buf_[PJ_ERR_MSG_SIZE]; - -} pjsua_acc_info; - - + void (*on_pager)(pjsua_call_id call_id, const pj_str_t *from, + const pj_str_t *to, const pj_str_t *contact, + const pj_str_t *mime_type, const pj_str_t *body); -/** - * STUN configuration. - */ -typedef struct pjsua_stun_config -{ /** - * The first STUN server IP address or hostname. + * Notify application about the delivery status of outgoing pager + * request. + * + * @param call_id Containts the ID of the call where the IM was + * sent, or PJSUA_INVALID_ID if the IM was sent + * outside call context. + * @param to Destination URI. + * @param body Message body. + * @param user_data Arbitrary data that was specified when sending + * IM message. + * @param status Delivery status. + * @param reason Delivery status reason. */ - pj_str_t stun_srv1; + void (*on_pager_status)(pjsua_call_id call_id, + const pj_str_t *to, + const pj_str_t *body, + void *user_data, + pjsip_status_code status, + const pj_str_t *reason); /** - * Port number of the first STUN server. - * If zero, default STUN port will be used. - */ - unsigned stun_port1; - - /** - * Optional second STUN server IP address or hostname, for which the - * result of the mapping request will be compared to. If the value - * is empty, only one STUN server will be used. + * Notify application about typing indication. */ - pj_str_t stun_srv2; + void (*on_typing)(pjsua_call_id call_id, const pj_str_t *from, + const pj_str_t *to, const pj_str_t *contact, + pj_bool_t is_typing); - /** - * Port number of the second STUN server. - * If zero, default STUN port will be used. - */ - unsigned stun_port2; +} pjsua_callback; -} pjsua_stun_config; /** - * Call this function to initialize STUN config with default values. - * - * @param cfg The STUN config to be initialized. + * PJSUA settings. */ -PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg) +typedef struct pjsua_config { - pj_memset(cfg, 0, sizeof(*cfg)); -} + /** + * Maximum calls to support (default: 4) + */ + unsigned max_calls; -/** - * Transport configuration for creating UDP transports for both SIP - * and media. - */ -typedef struct pjsua_transport_config -{ - /** - * UDP port number to bind locally. This setting MUST be specified - * even when default port is desired. If the value is zero, the - * transport will be bound to any available port, and application - * can query the port by querying the transport info. + /** + * Number of worker threads. Normally application will want to have at + * least one worker thread, unless when it wants to poll the library + * periodically, which in this case the worker thread can be set to + * zero. */ - unsigned port; + unsigned thread_cnt; /** - * Optional address where the socket should be bound. + * Number of outbound proxies in the array. */ - pj_in_addr ip_addr; + unsigned outbound_proxy_cnt; - /** - * Flag to indicate whether STUN should be used. + /** + * Specify the URL of outbound proxies to visit for all outgoing requests. + * The outbound proxies will be used for all accounts, and it will + * be used to build the route set for outgoing requests. The final + * route set for outgoing requests will consists of the outbound proxies + * and the proxy configured in the account. */ - pj_bool_t use_stun; + pj_str_t outbound_proxy[4]; + + /** + * Number of credentials in the credential array. + */ + unsigned cred_count; + + /** + * Array of credentials. These credentials will be used by all accounts, + * and can be used to authenticate against outbound proxies. + */ + pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; /** - * STUN configuration, must be specified when STUN is used. + * Application callback. */ - pjsua_stun_config stun_config; + pjsua_callback cb; -} pjsua_transport_config; +} pjsua_config; /** - * Call this function to initialize UDP config with default values. + * Use this function to initialize pjsua config. * - * @param cfg The UDP config to be initialized. + * @param cfg pjsua config to be initialized. */ -PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg) +PJ_INLINE(void) pjsua_config_default(pjsua_config *cfg) { pj_memset(cfg, 0, sizeof(*cfg)); + + cfg->max_calls = 4; + cfg->thread_cnt = 1; } /** - * Normalize STUN config. + * Duplicate credential. */ -PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg ) +PJ_INLINE(void) pjsip_cred_dup( pj_pool_t *pool, + pjsip_cred_info *dst, + const pjsip_cred_info *src) { - if (cfg->stun_srv1.slen) { - - if (cfg->stun_port1 == 0) - cfg->stun_port1 = 3478; - - if (cfg->stun_srv2.slen == 0) { - cfg->stun_srv2 = cfg->stun_srv1; - cfg->stun_port2 = cfg->stun_port1; - } else { - if (cfg->stun_port2 == 0) - cfg->stun_port2 = 3478; - } + pj_strdup_with_null(pool, &dst->realm, &src->realm); + pj_strdup_with_null(pool, &dst->scheme, &src->scheme); + pj_strdup_with_null(pool, &dst->username, &src->username); + pj_strdup_with_null(pool, &dst->data, &src->data); - } else { - cfg->stun_port1 = 0; - cfg->stun_srv2.slen = 0; - cfg->stun_port2 = 0; - } } /** - * Duplicate transport config. + * Duplicate pjsua_config. */ -PJ_INLINE(void) pjsua_transport_config_dup(pj_pool_t *pool, - pjsua_transport_config *dst, - const pjsua_transport_config *src) +PJ_INLINE(void) pjsua_config_dup(pj_pool_t *pool, + pjsua_config *dst, + const pjsua_config *src) { + unsigned i; + pj_memcpy(dst, src, sizeof(*src)); - if (src->stun_config.stun_srv1.slen) { - pj_strdup_with_null(pool, &dst->stun_config.stun_srv1, - &src->stun_config.stun_srv1); + for (i=0; ioutbound_proxy_cnt; ++i) { + pj_strdup_with_null(pool, &dst->outbound_proxy[i], + &src->outbound_proxy[i]); } - if (src->stun_config.stun_srv2.slen) { - pj_strdup_with_null(pool, &dst->stun_config.stun_srv2, - &src->stun_config.stun_srv2); + for (i=0; icred_count; ++i) { + pjsip_cred_dup(pool, &dst->cred_info[i], &src->cred_info[i]); } - - pjsua_normalize_stun_config(&dst->stun_config); } /** - * Transport info. + * This structure describes additional information to be sent with + * outgoing SIP message. */ -typedef struct pjsua_transport_info +typedef struct pjsua_msg_data { /** - * PJSUA transport identification. + * Additional message headers as linked list. */ - pjsua_transport_id id; + pjsip_hdr hdr_list; /** - * Transport type. + * MIME type of optional message body. */ - pjsip_transport_type_e type; + pj_str_t content_type; /** - * Transport type name. + * Optional message body. */ - pj_str_t type_name; + pj_str_t msg_body; - /** - * Transport string info/description. - */ - pj_str_t info; +} pjsua_msg_data; - /** - * Transport flag (see ##pjsip_transport_flags_e). - */ - unsigned flag; - /** - * Local address length. - */ - unsigned addr_len; +/** + * Initialize message data. + * + * @param msg_data Message data to be initialized. + */ +PJ_INLINE(void) pjsua_msg_data_init(pjsua_msg_data *msg_data) +{ + pj_memset(msg_data, 0, sizeof(*msg_data)); + pj_list_init(&msg_data->hdr_list); +} - /** - * Local/bound address. - */ - pj_sockaddr local_addr; - /** - * Published address (or transport address name). - */ - pjsip_host_port local_name; - /** - * Current number of objects currently referencing this transport. - */ - unsigned usage_count; +/** + * Instantiate pjsua application. Application must call this function before + * calling any other functions, to make sure that the underlying libraries + * are properly initialized. Once this function has returned success, + * application must call pjsua_destroy() before quitting. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsua_create(void); -} pjsua_transport_info; +/** + * Initialize pjsua with the specified settings. All the settings are + * optional, and the default values will be used when the config is not + * specified. + * + * @param ua_cfg User agent configuration. + * @param log_cfg Optional logging configuration. + * @param media_cfg Optional media configuration. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg, + const pjsua_logging_config *log_cfg, + const pjsua_media_config *media_cfg); /** - * Media configuration. + * Application is recommended to call this function after all initialization + * is done, so that the library can do additional checking set up + * additional + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -typedef struct pjsua_media_config -{ - /** - * Clock rate to be applied to the conference bridge. - * If value is zero, default clock rate will be used (16KHz). - */ - unsigned clock_rate; - - /** - * Specify maximum number of media ports to be created in the - * conference bridge. Since all media terminate in the bridge - * (calls, file player, file recorder, etc), the value must be - * large enough to support all of them. However, the larger - * the value, the more computations are performed. - */ - unsigned max_media_ports; - - /** - * Specify whether the media manager should manage its own - * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created - * and at least one worker thread will be created too. If no, - * the RTP/RTCP sockets will share the same ioqueue as SIP sockets, - * and no worker thread is needed. - * - * Normally application would say yes here, unless it wants to - * run everything from a single thread. - */ - pj_bool_t has_ioqueue; - - /** - * Specify the number of worker threads to handle incoming RTP - * packets. A value of one is recommended for most applications. - */ - unsigned thread_cnt; +PJ_DECL(pj_status_t) pjsua_start(void); -} pjsua_media_config; +/** + * Destroy pjsua. This function must be called once PJSUA is created. To + * make it easier for application, application may call this function + * several times with no danger. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsua_destroy(void); /** - * Use this function to initialize media config. + * Poll pjsua for events, and if necessary block the caller thread for + * the specified maximum interval (in miliseconds). * - * @param cfg The media config to be initialized. + * @param msec_timeout Maximum time to wait, in miliseconds. + * + * @return The number of events that have been handled during the + * poll. Negative value indicates error, and application + * can retrieve the error as (err = -return_value). */ -PJ_INLINE(void) pjsua_media_config_default(pjsua_media_config *cfg) -{ - pj_memset(cfg, 0, sizeof(*cfg)); +PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout); - cfg->clock_rate = 16000; - cfg->max_media_ports = 32; - cfg->has_ioqueue = PJ_TRUE; - cfg->thread_cnt = 1; -} +/** + * Create memory pool. + * + * @param name Optional pool name. + * @param init_size Initial size of the pool. + * @param increment Increment size. + * + * @return The pool, or NULL when there's no memory. + */ +PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size, + pj_size_t increment); /** - * Logging configuration. + * Application can call this function at any time (after pjsua_create(), of + * course) to change logging settings. + * + * @param c Logging configuration. + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -typedef struct pjsua_logging_config -{ - /** - * Log incoming and outgoing SIP message? Yes! - */ - pj_bool_t msg_logging; - - /** - * Input verbosity level. Value 5 is reasonable. - */ - unsigned level; +PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c); - /** - * Verbosity level for console. Value 4 is reasonable. - */ - unsigned console_level; - /** - * Log decoration. - */ - unsigned decor; +/** + * Internal function to get SIP endpoint instance of pjsua, which is + * needed for example to register module, create transports, etc. + * Probably is only valid after #pjsua_init() is called. + * + * @return SIP endpoint instance. + */ +PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void); - /** - * Optional log filename. - */ - pj_str_t log_filename; +/** + * Internal function to get media endpoint instance. + * Only valid after #pjsua_init() is called. + * + * @return Media endpoint instance. + */ +PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); - /** - * Optional callback function to be called to write log to - * application specific device. This function will be called for - * log messages on input verbosity level. - */ - void (*cb)(int level, const char *data, pj_size_t len); +/***************************************************************************** + * Utilities. + * + */ -} pjsua_logging_config; +/** + * Verify that valid SIP url is given. + * + * @param c_url The URL, as NULL terminated string. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *c_url); /** - * Use this function to initialize logging config. + * Display error message for the specified error code. * - * @param cfg The logging config to be initialized. + * @param sender The log sender field. + * @param title Message title for the error. + * @param status Status code. */ -PJ_INLINE(void) pjsua_logging_config_default(pjsua_logging_config *cfg) -{ - pj_memset(cfg, 0, sizeof(*cfg)); +PJ_DECL(void) pjsua_perror(const char *sender, const char *title, + pj_status_t status); + + - cfg->msg_logging = PJ_TRUE; - cfg->level = 5; - cfg->console_level = 4; - cfg->decor = PJ_LOG_HAS_SENDER | PJ_LOG_HAS_TIME | - PJ_LOG_HAS_MICRO_SEC | PJ_LOG_HAS_NEWLINE; -} /** - * Use this function to duplicate logging config. - * - * @param pool Pool to use. - * @param dst Destination config. - * @param src Source config. + * @} */ -PJ_INLINE(void) pjsua_logging_config_dup(pj_pool_t *pool, - pjsua_logging_config *dst, - const pjsua_logging_config *src) -{ - pj_memcpy(dst, src, sizeof(*src)); - pj_strdup_with_null(pool, &dst->log_filename, &src->log_filename); -} + +/***************************************************************************** + * TRANSPORT API + */ + /** - * Buddy configuration. + * @defgroup PJSUA_LIB_TRANSPORT Signaling Transport + * @ingroup PJSUA_LIB + * @brief API for managing SIP transports + * @{ + * SIP transport must be created before adding an account. SIP transport is + * created by calling #pjsua_transport_create() function. */ -typedef struct pjsua_buddy_config -{ - /** - * Buddy URL or name address. - */ - pj_str_t uri; - /** - * Specify whether presence subscription should start immediately. - */ - pj_bool_t subscribe; -} pjsua_buddy_config; +/** SIP transport identification */ +typedef int pjsua_transport_id; /** - * Buddy's online status. + * STUN configuration. */ -typedef enum pjsua_buddy_status +typedef struct pjsua_stun_config { /** - * Online status is unknown (possibly because no presence subscription - * has been established). + * The first STUN server IP address or hostname. */ - PJSUA_BUDDY_STATUS_UNKNOWN, + pj_str_t stun_srv1; /** - * Buddy is known to be offline. + * Port number of the first STUN server. + * If zero, default STUN port will be used. */ - PJSUA_BUDDY_STATUS_ONLINE, + unsigned stun_port1; + + /** + * Optional second STUN server IP address or hostname, for which the + * result of the mapping request will be compared to. If the value + * is empty, only one STUN server will be used. + */ + pj_str_t stun_srv2; /** - * Buddy is offline. + * Port number of the second STUN server. + * If zero, default STUN port will be used. */ - PJSUA_BUDDY_STATUS_OFFLINE, + unsigned stun_port2; -} pjsua_buddy_status; +} pjsua_stun_config; /** - * Buddy info. + * Call this function to initialize STUN config with default values. + * + * @param cfg The STUN config to be initialized. */ -typedef struct pjsua_buddy_info +PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg) { - /** - * The buddy ID. - */ - pjsua_buddy_id id; - - /** - * The full URI of the buddy, as specified in the configuration. - */ - pj_str_t uri; + pj_memset(cfg, 0, sizeof(*cfg)); +} - /** - * Buddy's Contact, only available when presence subscription has - * been established to the buddy. - */ - pj_str_t contact; +/** + * Transport configuration for creating UDP transports for both SIP + * and media. + */ +typedef struct pjsua_transport_config +{ /** - * Buddy's online status. + * UDP port number to bind locally. This setting MUST be specified + * even when default port is desired. If the value is zero, the + * transport will be bound to any available port, and application + * can query the port by querying the transport info. */ - pjsua_buddy_status status; + unsigned port; /** - * Text to describe buddy's online status. + * Optional address where the socket should be bound. */ - pj_str_t status_text; + pj_in_addr ip_addr; /** - * Flag to indicate that we should monitor the presence information for - * this buddy (normally yes, unless explicitly disabled). + * Flag to indicate whether STUN should be used. */ - pj_bool_t monitor_pres; + pj_bool_t use_stun; /** - * Internal buffer. + * STUN configuration, must be specified when STUN is used. */ - char buf_[256]; + pjsua_stun_config stun_config; -} pjsua_buddy_info; +} pjsua_transport_config; /** - * Codec config. + * Call this function to initialize UDP config with default values. + * + * @param cfg The UDP config to be initialized. */ -typedef struct pjsua_codec_info +PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg) { - /** - * Codec unique identification. - */ - pj_str_t codec_id; + pj_memset(cfg, 0, sizeof(*cfg)); +} - /** - * Codec priority (integer 0-255). - */ - pj_uint8_t priority; - /** - * Internal buffer. - */ - char buf_[32]; +/** + * Normalize STUN config. + */ +PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg ) +{ + if (cfg->stun_srv1.slen) { -} pjsua_codec_info; + if (cfg->stun_port1 == 0) + cfg->stun_port1 = 3478; + + if (cfg->stun_srv2.slen == 0) { + cfg->stun_srv2 = cfg->stun_srv1; + cfg->stun_port2 = cfg->stun_port1; + } else { + if (cfg->stun_port2 == 0) + cfg->stun_port2 = 3478; + } + + } else { + cfg->stun_port1 = 0; + cfg->stun_srv2.slen = 0; + cfg->stun_port2 = 0; + } +} /** - * Application callbacks. + * Duplicate transport config. */ -typedef struct pjsua_callback +PJ_INLINE(void) pjsua_transport_config_dup(pj_pool_t *pool, + pjsua_transport_config *dst, + const pjsua_transport_config *src) +{ + pj_memcpy(dst, src, sizeof(*src)); + + if (src->stun_config.stun_srv1.slen) { + pj_strdup_with_null(pool, &dst->stun_config.stun_srv1, + &src->stun_config.stun_srv1); + } + + if (src->stun_config.stun_srv2.slen) { + pj_strdup_with_null(pool, &dst->stun_config.stun_srv2, + &src->stun_config.stun_srv2); + } + + pjsua_normalize_stun_config(&dst->stun_config); +} + + + +/** + * Transport info. + */ +typedef struct pjsua_transport_info { /** - * Notify application when invite state has changed. - * Application may then query the call info to get the - * detail call states. + * PJSUA transport identification. */ - void (*on_call_state)(pjsua_call_id call_id, pjsip_event *e); + pjsua_transport_id id; /** - * Notify application on incoming call. + * Transport type. */ - void (*on_incoming_call)(pjsua_acc_id acc_id, pjsua_call_id call_id, - pjsip_rx_data *rdata); + pjsip_transport_type_e type; /** - * Notify application when media state in the call has changed. - * Normal application would need to implement this callback, e.g. - * to connect the call's media to sound device. + * Transport type name. */ - void (*on_call_media_state)(pjsua_call_id call_id); + pj_str_t type_name; /** - * Notify application on call being transfered. - * Application can decide to accept/reject transfer request - * by setting the code (default is 200). When this callback - * is not defined, the default behavior is to accept the - * transfer. + * Transport string info/description. */ - void (*on_call_transfered)(pjsua_call_id call_id, - const pj_str_t *dst, - pjsip_status_code *code); + pj_str_t info; /** - * Notify application when registration status has changed. - * Application may then query the account info to get the - * registration details. + * Transport flag (see ##pjsip_transport_flags_e). */ - void (*on_reg_state)(pjsua_acc_id acc_id); + unsigned flag; /** - * Notify application when the buddy state has changed. - * Application may then query the buddy into to get the details. + * Local address length. */ - void (*on_buddy_state)(pjsua_buddy_id buddy_id); + unsigned addr_len; /** - * Notify application on incoming pager (i.e. MESSAGE request). - * Argument call_id will be -1 if MESSAGE request is not related to an - * existing call. + * Local/bound address. */ - void (*on_pager)(pjsua_call_id call_id, const pj_str_t *from, - const pj_str_t *to, const pj_str_t *contact, - const pj_str_t *mime_type, const pj_str_t *body); + pj_sockaddr local_addr; /** - * Notify application about the delivery status of outgoing pager - * request. - * - * @param call_id Containts the ID of the call where the IM was - * sent, or PJSUA_INVALID_ID if the IM was sent - * outside call context. - * @param to Destination URI. - * @param body Message body. - * @param user_data Arbitrary data that was specified when sending - * IM message. - * @param status Delivery status. - * @param reason Delivery status reason. + * Published address (or transport address name). */ - void (*on_pager_status)(pjsua_call_id call_id, - const pj_str_t *to, - const pj_str_t *body, - void *user_data, - pjsip_status_code status, - const pj_str_t *reason); + pjsip_host_port local_name; /** - * Notify application about typing indication. + * Current number of objects currently referencing this transport. */ - void (*on_typing)(pjsua_call_id call_id, const pj_str_t *from, - const pj_str_t *to, const pj_str_t *contact, - pj_bool_t is_typing); - -} pjsua_callback; + unsigned usage_count; +} pjsua_transport_info; /** - * PJSUA settings. + * Create SIP transport. + * + * @param type Transport type. + * @param cfg Transport configuration. + * @param p_id Optional pointer to receive transport ID. + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -typedef struct pjsua_config -{ - - /** - * Maximum calls to support (default: 4) - */ - unsigned max_calls; - - /** - * Number of worker threads. Normally application will want to have at - * least one worker thread, unless when it wants to poll the library - * periodically, which in this case the worker thread can be set to - * zero. - */ - unsigned thread_cnt; - - /** - * Number of outbound proxies in the array. - */ - unsigned outbound_proxy_cnt; - - /** - * Specify the URL of outbound proxies to visit for all outgoing requests. - * The outbound proxies will be used for all accounts, and it will - * be used to build the route set for outgoing requests. The final - * route set for outgoing requests will consists of the outbound proxies - * and the proxy configured in the account. - */ - pj_str_t outbound_proxy[4]; - - /** - * Number of credentials in the credential array. - */ - unsigned cred_count; - - /** - * Array of credentials. These credentials will be used by all accounts, - * and can be used to authenticate against outbound proxies. - */ - pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; - - /** - * Application callback. - */ - pjsua_callback cb; - -} pjsua_config; - +PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type, + const pjsua_transport_config *cfg, + pjsua_transport_id *p_id); /** - * Use this function to initialize pjsua config. + * Register transport that has been created by application. * - * @param cfg pjsua config to be initialized. + * @param tp Transport instance. + * @param p_id Optional pointer to receive transport ID. + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_INLINE(void) pjsua_config_default(pjsua_config *cfg) -{ - pj_memset(cfg, 0, sizeof(*cfg)); - - cfg->max_calls = 4; - cfg->thread_cnt = 1; -} +PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp, + pjsua_transport_id *p_id); /** - * Duplicate credential. + * Enumerate all transports currently created in the system. + * + * @param id Array to receive transport ids. + * @param count In input, specifies the maximum number of elements. + * On return, it contains the actual number of elements. + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_INLINE(void) pjsip_cred_dup( pj_pool_t *pool, - pjsip_cred_info *dst, - const pjsip_cred_info *src) -{ - pj_strdup_with_null(pool, &dst->realm, &src->realm); - pj_strdup_with_null(pool, &dst->scheme, &src->scheme); - pj_strdup_with_null(pool, &dst->username, &src->username); - pj_strdup_with_null(pool, &dst->data, &src->data); - -} +PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[], + unsigned *count ); /** - * Duplicate pjsua_config. + * Get information about transports. + * + * @param id Transport ID. + * @param info Pointer to receive transport info. + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_INLINE(void) pjsua_config_dup(pj_pool_t *pool, - pjsua_config *dst, - const pjsua_config *src) -{ - unsigned i; - - pj_memcpy(dst, src, sizeof(*src)); +PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id, + pjsua_transport_info *info); - for (i=0; ioutbound_proxy_cnt; ++i) { - pj_strdup_with_null(pool, &dst->outbound_proxy[i], - &src->outbound_proxy[i]); - } - for (i=0; icred_count; ++i) { - pjsip_cred_dup(pool, &dst->cred_info[i], &src->cred_info[i]); - } -} +/** + * Disable a transport or re-enable it. By default transport is always + * enabled after it is created. Disabling a transport does not necessarily + * close the socket, it will only discard incoming messages and prevent + * the transport from being used to send outgoing messages. + * + * @param id Transport ID. + * @param enabled Non-zero to enable, zero to disable. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id, + pj_bool_t enabled); /** - * Call media status. + * Close the transport. If transport is forcefully closed, it will be + * immediately closed, and any pending transactions that are using the + * transport may not terminate properly. Otherwise, the system will wait + * until all transactions are closed while preventing new users from + * using the transport, and will close the transport when it is safe to + * do so. + * + * @param id Transport ID. + * @param force Non-zero to immediately close the transport. This + * is not recommended! + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -typedef enum pjsua_call_media_status -{ - PJSUA_CALL_MEDIA_NONE, - PJSUA_CALL_MEDIA_ACTIVE, - PJSUA_CALL_MEDIA_LOCAL_HOLD, - PJSUA_CALL_MEDIA_REMOTE_HOLD, -} pjsua_call_media_status; - +PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, + pj_bool_t force ); /** - * Call info. + * @} */ -typedef struct pjsua_call_info -{ - /** Call identification. */ - pjsua_call_id id; - /** Initial call role (UAC == caller) */ - pjsip_role_e role; - /** Local URI */ - pj_str_t local_info; - /** Local Contact */ - pj_str_t local_contact; - /** Remote URI */ - pj_str_t remote_info; +/***************************************************************************** + * ACCOUNT API + */ - /** Remote contact */ - pj_str_t remote_contact; - /** Dialog Call-ID string. */ - pj_str_t call_id; +/** + * @defgroup PJSUA_LIB_ACC Account Management + * @ingroup PJSUA_LIB + * @brief PJSUA supports multiple accounts.. + * @{ + * PJSUA accounts provide identity (or identities) of the user who is currently + * using the application. More than one account maybe created with PJSUA. + * + * Account may or may not have client registration associated with it. + * An account is also associated with route set and some authentication + * credentials, which are used when sending SIP request messages using the + * account. An account also has presence's online status, which + * will be reported to remote peer when the subscribe to the account's + * presence. + * + * At least one account MUST be created in the application. If no user + * association is required, application can create a userless account by + * calling #pjsua_acc_add_local(). A userless account identifies local endpoint + * instead of a particular user. + * + * Also one account must be set as the default account, which is used as + * the account to use when PJSUA fails to match a request with any other + * accounts. + * + * When sending outgoing SIP requests (such as making calls or sending + * instant messages), normally PJSUA requires the application to specify + * which account to use for the request. If no account is specified, + * PJSUA may be able to select the account by matching the destination + * domain name, and fall back to default account when no match is found. + */ - /** Call state */ - pjsip_inv_state state; +/** + * Maximum accounts. + */ +#ifndef PJSUA_MAX_ACC +# define PJSUA_MAX_ACC 8 +#endif - /** Text describing the state */ - pj_str_t state_text; - /** Last status code heard, which can be used as cause code */ - pjsip_status_code last_status; +/** + * Default registration interval. + */ +#ifndef PJSUA_REG_INTERVAL +# define PJSUA_REG_INTERVAL 55 +#endif - /** The reason phrase describing the status. */ - pj_str_t last_status_text; - /** Call media status. */ - pjsua_call_media_status media_status; +/** + * Account configuration. + */ +typedef struct pjsua_acc_config +{ + /** + * The full SIP URL for the account. The value can take name address or + * URL format, and will look something like "sip:account@serviceprovider". + * + * This field is mandatory. + */ + pj_str_t id; - /** Media direction */ - pjmedia_dir media_dir; + /** + * This is the URL to be put in the request URI for the registration, + * and will look something like "sip:serviceprovider". + * + * This field should be specified if registration is desired. If the + * value is empty, no account registration will be performed. + */ + pj_str_t reg_uri; - /** The conference port number for the call */ - pjsua_conf_port_id conf_slot; + /** + * Optional URI to be put as Contact for this account. It is recommended + * that this field is left empty, so that the value will be calculated + * automatically based on the transport address. + */ + pj_str_t contact; - /** Up-to-date call connected duration (zero when call is not - * established) + /** + * Number of proxies in the proxy array below. */ - pj_time_val connect_duration; + unsigned proxy_cnt; - /** Total call duration, including set-up time */ - pj_time_val total_duration; + /** + * Optional URI of the proxies to be visited for all outgoing requests + * that are using this account (REGISTER, INVITE, etc). Application need + * to specify these proxies if the service provider requires that requests + * destined towards its network should go through certain proxies first + * (for example, border controllers). + * + * These proxies will be put in the route set for this account, with + * maintaining the orders (the first proxy in the array will be visited + * first). + */ + pj_str_t proxy[PJSUA_ACC_MAX_PROXIES]; - /** Internal */ - struct { - char local_info[128]; - char local_contact[128]; - char remote_info[128]; - char remote_contact[128]; - char call_id[128]; - char last_status_text[128]; - } buf_; + /** + * Optional interval for registration, in seconds. If the value is zero, + * default interval will be used (PJSUA_REG_INTERVAL, 55 seconds). + */ + unsigned reg_timeout; -} pjsua_call_info; + /** + * Number of credentials in the credential array. + */ + unsigned cred_count; + /** + * Array of credentials. If registration is desired, normally there should + * be at least one credential specified, to successfully authenticate + * against the service provider. More credentials can be specified, for + * example when the requests are expected to be challenged by the + * proxies in the route set. + */ + pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; +} pjsua_acc_config; /** - * Conference port info. + * Call this function to initialize account config with default values. + * + * @param cfg The account config to be initialized. */ -typedef struct pjsua_conf_port_info +PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg) { - /** Conference port number. */ - pjsua_conf_port_id slot_id; - - /** Port name. */ - pj_str_t name; - - /** Clock rate. */ - unsigned clock_rate; - - /** Number of channels. */ - unsigned channel_count; - - /** Samples per frame */ - unsigned samples_per_frame; - - /** Bits per sample */ - unsigned bits_per_sample; - - /** Number of listeners in the array. */ - unsigned listener_cnt; + pj_memset(cfg, 0, sizeof(*cfg)); - /** Array of listeners (in other words, ports where this port is - * transmitting to. - */ - pjsua_conf_port_id listeners[PJSUA_MAX_CONF_PORTS]; + cfg->reg_timeout = PJSUA_REG_INTERVAL; +} -} pjsua_conf_port_info; /** - * This structure holds information about custom media transport to - * be registered to pjsua. + * Account info. Application can query account info by calling + * #pjsua_acc_get_info(). */ -typedef struct pjsua_media_transport +typedef struct pjsua_acc_info { - /** - * Media socket information containing the address information - * of the RTP and RTCP socket. + /** + * The account ID. */ - pjmedia_sock_info skinfo; + pjsua_acc_id id; /** - * The media transport instance. + * Flag to indicate whether this is the default account. */ - pjmedia_transport *transport; + pj_bool_t is_default; -} pjsua_media_transport; + /** + * Account URI + */ + pj_str_t acc_uri; + /** + * Flag to tell whether this account has registration setting + * (reg_uri is not empty). + */ + pj_bool_t has_registration; + + /** + * An up to date expiration interval for account registration session. + */ + int expires; + + /** + * Last registration status code. If status code is zero, the account + * is currently not registered. Any other value indicates the SIP + * status code of the registration. + */ + pjsip_status_code status; -/** - * This structure describes additional information to be sent with - * outgoing SIP message. - */ -typedef struct pjsua_msg_data -{ /** - * Additional message headers as linked list. + * String describing the registration status. */ - pjsip_hdr hdr_list; + pj_str_t status_text; /** - * MIME type of optional message body. + * Presence online status for this account. */ - pj_str_t content_type; + pj_bool_t online_status; /** - * Optional message body. + * Buffer that is used internally to store the status text. */ - pj_str_t msg_body; + char buf_[PJ_ERR_MSG_SIZE]; + +} pjsua_acc_info; -} pjsua_msg_data; /** - * Initialize message data. + * Get number of current accounts. * - * @param msg_data Message data to be initialized. + * @return Current number of accounts. */ -PJ_INLINE(void) pjsua_msg_data_init(pjsua_msg_data *msg_data) -{ - pj_memset(msg_data, 0, sizeof(*msg_data)); - pj_list_init(&msg_data->hdr_list); -} +PJ_DECL(unsigned) pjsua_acc_get_count(void); -/***************************************************************************** - * PJSUA Core API +/** + * Check if the specified account ID is valid. + * + * @param acc_id Account ID to check. + * + * @return Non-zero if account ID is valid. */ +PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id); /** - * Instantiate pjsua application. Application must call this function before - * calling any other functions, to make sure that the underlying libraries - * are properly initialized. Once this function has returned success, - * application must call pjsua_destroy() before quitting. + * Add a new account to pjsua. PJSUA must have been initialized (with + * #pjsua_init()) before calling this function. + * + * @param cfg Account configuration. + * @param is_default If non-zero, this account will be set as the default + * account. The default account will be used when sending + * outgoing requests (e.g. making call) when no account is + * specified, and when receiving incoming requests when the + * request does not match any accounts. It is recommended + * that default account is set to local/LAN account. + * @param p_acc_id Pointer to receive account ID of the new account. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_create(void); +PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg, + pj_bool_t is_default, + pjsua_acc_id *p_acc_id); /** - * Initialize pjsua with the specified settings. All the settings are - * optional, and the default values will be used when the config is not - * specified. + * Add a local account. A local account is used to identify local endpoint + * instead of a specific user, and for this reason, a transport ID is needed + * to obtain the local address information. * - * @param ua_cfg User agent configuration. - * @param log_cfg Optional logging configuration. - * @param media_cfg Optional media configuration. + * @param tid Transport ID to generate account address. + * @param is_default If non-zero, this account will be set as the default + * account. The default account will be used when sending + * outgoing requests (e.g. making call) when no account is + * specified, and when receiving incoming requests when the + * request does not match any accounts. It is recommended + * that default account is set to local/LAN account. + * @param p_acc_id Pointer to receive account ID of the new account. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg, - const pjsua_logging_config *log_cfg, - const pjsua_media_config *media_cfg); - +PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid, + pj_bool_t is_default, + pjsua_acc_id *p_acc_id); /** - * Application is recommended to call this function after all initialization - * is done, so that the library can do additional checking set up - * additional + * Delete account. + * + * @param acc_id Id of the account to be deleted. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_start(void); +PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id); /** - * Destroy pjsua. This function must be called once PJSUA is created. To - * make it easier for application, application may call this function - * several times with no danger. + * Modify account information. + * + * @param acc_id Id of the account to be modified. + * @param cfg New account configuration. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_destroy(void); +PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id, + const pjsua_acc_config *cfg); /** - * Poll pjsua for events, and if necessary block the caller thread for - * the specified maximum interval (in miliseconds). + * Modify account's presence status to be advertised to remote/presence + * subscribers. * - * @param msec_timeout Maximum time to wait, in miliseconds. + * @param acc_id The account ID. + * @param is_online True of false. * - * @return The number of events that have been handled during the - * poll. Negative value indicates error, and application - * can retrieve the error as (err = -return_value). + * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout); +PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, + pj_bool_t is_online); /** - * Create memory pool. + * Update registration or perform unregistration. * - * @param name Optional pool name. - * @param size Initial size of the pool. - * @param increment Increment size. + * @param acc_id The account ID. + * @param renew If renew argument is zero, this will start + * unregistration process. * - * @return The pool, or NULL when there's no memory. + * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size, - pj_size_t increment); +PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, + pj_bool_t renew); /** - * Application can call this function at any time (after pjsua_create(), of - * course) to change logging settings. + * Get account information. * - * @param c Logging configuration. + * @param acc_id Account identification. + * @param info Pointer to receive account information. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c); - +PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id, + pjsua_acc_info *info); -/** - * Internal function to get SIP endpoint instance of pjsua, which is - * needed for example to register module, create transports, etc. - * Probably is only valid after #pjsua_init() is called. - * - * @return SIP endpoint instance. - */ -PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void); /** - * Internal function to get media endpoint instance. - * Only valid after #pjsua_init() is called. + * Enum accounts all account ids. * - * @return Media endpoint instance. + * @param ids Array of account IDs to be initialized. + * @param count In input, specifies the maximum number of elements. + * On return, it contains the actual number of elements. + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); - +PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], + unsigned *count ); -/***************************************************************************** - * PJSUA SIP Transport API. - */ /** - * Create SIP transport. + * Enum accounts info. * - * @param type Transport type. - * @param cfg Transport configuration. - * @param p_id Optional pointer to receive transport ID. + * @param info Array of account infos to be initialized. + * @param count In input, specifies the maximum number of elements. + * On return, it contains the actual number of elements. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type, - const pjsua_transport_config *cfg, - pjsua_transport_id *p_id); +PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[], + unsigned *count ); + /** - * Register transport that has been created by application. + * This is an internal function to find the most appropriate account to + * used to reach to the specified URL. * - * @param tp Transport instance. - * @param p_id Optional pointer to receive transport ID. + * @param url The remote URL to reach. * - * @return PJ_SUCCESS on success, or the appropriate error code. + * @return Account id. */ -PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp, - pjsua_transport_id *p_id); +PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url); /** - * Enumerate all transports currently created in the system. + * This is an internal function to find the most appropriate account to be + * used to handle incoming calls. * - * @param id Array to receive transport ids. - * @param count In input, specifies the maximum number of elements. - * On return, it contains the actual number of elements. + * @param rdata The incoming request message. * - * @return PJ_SUCCESS on success, or the appropriate error code. + * @return Account id. */ -PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[], - unsigned *count ); +PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); + + + +/** + * @} + */ + + +/***************************************************************************** + * CALLS API + */ + + +/** + * @defgroup PJSUA_LIB_CALL Calls + * @ingroup PJSUA_LIB + * @brief Call manipulation. + * @{ + */ + +/** + * Max simultaneous calls. + */ +#ifndef PJSUA_MAX_CALLS +# define PJSUA_MAX_CALLS 32 +#endif + + + +/** + * Call media status. + */ +typedef enum pjsua_call_media_status +{ + PJSUA_CALL_MEDIA_NONE, + PJSUA_CALL_MEDIA_ACTIVE, + PJSUA_CALL_MEDIA_LOCAL_HOLD, + PJSUA_CALL_MEDIA_REMOTE_HOLD, +} pjsua_call_media_status; + + +/** + * Call info. + */ +typedef struct pjsua_call_info +{ + /** Call identification. */ + pjsua_call_id id; + + /** Initial call role (UAC == caller) */ + pjsip_role_e role; + + /** Local URI */ + pj_str_t local_info; + + /** Local Contact */ + pj_str_t local_contact; + + /** Remote URI */ + pj_str_t remote_info; + + /** Remote contact */ + pj_str_t remote_contact; + /** Dialog Call-ID string. */ + pj_str_t call_id; -/** - * Get information about transports. - * - * @param id Transport ID. - * @param info Pointer to receive transport info. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id, - pjsua_transport_info *info); + /** Call state */ + pjsip_inv_state state; + /** Text describing the state */ + pj_str_t state_text; -/** - * Disable a transport or re-enable it. By default transport is always - * enabled after it is created. Disabling a transport does not necessarily - * close the socket, it will only discard incoming messages and prevent - * the transport from being used to send outgoing messages. - * - * @param id Transport ID. - * @param enabled Non-zero to enable, zero to disable. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id, - pj_bool_t enabled); + /** Last status code heard, which can be used as cause code */ + pjsip_status_code last_status; + /** The reason phrase describing the status. */ + pj_str_t last_status_text; -/** - * Close the transport. If transport is forcefully closed, it will be - * immediately closed, and any pending transactions that are using the - * transport may not terminate properly. Otherwise, the system will wait - * until all transactions are closed while preventing new users from - * using the transport, and will close the transport when it is safe to - * do so. - * - * @param id Transport ID. - * @param force Non-zero to immediately close the transport. This - * is not recommended! - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, - pj_bool_t force ); + /** Call media status. */ + pjsua_call_media_status media_status; + /** Media direction */ + pjmedia_dir media_dir; -/***************************************************************************** - * PJSUA Media Transport. - */ + /** The conference port number for the call */ + pjsua_conf_port_id conf_slot; -/** - * Create UDP media transports for all the calls. This function creates - * one UDP media transport for each call. - * - * @param cfg Media transport configuration. The "port" field in the - * configuration is used as the start port to bind the - * sockets. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) -pjsua_media_transports_create(const pjsua_transport_config *cfg); + /** Up-to-date call connected duration (zero when call is not + * established) + */ + pj_time_val connect_duration; + /** Total call duration, including set-up time */ + pj_time_val total_duration; -/** - * Register custom media transports to be used by calls. There must - * enough media transports for all calls. - * - * @param tp The media transport array. - * @param count Number of elements in the array. This number MUST - * match the number of maximum calls configured when - * pjsua is created. - * @param auto_delete Flag to indicate whether the transports should be - * destroyed when pjsua is shutdown. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) -pjsua_media_transports_attach( pjsua_media_transport tp[], - unsigned count, - pj_bool_t auto_delete); + /** Internal */ + struct { + char local_info[128]; + char local_contact[128]; + char remote_info[128]; + char remote_contact[128]; + char call_id[128]; + char last_status_text[128]; + } buf_; +} pjsua_call_info; -/***************************************************************************** - * PJSUA Call API. - */ /** * Get maximum number of calls configured in pjsua. @@ -1327,7 +1442,6 @@ PJ_DECL(pj_status_t) pjsua_enum_calls(pjsua_call_id ids[], * Make outgoing call to the specified URI using the specified account. * * @param acc_id The account to be used. - * @param target URI to be put in the request URI. * @param dst_uri URI to be put in the To header (normally is the same * as the target URI). * @param options Options (must be zero at the moment). @@ -1564,182 +1678,118 @@ PJ_DECL(pj_status_t) pjsua_call_dump(pjsua_call_id call_id, unsigned maxlen, const char *indent); - -/***************************************************************************** - * PJSUA Account and Client Registration API. - */ - - -/** - * Get number of current accounts. - * - * @return Current number of accounts. - */ -PJ_DECL(unsigned) pjsua_acc_get_count(void); - - -/** - * Check if the specified account ID is valid. - * - * @param acc_id Account ID to check. - * - * @return Non-zero if account ID is valid. - */ -PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id); - - /** - * Add a new account to pjsua. PJSUA must have been initialized (with - * #pjsua_init()) before calling this function. - * - * @param cfg Account configuration. - * @param is_default If non-zero, this account will be set as the default - * account. The default account will be used when sending - * outgoing requests (e.g. making call) when no account is - * specified, and when receiving incoming requests when the - * request does not match any accounts. It is recommended - * that default account is set to local/LAN account. - * @param p_acc_id Pointer to receive account ID of the new account. - * - * @return PJ_SUCCESS on success, or the appropriate error code. + * @} */ -PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg, - pj_bool_t is_default, - pjsua_acc_id *p_acc_id); - -/** - * Add a local account. A local account is used to identify local endpoint - * instead of a specific user, and for this reason, a transport ID is needed - * to obtain the local address information. - * - * @param tid Transport ID to generate account address. - * @param is_default If non-zero, this account will be set as the default - * account. The default account will be used when sending - * outgoing requests (e.g. making call) when no account is - * specified, and when receiving incoming requests when the - * request does not match any accounts. It is recommended - * that default account is set to local/LAN account. - * @param p_acc_id Pointer to receive account ID of the new account. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid, - pj_bool_t is_default, - pjsua_acc_id *p_acc_id); -/** - * Delete account. - * - * @param acc_id Id of the account to be deleted. - * - * @return PJ_SUCCESS on success, or the appropriate error code. +/***************************************************************************** + * BUDDY API */ -PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id); /** - * Modify account information. - * - * @param acc_id Id of the account to be modified. - * @param cfg New account configuration. - * - * @return PJ_SUCCESS on success, or the appropriate error code. + * @defgroup PJSUA_LIB_BUDDY Buddy, Presence, and Instant Messaging + * @ingroup PJSUA_LIB + * @brief Buddy management, buddy's presence, and instant messaging. + * @{ */ -PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id, - const pjsua_acc_config *cfg); - /** - * Modify account's presence status to be advertised to remote/presence - * subscribers. - * - * @param acc_id The account ID. - * @param is_online True of false. - * - * @return PJ_SUCCESS on success, or the appropriate error code. + * Max buddies in buddy list. */ -PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, - pj_bool_t is_online); +#ifndef PJSUA_MAX_BUDDIES +# define PJSUA_MAX_BUDDIES 256 +#endif /** - * Update registration or perform unregistration. - * - * @param acc_id The account ID. - * @param renew If renew argument is zero, this will start - * unregistration process. - * - * @return PJ_SUCCESS on success, or the appropriate error code. + * Buddy configuration. */ -PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, - pj_bool_t renew); +typedef struct pjsua_buddy_config +{ + /** + * Buddy URL or name address. + */ + pj_str_t uri; + /** + * Specify whether presence subscription should start immediately. + */ + pj_bool_t subscribe; -/** - * Get account information. - * - * @param acc_id Account identification. - * @param info Pointer to receive account information. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id, - pjsua_acc_info *info); +} pjsua_buddy_config; /** - * Enum accounts all account ids. - * - * @param ids Array of account IDs to be initialized. - * @param count In input, specifies the maximum number of elements. - * On return, it contains the actual number of elements. - * - * @return PJ_SUCCESS on success, or the appropriate error code. + * Buddy's online status. */ -PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], - unsigned *count ); +typedef enum pjsua_buddy_status +{ + /** + * Online status is unknown (possibly because no presence subscription + * has been established). + */ + PJSUA_BUDDY_STATUS_UNKNOWN, + /** + * Buddy is known to be offline. + */ + PJSUA_BUDDY_STATUS_ONLINE, -/** - * Enum accounts info. - * - * @param info Array of account infos to be initialized. - * @param count In input, specifies the maximum number of elements. - * On return, it contains the actual number of elements. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[], - unsigned *count ); + /** + * Buddy is offline. + */ + PJSUA_BUDDY_STATUS_OFFLINE, +} pjsua_buddy_status; -/** - * This is an internal function to find the most appropriate account to - * used to reach to the specified URL. - * - * @param url The remote URL to reach. - * - * @return Account id. - */ -PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url); /** - * This is an internal function to find the most appropriate account to be - * used to handle incoming calls. - * - * @param rdata The incoming request message. - * - * @return Account id. + * Buddy info. */ -PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); +typedef struct pjsua_buddy_info +{ + /** + * The buddy ID. + */ + pjsua_buddy_id id; + + /** + * The full URI of the buddy, as specified in the configuration. + */ + pj_str_t uri; + /** + * Buddy's Contact, only available when presence subscription has + * been established to the buddy. + */ + pj_str_t contact; + /** + * Buddy's online status. + */ + pjsua_buddy_status status; + + /** + * Text to describe buddy's online status. + */ + pj_str_t status_text; + + /** + * Flag to indicate that we should monitor the presence information for + * this buddy (normally yes, unless explicitly disabled). + */ + pj_bool_t monitor_pres; + + /** + * Internal buffer. + */ + char buf_[256]; + +} pjsua_buddy_info; -/***************************************************************************** - * PJSUA Presence (pjsua_pres.c) - */ /** * Get total number of buddies. @@ -1826,10 +1876,6 @@ PJ_DECL(pj_status_t) pjsua_buddy_subscribe_pres(pjsua_buddy_id buddy_id, PJ_DECL(void) pjsua_pres_dump(pj_bool_t verbose); -/***************************************************************************** - * PJSUA Instant Messaging (pjsua_im.c) - */ - /** * The MESSAGE method (defined in pjsua_im.c) */ @@ -1881,9 +1927,215 @@ PJ_DECL(pj_status_t) pjsua_im_typing(pjsua_acc_id acc_id, +/** + * @} + */ + + /***************************************************************************** - * Conference bridge manipulation. + * MEDIA API + */ + + +/** + * @defgroup PJSUA_LIB_MEDIA Media + * @ingroup PJSUA_LIB + * @brief Media manipulation. + * @{ + * + * PJSUA has rather powerful media features, which are built around the + * PJMEDIA conference bridge. Basically, all media termination (such as + * calls, file players, file recorders, sound device, tone generators, etc) + * are terminated in the conference bridge, and application can manipulate + * the interconnection between these terminations freely. If more than + * one media terminations are terminated in the same slot, the conference + * bridge will mix the signal automatically. + * + * Application connects one media termination/slot to another by calling + * #pjsua_conf_connect() function. This will establish unidirectional + * media flow from the source termination to the sink termination. For + * example, to stream a WAV file to remote call, application may use + * the following steps: + * + \code + + pj_status_t stream_to_call( pjsua_call_id call_id ) + { + pjsua_player_id player_id; + + status = pjsua_player_create("mysong.wav", 0, NULL, &player_id); + if (status != PJ_SUCCESS) + return status; + + status = pjsua_conf_connect( pjsua_player_get_conf_port(), + pjsua_call_get_conf_port() ); + } + \endcode + * + * + * Other features of PJSUA media: + * - efficient N to M interconnections between media terminations. + * - media termination can be connected to itself to create loopback + * media. + * - the media termination may have different clock rates, and resampling + * will be done automatically by conference bridge. + * - media terminations may also have different frame time; the + * conference bridge will perform the necessary bufferring to adjust + * the difference between terminations. + * - interconnections are removed automatically when media termination + * is removed from the bridge. + * - sound device may be changed even when there are active media + * interconnections. + * - correctly report call's media quality (in #pjsua_call_dump()) from + * RTCP packet exchange. + */ + +/** + * Max ports in the conference bridge. + */ +#ifndef PJSUA_MAX_CONF_PORTS +# define PJSUA_MAX_CONF_PORTS 254 +#endif + + + +/** + * Media configuration. + */ +struct pjsua_media_config +{ + /** + * Clock rate to be applied to the conference bridge. + * If value is zero, default clock rate will be used (16KHz). + */ + unsigned clock_rate; + + /** + * Specify maximum number of media ports to be created in the + * conference bridge. Since all media terminate in the bridge + * (calls, file player, file recorder, etc), the value must be + * large enough to support all of them. However, the larger + * the value, the more computations are performed. + */ + unsigned max_media_ports; + + /** + * Specify whether the media manager should manage its own + * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created + * and at least one worker thread will be created too. If no, + * the RTP/RTCP sockets will share the same ioqueue as SIP sockets, + * and no worker thread is needed. + * + * Normally application would say yes here, unless it wants to + * run everything from a single thread. + */ + pj_bool_t has_ioqueue; + + /** + * Specify the number of worker threads to handle incoming RTP + * packets. A value of one is recommended for most applications. + */ + unsigned thread_cnt; + + +}; + + +/** + * Use this function to initialize media config. + * + * @param cfg The media config to be initialized. + */ +PJ_INLINE(void) pjsua_media_config_default(pjsua_media_config *cfg) +{ + pj_memset(cfg, 0, sizeof(*cfg)); + + cfg->clock_rate = 16000; + cfg->max_media_ports = 32; + cfg->has_ioqueue = PJ_TRUE; + cfg->thread_cnt = 1; +} + + + +/** + * Codec config. + */ +typedef struct pjsua_codec_info +{ + /** + * Codec unique identification. + */ + pj_str_t codec_id; + + /** + * Codec priority (integer 0-255). + */ + pj_uint8_t priority; + + /** + * Internal buffer. + */ + char buf_[32]; + +} pjsua_codec_info; + + +/** + * Conference port info. + */ +typedef struct pjsua_conf_port_info +{ + /** Conference port number. */ + pjsua_conf_port_id slot_id; + + /** Port name. */ + pj_str_t name; + + /** Clock rate. */ + unsigned clock_rate; + + /** Number of channels. */ + unsigned channel_count; + + /** Samples per frame */ + unsigned samples_per_frame; + + /** Bits per sample */ + unsigned bits_per_sample; + + /** Number of listeners in the array. */ + unsigned listener_cnt; + + /** Array of listeners (in other words, ports where this port is + * transmitting to. + */ + pjsua_conf_port_id listeners[PJSUA_MAX_CONF_PORTS]; + +} pjsua_conf_port_info; + + +/** + * This structure holds information about custom media transport to + * be registered to pjsua. */ +typedef struct pjsua_media_transport +{ + /** + * Media socket information containing the address information + * of the RTP and RTCP socket. + */ + pjmedia_sock_info skinfo; + + /** + * The media transport instance. + */ + pjmedia_transport *transport; + +} pjsua_media_transport; + + + /** * Get maxinum number of conference ports. @@ -1968,7 +2220,9 @@ PJ_DECL(pj_status_t) pjsua_conf_disconnect(pjsua_conf_port_id source, * the conference bridge. * * @param filename The filename to be played. Currently only - * WAV files are supported. + * WAV files are supported, and the WAV file MUST be + * formatted as 16bit PCM mono/single channel (any + * clock rate is supported). * @param options Options (currently zero). * @param user_data Arbitrary user data to be associated with the player. * @param p_id Pointer to receive player ID. @@ -2165,36 +2419,51 @@ PJ_DECL(pj_status_t) pjsua_codec_set_param( const pj_str_t *id, - -/***************************************************************************** - * Utilities. +/** + * Create UDP media transports for all the calls. This function creates + * one UDP media transport for each call. + * + * @param cfg Media transport configuration. The "port" field in the + * configuration is used as the start port to bind the + * sockets. * + * @return PJ_SUCCESS on success, or the appropriate error code. */ +PJ_DECL(pj_status_t) +pjsua_media_transports_create(const pjsua_transport_config *cfg); -/* - * Verify that valid SIP url is given. + +/** + * Register custom media transports to be used by calls. There must + * enough media transports for all calls. * - * @param c_url The URL, as NULL terminated string. + * @param tp The media transport array. + * @param count Number of elements in the array. This number MUST + * match the number of maximum calls configured when + * pjsua is created. + * @param auto_delete Flag to indicate whether the transports should be + * destroyed when pjsua is shutdown. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *c_url); +PJ_DECL(pj_status_t) +pjsua_media_transports_attach( pjsua_media_transport tp[], + unsigned count, + pj_bool_t auto_delete); /** - * Display error message for the specified error code. - * - * @param sender The log sender field. - * @param title Message title for the error. - * @param status Status code. + * @} */ -PJ_DECL(void) pjsua_perror(const char *sender, const char *title, - pj_status_t status); - PJ_END_DECL +/** + * @} + */ + + #endif /* __PJSUA_H__ */ -- cgit v1.2.3