[svn-commits] oej: trunk r128485 - /trunk/channels/chan_sip.c
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Sun Jul 6 13:25:40 CDT 2008
Author: oej
Date: Sun Jul 6 13:25:39 2008
New Revision: 128485
URL: http://svn.digium.com/view/asterisk?view=rev&rev=128485
Log:
More doxygen comments.
Modified:
trunk/channels/chan_sip.c
Modified: trunk/channels/chan_sip.c
URL: http://svn.digium.com/view/asterisk/trunk/channels/chan_sip.c?view=diff&rev=128485&r1=128484&r2=128485
==============================================================================
--- trunk/channels/chan_sip.c (original)
+++ trunk/channels/chan_sip.c Sun Jul 6 13:25:39 2008
@@ -293,9 +293,10 @@
};
+/*! \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 @@
{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 @@
PARSE_REGISTER_QUERY,
};
+/*! \brief Type of subscription, based on the packages we do support */
enum subscriptiontype {
NONE = 0,
XPIDF_XML,
@@ -449,11 +454,13 @@
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 @@
*/
#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 @@
#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 @@
#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_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 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 @@
#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 @@
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 @@
-/*! \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 @@
/*! 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 @@
#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 @@
#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 @@
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 @@
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_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 @@
/*! \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 @@
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 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
More information about the svn-commits
mailing list