stv0g/re
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

ice: doxygen comments

Browse source
This commit is contained in:
Richard Aas 2011-12-05 12:32:24 +00:00
parent 8f449c0ce9
commit cad21b5dcd
9 changed files with 231 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
include/re_ice.h
View file

@ -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

1
mk/Doxyfile
View file

@ -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 \

9
src/ice/candpair.c
View file

@ -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,

12
src/ice/chklist.c
View file

@ -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);

18
src/ice/gather.c
View file

@ -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)
{

58
src/ice/ice.c
View file

@ -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;

83
src/ice/icem.c
View file

@ -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;

42
src/ice/icesdp.c
View file

@ -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)

7
src/ice/util.c
View file

@ -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)
{