From 10ac4a10bca82c94e8d5be37c0f35c099c9b225a Mon Sep 17 00:00:00 2001 From: paulc Date: Thu, 8 Jun 2006 18:31:00 +0000 Subject: [PATCH] API docs can be built with doxygen. Also cleaned headers to generate proper documentation. git-svn-id: http://yate.null.ro/svn/yate/trunk@845 acf43c95-373e-0410-b603-e72c3f656dc1 --- Doxyfile | 214 +++++++++++++++++++++++++++++++++++++++ Makefile.in | 24 ++++- configure.in | 31 ++++++ contrib/ypbx/yatepbx.h | 2 +- contrib/yrtp/yatertp.h | 13 ++- contrib/ysip/yatesip.h | 4 +- contrib/yss7/address.cpp | 1 - contrib/yss7/layer2.cpp | 5 +- contrib/yss7/layer3.cpp | 79 +++++++++++++-- contrib/yss7/router.cpp | 8 +- contrib/yss7/yatess7.h | 105 +++++++++++++++---- docs/api/.cvsignore | 1 + kdoc-filter.sh | 15 ++- yatecbase.h | 5 +- yateclass.h | 58 ++++++++--- yatengine.h | 12 ++- yatephone.h | 8 +- 17 files changed, 514 insertions(+), 71 deletions(-) create mode 100644 Doxyfile diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 00000000..5ed0dccb --- /dev/null +++ b/Doxyfile @@ -0,0 +1,214 @@ +# Doxyfile 1.3.5 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +PROJECT_NAME = Yate +PROJECT_NUMBER = +OUTPUT_DIRECTORY = docs +OUTPUT_LANGUAGE = English +USE_WINDOWS_ENCODING = NO +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = NO +INHERIT_DOCS = YES +DISTRIBUTE_GROUP_DOC = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +SUBGROUPING = YES +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = YES +SHOW_INCLUDE_FILES = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = NO +WARN_IF_DOC_ERROR = YES +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = yatecbase.h \ + yateclass.h \ + yatengine.h \ + yatephone.h \ + contrib/ysip/yatesip.h \ + contrib/yrtp/yatertp.h \ + contrib/ypbx/yatepbx.h \ + contrib/yss7/yatess7.h +FILE_PATTERNS = +RECURSIVE = NO +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = ./kdoc-filter.sh +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +VERBATIM_HEADERS = YES +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = api +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = NO +USE_PDFLATEX = NO +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = NO +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = NO +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::addtions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = YES +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +MAX_DOT_GRAPH_WIDTH = 1024 +MAX_DOT_GRAPH_HEIGHT = 1024 +MAX_DOT_GRAPH_DEPTH = 0 +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::addtions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/Makefile.in b/Makefile.in index 148cfac9..4ef5ee6b 100644 --- a/Makefile.in +++ b/Makefile.in @@ -31,6 +31,14 @@ CLEANS = $(PROGS) $(SLIBS) $(LIBS) $(OBJS) yatepaths.h core COMPILE = $(CXX) $(DEFS) $(DEBUG) $(INCLUDES) $(CFLAGS) LINK = $(CXX) $(LDFLAGS) +DOCGEN := +ifneq (_@KDOC_BIN@,_) +DOCGEN := @KDOC_BIN@ -C ./kdoc-filter.sh -d docs/api/ $(INCS) contrib/ysip/yatesip.h contrib/yrtp/yatertp.h +endif +ifneq (_@DOXYGEN_BIN@,_) +DOCGEN := @DOXYGEN_BIN@ Doxyfile +endif + prefix = @prefix@ exec_prefix = @exec_prefix@ @@ -88,7 +96,7 @@ clean-tables: check-topdir $(MAKE) -C ./tables -f Makefile.tables mrproper clean-apidocs: check-topdir - -rm docs/api/*.html + -rm docs/api/*.html docs/api/*.png distclean: check-topdir clean clean-config-files @@ -99,11 +107,16 @@ cvsclean: check-topdir clean clean-tables clean-apidocs clean-config-files engine: tables library libyate.so $(PROGS) apidocs-build: check-topdir - kdoc -C ./kdoc-filter.sh -d docs/api/ $(INCS) contrib/ysip/yatesip.h contrib/yrtp/yatertp.h + @if [ -n "$(DOCGEN)" ]; then \ + $(DOCGEN) ; \ + else \ + echo "Neither kdoc or doxygen is installed!" ; exit 1 ; \ + fi apidocs: @srcdir@/docs/api/index.html -@srcdir@/docs/api/index.html: @srcdir@/yateclass.h @srcdir@/yatengine.h \ +@srcdir@/docs/api/index.html: Doxyfile \ + @srcdir@/yateclass.h @srcdir@/yatengine.h \ @srcdir@/yatephone.h @srcdir@/yatecbase.h \ @srcdir@/contrib/ysip/yatesip.h @srcdir@/contrib/yrtp/yatertp.h $(MAKE) apidocs-build @@ -181,8 +194,9 @@ install-noapi: all done ; install-api: apidocs + mkdir -p "$(DESTDIR)$(docdir)/api/" && \ install -m 0644 @srcdir@/docs/*.html "$(DESTDIR)$(docdir)/" && \ - install -m 0644 @srcdir@/docs/api/*.html "$(DESTDIR)$(docdir)/api/" + install -m 0644 @srcdir@/docs/api/*.* "$(DESTDIR)$(docdir)/api/" uninstall uninstall-root: @-for i in $(SLIBS) ; do \ @@ -268,6 +282,6 @@ help: @echo -e 'Usual make targets:\n\ all engine contrib modules clients apidocs test everything\n\ install uninstall install-noapi install-root uninstall-root\n\ - clean distclean cvsclean (avoid this one!)\n\ + clean distclean cvsclean (avoid this one!) clean-apidocs\n\ debug ddebug xdebug (carefull!)\n\ snapshot tarball' diff --git a/configure.in b/configure.in index fbe7f850..eb18337d 100644 --- a/configure.in +++ b/configure.in @@ -626,6 +626,37 @@ AC_SUBST(MODULE_LDRELAX) AC_SUBST(MODULE_LDFLAGS) AC_SUBST(MODULE_SYMBOLS) +DOXYGEN_BIN="" +AC_ARG_WITH(doxygen,AC_HELP_STRING([--with-doxygen=EXE],[use doxygen to generate API docs (default: PATH)]),[ac_cv_use_doxygen=$withval],[ac_cv_use_doxygen=yes]) +if [[ "x$ac_cv_use_doxygen" != "xno" ]]; then +test "x$ac_cv_use_doxygen" = "xyes" && ac_cv_use_doxygen=`which doxygen 2>/dev/null` +AC_MSG_CHECKING([for doxygen version]) +if [[ "x$ac_cv_use_doxygen" != "x" -a -x "$ac_cv_use_doxygen" ]]; then +DOXYGEN_BIN="$ac_cv_use_doxygen" +ac_cv_use_doxygen=`$DOXYGEN_BIN --version 2>/dev/null` +else +ac_cv_use_doxygen="no" +fi +AC_MSG_RESULT([$ac_cv_use_doxygen]) +fi +AC_SUBST(DOXYGEN_BIN) + +KDOC_BIN="" +AC_ARG_WITH(kdoc,AC_HELP_STRING([--with-kdoc=EXE],[use kdoc to generate API docs (default: PATH)]),[ac_cv_use_kdoc=$withval],[ac_cv_use_kdoc=yes]) +if [[ "x$ac_cv_use_kdoc" != "xno" ]]; then +test "x$ac_cv_use_kdoc" = "xyes" && ac_cv_use_kdoc=`which kdoc 2>/dev/null` +AC_MSG_CHECKING([for kdoc version]) +if [[ "x$ac_cv_use_kdoc" != "x" -a -x "$ac_cv_use_kdoc" ]]; then +KDOC_BIN="$ac_cv_use_kdoc" +ac_cv_use_kdoc=`$KDOC_BIN --version 2>&1 | awk '{ print $2 }'` +else +ac_cv_use_kdoc="no" +fi +AC_MSG_RESULT([$ac_cv_use_kdoc]) +fi +AC_SUBST(KDOC_BIN) + + AC_CONFIG_FILES([yate.spec yate.pc yateversn.h diff --git a/contrib/ypbx/yatepbx.h b/contrib/ypbx/yatepbx.h index c8d6b5af..1d6f6c90 100644 --- a/contrib/ypbx/yatepbx.h +++ b/contrib/ypbx/yatepbx.h @@ -1,4 +1,4 @@ -/** +/* * yatepbx.h * This file is part of the YATE Project http://YATE.null.ro * diff --git a/contrib/yrtp/yatertp.h b/contrib/yrtp/yatertp.h index 75868311..acaffff4 100644 --- a/contrib/yrtp/yatertp.h +++ b/contrib/yrtp/yatertp.h @@ -1,4 +1,4 @@ -/** +/* * yatertp.h * Yet Another RTP Stack * This file is part of the YATE Project http://YATE.null.ro @@ -148,13 +148,13 @@ public: protected: /** * Add a RTP processor to this group - * @param processor Pointer to the RTP processor to add + * @param proc Pointer to the RTP processor to add */ void join(RTPProcessor* proc); /** * Remove a RTP processor from this group - * @param processor Pointer to the RTP processor to remove + * @param proc Pointer to the RTP processor to remove */ void part(RTPProcessor* proc); @@ -170,6 +170,9 @@ private: class YRTP_API RTPTransport : public RTPProcessor { public: + /** + * Activation status of the transport + */ enum Activation { Inactive, Bound, @@ -178,7 +181,6 @@ public: /** * Constructor, creates an unconnected transport - * @param grp RTP group to join */ RTPTransport(); @@ -613,6 +615,9 @@ private: class YRTP_API RTPSession : public RTPProcessor { public: + /** + * Direction of the session + */ enum Direction { FullStop = 0, RecvOnly = 1, diff --git a/contrib/ysip/yatesip.h b/contrib/ysip/yatesip.h index f75f51e7..f810dfa2 100644 --- a/contrib/ysip/yatesip.h +++ b/contrib/ysip/yatesip.h @@ -1,4 +1,4 @@ -/** +/* * yatesip.h * Yet Another SIP Stack * This file is part of the YATE Project http://YATE.null.ro @@ -774,6 +774,7 @@ protected: /** * Constructor from previous auto authenticated transaction. This is used only internally * @param original Original transaction that failed authentication + * @param answer SIP answer that creates the new transaction */ SIPTransaction(SIPTransaction& original, SIPMessage* answer); @@ -1011,6 +1012,7 @@ public: /** * Add a message into the transaction list + * @param ep Party of the received message * @param buf A buffer containing the SIP message text * @param len The length of the message or -1 to interpret as C string * @return Pointer to the transaction or NULL if message was invalid diff --git a/contrib/yss7/address.cpp b/contrib/yss7/address.cpp index 27b89010..b71e3fda 100644 --- a/contrib/yss7/address.cpp +++ b/contrib/yss7/address.cpp @@ -119,7 +119,6 @@ bool SS7Label::assign(SS7CodePoint::Type type, const SS7MSU& msu) m_spc.unpack(type,((s[2] & 0xc0) >> 6) | (s[3] << 2) | ((s[4] & 0x0f) << 10)); m_sls = (s[4] >> 4) & 0x0f; return true; - return 4; case SS7CodePoint::ANSI: m_type = type; m_dpc.assign(s[3],s[2],s[1]); diff --git a/contrib/yss7/layer2.cpp b/contrib/yss7/layer2.cpp index 95b03b9e..7c587aba 100644 --- a/contrib/yss7/layer2.cpp +++ b/contrib/yss7/layer2.cpp @@ -194,8 +194,10 @@ void SS7MTP2::timerTick(const Time& when) m_interval = 0; unlock(); if (operational()) { - if (tout) + if (tout) { Debug(engine(),DebugInfo,"Proving period ended, link operational [%p]",this); + SS7Layer2::notify(); + } transmitFISU(); } else { @@ -423,6 +425,7 @@ void SS7MTP2::abortAlignment() m_interval = Time::now() + 1000000; m_queue.clear(); unlock(); + SS7Layer2::notify(); } bool SS7MTP2::startProving() diff --git a/contrib/yss7/layer3.cpp b/contrib/yss7/layer3.cpp index afb5a7e2..bab9ad0e 100644 --- a/contrib/yss7/layer3.cpp +++ b/contrib/yss7/layer3.cpp @@ -23,9 +23,12 @@ #include "yatess7.h" +#include using namespace TelEngine; +typedef GenPointer L2Pointer; + void SS7Layer3::attach(SS7L3User* l3user) { if (m_l3user == l3user) @@ -40,33 +43,87 @@ void SS7Layer3::attach(SS7L3User* l3user) SS7MTP3::SS7MTP3(SS7CodePoint::Type type) - : SS7Layer3(type) + : SS7Layer3(type), m_total(0), m_active(0) { setName("mtp3"); } +unsigned int SS7MTP3::countLinks() +{ + unsigned int total = 0; + unsigned int active = 0; + ObjList* l = &m_links; + for (; l; l = l->next()) { + L2Pointer* p = static_cast(l->get()); + if (!(p && *p)) + continue; + total++; + if ((*p)->operational()) + active++; + } + m_total = total; + m_active = active; + return active; +} + void SS7MTP3::attach(SS7Layer2* link) { if (!link) return; Debug(toString(),DebugStub,"Please implement SS7MTP3::attach()"); SignallingComponent::insert(link); - if (!m_links.find(link)) - m_links.append(new GenPointer(link)); + if (!m_links.find(link)) { + m_links.append(new L2Pointer(link)); + countLinks(); + } link->attach(this); } -bool SS7MTP3::transmitMSU(const SS7MSU& msu, int sls) +int SS7MTP3::transmitMSU(const SS7MSU& msu, int sls) { Debug(toString(),DebugStub,"Please implement SS7MTP3::transmitMSU(%p,%d) type=%d [%p]", &msu,sls,type(),this); - return false; + + if (!m_active) { + Debug(toString(),DebugMild,"Could not transmit MSU, %s [%p]", + m_total ? "all links are down" : "no data links attached",this); + return -1; + } + ObjList* l = (sls >= 0) ? &m_links : 0; + for (; l; l = l->next()) { + L2Pointer* p = static_cast(l->get()); + if (!(p && *p)) + continue; + SS7Layer2* link = *p; + if (link->sls() == sls) { + if (link->operational()) + return link->transmitMSU(msu) ? sls : -1; + // found link but is down - reroute + Debug(toString(),DebugMild,"Rerouting MSU for SLS=%d, link is down",sls); + sls = -1; + break; + } + } + + int n = ::random() % m_active; + l = &m_links; + for (; l; l = l->next()) { + L2Pointer* p = static_cast(l->get()); + if (!(p && *p)) + continue; + SS7Layer2* link = *p; + // wait until Nth operational link + if (link->operational() && (--n < 0) && link->transmitMSU(msu)) + return link->sls(); + // FIXME: try to rescan the list + } + return -1; } -bool SS7MTP3::receivedMSU(const SS7MSU& msu, SS7Layer2* link) +bool SS7MTP3::receivedMSU(const SS7MSU& msu, SS7Layer2* link, int sls) { - Debug(toString(),DebugStub,"Please implement SS7MTP3::receivedMSU(%p,%p) type=%d [%p]", - &msu,link,type(),this); + Debug(toString(),DebugStub,"Please implement SS7MTP3::receivedMSU(%p,%p,%d) type=%d [%p]", + &msu,link,sls,type(),this); unsigned int llen = SS7Label::length(type()); if (!llen) { Debug(toString(),DebugWarn,"Received MSU but codepoint type is unconfigured [%p]",this); @@ -90,4 +147,10 @@ bool SS7MTP3::receivedMSU(const SS7MSU& msu, SS7Layer2* link) return false; } +void SS7MTP3::notify(SS7Layer2* link) +{ + Debug(toString(),DebugStub,"Please implement SS7MTP3::notify(%p) [%p]", + link,this); +} + /* vi: set ts=8 sw=4 sts=4 noet: */ diff --git a/contrib/yss7/router.cpp b/contrib/yss7/router.cpp index 82a7dca2..a06e1cfc 100644 --- a/contrib/yss7/router.cpp +++ b/contrib/yss7/router.cpp @@ -48,15 +48,15 @@ void SS7Router::attach(SS7Layer4* service) service->attach(this); } -bool SS7Router::transmitMSU(const SS7MSU& msu, int sls) +int SS7Router::transmitMSU(const SS7MSU& msu, int sls) { Debug(toString(),DebugStub,"Please implement SS7Router::transmitMSU(%p,%d)",&msu,sls); - return false; + return -1; } -bool SS7Router::receivedMSU(const SS7MSU& msu, SS7Layer3* network) +bool SS7Router::receivedMSU(const SS7MSU& msu, SS7Layer3* network, int sls) { - Debug(toString(),DebugStub,"Please implement SS7Router::receivedMSU(%p,%p)",&msu,network); + Debug(toString(),DebugStub,"Please implement SS7Router::receivedMSU(%p,%p,%d)",&msu,network,sls); return false; } diff --git a/contrib/yss7/yatess7.h b/contrib/yss7/yatess7.h index 4a70d522..ccea71f6 100644 --- a/contrib/yss7/yatess7.h +++ b/contrib/yss7/yatess7.h @@ -1,4 +1,4 @@ -/** +/* * yatess7.h * Yet Another SS7 Stack * This file is part of the YATE Project http://YATE.null.ro @@ -388,7 +388,7 @@ public: /** * Attach a receiver to the interface - * @param iface Pointer to receiver to attach + * @param receiver Pointer to receiver to attach */ virtual void attach(SignallingReceiver* receiver); @@ -894,7 +894,7 @@ private: /** * Operator to write a routing label to a string * @param str String to append to - * @param cp Label to append to the string + * @param label Label to append to the string */ String& operator<<(String& str, const SS7Label& label); @@ -938,7 +938,7 @@ public: /** * Attach an user to this SS7 SCCP - * @param sccp Pointer to the SCCP user + * @param user Pointer to the SCCP user */ virtual void attach(SCCPUser* user); @@ -1023,9 +1023,17 @@ protected: * Process a MSU received from the Layer 2 component * @param msu Message data, starting with Service Indicator Octet * @param link Data link that delivered the MSU + * @param sls Signalling Link the MSU was received from * @return True if the MSU was processed */ - virtual bool receivedMSU(const SS7MSU& msu, SS7Layer2* link) = 0; + virtual bool receivedMSU(const SS7MSU& msu, SS7Layer2* link, int sls) = 0; + + /** + * Process a notification generated by the attached data link + * @param link Data link that generated the notification + * @return True if notification was processed + */ + virtual void notify(SS7Layer2* link) = 0; }; /** @@ -1116,6 +1124,20 @@ public: inline SS7L2User* user() const { return m_l2user; } + /** + * Get the Signalling Link Selection number allocated to this link + * @return SLS value assigned by the upper layer + */ + inline int sls() const + { return m_sls; } + + /** + * Assign a new Signalling Link Selection number + * @param linkSel New SLS to assign to this link + */ + inline void sls(int linkSel) + { if ((m_sls < 0) || !m_l2user) m_sls = linkSel; } + /** * Execute a control operation. Operations can change the link status or * can query the aligned status. @@ -1131,7 +1153,7 @@ protected: * Constructor */ inline SS7Layer2() - : m_l2user(0) + : m_l2user(0), m_sls(-1) { } /** @@ -1140,10 +1162,17 @@ protected: * @return True if message was successfully delivered to the user component */ inline bool receivedMSU(const SS7MSU& msu) - { return m_l2user && m_l2user->receivedMSU(msu,this); } + { return m_l2user && m_l2user->receivedMSU(msu,this,m_sls); } + + /** + * Notify out user part about a status change + */ + inline void notify() + { if (m_l2user) m_l2user->notify(this); } private: SS7L2User* m_l2user; + int m_sls; }; /** @@ -1164,10 +1193,11 @@ protected: /** * Process a MSU received from the Layer 3 component * @param msu Message data, starting with Service Indicator Octet - * @param link Network layer that delivered the MSU + * @param network Network layer that delivered the MSU + * @param sls Signalling Link the MSU was received from * @return True if the MSU was processed */ - virtual bool receivedMSU(const SS7MSU& msu, SS7Layer3* network) = 0; + virtual bool receivedMSU(const SS7MSU& msu, SS7Layer3* network, int sls) = 0; }; /** @@ -1181,9 +1211,9 @@ public: * Push a Message Signal Unit down the protocol stack * @param msu Message data, starting with Service Indicator Octet * @param sls Signalling Link Selection, negative to choose best - * @return True if message was successfully queued to a link + * @return Link the message was successfully queued to, negative for error */ - virtual bool transmitMSU(const SS7MSU& msu, int sls = -1) = 0; + virtual int transmitMSU(const SS7MSU& msu, int sls = -1) = 0; /** * Attach a Layer 3 user component to this network @@ -1217,10 +1247,11 @@ protected: /** * Push a received Message Signal Unit up the protocol stack * @param msu Message data, starting with Service Indicator Octet + * @param sls Signalling Link the MSU was received from * @return True if message was successfully delivered to the user component */ - inline bool receivedMSU(const SS7MSU& msu) - { return m_l3user && m_l3user->receivedMSU(msu,this); } + inline bool receivedMSU(const SS7MSU& msu, int sls) + { return m_l3user && m_l3user->receivedMSU(msu,this,sls); } private: SS7L3User* m_l3user; @@ -1236,7 +1267,7 @@ class YSS7_API SS7Layer4 : public SS7L3User public: /** * Attach a SS7 network or router to this service - * @param router Pointer to network or router to attach + * @param network Pointer to network or router to attach */ virtual void attach(SS7Layer3* network); @@ -1263,9 +1294,9 @@ public: * Push a Message Signal Unit down the protocol stack * @param msu Message data, starting with Service Indicator Octet * @param sls Signalling Link Selection, negative to choose best - * @return True if message was successfully queued to a link + * @return Link the message was successfully queued to, negative for error */ - virtual bool transmitMSU(const SS7MSU& msu, int sls = -1); + virtual int transmitMSU(const SS7MSU& msu, int sls = -1); /** * Attach a SS7 Layer 3 (network) to the router @@ -1283,10 +1314,11 @@ protected: /** * Process a MSU received from the Layer 3 component * @param msu Message data, starting with Service Indicator Octet - * @param link Network layer that delivered the MSU + * @param network Network layer that delivered the MSU + * @param sls Signalling Link the MSU was received from * @return True if the MSU was processed */ - virtual bool receivedMSU(const SS7MSU& msu, SS7Layer3* network); + virtual bool receivedMSU(const SS7MSU& msu, SS7Layer3* network, int sls); ObjList m_layer3; ObjList m_layer4; @@ -1473,9 +1505,9 @@ public: * Push a Message Signal Unit down the protocol stack * @param msu Message data, starting with Service Indicator Octet * @param sls Signalling Link Selection, negative to choose best - * @return True if message was successfully queued to a link + * @return Link the message was successfully queued to, negative for error */ - virtual bool transmitMSU(const SS7MSU& msu, int sls = -1); + virtual int transmitMSU(const SS7MSU& msu, int sls = -1); /** * Attach a SS7 Layer 2 (data link) to the network transport @@ -1483,16 +1515,47 @@ public: */ virtual void attach(SS7Layer2* link); + /** + * Get the total number of links attached + * @return Number of attached data links + */ + inline unsigned int linksTotal() const + { return m_total; } + + /** + * Get the number of links that are currently operational + * @return Number of operational data links + */ + inline unsigned int linksActive() const + { return m_active; } + protected: /** * Process a MSU received from the Layer 2 component * @param msu Message data, starting with Service Indicator Octet * @param link Data link that delivered the MSU + * @param sls Signalling Link the MSU was received from * @return True if the MSU was processed */ - virtual bool receivedMSU(const SS7MSU& msu, SS7Layer2* link); + virtual bool receivedMSU(const SS7MSU& msu, SS7Layer2* link, int sls); + /** + * Process a notification generated by the attached data link + * @param link Data link that generated the notification + * @return True if notification was processed + */ + virtual void notify(SS7Layer2* link); + + /** + * Count the total and active number of links + * @return Number of active links + */ + unsigned int countLinks(); + +private: ObjList m_links; + unsigned int m_total; + unsigned int m_active; }; /** diff --git a/docs/api/.cvsignore b/docs/api/.cvsignore index 6b7e947b..3407310f 100644 --- a/docs/api/.cvsignore +++ b/docs/api/.cvsignore @@ -1,5 +1,6 @@ core* *.html +*.png *.orig *~ .*.swp diff --git a/kdoc-filter.sh b/kdoc-filter.sh index 1d134d41..9077952c 100755 --- a/kdoc-filter.sh +++ b/kdoc-filter.sh @@ -1,7 +1,18 @@ #!/bin/sh -# Filter the Yate header files so they can be parsed by kdoc +# Filter the Yate header files so they can be parsed by kdoc or doxygen + +if [ -n "$2" -a -f "$2" ]; then + f="$2" +else + if [ -n "$1" -a -f "$1" ]; then + f="$1" + else + echo "Could not find file to process" >&2 + exit 1 + fi +fi filter='s/FORMAT_CHECK(.*)//; s/[A-Z]*_API//' -test -f "$2" && sed "$filter" "$2" +sed "$filter" "$f" diff --git a/yatecbase.h b/yatecbase.h index 03bd6e82..64936f80 100644 --- a/yatecbase.h +++ b/yatecbase.h @@ -1,4 +1,4 @@ -/** +/* * yatecbase.h * This file is part of the YATE Project http://YATE.null.ro * @@ -24,7 +24,7 @@ #ifndef __YATECBASE_H #define __YATECBASE_H - + #ifndef __cplusplus #error C++ is required #endif @@ -109,6 +109,7 @@ public: /** * Set an element as receiving input in the window * @param name Name of the element + * @param select Also select the content of the focused element * @return True if the operation was successfull */ virtual bool setFocus(const String& name, bool select = false) = 0; diff --git a/yateclass.h b/yateclass.h index 46eb6a72..54d834af 100644 --- a/yateclass.h +++ b/yateclass.h @@ -1,4 +1,4 @@ -/** +/* * yateclass.h * This file is part of the YATE Project http://YATE.null.ro * @@ -260,6 +260,7 @@ public: /** * Constructor * @param level The initial local debug level + * @param enabled Enable debugging on this object */ inline DebugEnabler(int level = TelEngine::debugLevel(), bool enabled = true) : m_level(DebugFail), m_enabled(enabled), m_chain(0), m_name(0) @@ -345,7 +346,7 @@ private: const char* m_name; }; -#if 0 +#if 0 /* for documentation generator */ /** * Convenience macro. * Does the same as @ref Debug if DEBUG is #defined (compiling for debugging) @@ -475,7 +476,6 @@ YATE_API void Debug(const DebugEnabler* local, int level, const char* format, .. /** * Outputs a string to the debug console with formatting - * @param facility Facility that outputs the message * @param format A printf() style format string */ YATE_API void Output(const char* format, ...) FORMAT_CHECK(1); @@ -537,12 +537,36 @@ private: * A table of such structures must end with an entry with a null token */ struct TokenDict { + /** + * Token to match + */ const char* token; + + /** + * Value the token translates to + */ int value; }; class String; +#if 0 /* for documentation generator */ +/** + * Macro to create a GenObject class from a base class and implement @ref GenObject::getObject + * @param type Class that is declared + * @param base Base class that is inherited + */ +void YCLASS(class type,class base); + +/** + * Macro to retrive a typed pointer to an interface from an object + * @param type Class we want to return + * @param pntr Pointer to the object we want to get the interface from + * @return Pointer to the class we want or NULL + */ +class* YOBJECT(class type,GenObject* pntr); +#endif + #define YCLASS(type,base) \ public: virtual void* getObject(const String& name) const \ { return (name == #type) ? const_cast(this) : base::getObject(name); } @@ -966,7 +990,7 @@ public: /** * Delete this list item - * @param delold True to delete the object (default) + * @param delobj True to delete the object (default) * @return Pointer to the object if not destroyed */ GenObject* remove(bool delobj = true); @@ -1074,6 +1098,7 @@ public: /** * Store an object in the array + * @param obj Object to store in the array * @param column Number of the column in the array * @param row Number of the row in the array * @return True for success, false if indexes were out of bounds @@ -2285,7 +2310,7 @@ public: /** * Constructs an initialized data block * @param value Data to assign, may be NULL to fill with zeros - * @param len Length of data, may be zero (then @ref value is ignored) + * @param len Length of data, may be zero (then value is ignored) * @param copyData True to make a copy of the data, false to just insert the pointer */ DataBlock(void* value, unsigned int len, bool copyData = true); @@ -2337,7 +2362,7 @@ public: /** * Assign data to the object * @param value Data to assign, may be NULL to fill with zeros - * @param len Length of data, may be zero (then @ref value is ignored) + * @param len Length of data, may be zero (then value is ignored) * @param copyData True to make a copy of the data, false to just insert the pointer */ DataBlock& assign(void* value, unsigned int len, bool copyData = true); @@ -2431,8 +2456,8 @@ public: MD5(const void* buf, unsigned int len); /** - * Construct a digest from a String - * @param str String to be included in digest + * Construct a digest from a binary DataBlock + * @param data Binary data to be included in digest */ MD5(const DataBlock& data); @@ -2810,7 +2835,7 @@ public: * Copy constructor creates a shared mutex * @param original Reference of the mutex to share */ - Mutex(const Mutex& orginal); + Mutex(const Mutex& original); /** * Destroy the mutex @@ -3122,14 +3147,14 @@ public: /** * Sleep for a number of milliseconds - * @param sec Number of milliseconds to sleep + * @param msec Number of milliseconds to sleep * @param exitCheck Terminate the thread if asked so */ static void msleep(unsigned long msec, bool exitCheck = false); /** * Sleep for a number of microseconds - * @param sec Number of microseconds to sleep, may be rounded to + * @param usec Number of microseconds to sleep, may be rounded to * milliseconds on some platforms * @param exitCheck Terminate the thread if asked so */ @@ -3754,6 +3779,7 @@ public: /** * Set socket options + * @param level Level of the option to set * @param name Socket option for which the value is to be set * @param value Pointer to a buffer holding the value for the requested option * @param length Size of the supplied buffer @@ -3763,8 +3789,9 @@ public: /** * Get socket options + * @param level Level of the option to set * @param name Socket option for which the value is to be set - * @param value Pointer to a buffer to return the value for the requested option + * @param buffer Pointer to a buffer to return the value for the requested option * @param length Pointer to size of the supplied buffer, will be filled on return * @return True if operation was successfull, false if an error occured */ @@ -3903,7 +3930,7 @@ public: * @param buffer Buffer for data transfer * @param length Length of the buffer * @param addr Address to send the message to - * @param addrlen Length of the address structure + * @param adrlen Length of the address structure * @param flags Operating system specific bit flags that change the behaviour * @return Number of bytes transferred, @ref socketError() if an error occurred */ @@ -3942,7 +3969,7 @@ public: * @param buffer Buffer for data transfer * @param length Length of the buffer * @param addr Address to fill in with the address of the incoming data - * @param addrlen Length of the address structure on input, length of address data on return + * @param adrlen Length of the address structure on input, length of address data on return * @param flags Operating system specific bit flags that change the behaviour * @return Number of bytes transferred, @ref socketError() if an error occurred */ @@ -4030,6 +4057,9 @@ protected: class YATE_API SysUsage { public: + /** + * Type of time usage requested + */ enum Type { WallTime, UserTime, diff --git a/yatengine.h b/yatengine.h index ca79cb0e..9f6b4da3 100644 --- a/yatengine.h +++ b/yatengine.h @@ -1,4 +1,4 @@ -/** +/* * yatengine.h * This file is part of the YATE Project http://YATE.null.ro * @@ -638,7 +638,8 @@ public: /** * Destroys the plugin. - * The destructor must never be called directly - the Loader will do it when @ref refCount() reaches zero. + * The destructor must never be called directly - the Loader will do it + * when the shared object's reference count reaches zero. */ virtual ~Plugin(); @@ -662,10 +663,14 @@ public: { return false; } }; +#if 0 /* for documentation generator */ /** * Macro to create static instance of the plugin * @param pclass Class of the plugin to create */ +void INIT_PLUGIN(class pclass); +#endif + #define INIT_PLUGIN(pclass) static pclass __plugin /** @@ -692,7 +697,7 @@ public: * @param argc Argument count * @param argv Argument array * @param env Environment variables - * @param client True to parse arguments and run as a client + * @param mode Mode the engine must run as - Console, Client or Server * @param fail Fail and return after parsing command line arguments * @return Program exit code */ @@ -701,6 +706,7 @@ public: /** * Display the help information on console + * @param client Display help for client running mode * @param errout Display on stderr intead of stdout */ static void help(bool client, bool errout = false); diff --git a/yatephone.h b/yatephone.h index 0a1ea84d..6129fd4f 100644 --- a/yatephone.h +++ b/yatephone.h @@ -1,4 +1,4 @@ -/** +/* * yatephone.h * This file is part of the YATE Project http://YATE.null.ro * @@ -861,14 +861,14 @@ public: inline DataConsumer* getCallRecord() const { return m_callRecord; } - /* + /** * Get a pointer to the peer endpoint * @return A pointer to the peer endpoint or NULL */ inline DataEndpoint* getPeer() const { return m_peer; } - /* + /** * Get a pointer to the owner call * @return A pointer to the owner call or NULL */ @@ -1354,7 +1354,7 @@ public: /** * Notification on remote tone(s) * @param msg Notification message - * @param tones Pointer to the received tone(s) + * @param tone Pointer to the received tone(s) * @return True to stop processing the message, false to let it flow */ virtual bool msgTone(Message& msg, const char* tone);