All Classes Namespaces Files Functions Pages
Layer3.IcmpEchoSession Class Reference

Session for handling ICMP Echo Requests and Replies. More...

Methods

 Data.Size.Get
 Returns the data size. More...
 
 Data.Size.Set dataSize
 Configures the data size. More...
 
 Description.Get
 Returns a textual description of the object.
 
 DestinationIp.Get
 Returns the ICMP Echo Request destination IPv4 address. More...
 
 DestinationIp.Set ipv4Address
 Configure the destination IPv4 address. More...
 
 Echo.Loop.Count.Get
 Returns the Echo Request count. More...
 
 Echo.Loop.Count.Set packetCount
 Configures the Echo Request count. More...
 
 Echo.Loop.Interval.Get
 Returns the Echo Request interval. More...
 
 Echo.Loop.Interval.Set loopInterval
 Configures the Echo Request interval. More...
 
 Echo.Loop.Start
 Starts sending Echo Requests in a loop. More...
 
 Echo.Loop.Stop
 Stops sending Echo Requests in a loop. More...
 
 Echo.Request.Send
 Transmit an ICMP Echo Request. More...
 
 Echo.Statistics.Clear
 Resets the ICMP Session statistics. More...
 
 Echo.Statistics.Get
 Returns the ICMP Echo Session statistics. More...
 
 Identifier.Get
 Returns the ICMP Echo Request IcmpID. More...
 
 Parent.Get
 Returns the parent object.
 
 Remote.Address.Get
 Returns the ICMP Echo Request destination IPv4 address. More...
 
 Remote.Address.Set ipv4Address
 Configure the destination IPv4 address. More...
 
 Session.Info.Get
 Returns the session information. More...
 
 Ttl.Get
 Returns the current IPv4 time-to-live. More...
 
 Ttl.Set ttl
 Configures the IPv4 time-to-live. More...
 
 TypeOfService.Get
 Retrieves the 'Type Of Service' configuration of the IP layer. More...
 
 TypeOfService.Set
 Configures the 'Type Of Service' used at the IP layer. More...
 

Class overview

Session for handling ICMP Echo Requests and Replies.

This Session uses the ICMP protocol for receiving and / or transmitting ICMP Echo Request and / or Replies

Some use cases for this session are:

DUT validation
  • Verify Echo Request / Replies are either or not filtered out
  • Verify public / private connectivity for Routers, NAT gateways, ...
DUT stability
Verify Echo Replies are received during some stability tests

Definition at line 6634 of file api.tcl.

Method documentation

Layer3.IcmpEchoSession::Data.Size.Get

Returns the data size.

This method returns the data size of our ICMP Echo Requests

The data size of our ICMP Echo Requests is the payload size of the packet

Default value: 56
Returns
ICMP Echo data size
Example

The ICMP session has been configure to add 76Bytes payload in the ICMP Request packets

1 $icmpSession Data.Size.Get

Returns:

76 

Definition at line 6652 of file api.tcl.

Layer3.IcmpEchoSession::Data.Size.Set   dataSize  

Configures the data size.

This method configures the data size of our ICMP Echo Requests

The data size of our ICMP Echo Requests is the payload size of the packet

Parameters
dataSizeThe ICMP data size you wish to configure.
Valid range: 0 to <port_mdl> - <icmp_header_size>.
Where
<port_mdl>
Value of ByteBlowerPort::MDL.Get
<icmp_header_size>
Ethernet header size (14) + IPv4 header size (20) + ICMP header size (8)
Default value: 56
Exceptions
<tcl_error>bad lexical cast: When the value could not be interpreted as a valid integer
ByteBlower.Protocol.InvalidValueWhen the value is out of range
Example

Configure 92Bytes payload for the ICMP Request packets

1 $icmpSession Data.Size.Set 92

Definition at line 6676 of file api.tcl.

Layer3.IcmpEchoSession::DestinationIp.Get

Returns the ICMP Echo Request destination IPv4 address.

Since
2.3.0

This method returns the IPv4 address which has been configured with Remote.Address.Set

Returns
The Destination IPv4 address for this session.
Exceptions
ByteBlower.SessionWhen the destination IPv4 address was not yet configured
Example
1 $icmpSession Remote.Address.Get

Returns:

1.2.3.4 

Definition at line 6699 of file api.tcl.

Layer3.IcmpEchoSession::DestinationIp.Set   ipv4Address  

Configure the destination IPv4 address.

Since
2.3.0

This method configures the destination IPv4 address for our ICMP Echo packets

The destination IPv4 address defines to where the ICMP Echo Requests will be sent or from where ICMP Echo Responses are / were received.

Parameters
ipv4AddressThe Destination IPv4 Address for this session.
Exceptions
<tcl_error>Invalid IPv4 address: When the value could not be interpreted as an IPv4 address
Example
1 $icmpSession Remote.Address.Set "1.2.3.4"

Definition at line 6719 of file api.tcl.

Layer3.IcmpEchoSession::Echo.Loop.Count.Get

Returns the Echo Request count.

This method returns the number of Echo Requests which will be transmitted when sending in a loop.

Default value: infinite
The actual value is <max_uint64> = 0xFFFFFFFFFFFFFFFF = 18446744073709551615)
Returns
The number of ICMP Echo Request packets in a loop
Since
1.8.18
Example

The transmit loop is configured to transmit 12345 packets

1 $icmpSession Echo.Loop.Count.Get

Returns:

12345 

Definition at line 6738 of file api.tcl.

Layer3.IcmpEchoSession::Echo.Loop.Count.Set   packetCount  

Configures the Echo Request count.

This method configures the number of Echo Requests which will be transmitted when sending in a loop.

The Echo Request Loop can be started using Echo.Loop.Start

Parameters
packetCountThe number of ICMP Echo Request packets to transmit
Default value: infinite
The actual value is <max_uint64> = 0xFFFFFFFFFFFFFFFF = 18446744073709551615)
Exceptions
<tcl_error>bad lexical cast: When the value could not be interpreted as a valid integer
Since
1.8.18
Example

Configure the loop to transmit 100 ICMP Echo Request packets

1 $icmpSession Echo.Loop.Count.Set 100

Definition at line 6761 of file api.tcl.

Layer3.IcmpEchoSession::Echo.Loop.Interval.Get

Returns the Echo Request interval.

This method returns the interval between subsequent Echo Request packets when sending in a loop.

The Echo Request Loop can be started using Echo.Loop.Start

Note
The interval is always returned in nanoseconds resolution. No unit is added to the value.
Default value: 1s
Returns
The interval between two ICMP Echo Request packets [ns]
Example

The transmit loop is configured with an interval of 625 microseconds

1 $icmpSession Echo.Loop.Interval.Get

Returns:

625000 

Definition at line 6781 of file api.tcl.

Layer3.IcmpEchoSession::Echo.Loop.Interval.Set   loopInterval  

Configures the Echo Request interval.

This method configures the interval between subsequent Echo Request packets when sending in a loop.

The interval has a nanosecond resolution. You can provide a time unit for the loop interval value.

The Echo Request Loop can be started using Echo.Loop.Start

Parameters
loopIntervalThe interval between two ICMP Echo Request packets [ns].
Valid range: 0 to <max_uint64>[ns]
Where
<max_uint64>
0xFFFFFFFFFFFFFFFF = 18446744073709551615 = maximum unsigned 64bit integer)
Default value: 1s
Exceptions
<tcl_error>Failed to parse time string: When the value could not be interpreted as a valid time string
Example

Configure an interval of 50 microseconds (50000 nanoseconds)

1 $icmpSession Echo.Loop.Interval.Set 50000

Configure an interval of 500 milliseconds

1 $icmpSession Echo.Loop.Interval.Set 500ms

Configure an interval of 1.25 milliseconds

1 $icmpSession Echo.Loop.Interval.Set 1250us

Definition at line 6805 of file api.tcl.

Layer3.IcmpEchoSession::Echo.Loop.Start

Starts sending Echo Requests in a loop.

This method start sending Echo Requests in a loop.

The interval between Echo Request can be configured using the method Echo.Loop.Interval.Set

If a limited number of Echo Request is desired, this can be configured using the method Echo.Loop.Count.Set

Note
This method call is (partially) non-blocking. The call will return as soon as the session is started an the loop is running or an error occurred during session initialization.
Precondition
The Destination IPv4 address must be configured (using DestinationIp.Set) before sending Echo Requests
Exceptions
ByteBlower.Session.UnavailableWhen the destination IPv4 address was not yet configured
ByteBlower.Protocol.Session.CreationFailedWhen the destination IPv4 address cannot be reached

Definition at line 6825 of file api.tcl.

Layer3.IcmpEchoSession::Echo.Loop.Stop

Stops sending Echo Requests in a loop.

This method stops sending Echo Requests in a loop. The loop can be started with Echo.Loop.Start

Note
This method does not throw an exception if the loop was not started

Definition at line 6835 of file api.tcl.

Layer3.IcmpEchoSession::Echo.Request.Send

Transmit an ICMP Echo Request.

This method sends one ICMP Echo Request.

Note
This method call is (partially) non-blocking. The call will not return as soon the session is setup and the request is sent or an error occurred (exception is thrown). The call does not wait until an Echo Reply is received.

The results/statistics can be obtained using the method Echo.Statistics.Get

Precondition
The Destination IPv4 address must be configured (using DestinationIp.Set) before sending Echo Requests
Exceptions
ByteBlower.Session.UnavailableWhen the destination IPv4 address was not yet configured
ByteBlower.Protocol.Session.CreationFailedWhen the destination IPv4 address cannot be reached

Definition at line 6853 of file api.tcl.

Layer3.IcmpEchoSession::Echo.Statistics.Clear

Resets the ICMP Session statistics.

Deprecated:
Deprecated since version 2.3.0. The recommended approach is to destruct this session and create a new one.

This method resets the ICMP Session statistics.

The counters which are returned by Echo.Statistics.Get are set to 0

Definition at line 6865 of file api.tcl.

Layer3.IcmpEchoSession::Echo.Statistics.Get

Returns the ICMP Echo Session statistics.

This method returns the ICMP Echo Session statistics

Deprecated:
Deprecated since version 2.3.0 in favor of Session.Info.Get , which provides the same information
Returns
Returns a list of 4 name-value pairs with various packet counters on this session:
RxEchoRequests
Number of ICMP Echo Requests received.
TxEchoReplies
Number of ICMP Echo Replies sent.
TxEchoRequests
Number of ICMP Echo Requests sent.
RxEchoReplies
Number of ICMP Echo Replies received.
Example
1 $icmpSession Echo.Statistics.Get

Returns:

RxEchoRequests 0 TxEchoReplies 0 TxEchoRequests 0 RxEchoReplies 0 

Definition at line 6881 of file api.tcl.

Layer3.IcmpEchoSession::Identifier.Get

Returns the ICMP Echo Request IcmpID.

This method returns the ICMP Echo Request IcmpID. This is also known as the Application ID

The Application ID is either generated randomly or is the one that has been provided with Layer3.IcmpProtocol::Session.Add

Returns
The ICMP Echo Request ICMP ID for this Session.
Example

Returns the (integer) value of the ICMP ID (Application ID)

1 $icmpSession Identifier.Get

Returns:

21764 

Definition at line 6897 of file api.tcl.

Layer3.IcmpEchoSession::Remote.Address.Get

Returns the ICMP Echo Request destination IPv4 address.

Since
2.3.0

This method returns the IPv4 address which has been configured with Remote.Address.Set

Returns
The Destination IPv4 address for this session.
Exceptions
ByteBlower.SessionWhen the destination IPv4 address was not yet configured
Example
1 $icmpSession Remote.Address.Get

Returns:

1.2.3.4 

Definition at line 6920 of file api.tcl.

Layer3.IcmpEchoSession::Remote.Address.Set   ipv4Address  

Configure the destination IPv4 address.

Since
2.3.0

This method configures the destination IPv4 address for our ICMP Echo packets

The destination IPv4 address defines to where the ICMP Echo Requests will be sent or from where ICMP Echo Responses are / were received.

Parameters
ipv4AddressThe Destination IPv4 Address for this session.
Exceptions
<tcl_error>Invalid IPv4 address: When the value could not be interpreted as an IPv4 address
Example
1 $icmpSession Remote.Address.Set "1.2.3.4"

Definition at line 6940 of file api.tcl.

Layer3.IcmpEchoSession::Session.Info.Get

Returns the session information.

Since
2.3.0

This method returns the SessionInfo object.

Returns
A SessionInfo object of type Layer3.Icmp.EchoSessionInfo object.
Example

The transmit loop is configured to transmit 12345 packets

1 $icmpSession Session.Info.Get

Returns:

OID 

Definition at line 6956 of file api.tcl.

Layer3.IcmpEchoSession::Ttl.Get

Returns the current IPv4 time-to-live.

This method returns the current IPv4 TTL (time-to-live) for the ICMP Echo packets.

The TTL defines the maximum lifetime of an IPv4 (in this case ICMP) packet in the network. Every router that the packet passes decrements the TTL field in the packet. When the TTL reaches value 0 before it is delivered at its destination, it will be dropped. The router will respond to the sender with an ICMP packet type 11 (Time Exceeded).

Note
The IPv4 TTL applies for all ICMP Echo packets (Requests and Responses)
Default value: 255
Returns
IPv4 time-to-live for all ICMP Echo packets
Since
1.8.18

Definition at line 6974 of file api.tcl.

Layer3.IcmpEchoSession::Ttl.Set   ttl  

Configures the IPv4 time-to-live.

This method configures the IPv4 TTL (time-to-live) for the ICMP Echo packets.

The TTL defines the maximum lifetime of an IPv4 (in this case ICMP) packet in the network. Every router that the packet passes decrements the TTL field in the packet. When the TTL reaches value 0 before it is delivered at its destination, it will be dropped. The router will respond to the sender with an ICMP packet type 11 (Time Exceeded).

Note
The IPv4 TTL applies for all ICMP Echo packets (Requests and Responses)
The TTL only applies for this session, other sessions in this Layer3.IcmpProtocol are not affected.
Parameters
ttlThe IPv4 TTL you wish to configure.
Valid range: 0 to 255.
Default value: 255
Exceptions
<tcl_error>bad lexical cast: When the value could not be interpreted as a valid integer
ByteBlower.Protocol.InvalidValueWhen the value is out of range
Since
1.8.18
Example

Configure a TTL of 127 for the ICMP Request and Reply packets

1 $icmpSession Ttl.Set 127

Definition at line 7003 of file api.tcl.

Layer3.IcmpEchoSession::TypeOfService.Get

Retrieves the 'Type Of Service' configuration of the IP layer.

Since
2.5.0

This method returns a number from 0 up to 255. This value represents the the byte used at the IP layer.

Returns
The byte value of the 'Type Of Service' or 'Traffic Class' field. The default value is 0.
Example
1 $icmpSession TypeOfServiceGet

Definition at line 7019 of file api.tcl.

Layer3.IcmpEchoSession::TypeOfService.Set

Configures the 'Type Of Service' used at the IP layer.

Since
2.5.0

The input accepts integers from 0 up to 255. This value will be directly used in byte-sized field at the IP layer. No additional coding is performed.

This method can be called solely during the configuration phase, thus before the parent ByteBlower port is started. Invoking the method at other moments will result in error.

Example
1 $icmpSession TypeOfServiceSet 16

Definition at line 7035 of file api.tcl.