* Document Zaptel::Span

* Minor changes to Zaptel::Xpp as well.

(Documentation-only changes. xpp r5746,r5747)


git-svn-id: http://svn.digium.com/svn/zaptel/branches/1.2@4308 5390a7c7-147a-4af0-8ec9-7488f05a26cb

2 files changed, 120 insertions, 3 deletions

diff --git a/xpp/utils/zconf/Zaptel/Span.pm b/xpp/utils/zconf/Zaptel/Span.pm
index 92dc4dd..be49c28 100644
--- a/xpp/utils/zconf/Zaptel/Span.pm
+++ b/xpp/utils/zconf/Zaptel/Span.pm
@@ -12,6 +12,107 @@ use Zaptel::Utils;
 use Zaptel::Chans;
 use Zaptel::Xpp::Xpd;
 
+=head1 NAME
+
+Zaptel::Spans - Perl interface to a Zaptel span information
+
+This package allows access from perl to information about a Zaptel
+channel. It is part of the Zaptel Perl package.
+
+A span is a logical unit of Zaptel channels. Normally a port in a
+digital card or a whole analog card.
+
+See documentation of module L<Zaptel> for usage example. Specifically
+C<Zaptel::spans()> must be run initially.
+
+=head1 by_number()
+
+Get a span by its Zaptel span number.
+
+=head1 Span Properties
+
+=head2 num()
+
+The span number.
+
+=head2 name()
+
+The name field of a Zaptel span. E.g.:
+
+  TE2/0/1
+
+=head2 description()
+
+The description field of the span. e.g:
+
+  "T2XXP (PCI) Card 0 Span 1" HDB3/CCS/CRC4 RED
+
+=head2 chans()
+
+The list of the channels (L<Zaptel::Chan> objects) of this span.
+In a scalar context returns the number of channels this span has.
+
+=head2 bchans()
+
+Likewise a list of bchannels (or a count in a scalar context).
+
+=head2 is_sync_master()
+
+Is this span the source of timing for Zaptel?
+
+=head2 type()
+
+Type of span, or "UNKNOWN" if could not be detected. Current known
+types: 
+
+BRI_TE, BRI_NT, E1_TE, E1_NT, J1_TE, J1_NT, T1_TE, T1_NT, FXS, FXO
+
+=head2 is_pri()
+
+Is this an E1/J1/T1 span?
+
+=head2 is_bri()
+
+Is this a BRI span?
+
+=head2 is_digital()
+
+Is this a digital (as opposed to analog) span?
+
+=head2 termtype()
+
+Set for digital spans. "TE" or "NT". Will probably be assumed to be "TE"
+if there's no information pointing either way.
+
+=head2 coding()
+
+Suggested sane coding type (e.g.: "hdb3", "b8zs") for this type of span. 
+
+=head2 framing()
+
+Suggested sane framing type (e.g.: "ccs", "esf") for this type of span. 
+
+=head2 yellow(), crc4()
+
+Likewise, suggestions ofr the respective fields in the span= line in
+zaptel.conf for this span.
+
+=head2 signalling()
+
+Suggested zapata.conf signalling for channels of this span.
+
+=head2 switchtype()
+
+Suggested zapata.conf switchtype for channels of this span.
+
+=head1 Note
+
+Most of those properties are normally used as lower-case functions, but
+actually set in the module as capital-letter propeties. To look at e.g.
+"signalling" is set, look for "SIGNALLING".
+
+=cut
+
 my $proc_base = "/proc/zaptel";
 
 sub chans($) {
diff --git a/xpp/utils/zconf/Zaptel/Xpp.pm b/xpp/utils/zconf/Zaptel/Xpp.pm
index 8a2a6eb..8b7458f 100644
--- a/xpp/utils/zconf/Zaptel/Xpp.pm
+++ b/xpp/utils/zconf/Zaptel/Xpp.pm
@@ -173,10 +173,26 @@ sub sync {
 
 =head1 SEE ALSO
 
-For the documentation of xbus objects, see L<Zaptel::Xpp::Xbus>. For
-information about XPD objects, see L<Zaptel::Xpp::Xpd>.
+=over
+
+=item L<Zaptel::Xpp::Xbus>
+
+Xbus (Astribank) object.
+
+=item L<Zaptel::Xpp::Xpd>
+
+XPD (the rough equivalent of a Zaptel span) object.
 
-General documentation can be found in the master package L<Zaptel>.
+=item L<Zaptel::Xpp::Line>
+
+Object for a line: an analog port or a time-slot in a adapter. 
+Equivalent of a channel in Zaptel.
+
+=item L<Zaptel>
+
+General documentation in the master package.
+
+=back
 
 =cut