From cad21b5dcd1eec64c1b1d427ebae88936a13041d Mon Sep 17 00:00:00 2001 From: Richard Aas Date: Mon, 5 Dec 2011 12:32:24 +0000 Subject: [PATCH] ice: doxygen comments --- include/re_ice.h | 4 +++ mk/Doxyfile | 1 - src/ice/candpair.c | 9 +++++ src/ice/chklist.c | 12 +++++++ src/ice/gather.c | 18 ++++++++++ src/ice/ice.c | 58 ++++++++++++++++++++++++++++++++ src/ice/icem.c | 83 ++++++++++++++++++++++++++++++++++++++++++++++ src/ice/icesdp.c | 42 ++++++++++++++++++++++- src/ice/util.c | 7 +++- 9 files changed, 231 insertions(+), 3 deletions(-) diff --git a/include/re_ice.h b/include/re_ice.h index ffd3496..a6eb66f 100644 --- a/include/re_ice.h +++ b/include/re_ice.h @@ -4,16 +4,20 @@ * Copyright (C) 2010 Creytiv.com */ + +/** ICE mode */ enum ice_mode { ICE_MODE_FULL, ICE_MODE_LITE }; +/** ICE Component ID */ enum ice_compid { ICE_COMPID_RTP = 1, ICE_COMPID_RTCP = 2 }; +/** ICE Nomination */ enum ice_nomination { ICE_NOMINATION_REGULAR = 0, ICE_NOMINATION_AGGRESSIVE diff --git a/mk/Doxyfile b/mk/Doxyfile index 4c1a1de..e506c25 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/httpauth include/re_httpauth.h \ - src/ice include/re_ice.h \ src/sdp include/re_sdp.h \ src/sip/ include/re_sip.h \ src/sipsess/ include/re_sipsess.h \ diff --git a/src/ice/candpair.c b/src/ice/candpair.c index 04087b1..a80ea00 100644 --- a/src/ice/candpair.c +++ b/src/ice/candpair.c @@ -260,6 +260,9 @@ bool icem_candpair_iscompleted(const struct candpair *cp) /** * Compare local and remote candidates of two candidate pairs * + * @param cp1 First Candidate pair + * @param cp2 Second Candidate pair + * * @return true if match */ bool icem_candpair_cmp(const struct candpair *cp1, const struct candpair *cp2) @@ -275,6 +278,12 @@ bool icem_candpair_cmp(const struct candpair *cp1, const struct candpair *cp2) * Find the highest-priority candidate-pair in a given list, with * optional match parameters * + * @param lst List of candidate pairs + * @param lcand Local candidate (optional) + * @param rcand Remote candidate (optional) + * + * @return Matching candidate pair if found, otherwise NULL + * * note: assume list is sorted by priority */ struct candpair *icem_candpair_find(const struct list *lst, diff --git a/src/ice/chklist.c b/src/ice/chklist.c index eaeb741..cd2e428 100644 --- a/src/ice/chklist.c +++ b/src/ice/chklist.c @@ -138,6 +138,10 @@ static void candpair_set_states(struct icem *icem) * the agent forms candidate pairs, computes a candidate pair priority, * orders the pairs by priority, prunes them, and sets their states. * These steps are described in this section. + * + * @param icem ICE Media object + * + * @return 0 if success, otherwise errorcode */ int icem_checklist_form(struct icem *icem) { @@ -270,6 +274,14 @@ void icem_checklist_update(struct icem *icem) } +/** + * Get the Local address of the Selected Candidate pair, if available + * + * @param icem ICE Media object + * @param compid Component ID + * + * @return Local address if available, otherwise NULL + */ const struct sa *icem_selected_laddr(const struct icem *icem, uint8_t compid) { const struct icem_comp *comp = icem_comp_find(icem, compid); diff --git a/src/ice/gather.c b/src/ice/gather.c index 0ca0389..14d7526 100644 --- a/src/ice/gather.c +++ b/src/ice/gather.c @@ -215,6 +215,14 @@ static int start_gathering(struct icem *icem, const struct sa *stun_srv, } +/** + * Gather Server Reflexive candidates using STUN Server + * + * @param icem ICE Media object + * @param stun_srv STUN Server network address + * + * @return 0 if success, otherwise errorcode + */ int icem_gather_srflx(struct icem *icem, const struct sa *stun_srv) { if (!icem || !stun_srv) @@ -224,6 +232,16 @@ int icem_gather_srflx(struct icem *icem, const struct sa *stun_srv) } +/** + * Gather Relayed and Server Reflexive candidates using TURN Server + * + * @param icem ICE Media object + * @param stun_srv TURN Server network address + * @param username TURN Server username + * @param password TURN Server password + * + * @return 0 if success, otherwise errorcode + */ int icem_gather_relay(struct icem *icem, const struct sa *stun_srv, const char *username, const char *password) { diff --git a/src/ice/ice.c b/src/ice/ice.c index 3a58ac9..bcd91c0 100644 --- a/src/ice/ice.c +++ b/src/ice/ice.c @@ -53,6 +53,15 @@ static void ice_destructor(void *arg) } +/** + * Allocate a new ICE Session + * + * @param icep Pointer to allocated ICE Session object + * @param mode ICE Mode; Full-mode or Lite-mode + * @param offerer True if we are SDP offerer, otherwise false + * + * @return 0 if success, otherwise errorcode + */ int ice_alloc(struct ice **icep, enum ice_mode mode, bool offerer) { struct ice *ice; @@ -81,12 +90,25 @@ int ice_alloc(struct ice **icep, enum ice_mode mode, bool offerer) } +/** + * Get the ICE Configuration + * + * @param ice ICE Session + * + * @return ICE Configuration + */ struct ice_conf *ice_conf(struct ice *ice) { return ice ? &ice->conf : NULL; } +/** + * Set the offerer flag on the ICE Session + * + * @param ice ICE Session + * @param offerer True if offerer, otherwise false + */ void ice_set_offerer(struct ice *ice, bool offerer) { if (!ice) @@ -96,6 +118,13 @@ void ice_set_offerer(struct ice *ice, bool offerer) } +/** + * Start the Connectivity checks on the ICE Session + * + * @param ice ICE Session + * + * @return 0 if success, otherwise errorcode + */ int ice_conncheck_start(struct ice *ice) { struct le *le; @@ -111,6 +140,14 @@ int ice_conncheck_start(struct ice *ice) } +/** + * Print debug information for the ICE Session + * + * @param pf Print function for debug output + * @param ice ICE Session + * + * @return 0 if success, otherwise errorcode + */ int ice_debug(struct re_printf *pf, const struct ice *ice) { struct le *le; @@ -133,18 +170,39 @@ int ice_debug(struct re_printf *pf, const struct ice *ice) } +/** + * Get the list of ICE Media objects (struct icem) for the ICE Session + * + * @param ice ICE Session + * + * @return List of ICE Media objects + */ struct list *ice_medialist(const struct ice *ice) { return ice ? (struct list *)&ice->ml : NULL; } +/** + * Get the local Username fragment for the ICE Session + * + * @param ice ICE Session + * + * @return Local Username-fragment + */ const char *ice_ufrag(const struct ice *ice) { return ice ? ice->lufrag : NULL; } +/** + * Get the local password for the ICE Session + * + * @param ice ICE Session + * + * @return Local password + */ const char *ice_pwd(const struct ice *ice) { return ice ? ice->lpwd : NULL; diff --git a/src/ice/icem.c b/src/ice/icem.c index 3327431..b4ff445 100644 --- a/src/ice/icem.c +++ b/src/ice/icem.c @@ -38,6 +38,19 @@ static void icem_destructor(void *data) } +/** + * Add a new ICE Media object to the ICE Session + * + * @param icemp Pointer to allocated ICE Media object + * @param ice ICE Session + * @param proto Transport protocol + * @param layer Protocol stack layer + * @param gh Gather handler + * @param chkh Connectivity check handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int icem_alloc(struct icem **icemp, struct ice *ice, int proto, int layer, ice_gather_h *gh, ice_connchk_h *chkh, void *arg) { @@ -95,6 +108,12 @@ int icem_alloc(struct icem **icemp, struct ice *ice, int proto, int layer, } +/** + * Set the name of the ICE Media object, used for debugging + * + * @param icem ICE Media object + * @param name Media name + */ void icem_set_name(struct icem *icem, const char *name) { if (!icem) @@ -104,6 +123,15 @@ void icem_set_name(struct icem *icem, const char *name) } +/** + * Add a new component to the ICE Media object + * + * @param icem ICE Media object + * @param compid Component ID + * @param sock Application protocol socket + * + * @return 0 if success, otherwise errorcode + */ int icem_comp_add(struct icem *icem, uint8_t compid, void *sock) { struct icem_comp *comp; @@ -125,6 +153,17 @@ int icem_comp_add(struct icem *icem, uint8_t compid, void *sock) } +/** + * Add a new candidate to the ICE Media object + * + * @param icem ICE Media object + * @param compid Component ID + * @param lprio Local priority + * @param ifname Name of the network interface + * @param addr Local network address + * + * @return 0 if success, otherwise errorcode + */ int icem_cand_add(struct icem *icem, uint8_t compid, uint16_t lprio, const char *ifname, const struct sa *addr) { @@ -159,6 +198,14 @@ void icem_cand_redund_elim(struct icem *icem) } +/** + * Get the Default Candidate + * + * @param icem ICE Media object + * @param compid Component ID + * + * @return Default Candidate address if set, otherwise NULL + */ const struct sa *icem_cand_default(struct icem *icem, uint8_t compid) { const struct icem_comp *comp = icem_comp_find(icem, compid); @@ -202,6 +249,15 @@ bool icem_verify_support(struct icem *icem, uint8_t compid, } +/** + * Add a TURN Channel for the selected remote address + * + * @param icem ICE Media object + * @param compid Component ID + * @param raddr Remote network address + * + * @return 0 if success, otherwise errorcode + */ int icem_add_chan(struct icem *icem, uint8_t compid, const struct sa *raddr) { struct icem_comp *comp; @@ -240,6 +296,11 @@ static void purge_relayed(struct icem *icem, struct icem_comp *comp) } +/** + * Update the ICE Media object + * + * @param icem ICE Media object + */ void icem_update(struct icem *icem) { struct le *le; @@ -261,12 +322,27 @@ void icem_update(struct icem *icem) } +/** + * Get the ICE Mismatch flag of the ICE Media object + * + * @param icem ICE Media object + * + * @return True if ICE mismatch, otherwise false + */ bool icem_mismatch(const struct icem *icem) { return icem ? icem->mismatch : true; } +/** + * Print debug information for the ICE Media + * + * @param pf Print function for debug output + * @param icem ICE Media object + * + * @return 0 if success, otherwise errorcode + */ int icem_debug(struct re_printf *pf, const struct icem *icem) { struct le *le; @@ -303,6 +379,13 @@ int icem_debug(struct re_printf *pf, const struct icem *icem) } +/** + * Get the list of Local Candidates (struct cand) + * + * @param icem ICE Media object + * + * @return List of Local Candidates + */ struct list *icem_lcandl(const struct icem *icem) { return icem ? (struct list *)&icem->lcandl : NULL; diff --git a/src/ice/icesdp.c b/src/ice/icesdp.c index 9638c33..6397861 100644 --- a/src/ice/icesdp.c +++ b/src/ice/icesdp.c @@ -55,6 +55,14 @@ static enum ice_transp transp_resolve(const struct pl *transp) } +/** + * Encode SDP candidate attribute + * + * @param pf Print function + * @param cand Candidate to encode + * + * @return 0 if success, otherwise errorcode + */ int ice_cand_encode(struct re_printf *pf, const struct cand *cand) { int err; @@ -75,6 +83,13 @@ int ice_cand_encode(struct re_printf *pf, const struct cand *cand) } +/** + * Check if remote candidates are available + * + * @param icem ICE Media object + * + * @return True if available, otherwise false + */ bool ice_remotecands_avail(const struct icem *icem) { if (!icem) @@ -85,7 +100,14 @@ bool ice_remotecands_avail(const struct icem *icem) } -/* "remote-candidates" Attribute */ +/** + * Encode the SDP "remote-candidates" Attribute + * + * @param pf Print function + * @param icem ICE Media object + * + * @return 0 if success, otherwise errorcode + */ int ice_remotecands_encode(struct re_printf *pf, const struct icem *icem) { struct le *le; @@ -234,6 +256,15 @@ static int cand_decode(struct icem *icem, const char *val) } +/** + * Decode SDP session attributes + * + * @param ice ICE Session + * @param name Name of the SDP attribute + * @param value Value of the SDP attribute (optional) + * + * @return 0 if success, otherwise errorcode + */ int ice_sdp_decode(struct ice *ice, const char *name, const char *value) { if (!ice) @@ -256,6 +287,15 @@ int ice_sdp_decode(struct ice *ice, const char *name, const char *value) } +/** + * Decode SDP media attributes + * + * @param icem ICE Media object + * @param name Name of the SDP attribute + * @param value Value of the SDP attribute (optional) + * + * @return 0 if success, otherwise errorcode + */ int icem_sdp_decode(struct icem *icem, const char *name, const char *value) { if (!icem) diff --git a/src/ice/util.c b/src/ice/util.c index b8a0849..93746f2 100644 --- a/src/ice/util.c +++ b/src/ice/util.c @@ -96,7 +96,12 @@ void ice_switch_local_role(struct ice *ice) /** * Remove duplicate elements from list, preserving order * - * note: O (n ^ 2) + * @param list Linked list + * @param uh Unique handler (return object to remove) + * + * @return Number of elements removed + * + * @note: O (n ^ 2) */ uint32_t ice_list_unique(struct list *list, list_unique_h *uh) {