From 40c0e6ed47bf29aa9aa19965bee5e689908d19cd Mon Sep 17 00:00:00 2001 From: Olle Johansson Date: Sun, 6 Jul 2008 18:25:39 +0000 Subject: More doxygen comments. git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@128485 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- channels/chan_sip.c | 89 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 52 insertions(+), 37 deletions(-) (limited to 'channels') diff --git a/channels/chan_sip.c b/channels/chan_sip.c index 35f47fdd6..f22f6361a 100644 --- a/channels/chan_sip.c +++ b/channels/chan_sip.c @@ -293,9 +293,10 @@ enum transfermodes { }; +/*! \brief The result of a lot of functions */ enum sip_result { - AST_SUCCESS = 0, - AST_FAILURE = -1, + AST_SUCCESS = 0, /*! FALSE means success, funny enough */ + AST_FAILURE = -1, }; /*! \brief States for the INVITE transaction, not the dialog @@ -329,6 +330,9 @@ static const struct invstate2stringtable { {INV_CANCELLED, "Cancelled"} }; +/*! \brief When sending a SIP message, we can send with a few options, depending on + type of SIP request. UNRELIABLE is moslty used for responses to repeated requests, + where the original response would be sent RELIABLE in an INVITE transaction */ enum xmittype { XMIT_CRITICAL = 2, /*!< Transmit critical SIP message reliably, with re-transmits. If it fails, it's critical and will cause a teardown of the session */ @@ -342,6 +346,7 @@ enum parse_register_result { PARSE_REGISTER_QUERY, }; +/*! \brief Type of subscription, based on the packages we do support */ enum subscriptiontype { NONE = 0, XPIDF_XML, @@ -449,11 +454,13 @@ enum st_refresher { SESSION_TIMER_REFRESHER_UAS /*!< Session is refreshed by the UAS */ }; -/*!< Define some SIP transports */ +/*! \brief Define some implemented SIP transports + \note Asterisk does not support SCTP or UDP/DTLS +*/ enum sip_transport { - SIP_TRANSPORT_UDP = 1, - SIP_TRANSPORT_TCP = 1 << 1, - SIP_TRANSPORT_TLS = 1 << 2, + SIP_TRANSPORT_UDP = 1, /*!< Unreliable transport for SIP, needs retransmissions */ + SIP_TRANSPORT_TCP = 1 << 1, /*!< Reliable, but unsecure */ + SIP_TRANSPORT_TLS = 1 << 2, /*!< TCP/TLS - reliable and secure transport for signalling */ }; /*! \brief definition of a sip proxy server @@ -640,12 +647,18 @@ static const struct cfsip_options { */ #define ALLOWED_METHODS "INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY" -/*! \brief SIP Extensions we support */ +/*! \brief SIP Extensions we support + \note This should be generated based on the previous array + in combination with settings. + \todo We should not have "timer" if it's disabled in the configuration file. +*/ #define SUPPORTED_EXTENSIONS "replaces, timer" -/*! \brief Standard SIP and TLS port from RFC 3261. DO NOT CHANGE THIS */ +/*! \brief Standard SIP unsecure port for UDP and TCP from RFC 3261. DO NOT CHANGE THIS */ #define STANDARD_SIP_PORT 5060 +/*! \brief Standard SIP TLS port for sips: from RFC 3261. DO NOT CHANGE THIS */ #define STANDARD_TLS_PORT 5061 + /*! \note in many SIP headers, absence of a port number implies port 5060, * and this is why we cannot change the above constant. * There is a limited number of places in asterisk where we could, @@ -676,12 +689,12 @@ static const struct cfsip_options { #define DEFAULT_TOS_AUDIO 0 /*!< Audio packets should be marked as DSCP EF (Expedited Forwarding), but the default is 0 to be compatible with previous versions. */ #define DEFAULT_TOS_VIDEO 0 /*!< Video packets should be marked as DSCP AF41, but the default is 0 to be compatible with previous versions. */ #define DEFAULT_TOS_TEXT 0 /*!< Text packets should be marked as XXXX XXXX, but the default is 0 to be compatible with previous versions. */ -#define DEFAULT_COS_SIP 4 -#define DEFAULT_COS_AUDIO 5 -#define DEFAULT_COS_VIDEO 6 -#define DEFAULT_COS_TEXT 5 -#define DEFAULT_ALLOW_EXT_DOM TRUE -#define DEFAULT_REALM "asterisk" +#define DEFAULT_COS_SIP 4 /*!< Level 2 class of service for SIP signalling */ +#define DEFAULT_COS_AUDIO 5 /*!< Level 2 class of service for audio media */ +#define DEFAULT_COS_VIDEO 6 /*!< Level 2 class of service for video media */ +#define DEFAULT_COS_TEXT 5 /*!< Level 2 class of service for text media (T.140) */ +#define DEFAULT_ALLOW_EXT_DOM TRUE /*!< Allow external domains */ +#define DEFAULT_REALM "asterisk" /*!< Realm for HTTP digest authentication */ #define DEFAULT_NOTIFYRINGING TRUE #define DEFAULT_PEDANTIC FALSE #define DEFAULT_AUTOCREATEPEER FALSE @@ -692,7 +705,7 @@ static const struct cfsip_options { #ifndef DEFAULT_USERAGENT #define DEFAULT_USERAGENT "Asterisk PBX" /*!< Default Useragent: header unless re-defined in sip.conf */ #define DEFAULT_SDPSESSION "Asterisk PBX" /*!< Default SDP session name, (s=) header unless re-defined in sip.conf */ -#define DEFAULT_SDPOWNER "root" /*!< Default SDP username field in (o=) header unless re-defined in sip.conf */ +#define DEFAULT_SDPOWNER "root" /*!< Default SDP username field in (o=) header unless re-defined in sip.conf */ #endif /*@}*/ @@ -773,17 +786,18 @@ static int global_callevents; /*!< Whether we send manager events or not */ static int global_authfailureevents; /*!< Whether we send authentication failure manager events or not. Default no. */ static int global_t1; /*!< T1 time */ static int global_t1min; /*!< T1 roundtrip time minimum */ -static int global_timer_b; /*!< Timer B - RFC 3261 Section 17.1.1.2 */ -static int global_regextenonqualify; /*!< Whether to add/remove regexten when qualifying peers */ -static int global_autoframing; /*!< Turn autoframing on or off. */ +static int global_timer_b; /*!< Timer B - RFC 3261 Section 17.1.1.2 */ +static int global_regextenonqualify; /*!< Whether to add/remove regexten when qualifying peers */ +static int global_autoframing; /*!< Turn autoframing on or off. */ static enum transfermodes global_allowtransfer; /*!< SIP Refer restriction scheme */ static struct sip_proxy global_outboundproxy; /*!< Outbound proxy */ -static int global_matchexterniplocally; /*!< Match externip/externhost setting against localnet setting */ -static int global_qualifyfreq; /*!< Qualify frequency */ +static int global_matchexterniplocally; /*!< Match externip/externhost setting against localnet setting */ +static int global_qualifyfreq; /*!< Qualify frequency */ /*! \brief Codecs that we support by default: */ static int global_capability = AST_FORMAT_ULAW | AST_FORMAT_ALAW | AST_FORMAT_GSM | AST_FORMAT_H263; + static enum st_mode global_st_mode; /*!< Mode of operation for Session-Timers */ static enum st_refresher global_st_refresher; /*!< Session-Timer refresher */ static int global_min_se; /*!< Lowest threshold for session refresh interval */ @@ -801,14 +815,13 @@ static int regobjs = 0; /*!< Registry objects */ /* }@ */ static struct ast_flags global_flags[2] = {{0}}; /*!< global SIP_ flags */ -static char used_context[AST_MAX_CONTEXT]; /*!< name of automatically created context for unloading */ +static char used_context[AST_MAX_CONTEXT]; /*!< name of automatically created context for unloading */ AST_MUTEX_DEFINE_STATIC(netlock); /*! \brief Protect the monitoring thread, so only one process can kill or start it, and not when it's doing something critical. */ - AST_MUTEX_DEFINE_STATIC(monlock); AST_MUTEX_DEFINE_STATIC(sip_reload_lock); @@ -829,12 +842,12 @@ static int *sipsock_read_id; /*!< ID of IO entry for sipsock FD */ #define DEC_CALL_RINGING 2 #define INC_CALL_RINGING 3 -/*!< The SIP socket definition */ +/*! \brief The SIP socket definition */ struct sip_socket { - enum sip_transport type; - int fd; + enum sip_transport type; /*!< UDP, TCP or TLS */ + int fd; /*!< Filed descriptor, the actual socket */ uint16_t port; - struct ast_tcptls_session_instance *ser; + struct ast_tcptls_session_instance *ser; /* If tcp or tls, a socket manager */ }; /*! \brief sip_request: The data grabbed from the UDP socket @@ -1097,8 +1110,8 @@ enum sip_debug_e { static enum sip_debug_e sipdebug; /*! \brief extra debugging for 'text' related events. - * At thie moment this is set together with sip_debug_console. - * It should either go away or be implemented properly. + * At the moment this is set together with sip_debug_console. + * \note It should either go away or be implemented properly. */ static int sipdebug_text; @@ -1210,7 +1223,7 @@ struct sip_st_cfg { -/*! \brief sip_pvt: structures used for each SIP dialog, ie. a call, a registration, a subscribe. +/*! \brief Structure used for each SIP dialog, ie. a call, a registration, a subscribe. * Created and initialized by sip_alloc(), the descriptor goes into the list of * descriptors (dialoglist). */ @@ -1364,7 +1377,7 @@ struct sip_pvt { /*! Max entires in the history list for a sip_pvt */ #define MAX_HISTORY_ENTRIES 50 -/*! +/*! \brief * Here we implement the container for dialogs (sip_pvt), defining * generic wrapper functions to ease the transition from the current * implementation (a single linked list) to a different container. @@ -1378,7 +1391,7 @@ struct ao2_container *dialogs; #define sip_pvt_trylock(x) ao2_trylock(x) #define sip_pvt_unlock(x) ao2_unlock(x) -/*! +/*! \brief * when we create or delete references, make sure to use these * functions so we keep track of the refcounts. * To simplify the code, we allow a NULL to be passed to dialog_unref(). @@ -1386,6 +1399,7 @@ struct ao2_container *dialogs; #ifdef REF_DEBUG #define dialog_ref(arg1,arg2) dialog_ref_debug((arg1),(arg2), __FILE__, __LINE__, __PRETTY_FUNCTION__) #define dialog_unref(arg1,arg2) dialog_unref_debug((arg1),(arg2), __FILE__, __LINE__, __PRETTY_FUNCTION__) + static struct sip_pvt *dialog_ref_debug(struct sip_pvt *p, char *tag, char *file, int line, const char *func) { if (p) @@ -1567,7 +1581,7 @@ struct sip_registry { AST_STRING_FIELD(callback); /*!< Contact extension */ AST_STRING_FIELD(random); ); - enum sip_transport transport; + enum sip_transport transport; /*!< Transport for this registration UDP, TCP or TLS */ int portno; /*!< Optional port override */ int expire; /*!< Sched ID of expiration */ int expiry; /*!< Value to use for the Expires header */ @@ -1585,11 +1599,12 @@ struct sip_registry { char lastmsg[256]; /*!< Last Message sent/received */ }; +/*! \brief Definition of a thread that handles a socket */ struct sip_threadinfo { int stop; pthread_t threadid; struct ast_tcptls_session_instance *ser; - enum sip_transport type; /* We keep a copy of the type here so we can display it in the connection list */ + enum sip_transport type; /*!< We keep a copy of the type here so we can display it in the connection list */ AST_LIST_ENTRY(sip_threadinfo) list; }; @@ -1600,7 +1615,7 @@ static int hash_peer_size = 17; static int hash_dialog_size = 17; static int hash_user_size = 17; #else -static int hash_peer_size = 563; +static int hash_peer_size = 563; /*!< Size of peer hash table, prime number preferred! */ static int hash_dialog_size = 563; static int hash_user_size = 563; #endif @@ -1608,7 +1623,7 @@ static int hash_user_size = 563; /*! \brief The thread list of TCP threads */ static AST_LIST_HEAD_STATIC(threadl, sip_threadinfo); -/*! \brief The peer list: Peers and Friends */ +/*! \brief The peer list: Users, Peers and Friends */ struct ao2_container *peers; struct ao2_container *peers_by_ip; @@ -1618,7 +1633,7 @@ static struct ast_register_list { int recheck; } regl; -/*! +/*! \brief * \note The only member of the peer used here is the name field */ static int peer_hash_cb(const void *obj, const int flags) @@ -1731,7 +1746,7 @@ static struct sip_auth *authl = NULL; */ static int sipsock = -1; -static struct sockaddr_in bindaddr; /*!< The address we bind to */ +static struct sockaddr_in bindaddr; /*!< UDP: The address we bind to */ /*! \brief our (internal) default address/port to put in SIP/SDP messages * internip is initialized picking a suitable address from one of the -- cgit v1.2.3