From 2c1b4c94d9d10c71e47300994fec27c614327c4a Mon Sep 17 00:00:00 2001 From: Richard Aas Date: Mon, 21 May 2012 06:19:38 +0000 Subject: [PATCH] sipsess: doxygen comments --- include/re_sipsess.h | 2 +- mk/Doxyfile | 1 - src/sdp/format.c | 1 + src/sipevent/listen.c | 2 +- src/sipsess/accept.c | 57 +++++++++++++++++++++++++++++++++++++++++++ src/sipsess/connect.c | 28 +++++++++++++++++++++ src/sipsess/info.c | 11 +++++++++ src/sipsess/listen.c | 18 +++++++++++++- src/sipsess/modify.c | 8 ++++++ src/sipsess/sess.c | 9 ++++++- 10 files changed, 132 insertions(+), 5 deletions(-) diff --git a/include/re_sipsess.h b/include/re_sipsess.h index 96c5bc0..a97e343 100644 --- a/include/re_sipsess.h +++ b/include/re_sipsess.h @@ -56,4 +56,4 @@ int sipsess_modify(struct sipsess *sess, struct mbuf *desc); int sipsess_info(struct sipsess *sess, const char *ctype, struct mbuf *body, sip_resp_h *resph, void *arg); void sipsess_close_all(struct sipsess_sock *sock); -struct sip_dialog *sipsess_dialog(struct sipsess *sess); +struct sip_dialog *sipsess_dialog(const struct sipsess *sess); diff --git a/mk/Doxyfile b/mk/Doxyfile index e5d7f02..33ccce7 100644 --- a/mk/Doxyfile +++ b/mk/Doxyfile @@ -92,7 +92,6 @@ EXCLUDE = test.c \ src/md5/md5.h src/md5/md5.c \ src/dns include/re_dns.h \ src/sip/ include/re_sip.h \ - src/sipsess/ include/re_sipsess.h \ src/stun include/re_stun.h EXCLUDE_SYMLINKS = NO diff --git a/src/sdp/format.c b/src/sdp/format.c index 6a8b67a..9cc9dd9 100644 --- a/src/sdp/format.c +++ b/src/sdp/format.c @@ -41,6 +41,7 @@ static void destructor(void *arg) * @param name Format name * @param srate Sampling rate * @param ch Number of channels + * @param ench Optional format encode handler * @param cmph Optional format comparison handler * @param data Opaque data for handler * @param ref True to mem_ref() data diff --git a/src/sipevent/listen.c b/src/sipevent/listen.c index 5c588c5..9e05126 100644 --- a/src/sipevent/listen.c +++ b/src/sipevent/listen.c @@ -1,5 +1,5 @@ /** - * @file listen.c SIP Event Listen + * @file sipevent/listen.c SIP Event Listen * * Copyright (C) 2010 Creytiv.com */ diff --git a/src/sipsess/accept.c b/src/sipsess/accept.c index 0f08e96..fdfbd9e 100644 --- a/src/sipsess/accept.c +++ b/src/sipsess/accept.c @@ -33,6 +33,31 @@ static void cancel_handler(void *arg) } +/** + * Accept an incoming SIP Session connection + * + * @param sessp Pointer to allocated SIP Session + * @param sock SIP Session socket + * @param msg Incoming SIP message + * @param scode Response status code + * @param reason Response reason phrase + * @param cuser Contact username + * @param ctype Session content-type + * @param desc Content description (e.g. SDP) + * @param authh SIP Authentication handler + * @param aarg Authentication handler argument + * @param aref True to mem_ref() aarg + * @param offerh Session offer handler + * @param answerh Session answer handler + * @param estabh Session established handler + * @param infoh Session info handler + * @param referh Session refer handler + * @param closeh Session close handler + * @param arg Handler argument + * @param fmt Formatted strings with extra SIP Headers + * + * @return 0 if success, otherwise errorcode + */ int sipsess_accept(struct sipsess **sessp, struct sipsess_sock *sock, const struct sip_msg *msg, uint16_t scode, const char *reason, const char *cuser, const char *ctype, @@ -111,6 +136,17 @@ int sipsess_accept(struct sipsess **sessp, struct sipsess_sock *sock, } +/** + * Send progress response + * + * @param sess SIP Session + * @param scode Response status code + * @param reason Response reason phrase + * @param desc Content description (e.g. SDP) + * @param fmt Formatted strings with extra SIP Headers + * + * @return 0 if success, otherwise errorcode + */ int sipsess_progress(struct sipsess *sess, uint16_t scode, const char *reason, struct mbuf *desc, const char *fmt, ...) { @@ -146,6 +182,17 @@ int sipsess_progress(struct sipsess *sess, uint16_t scode, const char *reason, } +/** + * Answer an incoming SIP Session connection + * + * @param sess SIP Session + * @param scode Response status code + * @param reason Response reason phrase + * @param desc Content description (e.g. SDP) + * @param fmt Formatted strings with extra SIP Headers + * + * @return 0 if success, otherwise errorcode + */ int sipsess_answer(struct sipsess *sess, uint16_t scode, const char *reason, struct mbuf *desc, const char *fmt, ...) { @@ -164,6 +211,16 @@ int sipsess_answer(struct sipsess *sess, uint16_t scode, const char *reason, } +/** + * Reject an incoming SIP Session connection + * + * @param sess SIP Session + * @param scode Response status code + * @param reason Response reason phrase + * @param fmt Formatted strings with extra SIP Headers + * + * @return 0 if success, otherwise errorcode + */ int sipsess_reject(struct sipsess *sess, uint16_t scode, const char *reason, const char *fmt, ...) { diff --git a/src/sipsess/connect.c b/src/sipsess/connect.c index 7bc0005..cc9b37e 100644 --- a/src/sipsess/connect.c +++ b/src/sipsess/connect.c @@ -147,6 +147,34 @@ static int invite(struct sipsess *sess) } +/** + * Connect to a remote SIP useragent + * + * @param sessp Pointer to allocated SIP Session + * @param sock SIP Session socket + * @param to_uri To SIP uri + * @param from_name From display name + * @param from_uri From SIP uri + * @param cuser Contact username + * @param routev Outbound route vector + * @param routec Outbound route vector count + * @param ctype Session content-type + * @param desc Content description (e.g. SDP) + * @param authh SIP Authentication handler + * @param aarg Authentication handler argument + * @param aref True to mem_ref() aarg + * @param offerh Session offer handler + * @param answerh Session answer handler + * @param progrh Session progress handler + * @param estabh Session established handler + * @param infoh Session info handler + * @param referh Session refer handler + * @param closeh Session close handler + * @param arg Handler argument + * @param fmt Formatted strings with extra SIP Headers + * + * @return 0 if success, otherwise errorcode + */ int sipsess_connect(struct sipsess **sessp, struct sipsess_sock *sock, const char *to_uri, const char *from_name, const char *from_uri, const char *cuser, diff --git a/src/sipsess/info.c b/src/sipsess/info.c index b86e4bb..c665e3f 100644 --- a/src/sipsess/info.c +++ b/src/sipsess/info.c @@ -87,6 +87,17 @@ static int info_request(struct sipsess_request *req) } +/** + * Send a SIP INFO request in the SIP Session + * + * @param sess SIP Session + * @param ctype Content-type + * @param body Content description (e.g. SDP) + * @param resph Response handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int sipsess_info(struct sipsess *sess, const char *ctype, struct mbuf *body, sip_resp_h *resph, void *arg) { diff --git a/src/sipsess/listen.c b/src/sipsess/listen.c index 81820ee..9b94ab1 100644 --- a/src/sipsess/listen.c +++ b/src/sipsess/listen.c @@ -1,5 +1,5 @@ /** - * @file listen.c SIP Session Listen + * @file sipsess/listen.c SIP Session Listen * * Copyright (C) 2010 Creytiv.com */ @@ -294,6 +294,17 @@ static bool response_handler(const struct sip_msg *msg, void *arg) } +/** + * Listen to a SIP Session socket for incoming connections + * + * @param sockp Pointer to allocated SIP Session socket + * @param sip SIP Stack instance + * @param htsize Hashtable size + * @param connh Connection handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int sipsess_listen(struct sipsess_sock **sockp, struct sip *sip, int htsize, sipsess_conn_h *connh, void *arg) { @@ -337,6 +348,11 @@ int sipsess_listen(struct sipsess_sock **sockp, struct sip *sip, } +/** + * Close all SIP Sessions + * + * @param sock SIP Session socket + */ void sipsess_close_all(struct sipsess_sock *sock) { if (!sock) diff --git a/src/sipsess/modify.c b/src/sipsess/modify.c index ac8d8e7..67b3ff4 100644 --- a/src/sipsess/modify.c +++ b/src/sipsess/modify.c @@ -143,6 +143,14 @@ int sipsess_reinvite(struct sipsess *sess, bool reset_ls) } +/** + * Modify an established SIP Session sending Re-INVITE or UPDATE + * + * @param sess SIP Session + * @param desc Content description (e.g. SDP) + * + * @return 0 if success, otherwise errorcode + */ int sipsess_modify(struct sipsess *sess, struct mbuf *desc) { if (!sess || sess->st || sess->terminated) diff --git a/src/sipsess/sess.c b/src/sipsess/sess.c index 3dde051..b062513 100644 --- a/src/sipsess/sess.c +++ b/src/sipsess/sess.c @@ -220,7 +220,14 @@ void sipsess_terminate(struct sipsess *sess, int err, } -struct sip_dialog *sipsess_dialog(struct sipsess *sess) +/** + * Get the SIP dialog from a SIP Session + * + * @param sess SIP Session + * + * @return SIP Dialog object + */ +struct sip_dialog *sipsess_dialog(const struct sipsess *sess) { return sess ? sess->dlg : NULL; }