freetdm: documentation

libs/freetdm/docs/Doxygen.conf

@@ -3,9 +3,9 @@
 #---------------------------------------------------------------------------
 # Project related configuration options
 #---------------------------------------------------------------------------
-PROJECT_NAME           = OpenZAP
+PROJECT_NAME           = FreeTDM
 PROJECT_NUMBER         = 
-OUTPUT_DIRECTORY       = .
+OUTPUT_DIRECTORY       = docs/
 CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English
 USE_WINDOWS_ENCODING   = YES
@@ -39,7 +39,7 @@ OPTIMIZE_OUTPUT_FOR_C  = YES
 OPTIMIZE_OUTPUT_JAVA   = NO
 DISTRIBUTE_GROUP_DOC   = NO
 SUBGROUPING            = YES
-IGNORE_PREFIX          = zap_ ZAP_ Q921 Q931
+IGNORE_PREFIX          = ftdm_ FTDM_ Q921 Q931
 
 #---------------------------------------------------------------------------
 # Build related configuration options
@@ -83,18 +83,7 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = ../src ../src/include \
+INPUT                  = src/include/freetdm.h 
-                         ../src/isdn ../src/isdn/include \
-                         ../mod_openzap ../ \
-                         ../src/ozmod \
-                         ../src/ozmod/ozmod_analog \
-                         ../src/ozmod/ozmod_analog_em \
-                         ../src/ozmod/ozmod_isdn \
-                         ../src/ozmod/ozmod_pika \
-                         ../src/ozmod/ozmod_skel \
-                         ../src/ozmod/ozmod_ss7_boost \
-                         ../src/ozmod/ozmod_wanpipe \
-                         ../src/ozmod/ozmod_zt
 
 FILE_PATTERNS          = *.c \
                          *.cc \
@@ -149,7 +138,7 @@ VERBATIM_HEADERS       = NO
 #---------------------------------------------------------------------------
 ALPHABETICAL_INDEX     = YES
 COLS_IN_ALPHA_INDEX    = 1
-IGNORE_PREFIX          = zap_
+IGNORE_PREFIX          = ftdm_
 #---------------------------------------------------------------------------
 # configuration options related to the HTML output
 #---------------------------------------------------------------------------
@@ -161,7 +150,7 @@ HTML_FOOTER            =
 HTML_STYLESHEET        = 
 HTML_ALIGN_MEMBERS     = YES
 GENERATE_HTMLHELP      = NO
-CHM_FILE               = freeswitch.chm
+CHM_FILE               = freetdm.chm
 HHC_LOCATION           = 
 GENERATE_CHI           = YES
 BINARY_TOC             = NO
@@ -230,9 +219,8 @@ EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = NO
 INCLUDE_PATH           = 
 INCLUDE_FILE_PATTERNS  = *.h
-PREDEFINED             = ZAP_DECLARE(x)=x \
+PREDEFINED             = FT_DECLARE(x)=x \
-					APR_DECLARE(x)=x \
+					FT_MOD_DECLARE(x)=x \
-					ZAP_MOD_DECLARE(x)=x \
 					DoxyDefine(x)=x
 					
 EXPAND_AS_DEFINED      = NO

libs/freetdm/src/ftdm_io.c

@@ -512,30 +512,6 @@ static void ftdm_span_add(ftdm_span_t *span)
 	ftdm_mutex_unlock(globals.span_mutex);
 }
 
-#if 0
-static void ftdm_span_del(ftdm_span_t *span)
-{
-	ftdm_span_t *last = NULL, *sp;
-
-	ftdm_mutex_lock(globals.span_mutex);
-	for (sp = globals.spans; sp; sp = sp->next) {
-		
-		if (sp == span) {
-			if (last) {
-				last->next = sp->next;
-			} else {
-				globals.spans = sp->next;
-			}
-			hashtable_remove(globals.span_hash, (void *)sp->name);
-			break;
-		}
-
-		last = sp;
-	}
-	ftdm_mutex_unlock(globals.span_mutex);
-}
-#endif
-
 FT_DECLARE(ftdm_status_t) ftdm_span_stop(ftdm_span_t *span)
 {
 	if (span->stop) {
@@ -3066,10 +3042,10 @@ FT_DECLARE(ftdm_status_t) ftdm_channel_write(ftdm_channel_t *ftdmchan, void *dat
 	}
 
 
-    if (!ftdm_test_flag(ftdmchan, FTDM_CHANNEL_OPEN)) {
+	if (!ftdm_test_flag(ftdmchan, FTDM_CHANNEL_OPEN)) {
 		snprintf(ftdmchan->last_error, sizeof(ftdmchan->last_error), "channel not open");
-        return FTDM_FAIL;
+		return FTDM_FAIL;
-    }
+	}
 
 	if (!ftdmchan->fio->write) {
 		snprintf(ftdmchan->last_error, sizeof(ftdmchan->last_error), "method not implemented");
@@ -3110,7 +3086,7 @@ FT_DECLARE(ftdm_status_t) ftdm_channel_write(ftdm_channel_t *ftdmchan, void *dat
 			wdata[i] = ftdmchan->txgain_table[wdata[i]];
 		}
 	}
-    status = ftdmchan->fio->write(ftdmchan, data, datalen);
+	status = ftdmchan->fio->write(ftdmchan, data, datalen);
 
 	return status;
 }

libs/freetdm/src/include/freetdm.h

@@ -634,7 +634,8 @@ FT_DECLARE(ftdm_status_t) ftdm_channel_clear_token(ftdm_channel_t *ftdmchan, con
  * \brief Replace the given token with the new token
  *
  * \param ftdmchan The channel where the token is
- * \param token The token string. If NULL, all tokens in the channel are cleared
+ * \param old_token The token to replace
+ * \param new_token The token to put in place
  */
 FT_DECLARE(void) ftdm_channel_replace_token(ftdm_channel_t *ftdmchan, const char *old_token, const char *new_token);
 
@@ -710,6 +711,7 @@ FT_DECLARE(const char *) ftdm_channel_get_last_error(const ftdm_channel_t *ftdmc
  * \brief Get the current alarm bitmask for the channel
  *
  * \param ftdmchan The channel to get the alarm bitmask from
+ * \param alarmbits The alarm bitmask pointer to store the current alarms (you are responsible for allocation/deallocation)
  *
  * \retval FTDM_SUCCESS success
  * \retval FTDM_FAIL failure
@@ -729,6 +731,8 @@ FT_DECLARE(ftdm_chan_type_t) ftdm_channel_get_type(const ftdm_channel_t *ftdmcha
  * \brief Get the channel type
  *
  * \param ftdmchan The channel to get the type from
+ * \param dtmf DTMF buffer to store the dtmf (you are responsible for its allocation and deallocation)
+ * \param len The size of the DTMF buffer
  *
  * \retval channel type (FXO, FXS, B-channel, D-channel, etc)
  */
@@ -794,15 +798,13 @@ FT_DECLARE(ftdm_status_t) ftdm_span_next_event(ftdm_span_t *span, ftdm_event_t *
 FT_DECLARE(ftdm_status_t) ftdm_span_find(uint32_t id, ftdm_span_t **span);
 
 /*! 
- * \brief Find a span by its id
+ * \brief Get the last error string for the given span
  *
- * \param id The span id 
+ * \param span The span to get the last error from
- * \param span Pointer to store the span if found
  *
- * \retval FTDM_SUCCESS success (span is valid)
+ * \retval character string for the last error
- * \retval FTDM_FAIL failure (span is not valid)
  */
-FT_DECLARE(const char *) ftdm_span_get_last_error(const ftdm_span_t *ftdmchan);
+FT_DECLARE(const char *) ftdm_span_get_last_error(const ftdm_span_t *span);
 
 /*! 
  * \brief Create a new span (not needed if you are using freetdm.conf)
@@ -958,9 +960,22 @@ FT_DECLARE(ftdm_status_t) ftdm_channel_read(ftdm_channel_t *ftdmchan, void *data
 /*! 
  * \brief Write data to a channel
  *
+ * \note The difference between data and datasize is subtle but important.
+ *
+ *       datalen is a pointer to the size of the actual data that you want to write. This pointer
+ *       will be updated with the number of bytes actually written.
+ *       
+ *       datasize on the other hand is the size of the entire buffer provided in data, whether 
+ *       all of that buffer is in use or not is a different matter. The difference becomes
+ *       important only if you are using FreeTDM doing transcoding, for example, providing
+ *       a ulaw frame of 160 bytes but where the I/O device accepts input in signed linear,
+ *       the data to write will be 320 bytes, therefore datasize is expected to be at least
+ *       320 where datalen would be just 160.
+ *
  * \param ftdmchan The channel to write data to
  * \param data The pointer to the buffer to write
- * \param datalen The size in bytes of the provided buffer
+ * \param datasize The maximum number of bytes in data that can be used (in case transcoding is necessary)
+ * \param datalen The size of the actual data
  *
  * \retval FTDM_SUCCESS success (a suitable channel was found available)
  * \retval FTDM_FAIL failure (no suitable channel was found available)
@@ -1024,7 +1039,7 @@ FT_DECLARE(ftdm_status_t) ftdm_configure_span(ftdm_span_t *span, const char *typ
  * \param span The span to configure
  * \param type The signaling type ("boost", "isdn" and others, this depends on the available signaling modules)
  * \param sig_cb The callback that the signaling stack will use to notify about events
- * \param ... variable argument list with "var", value sequence, the variable and values are signaling type dependant
+ * \param parameters The array if signaling-specific parameters (the last member of the array MUST have its var member set to NULL, ie: .var = NULL)
  *
  * \retval FTDM_SUCCESS success 
  * \retval FTDM_FAIL failure 
@@ -1111,6 +1126,7 @@ FT_DECLARE(ftdm_status_t) ftdm_conf_node_create(const char *name, ftdm_conf_node
 /*! 
  * \brief Adds a new parameter to the specified configuration node
  *
+ * \param node The configuration node to add the param-val pair to
  * \param param The parameter name
  * \param val The parameter value
  *