The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
SNMP-Class-0.15
River stage zero No dependents
++
/ SNMP::Class::OID

NAME

SNMP::Class::OID - Represents an SNMP Object-ID.

SYNOPSIS

 use SNMP::Class::OID;

 #create an object
 my $oid = SNMP::Class::OID->new('.1.3.6.1.2.1.1.5.0');
 #-or-
 my $oid = SNMP::Class::OID->new('sysName.0');
 
 #overloaded scalar representation
 print $oid; # evaluates to sysName.0

 #representations
 $oid->to_string; #string representation -- sysName.0
 $oid->numeric; #numeric representation -- .1.3.6.1.2.1.1.5.0
 $oid->to_array; #(1,3,6,1,2,1,1,5,0)
 $oid->[1]; #can be used as array reference -- returns 5
 $oid->length; #9

 #slicing
 my $oid2 = $oid->slice(3,6); #new object : .6.1.2.1
 my $oid2 = $oid->slice(3..6); #same

 #equality
 $oid1 == $oid2; # yields true if they are the same
 $oid1 == '.1.3.6.1.2.1.1.5.0' #also acceptable, second operand will be converted 

 #hierarchy
 $oid2 = SNMP::Class::OID->new('.1.3.6.1.2.1.1');
 $oid2->contains($oid); #true; Because .1.3.6.1.2.1.1.5.0 is under .1.3.6.1.2.1.1
 $oid2->contains('.1.3.6.1.2.1.1.5.0'); #also true, string autoconverted to SNMP::Class::OID

 #concatenation
 SNMP::Class::OID(".1.3.6") . SNMP::Class::OID("1.2.1"); #returns .1.3.6.1.2.1
 SNMP::Class::OID(".1.3.6") . '.1.2.1'; #also acceptable, returns the same

METHODS

overloaded operators

The following operators are overloaded:

  • <=>

    Two SNMP::Class::OID objects can be compared using the == operator. The result is what everybody expects.

  • '+'

    Two SNMP::Class::OID objects can be concatenated using the + operator. Note that order actually is important. Example: .1.3.6 + .1.4.1 will yield .1.3.6.1.4.1.

  • @{}

    If an SNMP::Class::OID object is used as an array reference, it will act as an array containing the individual numbers of the OID. Example:

     my $oid = SNMP::Class::OID->new("1.3.6.1.4.1");
 print $oid->[1]; #will print 3

new

new can be used to construct a new object-id. Takes one string as an argument, like ".1.3.6.4.1". Returns an SNMP::Class::OID object, or confesses if that is not possible. If the 1rst argument is a NetSNMP::OID instead of a string, the constructor will notice and take appropriate action to return a valid object.

get_syntax

Returns, if it exists, the SNMP SYNTAX clause for the oid or undef if it doesn't.

has_syntax

Tells if we know the syntax for the object. Convenience shortcut instead of testing get_syntax for definedness.

get_label

Returns the label for this oid if it exists or undef if it doesn't.

get_label_oid

Returns an SNMP::Class::OID object corresponding to the appropriate object-id. For example, for an oid like ifDescr.3, we would get a new SNMP::Class::OID equivalent to ifDescr. May return undef, as the label may not be found in the loaded MIBs.

has_label

Tells if there is a label for the object. Convenience shortcut instead of testing get_label_oid for definedness.

get_instance_oid

Returns an SNMP::Class::OID object corresponding to the instance of this oid. For example, for an oid like ifDescr.3, we would get a new SNMP::Class::OID equivalent to .3. May return undef, as there may be no instance (for example a non-leaf oid) or it may not be possible to know it.

has_instance

Tells if there is an instance for the object. Convenience shortcut instead of testing get_instance_oid for definedness.

slice

Slice can extract a portion of an object-id and return it as a new SNMP::Class::OID object. Example:

 my $oid = SNMP::Class::OID->new("1.3.6.1.4.1");
 my $suboid = $oid->slice(1..3); #will return .1.3.6
 my $suboid = $oid->slice(1,2,3); #completely equivalent
 my $suboid = $oid->slice(1,3); #also completely equivalent

To extract a single number from the object-id you can simply say for example:

 my $suboid = $oid->slice(2);

to_array

Returns an array representation of the object OID.

length

Returns the length (in items) of the object OID.

is_null

returns true if the object represents the null object identifier. SNMPv2-SMI defines a null object id to be { 0 0 } or 0.0 or zeroDotZero. Let's just hope that we won't encounter 0.0 instances any time soon.

numeric

Returns a numeric representation of the object.

to_string

Returns a string representation of the object. Difference with numeric is that numeric always returns numbers like .1.3.6.1.2.1.1.5.0, while this method may return strings like "sysName.0" etc.

add

Concatenates two OIDs. Use it through the . overloaded operator. Second argument can be a string, will be autoconverted to SNMP::Class::OID before addition. If one of the arguments is 0.0, the result should be equal to the other.

oid_compare

Compares two OIDs. Has the same semantic with the spaceship <=> operator. Second argument can also be a string. You probably will never use that method explicitly, only through the overloaded operators <,>,==,!= etc. See also the is_equal method.

oid_is_equal

Returns 1 if the 1st argument is the same oid, else undef.

contains

Can ascertain if an oid is a subset of the oid represented by the object. Takes SNMP::Class::OID as 1st and only argument. String also acceptable as it will be autoconverted. Example:

 $oid1 = SNMP::Class::OID->new(".1.3.6.1.4.1");
 $oid2 = SNMP::Class::OID->new(".1.3.6.1.4.1.1");
 $oid1->contains($oid2); #yields true
 $oid1->contains(".1.3.6.1.4.1.1");#the same

new_from_string

Can create an oid from a literal string. Useful to generate instances which correspond to strings. 1st argument is the string to represent with an OID. If the 2nd argument is there and is true, the SNMP octet-string is assumed to be IMPLIED, thus the first number which represents the length of the string is missing. Example:

 my $instance = SNMP::Class::OID->new_from_string("foo"); # returns .3.102.111.111

 #but

 my $instance = SNMP::Class::OID->new_from_string("foo","yes_it_is_implied"); # returns .102.111.111

AUTHOR

Athanasios Douitsis, <aduitsis at cpan.org>

BUGS

Please report any bugs or feature requests to bug-snmp-class-oid at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SNMP::Class. 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 SNMP::Class

You can also look for information at:

ACKNOWLEDGEMENTS

Since I am using NetSNMP::OID internally, my gratitude goes to the fine folks that gave us the original SNMP module. Many thanks to all.

COPYRIGHT & LICENSE

Copyright 2008 Athanasios Douitsis, all rights reserved.

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