utils.tcl

Go to the documentation of this file.

##
# @brief Basic namespace for all Excentis Tcl extensions
#
namespace eval excentis {

##
# @brief Namespace for Excentis Tcl extensions for basic functions.
#
# This includes functionality such as:
# - Network frame generation
# - Address parsing and conversion
# - ...
#
namespace eval basic {

## \file
#
# @brief Utility module that provides <b>various generic helper methods</b> to ease Tcl development.
#
# It contains utilities such as data conversion methods, checksum calculation, IP validation, etc.
#
# @copyright Excentis nv - www.excentis.com
#

proc ByteList.Check { byteList } {
    # Method to check if the byteList is a valid list of hexadecimal bytes.
    #
    # @param byteList List of hexadecimal bytes 0xX, where X is 1 or 2 hexadecimal bytes.
    #
    # @return 1 for correct list of bytes,
    #         0 for incorrect list of bytes
    ##

    return [ regexp {^[ \t]*((0[xX][0-9a-fA-F]{1,2}[ \t]+)*)(0[xX][0-9a-fA-F]{1,2}){0,1}[ \t]*$} $byteList dummy s_stripped dummy1 dummy2 ]

}

proc Mac.To.Hex { macAddress } {
    # Convert a MAC address to a ByteList of 6 bytes
    #
    # macAddress possible inputs:
    # FF-FF-FF-FF-FF-FF
    # FF:FF:FF:FF:FF:FF
    # FF FF FF FF FF FF
    # 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
    # 0xFF:0xFF:0xFF:0xFF:0xFF:0xFF
    # 0xFF-0xFF-0xFF-0xFF-0xFF-0xFF
    # 0xFF0xFF0xFF0xFF0xFF0xFF
    # FFFFFFFFFFFF
    # FFFF.FFFF.FFFF
    # FFFF FFFF FFFF
    # FFFF-FFFF-FFFF
    # FFFFL:FFFF:FFFF
    #
    # @param macAddress: MAC address to be converted to the standard (in capitals or small letters)
    #
    # @return 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF ("0x", spaces and capitals)
    ##

    # Remove leading/ending spaces
    set macAddress [ string trim $macAddress ]

    if {[ string equal $macAddress "" ]} {
        error "The given MAC address \"$macAddress\" is empty"
    }

    if { [ catch {
                if {[ regexp {^((([0-9a-fA-F]{2})[" ":-]([0-9a-fA-F]{2})[" ":-]([0-9a-fA-F]{2})[" ":-]([0-9a-fA-F]{2})[" ":-]([0-9a-fA-F]{2})[" ":-])(([0-9a-fA-F]{2})))$} $macAddress dummy1 dummy2 dummy3 a b c d e f ]} {
                    # FF-FF-FF-FF-FF-FF
                    # FF:FF:FF:FF:FF:FF
                    # FF FF FF FF FF FF
                    set macAddress ""
                    foreach letter { a b c d e } { append macAddress "0x[ subst $[ subst $letter ]] " }
                    append macAddress "0x$f"
                } elseif {[ regexp {^(((0x[0-9a-fA-F]{2})[" ":-](0x[0-9a-fA-F]{2})[" ":-](0x[0-9a-fA-F]{2})[" ":-](0x[0-9a-fA-F]{2})[" ":-](0x[0-9a-fA-F]{2})[" ":-])((0x[0-9a-fA-F]{2})))$} $macAddress dummy1 dummy2 dummy3 a b c d e f ]} {
                    # 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
                    # 0xFF:0xFF:0xFF:0xFF:0xFF:0xFF
                    # 0xFF-0xFF-0xFF-0xFF-0xFF-0xFF
                    set macAddress ""
                    foreach letter { a b c d e } { append macAddress "0x[ string range [ subst $[ subst $letter ]] 2 end ] " }
                    append macAddress "0x[ string range $f 2 end ]"
                } elseif {[ regexp {^(0x[0-9a-fA-F]{2})(0x[0-9a-fA-F]{2})(0x[0-9a-fA-F]{2})(0x[0-9a-fA-F]{2})(0x[0-9a-fA-F]{2})(0x[0-9a-fA-F]{2})$} $macAddress dummy1 a b c d e f ]} {
                    # 0xFF0xFF0xFF0xFF0xFF0xFF
                    set macAddress ""
                    foreach letter { a b c d e } { append macAddress "0x[ string range [ subst $[ subst $letter ]] 2 end ] " }
                    append macAddress "0x[ string range $f 2 end ]"
                } elseif {[ regexp {^([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$} $macAddress dummy a b c d e f ]} {
                    # FFFFFFFFFFFF
                    set macAddress ""
                    foreach letter { a b c d e } { append macAddress "0x[ subst $[ subst $letter ]] " }
                    append macAddress "0x$f"
                } elseif {[ regexp {^(([0-9a-fA-F]{2})([0-9a-fA-F]{2}))[" "-:.](([0-9a-fA-F]{2})([0-9a-fA-F]{2}))[" "-:.](([0-9a-fA-F]{2})([0-9a-fA-F]{2}))$} $macAddress dummy1 dummy2 a b dummy3 c d dummy4 e f ]} {
                    # FFFF.FFFF.FFFF
                    # FFFF FFFF FFFF
                    # FFFF-FFFF-FFFF
                    # FFFFL:FFFF:FFFF
                    set macAddress ""
                    foreach letter { a b c d e } { append macAddress "0x[ subst $[ subst $letter ]] " }
                    append macAddress "0x$f"
                } else {
                    error "The given MAC address \"$macAddress\" is not in a valid format or contains wrong characters!\
                           \nAllowed formats are enumerated in the helpbox"
                }
            } ERROR ]
    } {
        #if an error occured at the regexp
        error $ERROR
    } else {
        return $macAddress
    }
}

proc IPv4.IsValid { ip } {
    # This Method checks if <ip> is a valid IPv4 address.
    #
    # @param ip
    #     The IPv4 address to check
    #
    # @return
    #     1 for a valid IPv4 address, 0 for an invalid IPv4 address.
    ##

    return [ regexp {^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$} $ip match ip1 ip2 ip3 ip4 ]

}

proc IPv4.IsNullIpAddress { ip } {
    # Returns whether this address is the null IPv4 address 0.0.0.0/32
    #
    # @param ip
    #     The IPv4 address to check
    #
    # @return
    #     1 for a null IPv4 address, 0 for an other or invalid IPv4 address.
    ##

    return [ regexp {^([0]{1,3})\.([0]{1,3})\.([0]{1,3})\.([0]{1,3})$} $ip match ip1 ip2 ip3 ip4 ]

}

proc IPv4.IsThisNetwork { ip } {
    # Returns whether the IPv4 address is in subnet 0.0.0.0/8
    #
    # @param ip
    #     The IPv4 address to check
    #
    # @return
    #     1 for a "this network" IPv4 address, 0 for an other or invalid IPv4 address.
    ##

    return [ regexp {^([0]{1,3})\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$} $ip match ip1 ip2 ip3 ip4 ]

}

proc IPv4.IsLoopback { ip } {
    # Returns whether this address is in subnet 127.0.0.0/8
    #
    # @param ip
    #     The IPv4 address to check
    #
    # @return
    #     1 for a loopback IPv4 address, 0 for an other or invalid IPv4 address.
    ##

    return [ regexp {^(127)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$} $ip match ip1 ip2 ip3 ip4 ]

}

proc IPv4.IsMulticast { ip } {
    # Returns whether this address is in subnet 224.0.0.0/4
    #
    # @param ip
    #     The IPv4 address to check
    #
    # @return
    #     1 for a multicast IPv4 address, 0 for an other or invalid IPv4 address.
    ##

    return [ expr [ regexp {^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$} $ip match ip1 ip2 ip3 ip4 ] && \
           [ expr ( $ip1 & 0xf0 ) == 0xe0 ] ]

}

proc IPv4.IsBroadcast { ip { netmask "" } } {
    # Check if the IPv4 address is a broadcast address 255.255.255.255/32
    # or check if the IPv4 address is a broadcast address for the given subnet when @p netmask is given.
    #
    # @param ip
    #     The IPv4 address to check
    #
    # @param netmask
    #     Check if the IPv4Address is the given subnet's broadcast address.
    #
    # @return
    #     1 for a broadcast IPv4 address, 0 for an other or invalid IPv4 address.
    #
    ##

    if { [ string equal "${netmask}" "" ]} {
        return [ string equal "${ip}" "255.255.255.255" ]
    }

    if { ! [ IPv4.IsValid "${ip}" ] || ! [ IPv4.IsValid "${netmask}" ]} {
        return 0
    }

    set ipBytes [ split "${ip}" "." ]
    set netmaskBytes [ split "${netmask}" "." ]
    foreach ipPart $ipBytes netmaskPart $netmaskBytes {
        set broadcastPart [ expr ( ${ipPart} & ${netmaskPart} ) | ( ~ ${netmaskPart} & 0x0ff ) ]
        if { $ipPart != $broadcastPart} {
            return 0
        }
    }
    return 1

}

proc IPv6.IsComplete { ip } {
    # Check if the given IPv6 address is a complete format IPv6 address:
    # X:X:X:X:X:X:X:X (X = 1 to 4 hexadecimal values)
    #
    # @param ip The IPv6 address to check
    #
    # @return 1 if the IPv6 address is in this format, 0 if not
    ##

    set pattern_8hex {^([0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}$}
    return [ regexp -- $pattern_8hex $ip ]

}

proc IPv6.IsCompressed { ip } {
    # Check if the given IPv6 address is a compressed format IPv6 address:
    # Compresses zeroes at one place in the address
    # e.g.    'X:0:0:X:0:0:0:X' (X = 1 to 4 hexadecimal values)
    #      -> 'X::X:0:0:0:X' OR 'X:0:0:X::X'
    #
    # @param ip The IPv6 address to check
    #
    # @return 1 if the IPv6 address is in this format, 0 if not
    #
    # @apiexample
    #     @apisnippet{IPv6.IsCompressed "2001:db8:1:81:0:0:0:1"}
    #     @apisnippetretval{2001:db8:1:81::1}
    # @endapiexample
    ##

    # This one includes complete IPv6 address also
    #set pattern_compressedhex {(^(([0-9A-Fa-f]{1,4}(((:[0-9A-Fa-f]{1,4}){5}::[0-9A-Fa-f]{1,4})|((:[0-9A-Fa-f]{1,4}){4}::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,1})|((:[0-9A-Fa-f]{1,4}){3}::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,2})|((:[0-9A-Fa-f]{1,4}){2}::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,3})|(:[0-9A-Fa-f]{1,4}::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,4})|(::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,5})|(:[0-9A-Fa-f]{1,4}){7}))$|^(::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,6})$)|^::$)}
    set pattern_compressedhex {(^(([0-9A-Fa-f]{1,4}(((:[0-9A-Fa-f]{1,4}){5}::[0-9A-Fa-f]{1,4})|((:[0-9A-Fa-f]{1,4}){4}::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,1})|((:[0-9A-Fa-f]{1,4}){3}::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,2})|((:[0-9A-Fa-f]{1,4}){2}::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,3})|(:[0-9A-Fa-f]{1,4}::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,4})|(::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,5})))$|^(::[0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4}){0,6})$)|^::$)}
    return [ regexp -- $pattern_compressedhex $ip ]

}

proc IPv6.Isv4Inv6 { ip } {
    # Check if the given IPv6 address is the alternative IPv4 in IPv6 format:
    # X:X:X:X:X:d.d.d.d (X = 1 to 4 hexadecimal values, d = decimal value 0-255)
    # @param ip The IPv6 address to check
    # @return 1 if the IPv6 address is in this format, 0 if not

    set pattern_hex6dec4 {^([0-9A-Fa-f]{1,4}):([0-9A-Fa-f]{1,4}):([0-9A-Fa-f]{1,4}):([0-9A-Fa-f]{1,4}):([0-9A-Fa-f]{1,4}):([0-9A-Fa-f]{1,4}):([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])[.]{1}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])[.]{1}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])[.]{1}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])$}
    return [ regexp -- $pattern_hex6dec4 $ip ]

}

proc IPv6.IsCompressedv4Inv6 { ip } {
    # Check if the given IPv6 address is a complete format IPv6 address:
    # X:X:X:X:X:X:X:X (X = 1 to 4 hexadecimal values)
    #
    # @param ip The IPv6 address to check
    #
    # @return 1 if the IPv6 address is in this format, 0 if not
    ##

    set pattern_hex6dec4_compressed {^(([0-9A-Fa-f]{1,4}:)*)[:]?((:[0-9A-Fa-f]{1,4})*):([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])[.]{1}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])[.]{1}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])[.]{1}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])$}
    return [ regexp -- $pattern_hex6dec4_compressed $ip ]

}

proc IPv6.IsValid { ip } {
    # This Method checks if <ip> is a valid IPv6 address.
    #
    # @param ip The IPv6 address to check
    #
    # @return 1 for a valid IPv6 address, 0 for an invalid IPv6 address.
    ##

    return [ expr [ IPv6.IsComplete $ip ] ||\
        [ IPv6.IsCompressed $ip ] ||\
        [ IPv6.Isv4Inv6 $ip ] ||\
        [ IPv6.IsCompressedv4Inv6 $ip ] ]

}

proc IPv6.IsMulticast { ip } {
    return [ IPv6.IsValid $ip ] && \
        [ regexp -- {^([Ff]{2}[0-9A-Fa-f]{2}):} $ip ]
}

proc IP.IsValid { ip } {
    # This Method checks if <ip> is a valid IPv4 address OR a valid IPv6 address.
    #
    # @param ip The IPv4/IPv6 address to check
    #
    # @return 1 for a valid IPv6 address OR a valid IPv6 address,
    #         0 for an invalid IPv4/IPv6 address.
    ##

    return [ expr [ IPv4.IsValid $ip ] ||\
        [ IPv6.IsValid $ip ] ]

}

proc IP.To.Hex { ip } {
    # convertor 10.11.0.2  -> 0x0a 0x0b 0x00 0x02
    #
    # @param ip The IPv4 address to convert
    #
    # @return IPv4 address as a ByteList of 4 bytes
    ##

    if { ![ IPv4.IsValid $ip ]} {
        error "IP.To.Hex: Invalid IPv4 Format: '$ip'"
    }

    if { ![ regexp {^([0-9]*)\.([0-9]*)\.([0-9]*)\.([0-9]*)$} $ip dummy ip1 ip2 ip3 ip4 ]} {
        error "IP.To.Hex: Invalid IPv4 Format: '$ip'"
    }

    return [ list [ Byte.To.Hex $ip1 ] [ Byte.To.Hex $ip2 ] [ Byte.To.Hex $ip3 ] [ Byte.To.Hex $ip4 ] ]

}

proc Hex.To.IP { hex } {
    # Convert a hexadecimal string of 4 bytes (8 hex values) to an IPv4 address
    # XX:XX:XX:XX -> d.d.d.d
    #
    # @param hex hexadecimal representation of an IPv4 address will be converted into an IPv4 address
    #
    # @return IPv4 address, throws error on invalid <hex>
    #
    # @apiexample
    #     @apisnippet{01020304}
    #     @apisnippetretval{1.2.3.4}
    #     @apisnippet{Hex.To.IP 01:02:03:04}
    #     @apisnippetretval{1.2.3.4}
    #     @apisnippet{Hex.To.IP 01.02.03.04}
    #     @apisnippetretval{1.2.3.4}
    #     @apisnippet{Hex.To.IP 01-02-03-04}
    #     @apisnippetretval{1.2.3.4}
    #     @apisnippet{Hex.To.IP 01 02 03 04}
    #     @apisnippetretval{1.2.3.4}
    #     @apisnippet{Hex.To.IP 0x01 0x02 0x03 0x04}
    #     @apisnippetretval{1.2.3.4}
    # @endapiexample
    ##

    set hexMap [ string map {":" "" "." "" ";" "" "-" "" " " "" "0x" ""} $hex ]
    if { [ string length $hexMap ] != 8 || [ string is xdigit $hexMap ] != 1} {
        error "Hex.To.IP: Invalid hexadecimal IPv4 value : '${hex}'"
    }

    set result ""
    append result [ format "%d" 0x[ string range $hexMap 0 1 ] ] "." [ format "%d" 0x[ string range $hexMap 2 3 ] ] "."
    append result [ format "%d" 0x[ string range $hexMap 4 5 ] ] "." [ format "%d" 0x[ string range $hexMap 6 7 ] ]

    return $result

}

proc Byte.To.Hex { byte } {
    # converts the integer <byte> value to the hex notation 0xXX
    # eg: Byte.To.Hex 2     ->  0x02
    #     Byte.To.Hex 0x8   ->  0x08
    #
    # @param byte Integer value, maximum 255 (0xFF)
    #
    # @return 0xXX
    ##

    if { [ string equal $byte "" ] || ![ string is integer $byte ]} {
        error "Byte.To.Hex: Invalid Byte format <$byte>"
    }
    if { $byte > 0xFF} {
        error "Byte.To.Hex: Byte <$byte> greater than 255 (0xFF)"
    }

    return [ format "0x%02x" [ expr ( $byte & 0xFF ) ] ]

}

proc Short.To.Hex { short } {
    # converts the integer <short> value to the double hex notation 0xXX 0xXX list
    # eg: Short.To.Hex 2     ->  0x00 0x02
    #     Short.To.Hex 800   ->  0x03 0x20
    #     Short.To.Hex 0x806 ->  0x08 0x06
    #
    # @param short Integer value, maximum 65535 (0xFFFF)
    #
    # @return 0xXX 0xXX
    ##

    if { [ string equal $short "" ] || ![ string is integer $short ]} {
        error "Short.To.Hex: Invalid Short format <$short>"
    }
    if { $short > 0xFFFF} {
        error "Short.To.Hex: Short <$short> greater than 65535 (0xFFFF)"
    }

    return [ list [ format "0x%02x" [ expr ( ( $short / 0x100 ) & 0xFF ) ] ] [ format "0x%02x" [ expr ( $short & 0xFF ) ] ] ]

}

proc CheckSum.16 { byteList } {
    # This procedure calculates the 1's complement checksum for the listed ByteList
    # The List is divided in k sections of 16 bits
    # The 1's complement sum is made
    # The result is complemented
    # A list containing 2 elements checkSumH and checkSumL is returned
    #
    # CheckSum.16 "0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08"    -->  {0xef 0xeb}
    #
    # @param byteList The list of bytes to calculate the checksum from (multiple of 2 bytes!)
    #
    # @return the Checksum, ByteList of 2 bytes
    ##

    if { ![ ByteList.Check $byteList ]} {
        error "CheckSum.16 : Invalid ByteList, expecting list of 0xXX, where X is a hexadecimal value, got $byteList"
    }

    set length [ llength $byteList ]
    if { [ expr ( $length % 2 ) ]} {
        error "CheckSum.16 : ByteList is expected to hold multiple of 2 elements"
    }

    set twoByteList [ list ]
    foreach {byte1 byte2} $byteList {
        lappend twoByteList [ expr ( $byte1 * 0x100 + $byte2 ) ]
    }
    #puts $TwoByteList

    set checkSum 0
    foreach twoByte $twoByteList {
        incr checkSum $twoByte
        if { $checkSum > 0xFFFF} {
            set checkSum [ expr ( $checkSum & 0xFFFF ) ]
            incr checkSum
        }
    }
    #puts "0x[ format "%x" $checkSum ]"

    set checkSum [ expr (  0xFFFF - $checkSum  ) ]
    #puts "0x[ format "%x" $checkSum ]"

    return [ list [ format "0x%02x" [ expr ( $checkSum / 0x100 ) & 0xFF ] ] [ format "0x%02x" [ expr ( $checkSum & 0xFF ) ] ] ]

}

proc IPv6.To.Hex { ip } {
    # Converts an ipv6 address in colon notation to the hexadecimal notation 0xXX 0xXX ..
    #
    # @param ip The IPv6 address to convert
    #
    # @return IPv6 address as a ByteList (16 bytes)
    ##

    set octets [ split $ip ":" ]
    set result [ list ]
    if { [ IPv6.IsComplete $ip ]} {
        foreach octet $octets {
            set decOctet [ scan $octet "%x" ]
            lappend result [ format "0x%02x" [ expr ( $decOctet / 0x100 ) & 0xFF ] ] [ format "0x%02x" [ expr ( $decOctet & 0xFF ) ] ]
        }
    } elseif { [ IPv6.IsCompressed $ip ]} {
        set length [ llength $octets ]
        for { set teller 0} { $teller < $length} { incr teller} {
            set octet [ lindex $octets $teller ]
            # Replace compressed octet
            if { [ string equal $octet "" ]} {
                if { $teller == 0 || $teller == ( $length - 1 )} {
                    # First or last octet
                    lappend result 0x00 0x00
                } else {
                    # Calculate the number of missing 16 bit fields. Those are all 0x00 0x00.
                    for { set i $length} { $i < 9} { incr i} {
                        lappend result 0x00 0x00
                    }
                }
            } else {
                # Calculate the number of leading zeros.
                set decOctet [ scan $octet "%x" ]
                lappend result [ format "0x%02x" [ expr ( $decOctet / 0x100 ) & 0xFF ] ] [ format "0x%02x" [ expr ( $decOctet & 0xFF ) ] ]
            }
        }
    } else {
        # Invalid ip address
        error "IPv6.To.Hex: Unsupported IPv6 format: '$ip'"
    }

    return $result

}

proc Hex.To.IPv6 { hex } {
    # Convert a hexadecimal string of 16 bytes (32 hex values) to a Complete IPv6 address
    # e.g. XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    #      -> XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX
    # e.g. 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX
    #      -> XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX
    #
    # @param hex hexstring to convert to an IPv6 address
    #
    # @return IPv6 address, throws error on invalid <hex>
    ##

    set hexMap [ string map { ":" "" "." "" ";" "" " " "" "0x" ""} $hex ]
    if { [ string length $hexMap ] != 32 || [ string is xdigit $hexMap ] != 1} {
        error "Hex.To.IPv6: Invalid hexadecimal IPv6 value : '${hex}'"
    }
    set result ""
    append result [ string range $hexMap 0 3 ]  ":" [string range $hexMap 4 7 ] ":"\
        [ string range $hexMap 8 11 ] ":" [ string range $hexMap 12 15 ] ":" \
        [ string range $hexMap 16 19 ] ":" [ string range $hexMap 20 23 ] ":" \
        [ string range $hexMap 24 27 ] ":" [ string range $hexMap 28 31 ]

    return $result

}

proc IP.Increment { address { amount 1 } } {
    # Method which will create a new IPv4 address based on the provided address.
    # E.g. IP.Increment 10.0.0.1
    # will return 10.0.0.2
    #
    # @param address The IPv4 address to increment
    # @param amount The amount the IPv4 address will be incremented with
    #
    # @return IPv4 <address> incremented by 1, throws error on invalid <address>
    ##

    if { ![ IPv4.IsValid $address ]} {
        error "IP.To.Hex: Invalid IPv4 Format: '$address'"
    }

    set ipInt 0
    foreach integer [ split $address "." ] {
        set ipInt [ expr $ipInt * 256 + $integer ]
    }
    incr ipInt $amount
    set hexIp [ format %08x [ expr $ipInt & 0xFFFFFFFF ] ]
    return [ Hex.To.IP $hexIp ]

}

proc IPv6.Increment { address { amount 1 } } {
    # Method which will create a new IPv6 address based on the provided address.
    # E.g. IPv6.Increment 2001::5
    # will return 2001::6 ( but in full format )
    #
    # @param address The IPv6 address to increment
    # @param amount The amount the IPv6 address will be incremented with
    #
    # @return IPv6 <address> incremented by 1, throws error when a conversion problem occurs
    ##

    set ipInt 0
    set hexList [ split $address ":" ]

    if { ![ IPv6.IsValid $address ]} {
        error "IPv6.Increment: Invalid IPv6 Format: '$address'"
    }

    # If the IPv6 address is in compressed format,
    # we will expand it to the full format
    # If we have an empty element, replace it with the necessary zeros.
    if { [ set lpos [ lsearch $hexList {} ] ] != -1} {
        set zeros  [ expr 9 - [ llength $hexList ] ]
        for { set i 0} { $i <  $zeros} { incr i} {
            lappend zeroList 0000
        }
        set hexList [ eval lreplace [ list $hexList ] $lpos $lpos $zeroList ]
    }

    if { [ llength $hexList ] != 8} {
        error "IPv6.Increment: Error during convertion, did not receive 8 parts after decompressing address"
    }

    # Walk the 16 byte parts, increment, and update the hex result.
    set hexResults [ list ]
    set carry $amount
    for { set i 7} { $i >= 0} { incr i -1} {
        set decPart [ expr [ scan [ lindex $hexList $i ] "%x" ] + $carry ]
        #set decList [ lreplace $decList $i $i [ expr $decPart & 0xFFFF ] ]
        set hexResults [ linsert $hexResults 0 [ format "%04x" [ expr $decPart & 0xFFFF ] ] ]
        set carry [ expr ( $decPart >> 16 ) & 0xFFFF ]
    }
    return [ Hex.To.IPv6 [ join $hexResults "" ] ]

}

proc Mac.Increment { address } {
    # Method which will create a new Mac address based on the provided address.
    # E.g. Mac.Increment 00:ff:0a:00:00:01
    # will return 00:ff:0a:00:00:02
    #
    # @param address The MAC address to increment
    #
    # @return MAC <address> incremented by 1, throws error on invalid <address>
    ##

    #    if { ![ regexp {^((([0-9a-fA-F]{1,2})[" ":-]([0-9a-fA-F]{1,2})[" ":-]([0-9a-fA-F]{1,2})[" ":-]([0-9a-fA-F]{1,2})[" ":-]([0-9a-fA-F]{1,2})[" ":-])(([0-9a-fA-F]{1,2})))$} $address dummy1 dummy2 dummy3 a b c d e f ] } {
    #        error "Mac.Increment: Invalid MAC address format"
    #    }
    #    set hexInt 0x[ format "%02x%02x%02x%02x" [ scan $c "%x" ] [ scan $d "%x" ] [ scan $e "%x" ] [ scan $f "%x" ] ]
    #    set macPrefix [ format "%02x:%02x" [ scan $a "%x" ] [ scan $b "%x" ] ]
    #    incr hexInt
    #    set hexString [ format %08x $hexInt ]
    #
    #    return [ format "%s:%s:%s:%s:%s" $macPrefix [ string range $hexString end-7 end-6 ] [ string range $hexString end-5 end-4 ] [ string range $hexString end-3 end-2 ] [ string range $hexString end-1 end ] ]

    if { ![ regexp {^((([0-9a-fA-F]{1,2})[" ":-]([0-9a-fA-F]{1,2})[" ":-]([0-9a-fA-F]{1,2})[" ":-]([0-9a-fA-F]{1,2})[" ":-]([0-9a-fA-F]{1,2})[" ":-])(([0-9a-fA-F]{1,2})))$} $address dummy1 dummy2 dummy3 a b c d e f ]} {
        error "Mac.Increment: Invalid MAC address format"
    }
    set hexInt1 0x[ format "%02x%02x%02x" [ scan $a "%x" ] [ scan $b "%x" ] [ scan $c "%x" ] ]
    set hexInt2 0x[ format "%02x%02x%02x" [ scan $d "%x" ] [ scan $e "%x" ] [ scan $f "%x" ] ]
    incr hexInt2
    if { $hexInt2 > 0xFFFFFF} {
        incr hexInt1
    }
    set hexString [ format "%06x%06x" [ expr $hexInt1 & 0xFFFFFF ] [ expr $hexInt2 & 0xFFFFFF ] ]

    return [ format "%s:%s:%s:%s:%s:%s" [ string range $hexString 0 1 ] [ string range $hexString 2 3 ] [ string range $hexString 4 5 ] [ string range $hexString 6 7 ] [ string range $hexString 8 9 ] [ string range $hexString 10 11 ] ]

}

proc Multicast.IP.To.Mac { multicastAddress } {
    # Returns the multicast destination MAC Address for a given multicast IP Address
    # mac = (01-00-5E) - (3 last bytes of the multicastAddress & 0x7FFFFF)
    #
    # @param multicastAddress The multicast group IP Address
    #
    # @return The corresponding multicast destination MAC Address
    ##

    set ipList [ IP.To.Hex $multicastAddress ]

    set macList [ list "01" "00" "5E" ]
    lappend macList [ format "%02X" [ expr [ lindex $ipList 1 ] & 0x7F ] ]
    lappend macList [ format "%02X" [ lindex $ipList 2 ] ]
    lappend macList [ format "%02X" [ lindex $ipList 3 ] ]

    set multicastMac [ string toupper [ join $macList ":" ] ]

    return $multicastMac

}

proc Multicast.IPv6.To.Mac { ipv6MulticastAddress } {
    # Returns the multicast destination MAC Address for a given multicast IPv6 Address
    # IPv6   :    FF....:XXXX:XXXX
    #  |
    #  V
    # MAC    :    33:33:XX:XX:XX:XX (uses '33:33:' + 32 last bits of the ipv6MulticastAddress)
    #
    # @param ipv6MulticastAddress The IPv6 Multicast Address
    #
    # @return The corresponding multicast destination MAC Address
    ##

    set ipList [ IPv6.To.Hex $ipv6MulticastAddress ]

    set macList [ list "33" "33" ]
    lappend macList [ format "%02X" [ lindex $ipList end-3 ] ]
    lappend macList [ format "%02X" [ lindex $ipList end-2 ] ]
    lappend macList [ format "%02X" [ lindex $ipList end-1 ] ]
    lappend macList [ format "%02X" [ lindex $ipList end ] ]

    set multicastMac [ string toupper [ join $macList ":" ] ]

    return $multicastMac

}

proc String.To.Hex { byteString } {
    # converts a continuous string of bytes in hex format <byteString> to a list of bytes in hex notation 0xXX
    # eg: String.To.Hex 00A12BCC ->  0x00 0xA1 0x2B 0xCC
    #
    # @param byteString Hex bytestring of any size
    #
    # @return The list of bytes in hex notation
    ##

    if { [ expr [ string length $byteString ] % 2 ] != 0} {
        error "String.To.Hex: Invalid string format, need even number of characters <$byteString>"
    }

    set byteString [ string toupper $byteString ]
    set result [ list ]
    foreach {1 2} [ split $byteString {} ] { lappend result "0x$1$2"}
    return $result
}


proc Hex.To.String { byteList } {
    # converts a list of bytes in hex notation 0xXX <byteList> to a continuous string of bytes in hex format
    # eg: Hex.To.String 0x12 0x4 0x0b 0x0C -> 12040B0C 
    #
    # @param byteList The list of bytes in hex notation of any size
    #
    # @return Continuous string of bytes in hex format
    ##

    set formattedByteList [ list]
    foreach value $byteList { lappend formattedByteList [ format "%02X" $value ]}
    return [ join $formattedByteList "" ]
}


}

}