NAME

DOCSIS::ConfigFile - Decodes and encodes DOCSIS config-files

VERSION

0.6004

SYNOPSIS

        use DOCSIS::ConfigFile;
        use JSON;

        my $obj     = DOCSIS::ConfigFile->new(
                          shared_secret   => '', # default
                          advanced_output => 0,  # default
                      );

                      $obj->shared_secret("foobar");
        my $encoded = $obj->encode([ {...}, {...}, ... ]);
        my $decoded = $obj->decode($filename);
                      $obj->advanced_output(1);
        my $dec_adv = $obj->decode(\$encoded);

        # see simple config in JSON format
        print JSON->new->pretty->decode($decoded);

        # see advanced config in JSON format
        print JSON->new->pretty->decode($dec_adv);

DESCRIPTION

An instance from this class can be used to encode or decode <DOCSIS> (Data over Cable Service Interface Specifications) config files. These files are usually served using a TFTP server, after a <cable modem> or MTA (Multimedia Terminal Adapter) has recevied an IP address from a DHCP server. These files are binary encode using a variety of functions, but all the data in the file are constructed by TLVs (type-length-value) blocks. These can be nested and concatenated.

This module is used as a layer between any human readable data and the binary structure. The config file in human readable format can look something like this:

        [
            { name => NetworkAccess => value => 1 },
            { name => GlobalPrivacyEnable => value => 1 },
            { name => MaxCPE => value => 10 },
            { name => BaselinePrivacy =>
                nested => [
                    { name => AuthTimeout => value => 10 },
                    { name => ReAuthTimeout => value => 10 },
                    { name => AuthGraceTime => value => 600 },
                    { name => OperTimeout => value => 1 },
                    { name => ReKeyTimeout => value => 1 },
                    { name => TEKGraceTime => value => 600 },
                    { name => AuthRejectTimeout => value => 60 },
                    { name => SAMapWaitTimeout => value => 1 },
                    { name => SAMapMaxRetries => value => 4 }
                ]
            },
        ]

There is also an optional "advanced_output" flag which can include more information, but this is what is required/default: An array-ref of hash-refs, containing a "name" and a "value" (or "nested" for nested data structures). The rest will this module figure out.

FAULT HANDLING

As for version 0.60, this module has changed from holding errors in an attribute to actively reporting errors, using "confess()", "carp()" and the module autodie for reporting system errors from "open()" and friends. Constructing the object, and changing attribute values are still safe to do, but "encode" and "decode" might die.

ATTRIBUTES
shared_secret
Sets or gets the shared secret.

advanced_output
Sets weither advanced output should be enabled. Takes 0 or 1 as argument. Advanced output is off (0) by default.

METHODS
new

$self = $class->new(\%args);

Arguments can be:

     shared_secret   => Shared secret in encoded cm config file
     advanced_output => Advanced decoded config format
     mibs            => will set $ENV{MIBS} to load custom mibs

decode

        $array_ref = $self->decode($path_to_file);
        $array_ref = $self->decode(\$binary_string);
        $array_ref = $self->decode($FH);

This method decodes a binary config file stored in either a file on disk, a binary string, or a filehandle. It returns an array-ref of hashes, containing the config as a perl data structure.

encode

$binary_str = $self->encode([ { ... }, ... ]);

Encodes an array of hashes, containing the DOCSIS config-file settings and returns a binary encoded string. See "DESCRIPTION" and the unit tests for example input. For other structures, see the table generated by "dump_symbol_tree" in DOCSIS::ConfigFile::Syminfo.

CONSTANTS
Decode
Returns DOCSIS::ConfigFile::Decode.

Encode
Returns DOCSIS::ConfigFile::Encode.

Syminfo
Returns DOCSIS::ConfigFile::Syminfo.

AUTHOR

Jan Henning Thorsen, "<pm at flodhest.net>"

BUGS

Please report any bugs or feature requests to "bug-docsis-perl at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DOCSIS-ConfigFile>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc DOCSIS::ConfigFile

You can also look for information at <http://search.cpan.org/dist/DOCSIS-ConfigFile>

ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Copyright (c) 2007 Jan Henning Thorsen

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

DOCSIS is a registered trademark of Cablelabs, http://www.cablelabs.com

This module got its inspiration from the program docsis, http://docsis.sf.net.