All Classes Namespaces Files Functions Pages
Layer5.Telnet.Client Class Reference

A Telnet client application that allows communication with an external Telnet server. More...

Methods

 Close
 Closes the Telnet session with the server and stops the Telnet client. More...
 
 ConnectionState.Get
 Returns the current TCP connection state. More...
 
 Description.Get
 Returns a textual description of the object.
 
 Local.Port.Get
 Returns the (local) TCP port used by this client. More...
 
 Local.Port.Set port
 Configures the (local) TCP port used by this client. More...
 
 Open
 Starts the Telnet client and opens the session with the Telnet server. More...
 
 Parent.Get
 Returns the parent object.
 
 Receive
 Reads data received over the Telnet session from the network and returns it. More...
 
 Remote.Address.Get
 Returns the IP address of the Telnet server to which this client connects. More...
 
 Remote.Address.Set address
 Sets the IP address of the Telnet server to which this client connects. More...
 
 Remote.Port.Get
 Returns the (remote) TCP port on the Telnet server to which this client connects.. More...
 
 Remote.Port.Set port
 Configures (remote) TCP port on the Telnet server to which this client connects. More...
 
 Send data
 Sends the provided to the Telnet server over the network.. More...
 

Class overview

A Telnet client application that allows communication with an external Telnet server.

The Telnet protocol allows for bidirectional interactive communication between a Telnet client (i.e. this application) on a ByteBlower port and an external Telnet server.

The Telnet protocol can be used to log in on other machines using a virtual terminal. By sending Telnet commands using Send, waiting for a small amount of time and reading the respons using Receive, a complete interactive session may be constructed.

The protocol can also be used to debug other network protocols. For example, contacting an HTTP server (on port 80) using a Telnet client and sending a valid HTTP request towards it, should correctly return the HTTP response data.

Since
API 2.2.0

Definition at line 17327 of file api.tcl.

Method documentation

Layer5.Telnet.Client::Close

Closes the Telnet session with the server and stops the Telnet client.

The TCP session will be closed and reset, so a new session can be opened.

If no Telnet session is open, nothing is done.

Example

This command closes the Telnet session if one is active.

1 $telnetClient Close

Definition at line 17341 of file api.tcl.

Layer5.Telnet.Client::ConnectionState.Get

Returns the current TCP connection state.

Returns
TCP ConnectionState Possible values are:
  • LISTEN
  • SYN_SENT
  • SYN_RECEIVED
  • ESTABLISHED
  • FIN_WAIT_1
  • FIN_WAIT_2
  • CLOSE_WAIT
  • CLOSING
  • LAST_ACK
  • TIME_WAIT
  • CLOSED
Example
1 set tcpSessionInfo [ $httpClientSessionInfo Tcp.Session.Info.Get ]
2  $tcpSessionInfo ConnectionState.Get

Returns:

TIME_WAIT 

Definition at line 17354 of file api.tcl.

Layer5.Telnet.Client::Local.Port.Get

Returns the (local) TCP port used by this client.

The client will communicate with the server through a TCP network socket on this port and listen on it for incoming traffic.

If the TCP port isn't explicitly set (yet), this will return a valid and unique TCP port number for within the scope of the ByteBlower port (e.g. 32687).

Default value
Valid unique client TCP port
Returns
The currently configured TCP port on this client. This is an integer value.
Example

This example returns the port number on which this client connects to the Telnet server.

1 $telnetClient Local.Port.Get

Returns:

40404 

Definition at line 17378 of file api.tcl.

Layer5.Telnet.Client::Local.Port.Set   port  

Configures the (local) TCP port used by this client.

The client will communicate with the server through a TCP network socket on this port and listen on it for incoming traffic.

If the TCP port isn't explicitly set (yet), the server will use a valid and unique TCP port number for within the scope of the ByteBlower port (e.g. 32687).

Default value
Valid and unique client TCP port
Parameters
portThe TCP port to be used by this client. This should be an integer value. Values larger the maximum port value of 65536 overflow into a valid port number.
Exceptions
InvalidValue.IntegerIf the parameter value isn't an integer, this exception is thrown.
ByteBlower.Protocol.ConfigLockedIf a Telnet session is currently opened, this exception is thrown. Use Close to close the session before changing the Telnet server port.
Example

This snippet sets the port number on which this client will connect to the Telnet server.

1 $telnetClient Local.Port.Set 40404

Definition at line 17401 of file api.tcl.

Layer5.Telnet.Client::Open

Starts the Telnet client and opens the session with the Telnet server.

It will create a new TCP connection. The TCP statistics will be reset. If a Telnet session is already open, nothing is done.

After calling this method, data may be sent to the server Send will be queued for transmission after this handshake.

Bug:
When contacting a non-existing or unreachable Telnet server, this application has unexpected behavior. The Layer5.Telnet.Client::Open method returns immediately and TCP moves to the 'active' status. After the timeout expires, TCP moves to the 'finished' status instead of the 'timeOut' status. All the while, data may be sent using Layer5.Telnet.Client::Send. This data is queued during the handshake, but it will not be sent.
Exceptions
ByteBlower.Protocol.UnavailableIf the Telnet server address has not been configured, this exception is thrown. Use Remote.Address.Set to configure the Telnet server address.
Example

This command opens the Telnet session, which initiates the handshake of the underlying TCP session. It returns immediately.

1 $telnetClient Open

Definition at line 17419 of file api.tcl.

Layer5.Telnet.Client::Receive

Reads data received over the Telnet session from the network and returns it.

If this method is executed, all received data since the last time it was called is returned. If more data is still flowing in from the network, the rest of the data will be returned the next time the receive method is executed.

Bug:
When contacting a non-existing or unreachable Telnet server, this method will not provide an error. When the TCP handshake fails (probably due to timeout), TCP will move (incorrectly) to finished after a while. None of the traffic sent at layer 5 will be received by the Telnet server.
Returns
The data received from the Telnet server.
Exceptions
ByteBlower.Protocol.InvalidActionWhen no session is active, this exception is thrown. Use Open to open the session.
Example

This example shows the response received from the Telnet server after sending the 'uname -a' command.

1 $telnetClient Receive

Returns:

Linux mylaptop 3.5.0-43-generic #66~precise1-Ubuntu SMP Thu Oct 24 14:52:23 UTC 2013 x86_64 x86_64 x86_64 GNU/Linux 

Definition at line 17442 of file api.tcl.

Layer5.Telnet.Client::Remote.Address.Get

Returns the IP address of the Telnet server to which this client connects.

Before this address is set, no connection can be opened or traffic can be sent.

Both IPv4 and IPv6 addresses are supported, but the provided (remote) address must match use the same IP protocol as the ByteBlower port of this client.

Note
Currently, DNS is not supported, so providing a URL is not possible.
Returns
The IP address of the Telnet server to which this client connects. This should be either an valid IPv4 address or a valid IPv6 address.
Exceptions
ByteBlower.Protocol.InvalidValueIf the remote IP address is not configured yet, this exception is thrown.
Example

This example returns the IP address of the Telnet server.

1 $telnetClient Remote.Address.Get

Returns:

10.8.65.65 

Definition at line 17462 of file api.tcl.

Layer5.Telnet.Client::Remote.Address.Set   address  

Sets the IP address of the Telnet server to which this client connects.

Before this address is set, no connection can be opened or traffic can be sent.

Both IPv4 and IPv6 addresses are supported, but the provided (remote) address must match be of the same type as the ByteBlower port of this client.

Note
Currently, DNS is not supported, so providing a URL is not possible.
Parameters
addressThe IP address of the Telnet server to which this client connects. This should be either an valid IPv4 address or a valid IPv6 address.
Exceptions
ByteBlower.Exception.API.ConfigErrorIf an invalid IP address is entered, this error is thrown.
ByteBlower.Protocol.InvalidValueIf an IPv4 address is provided, while this client is on an IPv6 ByteBlower port or vice versa, this exception is thrown.
ByteBlower.Protocol.ConfigLockedIf a Telnet session is currently opened, this exception is thrown. Use Close to close the session before changing the Telnet server address.
Example

This snippet sets the IP address of the Telnet server to be contacted.

1 $telnetClient Remote.Address.Set 1.2.3.4

Definition at line 17486 of file api.tcl.

Layer5.Telnet.Client::Remote.Port.Get

Returns the (remote) TCP port on the Telnet server to which this client connects..

The client will communicate with the Telnet server on the configured port.

If the TCP port isn't explicitly set (yet), this will return the default Telnet server port (23).

Default value
23
Returns
The currently configured TCP port on the Telnet server to which this client connects. This is an integer value.
Example

This example returns the port number of the Telnet server.

1 $telnetClient Remote.Port.Get

Returns:

2323 

Definition at line 17505 of file api.tcl.

Layer5.Telnet.Client::Remote.Port.Set   port  

Configures (remote) TCP port on the Telnet server to which this client connects.

The client will communicate with the Telnet server on the configured port.

If the TCP port isn't explicitly set (yet), the server will take the default Telnet server port (23).

Default value
23
Parameters
portThe TCP port on the Telnet server to which this client connects. This should be an integer value. Values larger the maximum port value of 65536 overflow into a valid port number.
Exceptions
InvalidValue.IntegerIf the parameter value isn't an integer, this exception is thrown.
ByteBlower.Protocol.ConfigLockedIf a Telnet session is currently opened, this exception is thrown. Use Close to close the session before changing the Telnet server port.
Example

This snippet sets the port number of the Telnet server to be contacted.

1 $telnetClient Remote.Port.Set 2323

Definition at line 17528 of file api.tcl.

Layer5.Telnet.Client::Send   data  

Sends the provided to the Telnet server over the network..

Data may be sent as soon as a connection is opened. Data sent during the TCP handshake will be queued to be sent immediately after it.

Bug:
When contacting a non-existing or unreachable Telnet server, this method will not provide an error. When the TCP handshake fails (probably due to timeout), TCP will move (incorrectly) to finished after a while. None of the traffic sent at layer 5 will be received by the Telnet server.
Parameters
dataThis string will be sent to the server for processing.
Exceptions
ByteBlower.Protocol.InvalidActionWhen no session is active, this exception is thrown. Use Open to open the session.
Example

This command sends the provided data over the network towards the Telnet server.

1 $telnetClient Send "uname -a"

Definition at line 17546 of file api.tcl.