/ 
SNMP_Session-1.16
River stage zero No dependents
/ BER

NAME

BER - Basic Encoding Rules (BER) of Abstract Syntax Notation One (ASN.1)

SYNOPSIS

use BER;
$encoded = encode_sequence (encode_int (123), encode_string ("foo"));
($i, $s) = decode_by_template ($encoded, "%{%i%s");
# $i will now be 123, $s the string "foo".

DESCRIPTION

This is a simple library to encode and decode data using the Basic Encoding Rules (BER) of Abstract Syntax Notation One (ASN.1). It does not claim to be a complete implementation of the standard, but implements enough of the BER standard to encode and decode SNMP messages.

VARIABLES

$pretty_print_timeticks (default: 1)

If non-zero (the default), pretty_print will convert TimeTicks to "human readable" strings containing days, hours, minutes and seconds.

If the variable is zero, pretty_print will simply return an unsigned integer representing hundredths of seconds. If you prefer this, bind $pretty_print_timeticks to zero.

$errmsg - error message from last failed operation.

When they encounter errors, the routines in this module will generally return undef) and leave an informative error message in $errmsg).

METHODS

encode_int_0() - encode the integer 0.

This is functionally identical to encode_int(0).

encode_int() - encode an integer using the generic "integer" type tag.

encode_uinteger32() - encode an integer using the SNMP UInteger32 tag.

encode_counter32() - encode an integer using the SNMP Counter32 tag.

encode_counter64() - encode an integer using the SNMP Counter64 tag.

encode_gauge32() - encode an integer using the SNMP Gauge32 tag.

encode_oid() - encode an object ID, passed as a list of sub-IDs.

$encoded = encode_oid (1,3,6,1,...);

encode_null() - encode a null object.

This is used e.g. in binding lists for variables that don't have a value (yet)

encode_sequence()

encode_tagged_sequence()

$encoded = encode_sequence (encoded1, encoded2, ...);
$encoded = encode_tagged_sequence (tag, encoded1, encoded2, ...);

Take already encoded values, and extend them to an encoded sequence. encoded_sequence uses the generic sequence tag, while with encode_tagged_sequence you can specify your own tag.

encode_string() - encode a Perl string as an OCTET STRING.

encode_ip_address() - encode an IPv4 address.

This can either be passed as a four-octet sequence in network byte order, or as a text string in dotted-quad notation, e.g. "192.0.2.234".

encode_timeticks() - encode an integer as a TimeTicks object.

The integer should count hundredths of a second since the epoch defined by sysUpTime.0.

pretty_print() - convert an encoded byte sequence into human-readable form.

This function can be extended by registering pretty-printing methods for specific type codes. Most BER type codes used in SNMP already have such methods pre-registered by default. See register_pretty_printer for how new methods can be added.

hex_string() - convert OCTET STRING to hexadecimal notation.

hex_string_of_type() - convert octet string to hex, and check type against given tag.

decode_by_template() - decode complex object according to a template.

($var1, ...) = decode_by_template ($pdu, $template, ...);

The template can contain various %X directives. Some directives consume additional arguments following the template itself. Most directives will cause values to be returned. The values are returned as a sequence in the order of the directives that generated them.

%{ - decode sequence.

This doesn't assign any return value, just checks and skips the tag/length fields of the sequence. By default, the tag should be the generic sequence tag, but a tag can also be specified in the directive. The directive can either specify the tag as a prefix, e.g. %99{ will require a sequence tag of 99, or if the directive is given as %*{, the tag will be taken from the next argument.

%s - decode string
%i - decode integer
%u - decode unsigned integer
%O - decode Object ID (OID)
%A - decode IPv4 address
%@ - assigns the remaining undecoded part of the PDU to the next return value.

decode_sequence() - Split sequence into components.

($first, $rest) = decode_sequence ($pdu);

Checks whether the PDU has a sequence type tag and a plausible length field. Splits the initial element off the list, and returns both this and the remainder of the PDU.

register_pretty_printer() - register pretty-printing methods for typecodes.

This function takes a hashref that specifies functions to call when the specified value type is being printed. It returns the number of functions that were registered.

AUTHORS

Created by: Simon Leinen <simon.leinen@switch.ch>

Contributions and fixes by:

Andrzej Tobola <san@iem.pw.edu.pl>: Added long String decode
Tobias Oetiker <tobi@oetiker.ch>: Added 5 Byte Integer decode ...
Dave Rand <dlr@Bungi.com>: Added SysUpTime decode
Philippe Simonet <sip00@vg.swissptt.ch>: Support larger subids
Yufang HU <yhu@casc.com>: Support even larger subids
Mike Mitchell <Mike.Mitchell@sas.com>: New generalized encode_int()
Mike Diehn <mdiehn@mindspring.net>: encode_ip_address()
Rik Hoorelbeke <rik.hoorelbeke@pandora.be>: encode_oid() fix
Brett T Warden <wardenb@eluminant.com>: pretty UInteger32
Bert Driehuis <driehuis@playbeing.org>: Handle SNMPv2 exception codes
Jakob Ilves (/IlvJa) <jakob.ilves@oracle.com>: PDU decoding
Jan Kasprzak <kas@informatics.muni.cz>: Fix for PDU syntax check
Milen Pavlov <milen@batmbg.com>: Recognize variant length for ints

COPYRIGHT

Copyright (c) 1995-2009, Simon Leinen.

This program is free software; you can redistribute it under the "Artistic License 2.0" included in this distribution (file "Artistic").