diff options
42 files changed, 2129 insertions, 1456 deletions
diff --git a/pjlib/build/pjlib.dsp b/pjlib/build/pjlib.dsp index d4837679..be384e40 100644 --- a/pjlib/build/pjlib.dsp +++ b/pjlib/build/pjlib.dsp @@ -182,10 +182,6 @@ SOURCE=..\src\pj\ctype.c # End Source File
# Begin Source File
-SOURCE=..\src\pj\equeue_winnt.c
-# End Source File
-# Begin Source File
-
SOURCE=..\src\pj\errno.c
# End Source File
# Begin Source File
@@ -233,13 +229,6 @@ SOURCE=..\src\pj\ioqueue_common_abs.h # Begin Source File
SOURCE=..\src\pj\ioqueue_select.c
-
-!IF "$(CFG)" == "pjlib - Win32 Release"
-
-!ELSEIF "$(CFG)" == "pjlib - Win32 Debug"
-
-!ENDIF
-
# End Source File
# Begin Source File
diff --git a/pjlib/src/pj/equeue_winnt.c b/pjlib/src/pj/equeue_winnt.c deleted file mode 100644 index e7a20c47..00000000 --- a/pjlib/src/pj/equeue_winnt.c +++ /dev/null @@ -1,19 +0,0 @@ -/* $Id$ */ -/* - * Copyright (C)2003-2006 Benny Prijono <benny@prijono.org> - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ -#include <pj/equeue.h> diff --git a/pjsip/build/pjsip_core.dsp b/pjsip/build/pjsip_core.dsp index 3e5130bf..3d33540b 100644 --- a/pjsip/build/pjsip_core.dsp +++ b/pjsip/build/pjsip_core.dsp @@ -319,6 +319,10 @@ SOURCE=..\include\pjsip\sip_ua_layer.h # End Group
# Begin Source File
+SOURCE=..\docs\doxygen.h
+# End Source File
+# Begin Source File
+
SOURCE=..\include\pjsip.h
# End Source File
# End Group
diff --git a/pjsip/docs/doxygen.cfg b/pjsip/docs/doxygen.cfg index f1d26386..3edc5bfc 100644 --- a/pjsip/docs/doxygen.cfg +++ b/pjsip/docs/doxygen.cfg @@ -134,7 +134,7 @@ FULL_PATH_NAMES = NO # the path. It is allowed to use relative paths in the argument list.
#STRIP_FROM_PATH = "/cygdrive/e/project/bulukucing.org/pjsip/src"
-STRIP_FROM_PATH = "/c/project/bulukucing.org/pjsip/src"
+STRIP_FROM_PATH = "/c/project/pjproject/pjsip"
# The INTERNAL_DOCS tag determines if documentation
# that is typed after a \internal command is included. If the tag is set
@@ -346,7 +346,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = src/pjsip src/pjsip_mod_ua src/pjsip_simple src
+INPUT = docs include
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
@@ -474,7 +474,7 @@ COLS_IN_ALPHA_INDEX = 5 # The IGNORE_PREFIX tag can be used to specify one or more prefixes that
# should be ignored while generating the index headers.
-IGNORE_PREFIX =
+IGNORE_PREFIX = /c/project/pjproject/pjsip
#---------------------------------------------------------------------------
# configuration options related to the HTML output
@@ -495,19 +495,19 @@ HTML_OUTPUT = html # each generated HTML page (for example: .htm,.php,.asp). If it is left blank
# doxygen will generate files with .html extension.
-HTML_FILE_EXTENSION = .html
+HTML_FILE_EXTENSION = .htm
# The HTML_HEADER tag can be used to specify a personal HTML header for
# each generated HTML page. If it is left blank doxygen will generate a
# standard header.
-HTML_HEADER =
+HTML_HEADER = docs/header.html
# The HTML_FOOTER tag can be used to specify a personal HTML footer for
# each generated HTML page. If it is left blank doxygen will generate a
# standard footer.
-HTML_FOOTER =
+HTML_FOOTER = docs/footer.html
# The HTML_STYLESHEET tag can be used to specify a user defined cascading
# style sheet that is used by each HTML page. It can be used to
@@ -844,7 +844,6 @@ INCLUDE_FILE_PATTERNS = PREDEFINED = PJ_DECL(x)=x PJ_DEF(x)=x PJ_IDECL(x)=x \
-
PJ_IDEF(x)=x PJ_INLINE(x)=x
@@ -1010,37 +1009,3 @@ DOT_CLEANUP = YES SEARCHENGINE = NO
-# The CGI_NAME tag should be the name of the CGI script that
-# starts the search engine (doxysearch) with the correct parameters.
-# A script with this name will be generated by doxygen.
-
-CGI_NAME = search.cgi
-
-# The CGI_URL tag should be the absolute URL to the directory where the
-# cgi binaries are located. See the documentation of your http daemon for
-# details.
-
-CGI_URL =
-
-# The DOC_URL tag should be the absolute URL to the directory where the
-# documentation is located. If left blank the absolute path to the
-# documentation, with file:// prepended to it, will be used.
-
-DOC_URL =
-
-# The DOC_ABSPATH tag should be the absolute path to the directory where the
-# documentation is located. If left blank the directory on the local machine
-# will be used.
-
-DOC_ABSPATH =
-
-# The BIN_ABSPATH tag must point to the directory where the doxysearch binary
-# is installed.
-
-BIN_ABSPATH = /usr/local/bin/
-
-# The EXT_DOC_PATHS tag can be used to specify one or more paths to
-# documentation generated for other projects. This allows doxysearch to search
-# the documentation for these projects as well.
-
-EXT_DOC_PATHS =
diff --git a/pjsip/docs/doxygen.h b/pjsip/docs/doxygen.h new file mode 100644 index 00000000..d13ae200 --- /dev/null +++ b/pjsip/docs/doxygen.h @@ -0,0 +1,183 @@ +/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + +/** + * @file doxygen.h + * @brief PJSIP Doxygen's mainpage. + */ + +/*////////////////////////////////////////////////////////////////////////// */ +/* + INTRODUCTION PAGE + */ + +/** + + @mainpage PJSIP + + \n + \n + @section intro_sec Introduction + + PJSIP is an Open Source SIP prototol stack, designed to be very small in + footprint, have high performance, and very flexible. + + @subsection hist_sec History + + PJSIP has been actively developed since 2003, but its history goes well + beyond that. The author has been developing SIP stack since 1999 during + RFC 2543 era, and after several experimentation with different approaches + in the programming (the first stack actually was in C++!), and also with + the evolution of the SIP protocol itself, the current/third generation + of PJSIP (the 0.2.9 version is the second generation) can be considered + as pretty stable in term of design, and should + incorporate all design considerations (and implementation tricks!) that + have been learned over the years. Of course only time will tell if this + statement can still be held true in the future. + + + + + \n + \n + @section pjsipgetting_started Getting Started + + PJSIP consists of multiple levels of APIs, which each of them layered on + top of another. Because of this, new readers may find it a bit difficult + to find the place to start. + + In general, I think perhaps I can recommend two approaches on using PJSIP. + + + \n + @subsection getting_started_high Using PJSUA API + + @ref PJSUA_LIB wraps together all SIP components and media into a high level + API, suitable for creating typical SIP user agent applications. It + features easy to use API for: + - multiple client registration (accounts), + - high level SIP and media session (calls), + - buddy list, presence and instant messaging, + - powerful and very easy to use media manipulation, + + while maintaining some space for customization (custom SIP + transport, custom SIP media, etc.) needed by some types of applications. + @ref PJSUA_LIB is also aimed to be able to run on devices such as PDA + or mobile phones, by carefully allowing application to set the appropriate + threading strategy and memory limits (number of calls, media ports, etc.). + + However, @ref PJSUA_LIB may not be the most suitable API for some types + of applications, since it is directed towards an easy to use API. For + more more advanced use, you may better implement the application by using + PJSIP + PJMEDIA directly, as described below. + + + \n + @subsection getting_started_pjsip_pjmedia Using PJSIP and PJMEDIA Directly + + For the ultimate flexibility and power, using PJSIP and PJMEDIA directly + is the way to go. The drawback will be, of course, steeper learning curve. + + However, the following links may provide some useful information: + - <A HREF="/docs.htm">PJSIP Developer's Guide</A> PDF + document is the ultimate guide to understand PJSIP design concept. + - there are some samples in <A HREF="/cgi-bin/viewcvs.cgi/pjproject/trunk/pjsip-apps/src/samples/"> + <b>pjsip-apps/src/samples</b></A> directory. + - @ref PJSUA_LIB source code may also be useful to see how high level + API are implemented with PJSIP/PJMEDIA. + - and finally, you can always <b>Use the Source</b>! + + + + \n + \n + @section this_doc About This Document + + This document contains the reference information about PJSIP. For + more in-depth guide (and information in general), readers are + encouraged to read the <A HREF="/docs.htm"> + <b>PJSIP Developer's Guide</b></A> PDF document + which can be downloaded from http://www.pjsip.org/docs.htm. + + \n + @subsection doc_ver Version + + This document corresponds to PJSIP version 0.5.6. + + \n + @subsection doc_how_to_read How to Read This Document + + For main navigation, please go to <A HREF="modules.htm"><b>Modules</b></A> + link on top of this page. + + This document was generated with <A HREF="http://www.doxygen.org">Doxygen</A> + from PJSIP header files. + + + \n + \n + @section pjsip_toc Documentation Contents + + Click on <A HREF="modules.htm"><b>Modules</b></A> link on top of this page + to get the detailed table of contents. + + The following are top level sections in the <A HREF="modules.htm"> + <b>Modules</b></A>, as laid out in the following diagram: + + \image html pjsip-arch.jpg "Static Library Layout" + + Enumerating the static libraries from the bottom: + + - <A HREF="/pjlib/docs/main.htm">PJLIB</A>, is the platform abstraction + and framework library, on which all other libraries depend, + + - PJLIB-UTIL, provides auxiliary functions such as text scanning, + XML, and STUN, + + - PJMEDIA is the multimedia framework, + + - PJMEDIA-CODEC is the placeholder for media codecs, + + - @ref PJSIP_CORE (<b>PJSIP-CORE</b>) is the very core of the PJSIP library, + and contains the SIP @ref PJSIP_ENDPT, which is the owner/manager for all + SIP objects in the application, messaging elements, parsing, transport + management, module management, and stateless operations, and also + contains: + + - The @ref PJSIP_TRANSACT module inside <b>PJSIP-CORE</b> provides + stateful operation, and is the base for higher layer features such as + dialogs, + + - The @ref PJSIP_UA module inside <b>PJSIP-CORE</b> manages dialogs, and supports dialog + usages, + + - @ref PJSIP_SIMPLE (<b>PJSIP-SIMPLE</b>) provides the base SIP event framework + (which uses the common/base dialog framework) and implements presence + on top of it, and is also used by call transfer functions, + + - @ref PJSIP_HIGH_UA (<b>PJSIP-UA</b>) is the high level abstraction of INVITE sessions + (using the common/base dialog framework). This library also provides + SIP client registration and call transfer functionality, + + - and finally, @ref PJSUA_LIB (<b>PJSUA-LIB</b>) is the highest level of abstraction, + which wraps together all above functionalities into high level, easy to + use API. +*/ + + diff --git a/pjsip/docs/footer.html b/pjsip/docs/footer.html new file mode 100644 index 00000000..7e7b5529 --- /dev/null +++ b/pjsip/docs/footer.html @@ -0,0 +1,4 @@ + <!--#include virtual="/footer.html" -->
+
+</BODY>
+</HTML>
diff --git a/pjsip/docs/header.html b/pjsip/docs/header.html new file mode 100644 index 00000000..9faaf8d8 --- /dev/null +++ b/pjsip/docs/header.html @@ -0,0 +1,7 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
+<title>PJSIP - Open Source SIP, SIMPLE, Presence, IM Protocol Stack Documentation</title>
+<link href="/style/style.css" rel="stylesheet" type="text/css">
+</head><body>
+ <!--#include virtual="/header.html" -->
+
diff --git a/pjsip/docs/pjsip-arch.jpg b/pjsip/docs/pjsip-arch.jpg Binary files differnew file mode 100644 index 00000000..c591823e --- /dev/null +++ b/pjsip/docs/pjsip-arch.jpg 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 <pjsip/sip_msg.h> /** + * @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 <pjsip-simple/types.h> #include <pjlib-util/xml.h> +/** + * @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 <pjsip/sip_dialog.h> #include <pjmedia/sdp_neg.h> +/** + * @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 + * <A HREF="/docs.htm">PJSIP Developer's Guide</A> + * 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 <b>pjsip-ua</b> 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 <b>pjsip-ua</b> static library to use this API. + * + * More detailed information is explained in + * <A HREF="/docs.htm">PJSIP Developer's Guide</A> + * 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 <pjsip/sip_types.h> #include <pjsip/sip_auth.h> -//#include <pjsip/sip_ua.h> -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 <b>pjsip-ua</b> 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;/**<Number of contacts in response. */ + pjsip_contact_hdr *contact[PJSIP_REGC_MAX_CONTACT]; /**< Contacts. */ }; @@ -149,6 +153,7 @@ PJ_DECL(pj_pool_t*) pjsip_regc_get_pool(pjsip_regc *regc); * perform the registration. * * @param regc The client registration structure. + * @param srv_url Server URL. * @param from_url The person performing the registration, must be a SIP URL type. * @param to_url The address of record for which the registration is targetd, must * be a SIP/SIPS URL. @@ -259,4 +264,8 @@ PJ_DECL(pj_status_t) pjsip_regc_send(pjsip_regc *regc, pjsip_tx_data *tdata); PJ_END_DECL +/** + * @} + */ + #endif /* __PJSIP_REG_H__ */ diff --git a/pjsip/include/pjsip-ua/sip_xfer.h b/pjsip/include/pjsip-ua/sip_xfer.h index 16eb1956..56809141 100644 --- a/pjsip/include/pjsip-ua/sip_xfer.h +++ b/pjsip/include/pjsip-ua/sip_xfer.h @@ -28,6 +28,19 @@ #include <pjsip-simple/evsub.h> #include <pjsip/sip_msg.h> +/** + * @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 <b>pjsip-ua</b> AND <b>pjsip-simple</b> 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 @@ -29,17 +29,13 @@ 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,9 +19,44 @@ #ifndef __PJSIP_SIP_CONFIG_H__ #define __PJSIP_SIP_CONFIG_H__ +/** + * @file sip_config.h + * @brief Compile time configuration. + */ #include <pj/config.h> /** + * @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 <pj/config.h> 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 <pj/sock.h> #include <pj/assert.h> + +/** + * @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 <b>From</b> header, <b>To</b> header, <b>CSeq</b> + * sequencing, <b>Call-ID</b> header, <b>Contact</b> header management, + * dialog <b>route-set</b> management, and common <b>authentication</b>. + * This basic dialog functionality will be shared by all <b>dialog + * usages</b> of a particular dialog. + * + * More detailed information is explained in + * <A HREF="/docs.htm">PJSIP Developer's Guide</A> + * 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 <b>pjsip-core</b> 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 <pjsip/sip_transport.h> #include <pjsip/sip_resolve.h> -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. @@ -419,6 +419,11 @@ PJ_DECL(void) pjsip_endpt_dump( pjsip_endpoint *endpt, pj_bool_t detail ); /** + * @} + */ + + +/** * Log an error. */ PJ_DECL(void) pjsip_endpt_log_error( pjsip_endpoint *endpt, @@ -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/errno.h> 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 <pj/types.h> @@ -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 <A HREF="/docs.htm">PJSIP Developer's Guide</A> + * 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,18 +1117,9 @@ 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. */ typedef struct pjsip_clen_hdr @@ -1197,18 +1154,8 @@ 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. */ typedef struct pjsip_cseq_hdr @@ -1243,18 +1190,8 @@ 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 * multiple URI in the Contact header, the URI will be put in separate Contact @@ -1296,18 +1233,9 @@ 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. */ typedef struct pjsip_ctype_hdr @@ -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,18 +1305,9 @@ 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. */ typedef struct pjsip_fromto_hdr @@ -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,26 +1465,16 @@ 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. */ 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,19 +1669,8 @@ 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. * If a message arrives with multiple elements in a single Via, then they will @@ -1865,19 +1711,8 @@ 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 * header. @@ -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 <pjsip/sip_types.h> -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 <pjsip/sip_uri.h> +/** + * @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 <b>pjsip-core</b> 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 + * <A HREF="/docs.htm">PJSIP Developer's Guide</A> 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 <pjsip/sip_transport.h> +/** + * @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 <benny@prijono.org> * @@ -19,11 +19,25 @@ #ifndef __PJSIP_TRANSPORT_UDP_H__ #define __PJSIP_TRANSPORT_UDP_H__ +/** + * @file sip_transport_udp.h + * @brief SIP UDP Transport. + */ + #include <pjsip/sip_transport.h> 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. * * @param endpt The SIP endpoint. @@ -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 <pjsip/sip_config.h> #include <pj/types.h> /** - * 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 <b>pjsip-core</b> + * 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 <b>pjsip-core</b> 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. * @{ */ @@ -119,6 +125,17 @@ PJ_DECL(pj_ssize_t) pjsip_param_print_on(const pjsip_param *param_list, int sep); /** + * @} + */ + +/** + * @defgroup PJSIP_URI_GENERIC Generic URI + * @ingroup PJSIP_URI + * @brief Generic representation for all types of URI. + * @{ + */ + +/** * URI context. */ typedef enum pjsip_uri_context_e @@ -222,45 +239,6 @@ struct pjsip_uri /** - * 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. * @return the URI scheme. @@ -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 <pjsip.h> @@ -41,64 +47,138 @@ #include <pjlib.h> +/** + * @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 <b>pjsua-lib</b> to use this API. In addition, + * this library depends on the following libraries: + * - <b>pjsip-ua</b>, + * - <b>pjsip-simple</b>, + * - <b>pjsip-core</b>, + * - <b>pjmedia</b>, + * - <b>pjmedia-codec</b>, + * - <b>pjlib-util</b>, and + * - <b>pjlib</b>, + * + * 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,400 +193,13 @@ 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) - - - -/** - * 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; - - /** - * 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; - - /** - * 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; - - /** - * Number of proxies in the proxy array below. - */ - unsigned proxy_cnt; - - /** - * 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]; - - /** - * Optional interval for registration, in seconds. If the value is zero, - * default interval will be used (PJSUA_REG_INTERVAL, 55 seconds). - */ - unsigned reg_timeout; - - /** - * 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; - - -/** - * Call this function to initialize account config with default values. - * - * @param cfg The account config to be initialized. - */ -PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg) -{ - pj_memset(cfg, 0, sizeof(*cfg)); - - cfg->reg_timeout = PJSUA_REG_INTERVAL; -} - - - -/** - * Account info. Application can query account info by calling - * #pjsua_acc_get_info(). - */ -typedef struct pjsua_acc_info -{ - /** - * The account ID. - */ - pjsua_acc_id id; - - /** - * Flag to indicate whether this is the default account. - */ - pj_bool_t is_default; - - /** - * 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; - - /** - * String describing the registration status. - */ - pj_str_t status_text; - - /** - * Presence online status for this account. - */ - pj_bool_t online_status; - - /** - * Buffer that is used internally to store the status text. - */ - char buf_[PJ_ERR_MSG_SIZE]; - -} pjsua_acc_info; - - - -/** - * STUN configuration. - */ -typedef struct pjsua_stun_config -{ - /** - * The first STUN server IP address or hostname. - */ - pj_str_t stun_srv1; - - /** - * 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. - */ - pj_str_t stun_srv2; - - /** - * Port number of the second STUN server. - * If zero, default STUN port will be used. - */ - unsigned stun_port2; - -} pjsua_stun_config; - - - -/** - * Call this function to initialize STUN config with default values. - * - * @param cfg The STUN config to be initialized. - */ -PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg) -{ - pj_memset(cfg, 0, sizeof(*cfg)); -} - - -/** - * 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. - */ - unsigned port; - - /** - * Optional address where the socket should be bound. - */ - pj_in_addr ip_addr; - - /** - * Flag to indicate whether STUN should be used. - */ - pj_bool_t use_stun; - - /** - * STUN configuration, must be specified when STUN is used. - */ - pjsua_stun_config stun_config; - -} pjsua_transport_config; - - -/** - * Call this function to initialize UDP config with default values. - * - * @param cfg The UDP config to be initialized. - */ -PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg) -{ - pj_memset(cfg, 0, sizeof(*cfg)); -} - - -/** - * Normalize STUN config. - */ -PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg ) -{ - 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; - } - - } else { - cfg->stun_port1 = 0; - cfg->stun_srv2.slen = 0; - cfg->stun_port2 = 0; - } -} - - -/** - * Duplicate transport config. - */ -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 -{ - /** - * PJSUA transport identification. - */ - pjsua_transport_id id; - - /** - * Transport type. - */ - pjsip_transport_type_e type; - - /** - * Transport type name. - */ - pj_str_t type_name; - - /** - * Transport string info/description. - */ - pj_str_t info; - - /** - * Transport flag (see ##pjsip_transport_flags_e). - */ - unsigned flag; - - /** - * Local address length. - */ - unsigned addr_len; - - /** - * 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; - - -} pjsua_transport_info; - - -/** - * Media configuration. - */ -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; - - -} pjsua_media_config; - /** - * Use this function to initialize media config. - * - * @param cfg The media config to be initialized. + * Maximum proxies in account. */ -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; -} +#ifndef PJSUA_ACC_MAX_PROXIES +# define PJSUA_ACC_MAX_PROXIES 8 +#endif @@ -583,116 +276,6 @@ PJ_INLINE(void) pjsua_logging_config_dup(pj_pool_t *pool, } -/** - * Buddy configuration. - */ -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; - - -/** - * Buddy's online status. - */ -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, - - /** - * Buddy is offline. - */ - PJSUA_BUDDY_STATUS_OFFLINE, - -} pjsua_buddy_status; - - - -/** - * Buddy info. - */ -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; - - -/** - * 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; - /** * Application callbacks. @@ -888,141 +471,6 @@ PJ_INLINE(void) pjsua_config_dup(pj_pool_t *pool, } -/** - * 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; - - /** Call state */ - pjsip_inv_state state; - - /** 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; - - /** The reason phrase describing the status. */ - pj_str_t last_status_text; - - /** Call media status. */ - pjsua_call_media_status media_status; - - /** Media direction */ - pjmedia_dir media_dir; - - /** The conference port number for the call */ - pjsua_conf_port_id conf_slot; - - /** 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; - - /** 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; - - - - -/** - * 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; - /** * This structure describes additional information to be sent with @@ -1060,10 +508,6 @@ PJ_INLINE(void) pjsua_msg_data_init(pjsua_msg_data *msg_data) } -/***************************************************************************** - * PJSUA Core API - */ - /** * Instantiate pjsua application. Application must call this function before @@ -1129,7 +573,7 @@ PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout); * Create memory pool. * * @param name Optional pool name. - * @param size Initial size of the pool. + * @param init_size Initial size of the pool. * @param increment Increment size. * * @return The pool, or NULL when there's no memory. @@ -1168,8 +612,247 @@ PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); /***************************************************************************** - * PJSUA SIP Transport API. + * Utilities. + * + */ + +/** + * 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); + + +/** + * 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); + + + + +/** + * @} + */ + + + +/***************************************************************************** + * TRANSPORT API + */ + +/** + * @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. + */ + + +/** SIP transport identification */ +typedef int pjsua_transport_id; + + +/** + * STUN configuration. + */ +typedef struct pjsua_stun_config +{ + /** + * The first STUN server IP address or hostname. + */ + pj_str_t stun_srv1; + + /** + * 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. + */ + pj_str_t stun_srv2; + + /** + * Port number of the second STUN server. + * If zero, default STUN port will be used. + */ + unsigned stun_port2; + +} pjsua_stun_config; + + + +/** + * Call this function to initialize STUN config with default values. + * + * @param cfg The STUN config to be initialized. + */ +PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg) +{ + pj_memset(cfg, 0, sizeof(*cfg)); +} + + +/** + * 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. + */ + unsigned port; + + /** + * Optional address where the socket should be bound. + */ + pj_in_addr ip_addr; + + /** + * Flag to indicate whether STUN should be used. + */ + pj_bool_t use_stun; + + /** + * STUN configuration, must be specified when STUN is used. + */ + pjsua_stun_config stun_config; + +} pjsua_transport_config; + + +/** + * Call this function to initialize UDP config with default values. + * + * @param cfg The UDP config to be initialized. + */ +PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg) +{ + pj_memset(cfg, 0, sizeof(*cfg)); +} + + +/** + * Normalize STUN config. + */ +PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg ) +{ + 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; + } + + } else { + cfg->stun_port1 = 0; + cfg->stun_srv2.slen = 0; + cfg->stun_port2 = 0; + } +} + + +/** + * Duplicate transport config. + */ +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 +{ + /** + * PJSUA transport identification. + */ + pjsua_transport_id id; + + /** + * Transport type. + */ + pjsip_transport_type_e type; + + /** + * Transport type name. + */ + pj_str_t type_name; + + /** + * Transport string info/description. + */ + pj_str_t info; + + /** + * Transport flag (see ##pjsip_transport_flags_e). + */ + unsigned flag; + + /** + * Local address length. + */ + unsigned addr_len; + + /** + * 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; + + +} pjsua_transport_info; + /** * Create SIP transport. @@ -1253,48 +936,480 @@ PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id, PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, pj_bool_t force ); +/** + * @} + */ + + + /***************************************************************************** - * PJSUA Media Transport. + * ACCOUNT API */ + /** - * Create UDP media transports for all the calls. This function creates - * one UDP media transport for each call. + * @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. * - * @param cfg Media transport configuration. The "port" field in the - * configuration is used as the start port to bind the - * sockets. + * Account may or may not have client registration associated with it. + * An account is also associated with <b>route set</b> and some <b>authentication + * credentials</b>, which are used when sending SIP request messages using the + * account. An account also has presence's <b>online status</b>, 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 <b>default account</b>, 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. + */ + +/** + * Maximum accounts. + */ +#ifndef PJSUA_MAX_ACC +# define PJSUA_MAX_ACC 8 +#endif + + +/** + * Default registration interval. + */ +#ifndef PJSUA_REG_INTERVAL +# define PJSUA_REG_INTERVAL 55 +#endif + + +/** + * 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; + + /** + * 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; + + /** + * 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; + + /** + * Number of proxies in the proxy array below. + */ + unsigned proxy_cnt; + + /** + * 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]; + + /** + * Optional interval for registration, in seconds. If the value is zero, + * default interval will be used (PJSUA_REG_INTERVAL, 55 seconds). + */ + unsigned reg_timeout; + + /** + * 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; + + +/** + * Call this function to initialize account config with default values. + * + * @param cfg The account config to be initialized. + */ +PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg) +{ + pj_memset(cfg, 0, sizeof(*cfg)); + + cfg->reg_timeout = PJSUA_REG_INTERVAL; +} + + + +/** + * Account info. Application can query account info by calling + * #pjsua_acc_get_info(). + */ +typedef struct pjsua_acc_info +{ + /** + * The account ID. + */ + pjsua_acc_id id; + + /** + * Flag to indicate whether this is the default account. + */ + pj_bool_t is_default; + + /** + * 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; + + /** + * String describing the registration status. + */ + pj_str_t status_text; + + /** + * Presence online status for this account. + */ + pj_bool_t online_status; + + /** + * Buffer that is used internally to store the status text. + */ + char buf_[PJ_ERR_MSG_SIZE]; + +} pjsua_acc_info; + + + +/** + * 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_media_transports_create(const pjsua_transport_config *cfg); +PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg, + pj_bool_t is_default, + pjsua_acc_id *p_acc_id); /** - * Register custom media transports to be used by calls. There must - * enough media transports for all calls. + * 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 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. + * @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_media_transports_attach( pjsua_media_transport tp[], - unsigned count, - pj_bool_t auto_delete); +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. + */ +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. + */ +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. + */ +PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, + pj_bool_t is_online); +/** + * 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. + */ +PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, + pj_bool_t renew); + + +/** + * 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); + + +/** + * 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. + */ +PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], + unsigned *count ); + + +/** + * 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 ); + + +/** + * 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. + */ +PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); + + + +/** + * @} + */ + /***************************************************************************** - * PJSUA Call API. + * 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; + + /** Call state */ + pjsip_inv_state state; + + /** 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; + + /** The reason phrase describing the status. */ + pj_str_t last_status_text; + + /** Call media status. */ + pjsua_call_media_status media_status; + + /** Media direction */ + pjmedia_dir media_dir; + + /** The conference port number for the call */ + pjsua_conf_port_id conf_slot; + + /** 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; + + /** 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; + + /** * 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. +/***************************************************************************** + * BUDDY API */ -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. + * @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_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. + * Max buddies in buddy list. */ -PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id); +#ifndef PJSUA_MAX_BUDDIES +# define PJSUA_MAX_BUDDIES 256 +#endif /** - * 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. + * Buddy configuration. */ -PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id, - const pjsua_acc_config *cfg); +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; -/** - * 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. - */ -PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, - pj_bool_t is_online); +} pjsua_buddy_config; /** - * 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's online status. */ -PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, - pj_bool_t renew); +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, -/** - * 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); + /** + * Buddy is offline. + */ + PJSUA_BUDDY_STATUS_OFFLINE, +} pjsua_buddy_status; -/** - * 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. - */ -PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], - unsigned *count ); /** - * 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. + * Buddy info. */ -PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[], - unsigned *count ); +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; -/** - * 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); + /** + * 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; -/** - * 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. - */ -PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); + /** + * 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 <b>unidirectional</b> + * 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__ */ diff --git a/pjsip/src/pjsip/sip_parser.c b/pjsip/src/pjsip/sip_parser.c index 2272cd37..41be6926 100644 --- a/pjsip/src/pjsip/sip_parser.c +++ b/pjsip/src/pjsip/sip_parser.c @@ -97,7 +97,7 @@ const pj_str_t pjsip_SIPS_STR = { "sips", 4 }; const pj_str_t pjsip_TEL_STR = { "tel", 3 }; const pj_str_t pjsip_BRANCH_STR = { "branch", 6 }; const pj_str_t pjsip_TTL_STR = { "ttl", 3 }; -const pj_str_t pjsip_PNAME_STR = { "received", 8 }; +const pj_str_t pjsip_RECEIVED_STR = { "received", 8 }; const pj_str_t pjsip_Q_STR = { "q", 1 }; const pj_str_t pjsip_EXPIRES_STR = { "expires", 7 }; const pj_str_t pjsip_TAG_STR = { "tag", 3 }; @@ -1656,7 +1656,7 @@ static void int_parse_via_param( pjsip_via_hdr *hdr, pj_scanner *scanner, } else if (!parser_stricmp(pname, pjsip_MADDR_STR) && pvalue.slen) { hdr->maddr_param = pvalue; - } else if (!parser_stricmp(pname, pjsip_PNAME_STR) && pvalue.slen) { + } else if (!parser_stricmp(pname, pjsip_RECEIVED_STR) && pvalue.slen) { hdr->recvd_param = pvalue; } else if (!parser_stricmp(pname, pjsip_RPORT_STR)) { |
