diff options
author | Benny Prijono <bennylp@teluu.com> | 2008-01-25 16:06:33 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2008-01-25 16:06:33 +0000 |
commit | d583515e9daac73925c0cb1f617aa124666e5b34 (patch) | |
tree | c3c741cc68ecba2e1f414dee164d3c8e9a4e1a03 /pjmedia | |
parent | 1357c18f2e4cb7f2d9bddf1afb3603991b5ca08b (diff) |
Fixed doxygen comments everywhere
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@1748 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjmedia')
-rw-r--r-- | pjmedia/docs/doxygen.cfg | 11 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/transport.h | 60 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/transport_srtp.h | 54 | ||||
-rw-r--r-- | pjmedia/src/pjmedia/transport_udp.c | 1 |
4 files changed, 118 insertions, 8 deletions
diff --git a/pjmedia/docs/doxygen.cfg b/pjmedia/docs/doxygen.cfg index 50f8f201..e2fa0889 100644 --- a/pjmedia/docs/doxygen.cfg +++ b/pjmedia/docs/doxygen.cfg @@ -843,8 +843,15 @@ INCLUDE_FILE_PATTERNS = PREDEFINED = PJ_DECL(x)=x PJ_DEF(x)=x PJ_IDECL(x)=x \
PJ_IDEF(x)=x PJ_INLINE(x)=x \
- PJ_BEGIN_DECL= PJ_END_DECL= \
- PJMEDIA_HAS_MP3_WRITER=1
+ PJ_DECL_DATA(x)=x \
+ PJ_DECL_NO_RETURN(x)=x \
+ PJ_NO_RETURN=x \
+ PJ_HAS_HIGH_RES_TIMER=1 \
+ PJ_LOG_MAX_LEVEL=4 \
+ PJ_HAS_SEMAPHORE=1 \
+ PJ_HAS_EVENT_OBJ=1 \
+ PJ_HAS_TCP=1 \
+ PJMEDIA_HAS_SRTP=1
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
diff --git a/pjmedia/include/pjmedia/transport.h b/pjmedia/include/pjmedia/transport.h index e9fbb1f3..14b84e7d 100644 --- a/pjmedia/include/pjmedia/transport.h +++ b/pjmedia/include/pjmedia/transport.h @@ -56,6 +56,12 @@ * so it should not need to call the function pointer inside * #pjmedia_transport_op directly. * + * The connection between \ref PJMED_STRM and media transport is shown in + * the diagram below: + + \image html media-transport.PNG + + * \section PJMEDIA_TRANSPORT_H_USING Using the Media Transport * * The media transport's life-cycle normally follows the following stages. @@ -135,6 +141,39 @@ * all resources used by the transport, such as sockets and memory. * * + * \section PJMEDIA_TRANSPORT_H_EXT Media Transport Extended API + + Apart from the basic interface above, the media transport provides some + more APIs: + + - pjmedia_transport_media_create() + \n + This API is provided to allow the media transport to add more information + in the SDP offer, before the offer is sent to remote. Additionally, for + answerer side, this callback allows the media transport to reject the + offer before this offer is processed by the SDP negotiator. + + - pjmedia_transport_media_start() + \n + This API should be called after offer and answer are negotiated, and + both SDPs are available, and before the media is started. For answerer + side, this callback will be called before the answer is sent to remote, + to allow media transport to put additional info in the SDP. For + offerer side, this callback will be called after SDP answer is + received. In this callback, the media transport has the final chance + to negotiate/validate the offer and answer before media is really + started (and answer is sent, for answerer side). + + - pjmedia_transport_media_stop() + \n + This API should be called when the media is stopped, to allow the media + transport to release its resources. + + - pjmedia_transport_simulate_lost() + \n + This API can be used to instruct media transport to simulate packet lost + on a particular direction. + * \section PJMEDIA_TRANSPORT_H_IMPL Implementing Media Transport * * To implement a new type of media transport, one needs to "subclass" the @@ -168,7 +207,7 @@ PJ_BEGIN_DECL #include <pjmedia/sdp.h> -/* +/** * Forward declaration for media transport. */ typedef struct pjmedia_transport pjmedia_transport; @@ -458,6 +497,12 @@ PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp(pjmedia_transport *tp, * Generate local SDP parts that are related to the specified media transport. * Remote SDP might be needed as reference when application is in deciding * side of negotiation (callee side), otherwise it should be NULL. + * + * This API is provided to allow the media transport to add more information + * in the SDP offer, before the offer is sent to remote. Additionally, for + * answerer side, this callback allows the media transport to reject the + * offer before this offer is processed by the SDP negotiator. + * * This is just a simple wrapper which calls <tt>media_create()</tt> member * of the transport. * @@ -465,6 +510,7 @@ PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp(pjmedia_transport *tp, * @param pool The memory pool. * @param sdp_local Local SDP. * @param sdp_remote Remote SDP. + * @param media_index Media index in SDP. * * @return PJ_SUCCESS on success, or the appropriate error code. */ @@ -480,6 +526,15 @@ PJ_INLINE(pj_status_t) pjmedia_transport_media_create(pjmedia_transport *tp, /** * Start the transport with regards to SDP negotiation result. + * This API should be called after offer and answer are negotiated, and + * both SDPs are available, and before the media is started. For answerer + * side, this callback will be called before the answer is sent to remote, + * to allow media transport to put additional info in the SDP. For + * offerer side, this callback will be called after SDP answer is + * received. In this callback, the media transport has the final chance + * to negotiate/validate the offer and answer before media is really + * started (and answer is sent, for answerer side). + * * This is just a simple wrapper which calls <tt>media_start()</tt> member * of the transport. * @@ -503,6 +558,9 @@ PJ_INLINE(pj_status_t) pjmedia_transport_media_start(pjmedia_transport *tp, /** * Stop the transport. + * This API should be called when the media is stopped, to allow the media + * transport to release its resources. + * * This is just a simple wrapper which calls <tt>media_stop()</tt> member * of the transport. * diff --git a/pjmedia/include/pjmedia/transport_srtp.h b/pjmedia/include/pjmedia/transport_srtp.h index f7ea291d..d6ccc2e1 100644 --- a/pjmedia/include/pjmedia/transport_srtp.h +++ b/pjmedia/include/pjmedia/transport_srtp.h @@ -21,12 +21,52 @@ /** * @file srtp.h - * @brief transport SRTP encapsulates secure media transport. + * @brief Secure RTP (SRTP) transport. */ #include <pjmedia/transport.h> +/** + * @defgroup PJMEDIA_TRANSPORT_SRTP Secure RTP (SRTP) Transport Adapter + * @ingroup PJMEDIA_TRANSPORT + * @brief Media transport adapter to add SRTP feature to existing transports + * @{ + * + * This module implements SRTP as described by RFC 3711, using RFC 4568 as + * key exchange method. It implements \ref PJMEDIA_TRANSPORT_H to integrate + * with the rest of PJMEDIA framework. + * + * As we know, media transport is separated from the stream object (which + * does the encoding/decoding of PCM frames, (de)packetization of RTP/RTCP + * packets, and de-jitter buffering). The connection between stream and media + * transport is established when the stream is created (we need to specify + * media transport during stream creation), and the interconnection can be + * depicted from the diagram below: + * + \image html media-transport.PNG + + * I think the diagram above is self-explanatory. + * + * SRTP functionality is implemented as some kind of "adapter", which is + * plugged between the stream and the actual media transport that does + * sending/receiving RTP/RTCP packets. When SRTP is used, the interconnection + * between stream and transport is like the diagram below: + * + \image html media-srtp-transport.PNG + + * So to stream, the SRTP transport behaves as if it is a media transport + * (because it is a media transport), and to the media transport it behaves + * as if it is a stream. The SRTP object then forwards RTP packets back and + * forth between stream and the actual transport, encrypting/decrypting + * the RTP/RTCP packets as necessary. + * + * The neat thing about this design is the SRTP "adapter" then can be used + * to encrypt any kind of media transports. We currently have UDP and ICE + * media transports that can benefit SRTP, and we could add SRTP to any + * media transports that will be added in the future. + */ + PJ_BEGIN_DECL @@ -55,7 +95,7 @@ typedef struct pjmedia_srtp_crypto /** Crypto name. */ pj_str_t name; - /* Flags, bitmask from #pjmedia_srtp_crypto_option */ + /** Flags, bitmask from #pjmedia_srtp_crypto_option */ unsigned flags; } pjmedia_srtp_crypto; @@ -168,7 +208,7 @@ PJ_DECL(pj_status_t) pjmedia_transport_srtp_create( * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjmedia_transport_srtp_start( - pjmedia_transport *tp, + pjmedia_transport *srtp, const pjmedia_srtp_crypto *tx, const pjmedia_srtp_crypto *rx); @@ -181,7 +221,7 @@ PJ_DECL(pj_status_t) pjmedia_transport_srtp_start( * * @see #pjmedia_transport_srtp_start() */ -PJ_DECL(pj_status_t) pjmedia_transport_srtp_stop(pjmedia_transport *tp); +PJ_DECL(pj_status_t) pjmedia_transport_srtp_stop(pjmedia_transport *srtp); /** @@ -192,9 +232,13 @@ PJ_DECL(pj_status_t) pjmedia_transport_srtp_stop(pjmedia_transport *tp); * @return member media transport. */ PJ_DECL(pjmedia_transport*) pjmedia_transport_srtp_get_member( - pjmedia_transport *tp); + pjmedia_transport *srtp); PJ_END_DECL +/** + * @} + */ + #endif /* __PJMEDIA_TRANSPORT_SRTP_H__ */ diff --git a/pjmedia/src/pjmedia/transport_udp.c b/pjmedia/src/pjmedia/transport_udp.c index a9a4df70..3caea680 100644 --- a/pjmedia/src/pjmedia/transport_udp.c +++ b/pjmedia/src/pjmedia/transport_udp.c @@ -748,6 +748,7 @@ static pj_status_t transport_media_create(pjmedia_transport *tp, PJ_UNUSED_ARG(pool); PJ_UNUSED_ARG(sdp_local); PJ_UNUSED_ARG(sdp_remote); + PJ_UNUSED_ARG(media_index); return PJ_SUCCESS; } |