
//! @mainpage notitle
//! <center>
//! @image html vtlogo.gif
//! <h1>Voicetronix Voice Processing Board (VPB) Software</h1>
//! <h3>support@voicetronix.com.au</h3>
//!
//! This documentation covers both the public API for users of @c libvpb,
//! and the internal structures and functions for developers of the library.
//!
//! For information on the public interfaces, start @ref PublicAPI "here".
//!
//! <small>&copy; 1997 - 2009.  All rights reserved.</small>
//! </center>


//! @page ToneDetect Tone detection
//! The libvpb api functions for the programmable tone detector are described
//! @ref ToneDet "here".
//!
//! @section ToneDetectGeneral General information
//! When a tone is detected, a @c VPB_TONEDETECT event is placed on the event
//! queue with the tone identifier in the data element of the event structure.
//! There are 9 pre-defined tones, which default to a selection of standard
//! tones but which may be redefined to suit local requirements.  They are:
//!
//! - @c VPB_DIAL - dial for US
//! - @c VPB_RINGBACK - ringback for US
//! - @c VPB_BUSY - busy for US
//! - @c VPB_GRUNT - grunt detected
//! - @c VPB_RINGBACK_308 - ringback from Studio 308 PBX
//! - @c VPB_BUSY_308 - busy from studio 308 PBX
//! - @c VPB_FAX - fax CNG tone/preamble
//! - @c VPB_BUSY_AUST - busy/disconnect for Australia
//! - @c VPB_RINGBACK_AUS - ringback for Australia
//! 
//! Up to 10 tone detectors can be independently defined for each port of each
//! board.  To redefine a pre-defined tone, specify its tone identifier as the
//! @c tone_id parameter of the @c VPB_DETECT structure when programming.
//!
//! @section ToneDetectProg Programming the tone detectors
//! The tone detectors may be controlled either by direct calls to the
//! @ref ToneDet "api" functions with a user specified @c TONE_DETECT structure
//! or by setting the @c %VPB_TONE and @c VPB_TONE1 ... @c VPB_TONE9 variables
//! in the environment where the application is started.
//!
//! The parameters required to detect a particular tone may be computed manually
//! with reference to the appropriate standards that define it, or computed from
//! a recorded tone with the assistance of the @c tonetrain utility which is
//! provided with libvpb.
//!
//! @todo finish fleshing this out, import more (still relevant) details from
//!       the sgml docs.


//! @page VPBUtils Utility programs
//! The libvpb distribution includes a number of utility programs which may
//! be helpful for testing your hardware, tuning the software parameters, and
//! performing other simple tasks related to creating your own applications.
//!
//! <hr>
//! @section DevInfo Device and driver information
//! The following utilities may be used to query device and driver information:
//!
//! @subsection vpbscan
//! The @c vpbscan utility will scan the pci bus and report on any Voicetronix
//! hardware found in the machine.  This utility does not require kernel driver
//! support for the cards, but can only report the most basic information about
//! the type and presence of cards in a machine.
//! It is used by the @c VpbConfigurator utility to assist with creating a basic
//! configuration for a new system installation.  You should not normally need
//! to call this yourself, but it may be useful for low level applications.
//!
//! @subsection vpbconf
//! The @c vpbconf utility will query configured Voicetronix hardware for model
//! and port information.  It requires kernel driver support for the cards, and
//! for early model cards that cannot be properly autodetected, a correctly
//! defined @ref VPBconf "configuration file" must be present as well.
//! It is used by the @c PbxConfigurator utility from the @b OpenPBX distribution
//! to set up a basic @c PBX configuration for the available hardware.
//!
//! @subsection vtdeviceinfo
//! The @c vtdeviceinfo utility will query real time information about the state
//! of installed Voicetronix hardware from the kernel @c /proc interface.  It
//! requires kernel driver support for the cards.
//!
//! @subsection vtdriverinfo
//! The @c vtdriverinfo utility will query information about the state of the
//! Voicetronix kernel drivers from the kernel @c /sys interface.  It will
//! report the driver version and module parameter values for each Voicetronix
//! driver loaded in the running kernel, even if no cards are bound to them.
//!
//! <hr>
//! @section TuningUtils Tuning utilities
//! The following utilities are used to optimise or alter the operation of
//! the support software for Voicetronix hardware:
//!
//! @subsection tonetrain
//! The @c tonetrain utility is used to analyse recorded signal tones to
//! determine the parameters required for the programmable tone detector
//! to detect them.
//!
//! @subsection tonedebug
//! The @c tonedebug utility is used to verify that the parameters used for the
//! programmable tone detector actually do detect samples of the intended tones.
//!
//! <hr>
//! @section AudioUtils Audio utilities
//! The following utilities are used to optimise or alter the operation of
//! the support software for Voicetronix hardware:
//!
//! @subsection recwav
//! The @c recwav utility is used to record audio data from a Voicetronix
//! hardware port.
//!
//! @subsection playwav
//! The @c playwav utility is used to play audio data to a Voicetronix
//! hardware port.
//!
//! <hr>
//! @section TestUtils Test utilities
//! The following utilities are used to test the operation of installed
//! Voicetronix hardware:
//!
//! @subsection vpbecho
//! The @c vpbecho utility performs a simple echo test on any or all ports.
//! It will record a short period of audio data from a port, then play it
//! back into that same port.  For @c FXS ports, recording will begin when
//! the handset goes off hook.  For @c FXO ports, the line will be answered
//! and recording commenced after the second ring of an incoming call.
//!
//! @subsection measerl
//! The @c measerl utility performs some simple tests to determine the echo
//! return loss of the line.  For cards with manually tuned hybrid circuits,
//! this may be used to help determine the optimal settings for them.
//!
//! @subsection ringstat
//! The @c ringstat utility exercises the ring generators of all @c FXS ports
//! This is mostly used as a stress test to confirm the ringing operation of
//! the cards under a worst case load.
//!
//! @todo include cidtest, deccid, samcid and tv4log here too.


//! @page VPBenv Environment variables
//! The following environment variables affect the behaviour of libvpb.
//!
//! @section VPB_COUNTRY
//! Sets the region to use for global default values.  Its value may be either
//! a string, indicating the name of the region such as @c AUSTRALIA, @c JAPAN,
//! @c UK, @c USA, or the numerical value of that region used for international
//! phone numbering, such as 61, 81, 44, 1, respective to the names above.
//! If not specified, the default value is @c AUSTRALIA.  Per port country
//! selection may be made programmatically using the @c vpb_set_country() api
//! call, or through the use of a @ref VPBconf "configuration file".
//!
//! @section VPB_TONE
//! Sets new default parameters for use by the programmable
//! @ref ToneDetect "tone detector".  The variables @c VPB_TONE1 ... @c VPB_TONE9
//! may also be specified if more than one tone is to be redefined.
//!
//! @section VPB_VERBOSE
//! If set to the value of @c 1, this variable will cause libvpb to output
//! debugging messages tracing its activity to @c stdout.  If set to any other
//! value it will be used as the path to a file where such messages will be
//! written.
//!
//! @section VPB_MODEL
//! If set to the string @c "V4LOG", this variable indicates that @b OpenLog
//! cards should be assumed if the @b OpenLine card type has not otherwise been
//! explicitly specified.  Has no effect with cards of other types.


//! @page VPBconf Configuration files
//! As well as querying the environment for options, libvpb may be configured
//! through the use of files in the @c /etc/vpb directory.  For later model
//! hardware which can be fully autodetected, such as the @b OpenSwitch and
//! @b OpenPCI cards, these files are entirely optional and sensible defaults
//! will be used where possible if they are absent.  For the @b OpenLine and
//! @b OpenLog cards, they must be present and configured correctly as these
//! two cards are otherwise indistinguishable from each other to the host
//! machine.
//!
//! @section VPBtopconf vpb.conf
//! This is the top level configuration file for all cards.
//!
//! @section VTCOREconf vtcore.conf
//! Contains configuration options specific to cards that use the @c vtcore
//! driver, such as @c OpenPCI and @c OpenSwitch12 cards.
//!
//! @todo Document the rest of these, and import more details from the relevant
//!       @c README files.


//! @page L10N Localisation
//! Fewer standards are more numerous, or diverse, as those governing the
//! facets of international telecommunication.  That they may be applied
//! independently at various layers, and change at any junction point in the
//! system, means any system of localisation must be careful to define its
//! domain of influence.
//!
//! The primary cases we must consider are:
//! - @ref STDElec
//! - @ref STDSig
//! - @ref LangPref
//!
//! The @b libvpb api functions for configuring locale specific options can be
//! found @ref I18N "here".  For functions available at the kernel level, a
//! @c proc interface also exists at @c /proc/vt/ for all active hardware.
//!
//! <hr>
//! @section STDElec Electrical standards
//! The first set of standards to concern us are those of the hardware that
//! will be connected to the @b Voicetronix card. The @b OpenPCI and later cards
//! permit selection of the regional hardware standard globally, and provide
//! the ability to override the default on a per port basis.
//!
//! The selection of a region for a port entirely depends on the device it will
//! be connected to.  Each device should be matched for best compatibility from
//! the following list:
//!
//! - ARGENTINA
//! - AUSTRALIA
//! - AUSTRIA
//! - BAHRAIN
//! - BELGIUM
//! - BRAZIL
//! - BULGARIA
//! - CANADA
//! - CHILE
//! - CHINA
//! - COLOMBIA
//! - CROATIA
//! - CYPRUS
//! - CZECH
//! - DENMARK
//! - ECUADOR
//! - EGYPT
//! - ELSALVADOR
//! - FINLAND
//! - FRANCE
//! - GERMANY
//! - GREECE
//! - GUAM
//! - HONGKONG
//! - HUNGARY
//! - ICELAND
//! - INDIA
//! - INDONESIA
//! - IRELAND
//! - ISRAEL
//! - ITALY
//! - JAPAN
//! - JORDAN
//! - KAZAKHSTAN
//! - KUWAIT
//! - LATVIA
//! - LEBANON
//! - LUXEMBOURG
//! - MACAO
//! - MALAYSIA
//! - MALTA
//! - MEXICO
//! - MOROCCO
//! - NETHERLANDS
//! - NEWZEALAND
//! - NIGERIA
//! - NORWAY
//! - OMAN
//! - PAKISTAN
//! - PERU
//! - PHILIPPINES
//! - POLAND
//! - PORTUGAL
//! - ROMANIA
//! - RUSSIA
//! - SAUDIARABIA
//! - SINGAPORE
//! - SLOVAKIA
//! - SLOVENIA
//! - SOUTHAFRICA
//! - SOUTHKOREA
//! - SPAIN
//! - SWEDEN
//! - SWITZERLAND
//! - SYRIA
//! - TAIWAN
//! - THAILAND
//! - UAE
//! - UK
//! - USA
//! - YEMEN
//!
//! <hr>
//! @section STDSig Signalling standards
//! These may be loosely grouped into:
//! @par Line signalling
//! Which includes things like:
//! - Hook flash timing
//! - Loop drop timing
//! - Polarity change
//! - Caller ID
//! - Dialling
//!
//! @par User signalling
//! Which includes:
//! - Ring cadence
//! - Call progress tones
//!
//! <hr>
//! @section LangPref User language preferences
//! There is not presently support for translated text from libvpb, however
//! this will be available at a later time.  If you have a pressing need for
//! it sooner than that, then we should chat...


//! @page Credits Credits
//! Much of the credit for what you see here today belongs with our loyal
//! customers, who not only funded the efforts to produce it, but tested it,
//! shared suggestions, bugfixes and problems to solve, and generally kept
//! us on our toes to in turn keep their customers equipped with state of
//! the art solutions to their telephony needs.  We can't name you all here,
//! but you know who you are.  And so do we.  Many Thanks to you all!
//!
//! Blame for what is still in need of work then, over the years has fallen
//! on the heads of:
//!
//! @li Ron Lee           <small>(current maintainer)</small>
//! @li Mark Mickan       <small>(active developer)</small>
//! @li Peter Wintulich   <small>(hardware guru)</small>
//! @li Ian Roberts       <small>(<tt>ISDN</tt> support)</small>
//! @li Ben Kramer        <small>(prior maintainer)</small>
//! @li David Rowe        <small>(prior art)</small>
//! @li John Kostogiannis <small>(Our master of ceremonies)</small>
//!
//! An especial round of heartfelt finger-pointing goes out to John and David,
//! who lay the cornerstones for all we have built, what must seem like an
//! eternity ago, and to John's wife Rima, who together with John manage to
//! keep the rest of us shielded from the nasty realities of running a company
//! and leave us to immerse ourselves in the really fun stuff.  Without their
//! hard work, there wouldn't be any of this at all.
//! @image html vtlogo.gif

