From 964f5b6893a53fbe899b7fdd489e4445ed9c466c Mon Sep 17 00:00:00 2001 From: Richard Aas Date: Tue, 26 Jun 2012 07:01:09 +0000 Subject: [PATCH] sip: doxygen comments --- include/re_sip.h | 9 +++++ mk/Doxyfile | 8 ++-- src/bfcp/transp.c | 2 +- src/sip/auth.c | 23 ++++++++++++ src/sip/cseq.c | 8 ++++ src/sip/dialog.c | 91 +++++++++++++++++++++++++++++++++++++++++++++ src/sip/keepalive.c | 12 ++++++ src/sip/msg.c | 85 ++++++++++++++++++++++++++++++++++++++++++ src/sip/param.c | 18 +++++++++ src/sip/reply.c | 55 ++++++++++++++++++++++++++- src/sip/request.c | 70 ++++++++++++++++++++++++++++++++++ src/sip/sip.c | 50 +++++++++++++++++++++++++ src/sip/strans.c | 23 ++++++++++++ src/sip/transp.c | 55 ++++++++++++++++++++++++++- src/sip/via.c | 8 ++++ 15 files changed, 510 insertions(+), 7 deletions(-) diff --git a/include/re_sip.h b/include/re_sip.h index c7db95e..dad9188 100644 --- a/include/re_sip.h +++ b/include/re_sip.h @@ -10,6 +10,7 @@ enum { SIP_PORT_TLS = 5061, }; +/** SIP Transport */ enum sip_transp { SIP_TRANSP_NONE = -1, SIP_TRANSP_UDP = 0, @@ -19,6 +20,7 @@ enum sip_transp { }; +/** SIP Header ID (perfect hash value) */ enum sip_hdrid { SIP_HDR_ACCEPT = 3186, SIP_HDR_ACCEPT_CONTACT = 232, @@ -135,6 +137,7 @@ enum { }; +/** SIP Via header */ struct sip_via { struct pl sentby; struct sa addr; @@ -144,6 +147,7 @@ struct sip_via { enum sip_transp tp; }; +/** SIP Address */ struct sip_addr { struct pl dname; struct pl auri; @@ -151,6 +155,7 @@ struct sip_addr { struct pl params; }; +/** SIP Tag address */ struct sip_taddr { struct pl dname; struct pl auri; @@ -160,11 +165,13 @@ struct sip_taddr { struct pl val; }; +/** SIP CSeq header */ struct sip_cseq { struct pl met; uint32_t num; }; +/** SIP Header */ struct sip_hdr { struct le le; struct le he; @@ -173,6 +180,7 @@ struct sip_hdr { enum sip_hdrid id; }; +/** SIP Message */ struct sip_msg { struct sa src; struct sa dst; @@ -200,6 +208,7 @@ struct sip_msg { bool req; }; +/** SIP Loop-state */ struct sip_loopstate { uint32_t failc; uint16_t last_scode; diff --git a/mk/Doxyfile b/mk/Doxyfile index 33ccce7..f8f5702 100644 --- a/mk/Doxyfile +++ b/mk/Doxyfile @@ -67,7 +67,7 @@ GENERATE_DEPRECATEDLIST= YES ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 SHOW_USED_FILES = YES -SHOW_DIRECTORIES = NO +#SHOW_DIRECTORIES = NO FILE_VERSION_FILTER = #--------------------------------------------------------------------------- # configuration options related to warning and progress messages @@ -75,7 +75,7 @@ FILE_VERSION_FILTER = QUIET = YES WARNINGS = YES WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = NO +WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = YES WARN_FORMAT = "$file:$line: $text" WARN_LOGFILE = @@ -91,7 +91,6 @@ EXCLUDE = test.c \ include/re_bitv.h \ src/md5/md5.h src/md5/md5.c \ src/dns include/re_dns.h \ - src/sip/ include/re_sip.h \ src/stun include/re_stun.h EXCLUDE_SYMLINKS = NO @@ -129,7 +128,7 @@ HTML_FILE_EXTENSION = .html HTML_HEADER = HTML_FOOTER = HTML_STYLESHEET = -HTML_ALIGN_MEMBERS = YES +#HTML_ALIGN_MEMBERS = YES GENERATE_HTMLHELP = NO CHM_FILE = HHC_LOCATION = @@ -230,6 +229,7 @@ DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png DOT_PATH = DOTFILE_DIRS = +DOT_GRAPH_MAX_NODES = 150 #MAX_DOT_GRAPH_WIDTH = 1024 #MAX_DOT_GRAPH_HEIGHT = 1024 #MAX_DOT_GRAPH_DEPTH = 1000 diff --git a/src/bfcp/transp.c b/src/bfcp/transp.c index d61aaea..d4e555f 100644 --- a/src/bfcp/transp.c +++ b/src/bfcp/transp.c @@ -1,5 +1,5 @@ /** - * @file transp.c BFCP Transport + * @file bfcp/transp.c BFCP Transport * * Copyright (C) 2010 Creytiv.com */ diff --git a/src/sip/auth.c b/src/sip/auth.c index 11703f4..0570a5d 100644 --- a/src/sip/auth.c +++ b/src/sip/auth.c @@ -192,6 +192,14 @@ static bool auth_handler(const struct sip_hdr *hdr, const struct sip_msg *msg, } +/** + * Update a SIP authentication state from a SIP message + * + * @param auth SIP Authentication state + * @param msg SIP Message + * + * @return 0 if success, otherwise errorcode + */ int sip_auth_authenticate(struct sip_auth *auth, const struct sip_msg *msg) { if (!auth || !msg) @@ -270,6 +278,16 @@ int sip_auth_encode(struct mbuf *mb, struct sip_auth *auth, const char *met, } +/** + * Allocate a SIP authentication state + * + * @param authp Pointer to allocated SIP authentication state + * @param authh Authentication handler + * @param arg Handler argument + * @param ref True to mem_ref() argument + * + * @return 0 if success, otherwise errorcode + */ int sip_auth_alloc(struct sip_auth **authp, sip_auth_h *authh, void *arg, bool ref) { @@ -292,6 +310,11 @@ int sip_auth_alloc(struct sip_auth **authp, sip_auth_h *authh, } +/** + * Reset a SIP authentication state + * + * @param auth SIP Authentication state + */ void sip_auth_reset(struct sip_auth *auth) { if (!auth) diff --git a/src/sip/cseq.c b/src/sip/cseq.c index f29cb97..ff2d77f 100644 --- a/src/sip/cseq.c +++ b/src/sip/cseq.c @@ -12,6 +12,14 @@ #include +/** + * Decode a pointer-length string into a SIP CSeq header + * + * @param cseq SIP CSeq header + * @param pl Pointer-length string + * + * @return 0 for success, otherwise errorcode + */ int sip_cseq_decode(struct sip_cseq *cseq, const struct pl *pl) { struct pl num; diff --git a/src/sip/dialog.c b/src/sip/dialog.c index 1516a8a..89bf032 100644 --- a/src/sip/dialog.c +++ b/src/sip/dialog.c @@ -71,6 +71,19 @@ static void destructor(void *arg) } +/** + * Allocate a SIP Dialog + * + * @param dlgp Pointer to allocated SIP Dialog + * @param uri Target URI + * @param to_uri To URI + * @param from_name From displayname (optional) + * @param from_uri From URI + * @param routev Route vector + * @param routec Route count + * + * @return 0 if success, otherwise errorcode + */ int sip_dialog_alloc(struct sip_dialog **dlgp, const char *uri, const char *to_uri, const char *from_name, const char *from_uri, @@ -165,6 +178,14 @@ static bool record_route_handler(const struct sip_hdr *hdr, } +/** + * Accept and create a SIP Dialog from an incoming SIP Message + * + * @param dlgp Pointer to allocated SIP Dialog + * @param msg SIP Message + * + * @return 0 if success, otherwise errorcode + */ int sip_dialog_accept(struct sip_dialog **dlgp, const struct sip_msg *msg) { const struct sip_hdr *contact; @@ -248,6 +269,14 @@ int sip_dialog_accept(struct sip_dialog **dlgp, const struct sip_msg *msg) } +/** + * Initialize a SIP Dialog from an incoming SIP Message + * + * @param dlg SIP Dialog to initialize + * @param msg SIP Message + * + * @return 0 if success, otherwise errorcode + */ int sip_dialog_create(struct sip_dialog *dlg, const struct sip_msg *msg) { char *uri = NULL, *rtag = NULL; @@ -335,6 +364,15 @@ int sip_dialog_create(struct sip_dialog *dlg, const struct sip_msg *msg) } +/** + * Fork a SIP Dialog from an incoming SIP Message + * + * @param dlgp Pointer to allocated SIP Dialog + * @param odlg Original SIP Dialog + * @param msg SIP Message + * + * @return 0 if success, otherwise errorcode + */ int sip_dialog_fork(struct sip_dialog **dlgp, struct sip_dialog *odlg, const struct sip_msg *msg) { @@ -418,6 +456,14 @@ int sip_dialog_fork(struct sip_dialog **dlgp, struct sip_dialog *odlg, } +/** + * Update an existing SIP Dialog from a SIP Message + * + * @param dlg SIP Dialog to update + * @param msg SIP Message + * + * @return 0 if success, otherwise errorcode + */ int sip_dialog_update(struct sip_dialog *dlg, const struct sip_msg *msg) { const struct sip_hdr *contact; @@ -462,6 +508,14 @@ int sip_dialog_update(struct sip_dialog *dlg, const struct sip_msg *msg) } +/** + * Check if a remote sequence number is valid + * + * @param dlg SIP Dialog + * @param msg SIP Message + * + * @return True if valid, False if invalid + */ bool sip_dialog_rseq_valid(struct sip_dialog *dlg, const struct sip_msg *msg) { if (!dlg || !msg || !msg->req) @@ -505,24 +559,53 @@ const struct uri *sip_dialog_route(const struct sip_dialog *dlg) } +/** + * Get the Call-ID from a SIP Dialog + * + * @param dlg SIP Dialog + * + * @return Call-ID string + */ const char *sip_dialog_callid(const struct sip_dialog *dlg) { return dlg ? dlg->callid : NULL; } +/** + * Get the local sequence number from a SIP Dialog + * + * @param dlg SIP Dialog + * + * @return Local sequence number + */ uint32_t sip_dialog_lseq(const struct sip_dialog *dlg) { return dlg ? dlg->lseq : 0; } +/** + * Check if a SIP Dialog is established + * + * @param dlg SIP Dialog + * + * @return True if established, False if not + */ bool sip_dialog_established(const struct sip_dialog *dlg) { return dlg && dlg->rtag; } +/** + * Compare a SIP Dialog against a SIP Message + * + * @param dlg SIP Dialog + * @param msg SIP Message + * + * @return True if match, False if no match + */ bool sip_dialog_cmp(const struct sip_dialog *dlg, const struct sip_msg *msg) { if (!dlg || !msg) @@ -541,6 +624,14 @@ bool sip_dialog_cmp(const struct sip_dialog *dlg, const struct sip_msg *msg) } +/** + * Compare a half SIP Dialog against a SIP Message + * + * @param dlg SIP Dialog + * @param msg SIP Message + * + * @return True if match, False if no match + */ bool sip_dialog_cmp_half(const struct sip_dialog *dlg, const struct sip_msg *msg) { diff --git a/src/sip/keepalive.c b/src/sip/keepalive.c index 40d5b5f..d58163b 100644 --- a/src/sip/keepalive.c +++ b/src/sip/keepalive.c @@ -55,6 +55,18 @@ uint64_t sip_keepalive_wait(uint32_t interval) } +/** + * Start a keepalive handler on a SIP transport + * + * @param kap Pointer to allocated keepalive object + * @param sip SIP Stack instance + * @param msg SIP Message + * @param interval Keepalive interval in seconds + * @param kah Keepalive handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int sip_keepalive_start(struct sip_keepalive **kap, struct sip *sip, const struct sip_msg *msg, uint32_t interval, sip_keepalive_h *kah, void *arg) diff --git a/src/sip/msg.c b/src/sip/msg.c index 1af13b1..0db1211 100644 --- a/src/sip/msg.c +++ b/src/sip/msg.c @@ -248,6 +248,14 @@ static inline int hdr_add(struct sip_msg *msg, const struct pl *name, } +/** + * Decode a SIP message + * + * @param msgp Pointer to allocated SIP Message + * @param mb Buffer containing SIP Message + * + * @return 0 if success, otherwise errorcode + */ int sip_msg_decode(struct sip_msg **msgp, struct mbuf *mb) { struct pl x, y, z, e, name; @@ -428,12 +436,31 @@ int sip_msg_decode(struct sip_msg **msgp, struct mbuf *mb) } +/** + * Get a SIP Header from a SIP Message + * + * @param msg SIP Message + * @param id SIP Header ID + * + * @return SIP Header if found, NULL if not found + */ const struct sip_hdr *sip_msg_hdr(const struct sip_msg *msg, enum sip_hdrid id) { return sip_msg_hdr_apply(msg, true, id, NULL, NULL); } +/** + * Apply a function handler to certain SIP Headers + * + * @param msg SIP Message + * @param fwd True to traverse forwards, false to traverse backwards + * @param id SIP Header ID + * @param h Function handler + * @param arg Handler argument + * + * @return SIP Header if handler returns true, otherwise NULL + */ const struct sip_hdr *sip_msg_hdr_apply(const struct sip_msg *msg, bool fwd, enum sip_hdrid id, sip_hdr_h *h, void *arg) @@ -464,12 +491,31 @@ const struct sip_hdr *sip_msg_hdr_apply(const struct sip_msg *msg, } +/** + * Get an unknown SIP Header from a SIP Message + * + * @param msg SIP Message + * @param name Header name + * + * @return SIP Header if found, NULL if not found + */ const struct sip_hdr *sip_msg_xhdr(const struct sip_msg *msg, const char *name) { return sip_msg_xhdr_apply(msg, true, name, NULL, NULL); } +/** + * Apply a function handler to certain unknown SIP Headers + * + * @param msg SIP Message + * @param fwd True to traverse forwards, false to traverse backwards + * @param name SIP Header name + * @param h Function handler + * @param arg Handler argument + * + * @return SIP Header if handler returns true, otherwise NULL + */ const struct sip_hdr *sip_msg_xhdr_apply(const struct sip_msg *msg, bool fwd, const char *name, sip_hdr_h *h, void *arg) @@ -516,6 +562,14 @@ static bool count_handler(const struct sip_hdr *hdr, const struct sip_msg *msg, } +/** + * Count the number of SIP Headers + * + * @param msg SIP Message + * @param id SIP Header ID + * + * @return Number of SIP Headers + */ uint32_t sip_msg_hdr_count(const struct sip_msg *msg, enum sip_hdrid id) { uint32_t n = 0; @@ -526,6 +580,14 @@ uint32_t sip_msg_hdr_count(const struct sip_msg *msg, enum sip_hdrid id) } +/** + * Count the number of unknown SIP Headers + * + * @param msg SIP Message + * @param name SIP Header name + * + * @return Number of SIP Headers + */ uint32_t sip_msg_xhdr_count(const struct sip_msg *msg, const char *name) { uint32_t n = 0; @@ -545,6 +607,15 @@ static bool value_handler(const struct sip_hdr *hdr, const struct sip_msg *msg, } +/** + * Check if a SIP Header matches a certain value + * + * @param msg SIP Message + * @param id SIP Header ID + * @param value Header value to check + * + * @return True if value matches, false if not + */ bool sip_msg_hdr_has_value(const struct sip_msg *msg, enum sip_hdrid id, const char *value) { @@ -553,6 +624,15 @@ bool sip_msg_hdr_has_value(const struct sip_msg *msg, enum sip_hdrid id, } +/** + * Check if an unknown SIP Header matches a certain value + * + * @param msg SIP Message + * @param name SIP Header name + * @param value Header value to check + * + * @return True if value matches, false if not + */ bool sip_msg_xhdr_has_value(const struct sip_msg *msg, const char *name, const char *value) { @@ -561,6 +641,11 @@ bool sip_msg_xhdr_has_value(const struct sip_msg *msg, const char *name, } +/** + * Print a SIP Message to stdout + * + * @param msg SIP Message + */ void sip_msg_dump(const struct sip_msg *msg) { struct le *le; diff --git a/src/sip/param.c b/src/sip/param.c index ed50b41..74e62a8 100644 --- a/src/sip/param.c +++ b/src/sip/param.c @@ -12,6 +12,15 @@ #include +/** + * Check if a SIP parameter exists + * + * @param pl Pointer-length string + * @param name SIP Parameter name + * @param val Returned parameter value + * + * @return 0 for success, otherwise errorcode + */ int sip_param_exists(const struct pl *pl, const char *name, struct pl *val) { struct pl v1, v2; @@ -35,6 +44,15 @@ int sip_param_exists(const struct pl *pl, const char *name, struct pl *val) } +/** + * Decode a SIP Parameter + * + * @param pl Pointer-length string + * @param name SIP Parameter name + * @param val Returned parameter value + * + * @return 0 for success, otherwise errorcode + */ int sip_param_decode(const struct pl *pl, const char *name, struct pl *val) { char expr[128]; diff --git a/src/sip/reply.c b/src/sip/reply.c index 533bfd8..1242ddf 100644 --- a/src/sip/reply.c +++ b/src/sip/reply.c @@ -134,6 +134,20 @@ static int vreplyf(struct sip_strans **stp, struct mbuf **mbp, bool trans, } +/** + * Formatted reply using Server Transaction + * + * @param stp Pointer to allocated SIP Server Transaction (optional) + * @param mbp Pointer to allocated SIP message buffer (optional) + * @param sip SIP Stack instance + * @param msg Incoming SIP message + * @param rec_route True to copy Record-Route headers + * @param scode Response status code + * @param reason Response reason phrase + * @param fmt Formatted SIP message + * + * @return 0 if success, otherwise errorcode + */ int sip_treplyf(struct sip_strans **stp, struct mbuf **mbp, struct sip *sip, const struct sip_msg *msg, bool rec_route, uint16_t scode, const char *reason, const char *fmt, ...) @@ -150,6 +164,17 @@ int sip_treplyf(struct sip_strans **stp, struct mbuf **mbp, struct sip *sip, } +/** + * Reply using Server Transaction + * + * @param stp Pointer to allocated SIP Server Transaction (optional) + * @param sip SIP Stack instance + * @param msg Incoming SIP message + * @param scode Response status code + * @param reason Response reason phrase + * + * @return 0 if success, otherwise errorcode + */ int sip_treply(struct sip_strans **stp, struct sip *sip, const struct sip_msg *msg, uint16_t scode, const char *reason) { @@ -157,8 +182,19 @@ int sip_treply(struct sip_strans **stp, struct sip *sip, } +/** + * Stateless formatted reply + * + * @param sip SIP Stack instance + * @param msg Incoming SIP message + * @param scode Response status code + * @param reason Response reason phrase + * @param fmt Formatted SIP message + * + * @return 0 if success, otherwise errorcode + */ int sip_replyf(struct sip *sip, const struct sip_msg *msg, uint16_t scode, - const char *reason, const char *fmt, ...) + const char *reason, const char *fmt, ...) { va_list ap; int err; @@ -172,6 +208,16 @@ int sip_replyf(struct sip *sip, const struct sip_msg *msg, uint16_t scode, } +/** + * Stateless reply + * + * @param sip SIP Stack instance + * @param msg Incoming SIP message + * @param scode Response status code + * @param reason Response reason phrase + * + * @return 0 if success, otherwise errorcode + */ int sip_reply(struct sip *sip, const struct sip_msg *msg, uint16_t scode, const char *reason) { @@ -179,6 +225,13 @@ int sip_reply(struct sip *sip, const struct sip_msg *msg, uint16_t scode, } +/** + * Get the reply address from a SIP message + * + * @param addr Network address, set on return + * @param msg SIP message + * @param rport Rport value + */ void sip_reply_addr(struct sa *addr, const struct sip_msg *msg, bool rport) { uint16_t port; diff --git a/src/sip/request.c b/src/sip/request.c index 05d8e89..9d685e9 100644 --- a/src/sip/request.c +++ b/src/sip/request.c @@ -559,6 +559,24 @@ static int addr_lookup(struct sip_request *req, const char *name) } +/** + * Send a SIP request + * + * @param reqp Pointer to allocated SIP request object + * @param sip SIP Stack + * @param stateful Stateful client transaction + * @param met SIP Method string + * @param metl Length of SIP Method string + * @param uri Request URI + * @param uril Length of Request URI string + * @param route Next hop route URI + * @param mb Buffer containing SIP request + * @param sendh Send handler + * @param resph Response handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int sip_request(struct sip_request **reqp, struct sip *sip, bool stateful, const char *met, int metl, const char *uri, int uril, const struct uri *route, struct mbuf *mb, @@ -669,6 +687,23 @@ int sip_request(struct sip_request **reqp, struct sip *sip, bool stateful, } +/** + * Send a SIP request with formatted arguments + * + * @param reqp Pointer to allocated SIP request object + * @param sip SIP Stack + * @param stateful Stateful client transaction + * @param met Null-terminated SIP Method string + * @param uri Null-terminated Request URI string + * @param route Next hop route URI (optional) + * @param auth SIP authentication state + * @param sendh Send handler + * @param resph Response handler + * @param arg Handler argument + * @param fmt Formatted SIP headers + * + * @return 0 if success, otherwise errorcode + */ int sip_requestf(struct sip_request **reqp, struct sip *sip, bool stateful, const char *met, const char *uri, const struct uri *route, struct sip_auth *auth, sip_send_h *sendh, sip_resp_h *resph, @@ -727,6 +762,23 @@ int sip_requestf(struct sip_request **reqp, struct sip *sip, bool stateful, } +/** + * Send a SIP dialog request with formatted arguments + * + * @param reqp Pointer to allocated SIP request object + * @param sip SIP Stack + * @param stateful Stateful client transaction + * @param met Null-terminated SIP Method string + * @param dlg SIP Dialog state + * @param cseq CSeq number + * @param auth SIP authentication state + * @param sendh Send handler + * @param resph Response handler + * @param arg Handler argument + * @param fmt Formatted SIP headers + * + * @return 0 if success, otherwise errorcode + */ int sip_drequestf(struct sip_request **reqp, struct sip *sip, bool stateful, const char *met, struct sip_dialog *dlg, uint32_t cseq, struct sip_auth *auth, sip_send_h *sendh, sip_resp_h *resph, @@ -777,6 +829,11 @@ int sip_drequestf(struct sip_request **reqp, struct sip *sip, bool stateful, } +/** + * Cancel a pending SIP Request + * + * @param req SIP Request + */ void sip_request_cancel(struct sip_request *req) { if (!req || req->canceled) @@ -800,6 +857,14 @@ void sip_request_close(struct sip *sip) } +/** + * Check if a SIP request loops + * + * @param ls Loop state + * @param scode Status code from SIP response + * + * @return True if loops, otherwise false + */ bool sip_request_loops(struct sip_loopstate *ls, uint16_t scode) { bool loop = false; @@ -838,6 +903,11 @@ bool sip_request_loops(struct sip_loopstate *ls, uint16_t scode) } +/** + * Reset the loop state + * + * @param ls Loop state + */ void sip_loopstate_reset(struct sip_loopstate *ls) { if (!ls) diff --git a/src/sip/sip.c b/src/sip/sip.c index 676e4b1..8d41948 100644 --- a/src/sip/sip.c +++ b/src/sip/sip.c @@ -66,6 +66,20 @@ static void lsnr_destructor(void *arg) } +/** + * Allocate a SIP stack instance + * + * @param sipp Pointer to allocated SIP stack + * @param dnsc DNS Client (optional) + * @param ctsz Size of client transactions hashtable (power of 2) + * @param stsz Size of server transactions hashtable (power of 2) + * @param tcsz Size of SIP transport hashtable (power of 2) + * @param software Software identifier + * @param exith SIP-stack exit handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int sip_alloc(struct sip **sipp, struct dnsc *dnsc, uint32_t ctsz, uint32_t stsz, uint32_t tcsz, const char *software, sip_exit_h *exith, void *arg) @@ -120,6 +134,12 @@ int sip_alloc(struct sip **sipp, struct dnsc *dnsc, uint32_t ctsz, } +/** + * Close the SIP stack instance + * + * @param sip SIP stack instance + * @param force Don't wait for transactions to complete + */ void sip_close(struct sip *sip, bool force) { if (!sip) @@ -136,6 +156,17 @@ void sip_close(struct sip *sip, bool force) } +/** + * Send a SIP message + * + * @param sip SIP stack instance + * @param sock Optional socket to send from + * @param tp SIP transport + * @param dst Destination network address + * @param mb Buffer containing SIP message + * + * @return 0 if success, otherwise errorcode + */ int sip_send(struct sip *sip, void *sock, enum sip_transp tp, const struct sa *dst, struct mbuf *mb) { @@ -143,6 +174,17 @@ int sip_send(struct sip *sip, void *sock, enum sip_transp tp, } +/** + * Listen for incoming SIP Requests and SIP Responses + * + * @param lsnrp Pointer to allocated listener + * @param sip SIP stack instance + * @param req True for Request, false for Response + * @param msgh SIP message handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int sip_listen(struct sip_lsnr **lsnrp, struct sip *sip, bool req, sip_msg_h *msgh, void *arg) { @@ -170,6 +212,14 @@ int sip_listen(struct sip_lsnr **lsnrp, struct sip *sip, bool req, } +/** + * Print debug information about the SIP stack + * + * @param pf Print function for debug output + * @param sip SIP stack instance + * + * @return 0 if success, otherwise errorcode + */ int sip_debug(struct re_printf *pf, const struct sip *sip) { int err; diff --git a/src/sip/strans.c b/src/sip/strans.c index 1c96aae..f2d4460 100644 --- a/src/sip/strans.c +++ b/src/sip/strans.c @@ -237,6 +237,17 @@ static bool request_handler(const struct sip_msg *msg, void *arg) } +/** + * Allocate a SIP Server Transaction + * + * @param stp Pointer to allocated SIP Server Transaction + * @param sip SIP Stack instance + * @param msg Incoming SIP message + * @param cancelh Cancel handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int sip_strans_alloc(struct sip_strans **stp, struct sip *sip, const struct sip_msg *msg, sip_cancel_h *cancelh, void *arg) @@ -266,6 +277,18 @@ int sip_strans_alloc(struct sip_strans **stp, struct sip *sip, } +/** + * Reply using a SIP Server Transaction + * + * @param stp Pointer to allocated SIP Server Transaction + * @param sip SIP Stack instance + * @param msg Incoming SIP message + * @param dst Destination network address + * @param scode Response status code + * @param mb Buffer containing SIP response + * + * @return 0 if success, otherwise errorcode + */ int sip_strans_reply(struct sip_strans **stp, struct sip *sip, const struct sip_msg *msg, const struct sa *dst, uint16_t scode, struct mbuf *mb) diff --git a/src/sip/transp.c b/src/sip/transp.c index 7572145..89470db 100644 --- a/src/sip/transp.c +++ b/src/sip/transp.c @@ -1,5 +1,5 @@ /** - * @file transp.c SIP Transport + * @file sip/transp.c SIP Transport * * Copyright (C) 2010 Creytiv.com */ @@ -614,6 +614,16 @@ int sip_transp_init(struct sip *sip, uint32_t sz) } +/** + * Add a SIP transport + * + * @param sip SIP stack instance + * @param tp SIP Transport + * @param laddr Local network address + * @param ... Optional transport parameters such as TLS context + * + * @return 0 if success, otherwise errorcode + */ int sip_transp_add(struct sip *sip, enum sip_transp tp, const struct sa *laddr, ...) { @@ -680,6 +690,11 @@ int sip_transp_add(struct sip *sip, enum sip_transp tp, } +/** + * Flush all transports of a SIP stack instance + * + * @param sip SIP stack instance + */ void sip_transp_flush(struct sip *sip) { if (!sip) @@ -766,6 +781,15 @@ bool sip_transp_supported(struct sip *sip, enum sip_transp tp, int af) } +/** + * Check if network address is part of SIP transports + * + * @param sip SIP stack instance + * @param tp SIP transport + * @param laddr Local network address to check + * + * @return True if part of SIP transports, otherwise false + */ bool sip_transp_isladdr(const struct sip *sip, enum sip_transp tp, const struct sa *laddr) { @@ -791,6 +815,13 @@ bool sip_transp_isladdr(const struct sip *sip, enum sip_transp tp, } +/** + * Get the name of a given SIP Transport + * + * @param tp SIP Transport + * + * @return Name of the corresponding SIP Transport + */ const char *sip_transp_name(enum sip_transp tp) { switch (tp) { @@ -815,6 +846,13 @@ const char *sip_transp_srvid(enum sip_transp tp) } +/** + * Get the transport parameters for a given SIP Transport + * + * @param tp SIP Transport + * + * @return Transport parameters of the corresponding SIP Transport + */ const char *sip_transp_param(enum sip_transp tp) { switch (tp) { @@ -839,6 +877,14 @@ bool sip_transp_reliable(enum sip_transp tp) } +/** + * Get the default port number for a given SIP Transport + * + * @param tp SIP Transport + * @param port Port number + * + * @return Corresponding port number + */ uint16_t sip_transp_port(enum sip_transp tp, uint16_t port) { if (port) @@ -878,6 +924,13 @@ int sip_transp_debug(struct re_printf *pf, const struct sip *sip) } +/** + * Get the TCP Connection from a SIP Message + * + * @param msg SIP Message + * + * @return TCP Connection if reliable transport, otherwise NULL + */ struct tcp_conn *sip_msg_tcpconn(const struct sip_msg *msg) { if (!msg || !msg->sock) diff --git a/src/sip/via.c b/src/sip/via.c index c99cd1d..b8ea095 100644 --- a/src/sip/via.c +++ b/src/sip/via.c @@ -26,6 +26,14 @@ static int decode_hostport(const struct pl *hostport, struct pl *host, } +/** + * Decode a pointer-length string into a SIP Via header + * + * @param via SIP Via header + * @param pl Pointer-length string + * + * @return 0 for success, otherwise errorcode + */ int sip_via_decode(struct sip_via *via, const struct pl *pl) { struct pl transp, host, port;