NAME

App::Netdisco::Util::SNMPText

DESCRIPTION

Helper functions to turn the octets of an SNMP text value into a character string, without double encoding and without substituting U+FFFD.

There are no default exports, however the :all tag will export all subroutines.

EXPORT_OK

snmp_charsets_for( $device )

Returns an array reference of fallback charset names configured for the device, without duplicates. The snmp_charset setting is a list of maps from ACL to charsets. Maps are read in list order; within a map, matching ACL keys are read in alphabetical order, then group:__ANY__.

reset_snmp_charsets_cache()

Empties the cache by device IP which decode_snmp_text keeps of snmp_charsets_for, so that one job walks the ACLs once per device. The worker runner calls it at the start of every job, so a changed setting or device applies to the next job.

decode_text_with( $bytes, \@charsets )

Returns the character string for $bytes. Undef and empty values are returned unchanged, as is a string which already holds characters above 0xFF.

Plain ASCII is returned as is. Otherwise valid UTF-8 is tried first, then each charset in the list (accepted only if encoding the result gives back exactly $bytes and it holds no private use or U+FFFD characters), and lastly Latin-1, which accepts any octets. A charset name which Encode does not know is skipped, with one warning per process.

In list context returns ($text, $how) where $how is ascii, UTF-8, the charset name, or latin1.

decode_snmp_text( $bytes, $device_or_undef, $field_label )

Decodes as decode_text_with does, using the charsets from snmp_charsets_for for the device, or none when the device is undef. The charsets are looked up only when the value is neither ASCII nor UTF-8, and once per device until reset_snmp_charsets_cache. Returns the text. When the value is neither UTF-8 nor in a configured charset, it is stored as Latin-1 and a debug message names the device, $field_label and the octets.

decode_snmp_data( $data, $device_or_undef, $field_label )

Returns a copy of $data in which every defined plain scalar, in hashes and arrays to any depth, has been through decode_snmp_text. Hash keys are left as they are, and blessed objects and code references pass through unchanged. $field_label defaults to data. The argument is never modified.

decode_cli_extra( $extra )

Decodes the -e text given to netdisco-do for a cf_ action, which arrives as raw octets, with no device charsets. Undef and empty values are returned unchanged.

looks_garbled( $string )

True when the string holds a character from U+00C2 to U+00F4 followed by one from U+0080 to U+00BF, which is how UTF-8 octets look when read as Latin-1, and its characters read as octets are valid UTF-8. Correct text such as an accented letter before a non-breaking space or a closing guillemet fails the second test.

ungarble( $string, \@charsets )

Returns the text that $string would have been had its characters been read as octets, using decode_text_with. Returns undef when the string holds a character which Latin-1 cannot encode, so it cannot be garbled in that way.

scan_config_encoding( $config )

Walks hashes (keys and values) and arrays in $config and returns a list of { path => 'discover_no[2]', value => ..., suggestion => ... } for every string which looks_garbled. Other references are skipped. Reads only the data it is given. Under the settings which hold device credentials (device_auth, snmp_auth, community, community_rw) the value and suggestion are (hidden).

scan_stored_encoding( $schema, $limit )

Reads the database only. Returns findings for stored text that looks garbled or holds U+FFFD, in device.name, description, vendor, os and os_ver, device_port.descr, device_vlan.description and device_port_ssid.ssid. Each finding is { ip, column, value, suggestion } where suggestion is undef for U+FFFD, whose original octets are not recoverable. At most $limit findings are returned per column, followed by { column, more => $count } for the rest.