doxygen comments for SDP and TLS

This commit is contained in:
Richard Aas 2012-04-11 13:24:07 +00:00
parent 0f4e572462
commit 78241d4a60
12 changed files with 441 additions and 5 deletions

View file

@ -9,6 +9,7 @@ enum {
SDP_VERSION = 0
};
/** SDP Direction */
enum sdp_dir {
SDP_INACTIVE = 0,
SDP_RECVONLY = 1,
@ -36,6 +37,7 @@ typedef bool(sdp_fmtp_cmp_h)(const char *params1, const char *params2,
typedef bool(sdp_format_h)(struct sdp_format *fmt, void *arg);
typedef bool(sdp_attr_h)(const char *name, const char *value, void *arg);
/** SDP Format */
struct sdp_format {
struct le le;
char *id;

View file

@ -91,11 +91,9 @@ EXCLUDE = test.c \
include/re_bitv.h \
src/md5/md5.h src/md5/md5.c \
src/dns include/re_dns.h \
src/sdp include/re_sdp.h \
src/sip/ include/re_sip.h \
src/sipsess/ include/re_sipsess.h \
src/stun include/re_stun.h \
src/tls include/re_tls.h
src/stun include/re_stun.h
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS = */.svn/*

View file

@ -30,6 +30,23 @@ static void destructor(void *arg)
}
/**
* Add an SDP Format to an SDP Media line
*
* @param fmtp Pointer to allocated SDP Format
* @param m SDP Media line
* @param prepend True to prepend, False to append
* @param id Format identifier
* @param name Format name
* @param srate Sampling rate
* @param ch Number of channels
* @param cmph Optional format comparison handler
* @param data Opaque data for handler
* @param ref True to mem_ref() data
* @param params Formatted parameters
*
* @return 0 if success, otherwise errorcode
*/
int sdp_format_add(struct sdp_format **fmtp, struct sdp_media *m,
bool prepend, const char *id, const char *name,
uint32_t srate, uint8_t ch,
@ -145,6 +162,14 @@ struct sdp_format *sdp_format_find(const struct list *lst, const struct pl *id)
}
/**
* Set the parameters of an SDP format
*
* @param fmt SDP Format
* @param params Formatted parameters
*
* @return 0 if success, otherwise errorcode
*/
int sdp_format_set_params(struct sdp_format *fmt, const char *params, ...)
{
int err = 0;
@ -166,6 +191,14 @@ int sdp_format_set_params(struct sdp_format *fmt, const char *params, ...)
}
/**
* Compare two SDP Formats
*
* @param fmt1 First SDP format
* @param fmt2 Second SDP format
*
* @return True if matching, False if not
*/
bool sdp_format_cmp(const struct sdp_format *fmt1,
const struct sdp_format *fmt2)
{
@ -199,6 +232,14 @@ bool sdp_format_cmp(const struct sdp_format *fmt1,
}
/**
* Print SDP Format debug information
*
* @param pf Print function for output
* @param fmt SDP Format
*
* @return 0 if success, otherwise errorcode
*/
int sdp_format_debug(struct re_printf *pf, const struct sdp_format *fmt)
{
int err;

View file

@ -67,6 +67,17 @@ static int media_alloc(struct sdp_media **mp, struct list *list)
}
/**
* Add a media line to an SDP Session
*
* @param mp Pointer to allocated SDP Media line object
* @param sess SDP Session
* @param name Media name
* @param port Port number
* @param proto Transport protocol
*
* @return 0 if success, otherwise errorcode
*/
int sdp_media_add(struct sdp_media **mp, struct sdp_session *sess,
const char *name, uint16_t port, const char *proto)
{
@ -97,6 +108,16 @@ int sdp_media_add(struct sdp_media **mp, struct sdp_session *sess,
}
/**
* Add a remote SDP media line to an SDP Session
*
* @param mp Pointer to allocated SDP Media line object
* @param sess SDP Session
* @param name Media name
* @param proto Transport protocol
*
* @return 0 if success, otherwise errorcode
*/
int sdp_media_radd(struct sdp_media **mp, struct sdp_session *sess,
const struct pl *name, const struct pl *proto)
{
@ -124,6 +145,11 @@ int sdp_media_radd(struct sdp_media **mp, struct sdp_session *sess,
}
/**
* Reset the remote part of an SDP Media line
*
* @param m SDP Media line
*/
void sdp_media_rreset(struct sdp_media *m)
{
int i;
@ -144,6 +170,15 @@ void sdp_media_rreset(struct sdp_media *m)
}
/**
* Find an SDP Media line from name and transport protocol
*
* @param sess SDP Session
* @param name Media name
* @param proto Transport protocol
*
* @return Matching media line if found, NULL if not found
*/
struct sdp_media *sdp_media_find(const struct sdp_session *sess,
const struct pl *name,
const struct pl *proto)
@ -170,6 +205,12 @@ struct sdp_media *sdp_media_find(const struct sdp_session *sess,
}
/**
* Align the locate/remote formats of an SDP Media line
*
* @param m SDP Media line
* @param offer True if SDP Offer, False if SDP Answer
*/
void sdp_media_align_formats(struct sdp_media *m, bool offer)
{
struct sdp_format *rfmt, *lfmt;
@ -244,6 +285,12 @@ void sdp_media_align_formats(struct sdp_media *m, bool offer)
}
/**
* Set an SDP Media line to enabled/disabled
*
* @param m SDP Media line
* @param disabled True for disabled, False for enabled
*/
void sdp_media_set_disabled(struct sdp_media *m, bool disabled)
{
if (!m)
@ -253,6 +300,12 @@ void sdp_media_set_disabled(struct sdp_media *m, bool disabled)
}
/**
* Set the local port number of an SDP Media line
*
* @param m SDP Media line
* @param port Port number
*/
void sdp_media_set_lport(struct sdp_media *m, uint16_t port)
{
if (!m)
@ -262,6 +315,12 @@ void sdp_media_set_lport(struct sdp_media *m, uint16_t port)
}
/**
* Set the local network address of an SDP media line
*
* @param m SDP Media line
* @param laddr Local network address
*/
void sdp_media_set_laddr(struct sdp_media *m, const struct sa *laddr)
{
if (!m || !laddr)
@ -271,6 +330,13 @@ void sdp_media_set_laddr(struct sdp_media *m, const struct sa *laddr)
}
/**
* Set a local bandwidth of an SDP Media line
*
* @param m SDP Media line
* @param type Bandwidth type
* @param bw Bandwidth value
*/
void sdp_media_set_lbandwidth(struct sdp_media *m, enum sdp_bandwidth type,
int32_t bw)
{
@ -281,6 +347,12 @@ void sdp_media_set_lbandwidth(struct sdp_media *m, enum sdp_bandwidth type,
}
/**
* Set the local RTCP port number of an SDP Media line
*
* @param m SDP Media line
* @param port RTCP Port number
*/
void sdp_media_set_lport_rtcp(struct sdp_media *m, uint16_t port)
{
if (!m)
@ -290,6 +362,12 @@ void sdp_media_set_lport_rtcp(struct sdp_media *m, uint16_t port)
}
/**
* Set the local RTCP network address of an SDP media line
*
* @param m SDP Media line
* @param laddr Local RTCP network address
*/
void sdp_media_set_laddr_rtcp(struct sdp_media *m, const struct sa *laddr)
{
if (!m || !laddr)
@ -299,6 +377,12 @@ void sdp_media_set_laddr_rtcp(struct sdp_media *m, const struct sa *laddr)
}
/**
* Set the local direction flag of an SDP Media line
*
* @param m SDP Media line
* @param dir Media direction flag
*/
void sdp_media_set_ldir(struct sdp_media *m, enum sdp_dir dir)
{
if (!m)
@ -308,6 +392,16 @@ void sdp_media_set_ldir(struct sdp_media *m, enum sdp_dir dir)
}
/**
* Set a local attribute of an SDP Media line
*
* @param m SDP Media line
* @param replace True to replace attribute, False to append
* @param name Attribute name
* @param value Formatted attribute value
*
* @return 0 if success, otherwise errorcode
*/
int sdp_media_set_lattr(struct sdp_media *m, bool replace,
const char *name, const char *value, ...)
{
@ -328,6 +422,12 @@ int sdp_media_set_lattr(struct sdp_media *m, bool replace,
}
/**
* Delete a local attribute of an SDP Media line
*
* @param m SDP Media line
* @param name Attribute name
*/
void sdp_media_del_lattr(struct sdp_media *m, const char *name)
{
if (!m || !name)
@ -337,18 +437,38 @@ void sdp_media_del_lattr(struct sdp_media *m, const char *name)
}
/**
* Get the remote port number of an SDP Media line
*
* @param m SDP Media line
*
* @return Remote port number
*/
uint16_t sdp_media_rport(const struct sdp_media *m)
{
return m ? sa_port(&m->raddr) : 0;
}
/**
* Get the remote network address of an SDP Media line
*
* @param m SDP Media line
*
* @return Remote network address
*/
const struct sa *sdp_media_raddr(const struct sdp_media *m)
{
return m ? &m->raddr : NULL;
}
/**
* Get the remote RTCP network address of an SDP Media line
*
* @param m SDP Media line
* @param raddr On return, contains remote RTCP network address
*/
void sdp_media_raddr_rtcp(const struct sdp_media *m, struct sa *raddr)
{
if (!m || !raddr)
@ -370,6 +490,14 @@ void sdp_media_raddr_rtcp(const struct sdp_media *m, struct sa *raddr)
}
/**
* Get a remote bandwidth of an SDP Media line
*
* @param m SDP Media line
* @param type Bandwidth type
*
* @return Remote bandwidth value
*/
int32_t sdp_media_rbandwidth(const struct sdp_media *m,
enum sdp_bandwidth type)
{
@ -380,24 +508,53 @@ int32_t sdp_media_rbandwidth(const struct sdp_media *m,
}
/**
* Get the local media direction of an SDP Media line
*
* @param m SDP Media line
*
* @return Local media direction
*/
enum sdp_dir sdp_media_ldir(const struct sdp_media *m)
{
return m ? m->ldir : SDP_INACTIVE;
}
/**
* Get the remote media direction of an SDP Media line
*
* @param m SDP Media line
*
* @return Remote media direction
*/
enum sdp_dir sdp_media_rdir(const struct sdp_media *m)
{
return m ? m->rdir : SDP_INACTIVE;
}
/**
* Get the combined media direction of an SDP Media line
*
* @param m SDP Media line
*
* @return Combined media direction
*/
enum sdp_dir sdp_media_dir(const struct sdp_media *m)
{
return m ? (enum sdp_dir)(m->ldir & m->rdir) : SDP_INACTIVE;
}
/**
* Find a local SDP format from a payload type
*
* @param m SDP Media line
* @param pt Payload type
*
* @return Local SDP format if found, NULL if not found
*/
const struct sdp_format *sdp_media_lformat(const struct sdp_media *m, int pt)
{
struct le *le;
@ -417,6 +574,14 @@ const struct sdp_format *sdp_media_lformat(const struct sdp_media *m, int pt)
}
/**
* Find a remote SDP format from a format name
*
* @param m SDP Media line
* @param name Format name
*
* @return Remote SDP format if found, NULL if not found
*/
const struct sdp_format *sdp_media_rformat(const struct sdp_media *m,
const char *name)
{
@ -442,6 +607,19 @@ const struct sdp_format *sdp_media_rformat(const struct sdp_media *m,
}
/**
* Find an SDP Format of an SDP Media line
*
* @param m SDP Media line
* @param local True if local media, False if remote
* @param id SDP format id
* @param pt Payload type
* @param name Format name
* @param srate Sampling rate
* @param ch Number of channels
*
* @return SDP Format if found, NULL if not found
*/
struct sdp_format *sdp_media_format(const struct sdp_media *m,
bool local, const char *id,
int pt, const char *name,
@ -452,6 +630,21 @@ struct sdp_format *sdp_media_format(const struct sdp_media *m,
}
/**
* Apply a function handler to all matching SDP formats
*
* @param m SDP Media line
* @param local True if local media, False if remote
* @param id SDP format id
* @param pt Payload type
* @param name Format name
* @param srate Sampling rate
* @param ch Number of channels
* @param fmth SDP Format handler
* @param arg Handler argument
*
* @return SDP Format if found, NULL if not found
*/
struct sdp_format *sdp_media_format_apply(const struct sdp_media *m,
bool local, const char *id,
int pt, const char *name,
@ -494,6 +687,14 @@ struct sdp_format *sdp_media_format_apply(const struct sdp_media *m,
}
/**
* Get the list of SDP Formats
*
* @param m SDP Media line
* @param local True if local, False if remote
*
* @return List of SDP Formats
*/
const struct list *sdp_media_format_lst(const struct sdp_media *m, bool local)
{
if (!m)
@ -503,6 +704,14 @@ const struct list *sdp_media_format_lst(const struct sdp_media *m, bool local)
}
/**
* Get a remote attribute from an SDP Media line
*
* @param m SDP Media line
* @param name Attribute name
*
* @return Attribute value, NULL if not found
*/
const char *sdp_media_rattr(const struct sdp_media *m, const char *name)
{
if (!m || !name)
@ -512,6 +721,16 @@ const char *sdp_media_rattr(const struct sdp_media *m, const char *name)
}
/**
* Apply a function handler to all matching remote attributes
*
* @param m SDP Media line
* @param name Attribute name
* @param attrh Attribute handler
* @param arg Handler argument
*
* @return Attribute value if match
*/
const char *sdp_media_rattr_apply(const struct sdp_media *m, const char *name,
sdp_attr_h *attrh, void *arg)
{
@ -522,12 +741,27 @@ const char *sdp_media_rattr_apply(const struct sdp_media *m, const char *name,
}
/**
* Get the name of an SDP Media line
*
* @param m SDP Media line
*
* @return SDP Media line name
*/
const char *sdp_media_name(const struct sdp_media *m)
{
return m ? m->name : NULL;
}
/**
* Print SDP Media line debug information
*
* @param pf Print function for output
* @param m SDP Media line
*
* @return 0 if success, otherwise errorcode
*/
int sdp_media_debug(struct re_printf *pf, const struct sdp_media *m)
{
struct le *le;

View file

@ -227,6 +227,15 @@ static int version_decode(const struct pl *pl)
}
/**
* Decode an SDP message into an SDP Session
*
* @param sess SDP Session
* @param mb Memory buffer containing SDP message
* @param offer True if SDP offer, False if SDP answer
*
* @return 0 if success, otherwise errorcode
*/
int sdp_decode(struct sdp_session *sess, struct mbuf *mb, bool offer)
{
struct sdp_media *m;
@ -428,6 +437,15 @@ static int media_encode(const struct sdp_media *m, struct mbuf *mb, bool offer)
}
/**
* Encode an SDP Session into a memory buffer
*
* @param mbp Pointer to allocated memory buffer
* @param sess SDP Session
* @param offer True if SDP Offer, False if SDP Answer
*
* @return 0 if success, otherwise errorcode
*/
int sdp_encode(struct mbuf **mbp, struct sdp_session *sess, bool offer)
{
const int ipver = sa_af(&sess->laddr) == AF_INET ? 4 : 6;

View file

@ -26,6 +26,14 @@ static void destructor(void *arg)
}
/**
* Allocate a new SDP Session
*
* @param sessp Pointer to allocated SDP Session object
* @param laddr Local network address
*
* @return 0 if success, otherwise errorcode
*/
int sdp_session_alloc(struct sdp_session **sessp, const struct sa *laddr)
{
struct sdp_session *sess;
@ -59,6 +67,11 @@ int sdp_session_alloc(struct sdp_session **sessp, const struct sa *laddr)
}
/**
* Reset the remote side of an SDP Session
*
* @param sess SDP Session
*/
void sdp_session_rreset(struct sdp_session *sess)
{
int i;
@ -77,6 +90,12 @@ void sdp_session_rreset(struct sdp_session *sess)
}
/**
* Set the local network address of an SDP Session
*
* @param sess SDP Session
* @param laddr Local network address
*/
void sdp_session_set_laddr(struct sdp_session *sess, const struct sa *laddr)
{
if (!sess || !laddr)
@ -86,6 +105,13 @@ void sdp_session_set_laddr(struct sdp_session *sess, const struct sa *laddr)
}
/**
* Set the local bandwidth of an SDP Session
*
* @param sess SDP Session
* @param type Bandwidth type
* @param bw Bandwidth value
*/
void sdp_session_set_lbandwidth(struct sdp_session *sess,
enum sdp_bandwidth type, int32_t bw)
{
@ -96,6 +122,16 @@ void sdp_session_set_lbandwidth(struct sdp_session *sess,
}
/**
* Set a local attribute of an SDP Session
*
* @param sess SDP Session
* @param replace True to replace any existing attributes, false to append
* @param name Attribute name
* @param value Formatted attribute value
*
* @return 0 if success, otherwise errorcode
*/
int sdp_session_set_lattr(struct sdp_session *sess, bool replace,
const char *name, const char *value, ...)
{
@ -116,6 +152,12 @@ int sdp_session_set_lattr(struct sdp_session *sess, bool replace,
}
/**
* Delete a local attribute of an SDP Session
*
* @param sess SDP Session
* @param name Attribute name
*/
void sdp_session_del_lattr(struct sdp_session *sess, const char *name)
{
if (!sess || !name)
@ -125,6 +167,14 @@ void sdp_session_del_lattr(struct sdp_session *sess, const char *name)
}
/**
* Get the remote bandwidth of an SDP Session
*
* @param sess SDP Session
* @param type Bandwidth type
*
* @return Bandwidth value
*/
int32_t sdp_session_rbandwidth(const struct sdp_session *sess,
enum sdp_bandwidth type)
{
@ -135,6 +185,14 @@ int32_t sdp_session_rbandwidth(const struct sdp_session *sess,
}
/**
* Get a remote attribute of an SDP Session
*
* @param sess SDP Session
* @param name Attribute name
*
* @return Attribute value if exist, NULL if not exist
*/
const char *sdp_session_rattr(const struct sdp_session *sess, const char *name)
{
if (!sess || !name)
@ -144,6 +202,16 @@ const char *sdp_session_rattr(const struct sdp_session *sess, const char *name)
}
/**
* Apply a function handler of all matching remote attributes
*
* @param sess SDP Session
* @param name Attribute name
* @param attrh Attribute handler
* @param arg Handler argument
*
* @return Attribute value if match
*/
const char *sdp_session_rattr_apply(const struct sdp_session *sess,
const char *name,
sdp_attr_h *attrh, void *arg)
@ -155,6 +223,14 @@ const char *sdp_session_rattr_apply(const struct sdp_session *sess,
}
/**
* Get the list of media-lines from an SDP Session
*
* @param sess SDP Session
* @param local True for local, False for remote
*
* @return List of media-lines
*/
const struct list *sdp_session_medial(const struct sdp_session *sess,
bool local)
{
@ -165,6 +241,14 @@ const struct list *sdp_session_medial(const struct sdp_session *sess,
}
/**
* Print SDP Session debug information
*
* @param pf Print function for output
* @param sess SDP Session
*
* @return 0 if success, otherwise errorcode
*/
int sdp_session_debug(struct re_printf *pf, const struct sdp_session *sess)
{
struct le *le;

View file

@ -24,6 +24,13 @@ const char sdp_proto_rtpavp[] = "RTP/AVP"; /**< RTP Profile */
const char sdp_proto_rtpsavp[] = "RTP/SAVP"; /**< Secure RTP Profile */
/**
* Get the SDP media direction name
*
* @param dir Media direction
*
* @return Name of media direction
*/
const char *sdp_dir_name(enum sdp_dir dir)
{
switch (dir) {
@ -37,6 +44,13 @@ const char *sdp_dir_name(enum sdp_dir dir)
}
/**
* Get the SDP bandwidth name
*
* @param type Bandwidth type
*
* @return Bandwidth name
*/
const char *sdp_bandwidth_name(enum sdp_bandwidth type)
{
switch (type) {

View file

@ -1,5 +1,5 @@
/**
* @file msg.c SIP event messages
* @file sipevent/msg.c SIP event messages
*
* Copyright (C) 2010 Creytiv.com
*/

View file

@ -499,7 +499,7 @@ int sipevent_subscribe(struct sipsub **subp, struct sipevent_sock *sock,
* @param authh Authentication handler
* @param aarg Authentication handler argument
* @param aref True to ref argument
* @param noth Notify handler
* @param notifyh Notify handler
* @param closeh Close handler
* @param arg Response handler argument
* @param fmt Formatted strings with extra SIP Headers

View file

@ -79,6 +79,16 @@ static int password_cb(char *buf, int size, int rwflag, void *userdata)
}
/**
* Allocate a new TLS context
*
* @param tlsp Pointer to allocated TLS context
* @param method TLS method
* @param keyfile Optional private key file
* @param pwd Optional password
*
* @return 0 if success, otherwise errorcode
*/
int tls_alloc(struct tls **tlsp, enum tls_method method, const char *keyfile,
const char *pwd)
{
@ -178,6 +188,14 @@ int tls_alloc(struct tls **tlsp, enum tls_method method, const char *keyfile,
}
/**
* Set default locations for trusted CA certificates
*
* @param tls TLS Context
* @param capath Path to CA certificates
*
* @return 0 if success, otherwise errorcode
*/
int tls_add_ca(struct tls *tls, const char *capath)
{
if (!tls || !capath)
@ -193,6 +211,15 @@ int tls_add_ca(struct tls *tls, const char *capath)
}
/**
* Verify peer certificate of a TLS connection
*
* @param tc TLS Connection
* @param cn Returned common name
* @param cn_size Size of cn string
*
* @return 0 if success, otherwise errorcode
*/
int tls_verify_cert(struct tls_conn *tc, char *cn, size_t cn_size)
{
X509 *peer;

View file

@ -276,6 +276,16 @@ static bool send_handler(int *err, struct mbuf *mb, void *arg)
}
/**
* Start TLS on a TCP-connection
*
* @param ptc Pointer to allocated TLS connectioon
* @param tls TLS Context
* @param tcp TCP Connection
* @param layer Protocol stack layer
*
* @return 0 if success, otherwise errorcode
*/
int tls_start_tcp(struct tls_conn **ptc, struct tls *tls, struct tcp_conn *tcp,
int layer)
{

View file

@ -373,6 +373,14 @@ int tls_start_udp(struct tls_sock **tsp, struct tls *tls, struct udp_sock *us,
}
/**
* Get the TLS Connection for a given peer
*
* @param ts TLS Socket
* @param peer Network address of peer
*
* @return TLS Connection if found, NULL if not found
*/
struct tls_conn *tls_udp_conn(const struct tls_sock *ts, const struct sa *peer)
{
if (!ts)