.TH ct_telnet 3erl "common_test 1.24.0.3" "Ericsson AB" "Erlang Module Definition"
.SH NAME
ct_telnet \- Common Test specific layer on top of Telnet client ct_telnet_client.erl
.SH DESCRIPTION
.LP
\fICommon Test\fR\& specific layer on top of Telnet client \fIct_telnet_client\&.erl\fR\&\&.
.LP
Use this module to set up Telnet connections, send commands, and perform string matching on the result\&. For information about how to use \fIct_telnet\fR\& and configure connections, specifically for UNIX hosts, see the \fIunix_telnet\fR\& manual page\&.
.LP
Default values defined in \fIct_telnet\fR\&:
.RS 2
.TP 2
*
Connection timeout (time to wait for connection) = 10 seconds
.LP
.TP 2
*
Command timeout (time to wait for a command to return) = 10 seconds
.LP
.TP 2
*
Max number of reconnection attempts = 3
.LP
.TP 2
*
Reconnection interval (time to wait in between reconnection attempts) = 5 seconds
.LP
.TP 2
*
Keep alive (sends NOP to the server every 8 sec if connection is idle) = \fItrue\fR\&
.LP
.TP 2
*
Polling limit (max number of times to poll to get a remaining string terminated) = 0
.LP
.TP 2
*
Polling interval (sleep time between polls) = 1 second
.LP
.TP 2
*
The TCP_NODELAY option for the telnet socket is disabled (set to \fIfalse\fR\&) per default
.LP
.RE

.LP
These parameters can be modified by the user with the following configuration term:
.LP
.nf

 {telnet_settings, [{connect_timeout,Millisec},
                    {command_timeout,Millisec},
                    {reconnection_attempts,N},
                    {reconnection_interval,Millisec},
                    {keep_alive,Bool},
                    {poll_limit,N},
                    {poll_interval,Millisec},
                    {tcp_nodelay,Bool}]}.
.fi
.LP
\fIMillisec = integer(), N = integer()\fR\&
.LP
Enter the \fItelnet_settings\fR\& term in a configuration file included in the test and \fIct_telnet\fR\& retrieves the information automatically\&.
.LP
\fIkeep_alive\fR\& can be specified per connection, if necessary\&. For details, see \fIunix_telnet\fR\&\&.
.SH "LOGGING"

.LP
The default logging behavior of \fIct_telnet\fR\& is to print information about performed operations, commands, and their corresponding results to the test case HTML log\&. The following is not printed to the HTML log: text strings sent from the Telnet server that are not explicitly received by a \fIct_telnet\fR\& function, such as \fIexpect/3\fR\&\&. However, \fIct_telnet\fR\& can be configured to use a special purpose event handler, implemented in \fIct_conn_log_h\fR\&, for logging \fIall\fR\& Telnet traffic\&. To use this handler, install a \fICommon Test\fR\& hook named \fIcth_conn_log\fR\&\&. Example (using the test suite information function):
.LP
.nf

 suite() ->
     [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].
.fi
.LP
\fIconn_mod()\fR\& is the name of the \fICommon Test\fR\& module implementing the connection protocol, that is, \fIct_telnet\fR\&\&.
.LP
The \fIcth_conn_log\fR\& hook performs unformatted logging of Telnet data to a separate text file\&. All Telnet communication is captured and printed, including any data sent from the server\&. The link to this text file is located at the top of the test case HTML log\&.
.LP
By default, data for all Telnet connections is logged in one common file (named \fIdefault\fR\&), which can get messy, for example, if multiple Telnet sessions are running in parallel\&. Therefore a separate log file can be created for each connection\&. To configure this, use hook option \fIhosts\fR\& and list the names of the servers/connections to be used in the suite\&. The connections must be named for this to work (see \fIct_telnet:open/1,2,3,4\fR\&)\&.
.LP
Hook option \fIlog_type\fR\& can be used to change the \fIcth_conn_log\fR\& behavior\&. The default value of this option is \fIraw\fR\&, which results in the behavior described above\&. If the value is set to \fIhtml\fR\&, all Telnet communication is printed to the test case HTML log instead\&.
.LP
All \fIcth_conn_log\fR\& hook options described can also be specified in a configuration file with configuration variable \fIct_conn_log\fR\&\&.
.LP
\fIExample:\fR\&
.LP
.nf

 {ct_conn_log, [{ct_telnet,[{log_type,raw},
                            {hosts,[key_or_name()]}]}]}
.fi
.LP

.RS -4
.B
Note:
.RE
Hook options specified in a configuration file overwrite any hard-coded hook options in the test suite\&.

.LP
\fILogging Example:\fR\&
.LP
The following \fIct_hooks\fR\& statement causes printing of Telnet traffic to separate logs for the connections \fIserver1\fR\& and \fIserver2\fR\&\&. Traffic for any other connections is logged in the default Telnet log\&.
.LP
.nf

 suite() ->
     [{ct_hooks,
       [{cth_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}]}].
.fi
.LP
As previously explained, this specification can also be provided by an entry like the following in a configuration file:
.LP
.nf

 {ct_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}.
.fi
.LP
In this case the \fIct_hooks\fR\& statement in the test suite can look as follows:
.LP
.nf

 suite() ->
     [{ct_hooks, [{cth_conn_log, []}]}].
.fi
.SH DATA TYPES
.nf

.B
connection() = handle() | {target_name(), connection_type()} | target_name()
.br
.fi
.RS
.LP
For \fItarget_name()\fR\&, see module \fIct\fR\&\&.
.RE

.nf

.B
connection_type() = telnet | ts1 | ts2
.br
.fi
.nf

.B
handle() = handle()
.br
.fi
.RS
.LP
Handle for a specific Telnet connection, see module \fIct\fR\&\&.
.RE

.nf

.B
prompt_regexp() = string()
.br
.fi
.RS
.LP
Regular expression matching all possible prompts for a specific target type\&. \fIregexp\fR\& must not have any groups, that is, when matching, \fIre:run/3\fR\& (in STDLIB) must return a list with one single element\&.
.RE

.SH EXPORTS
.LP
.B
close(Connection) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Connection = connection()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Closes the Telnet connection and stops the process managing it\&.
.LP
A connection can be associated with a target name and/or a handle\&. If \fIConnection\fR\& has no associated target name, it can only be closed with the handle value (see \fIct_telnet:open/4\fR\&)\&.
.RE

.LP
.B
cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}
.br
.RS
.LP
Equivalent to \fIct_telnet:cmd(Connection, Cmd, [])\fR\&\&.
.RE

.LP
.B
cmd(Connection, Cmd, Opts) -> {ok, Data} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Connection = connection()
.br
Cmd = string()
.br
Opts = [Opt]
.br
Opt = {timeout, timeout()} | {newline, boolean() | string()}
.br
Data = [string()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Sends a command through Telnet and waits for prompt\&.
.LP
By default, this function adds "\\n" to the end of the specified command\&. If this is not desired, use option \fI{newline,false}\fR\&\&. This is necessary, for example, when sending Telnet command sequences prefixed with character Interpret As Command (IAC)\&. Option \fI{newline,string()}\fR\& can also be used if a different line end than "\\n" is required, for instance \fI{newline,"\\r\\n"}\fR\&, to add both carriage return and newline characters\&.
.LP
Option \fItimeout\fR\& specifies how long the client must wait for prompt\&. If the time expires, the function returns \fI{error,timeout}\fR\&\&. For information about the default value for the command timeout, see the list of default values in the beginning of this module\&.
.RE

.LP
.B
cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}
.br
.RS
.LP
Equivalent to \fIct_telnet:cmdf(Connection, CmdFormat, Args, [])\fR\&\&.
.RE

.LP
.B
cmdf(Connection, CmdFormat, Args, Opts) -> {ok, Data} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Connection = connection()
.br
CmdFormat = string()
.br
Args = list()
.br
Opts = [Opt]
.br
Opt = {timeout, timeout()} | {newline, boolean() | string()}
.br
Data = [string()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Sends a Telnet command and waits for prompt (uses a format string and a list of arguments to build the command)\&.
.LP
For details, see \fIct_telnet:cmd/3\fR\&\&.
.RE

.LP
.B
expect(Connection, Patterns) -> term()
.br
.RS
.LP
Equivalent to \fIct_telnet:expect(Connections, Patterns, [])\fR\&\&.
.RE

.LP
.B
expect(Connection, Patterns, Opts) -> {ok, Match} | {ok, MatchList, HaltReason} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Connection = connection()
.br
Patterns = Pattern | [Pattern]
.br
Pattern = string() | {Tag, string()} | prompt | {prompt, Prompt}
.br
Prompt = string()
.br
Tag = term()
.br
Opts = [Opt]
.br
Opt = {idle_timeout, IdleTimeout} | {total_timeout, TotalTimeout} | repeat | {repeat, N} | sequence | {halt, HaltPatterns} | ignore_prompt | no_prompt_check | wait_for_prompt | {wait_for_prompt, Prompt}
.br
IdleTimeout = infinity | integer()
.br
TotalTimeout = infinity | integer()
.br
N = integer()
.br
HaltPatterns = Patterns
.br
MatchList = [Match]
.br
Match = RxMatch | {Tag, RxMatch} | {prompt, Prompt}
.br
RxMatch = [string()]
.br
HaltReason = done | Match
.br
Reason = timeout | {prompt, Prompt}
.br
.RE
.RE
.RS
.LP
Gets data from Telnet and waits for the expected pattern\&.
.LP
\fIPattern\fR\& can be a POSIX regular expression\&. The function returns when a pattern is successfully matched (at least one, in the case of multiple patterns)\&.
.LP
\fIRxMatch\fR\& is a list of matched strings\&. It looks as follows \fI[FullMatch, SubMatch1, SubMatch2, \&.\&.\&.]\fR\&, where \fIFullMatch\fR\& is the string matched by the whole regular expression, and \fISubMatchN\fR\& is the string that matched subexpression number \fIN\fR\&\&. Subexpressions are denoted with \fI\&'(\&' \&')\&'\fR\& in the regular expression\&.
.LP
If a \fITag\fR\& is specified, the returned \fIMatch\fR\& also includes the matched \fITag\fR\&\&. Otherwise, only \fIRxMatch\fR\& is returned\&.
.LP
\fIOptions:\fR\&
.RS 2
.TP 2
.B
\fIidle_timeout\fR\&:
Indicates that the function must return if the Telnet client is idle (that is, if no data is received) for more than \fIIdleTimeout\fR\& milliseconds\&. Default time-out is 10 seconds\&.
.TP 2
.B
\fItotal_timeout\fR\&:
Sets a time limit for the complete \fIexpect\fR\& operation\&. After \fITotalTimeout\fR\& milliseconds, \fI{error,timeout}\fR\& is returned\&. Default is \fIinfinity\fR\& (that is, no time limit)\&.
.TP 2
.B
\fIignore_prompt | no_prompt_check\fR\&:
>The function returns when a prompt is received, even if no pattern has yet been matched, and \fI{error,{prompt,Prompt}}\fR\& is returned\&. However, this behavior can be modified with option \fIignore_prompt\fR\& or option \fIno_prompt_check\fR\&, which tells \fIexpect\fR\& to return only when a match is found or after a time-out\&.
.TP 2
.B
\fIignore_prompt\fR\&:
\fIct_telnet\fR\& ignores any prompt found\&. This option is useful if data sent by the server can include a pattern matching prompt \fIregexp\fR\& (as returned by \fITargedMod:get_prompt_regexp/0\fR\&), but is not to not cause the function to return\&.
.TP 2
.B
\fIno_prompt_check\fR\&:
\fIct_telnet\fR\& does not search for a prompt at all\&. This is useful if, for example, \fIPattern\fR\& itself matches the prompt\&.
.TP 2
.B
\fIwait_for_prompt\fR\&:
Forces \fIct_telnet\fR\& to wait until the prompt string is received before returning (even if a pattern has already been matched)\&. This is equal to calling \fIexpect(Conn, Patterns++[{prompt,Prompt}], [sequence|Opts])\fR\&\&. Notice that option \fIidle_timeout\fR\& and \fItotal_timeout\fR\& can abort the operation of waiting for prompt\&.
.TP 2
.B
\fIrepeat | repeat, N\fR\&:
The pattern(s) must be matched multiple times\&. If \fIN\fR\& is specified, the pattern(s) are matched \fIN\fR\& times, and the function returns \fIHaltReason = done\fR\&\&. This option can be interrupted by one or more \fIHaltPatterns\fR\&\&. \fIMatchList\fR\& is always returned, that is, a list of \fIMatch\fR\& instead of only one \fIMatch\fR\&\&. Also \fIHaltReason\fR\& is returned\&.
.TP 2
.B
\fIsequence\fR\&:
All patterns must be matched in a sequence\&. A match is not concluded until all patterns are matched\&. This option can be interrupted by one or more \fIHaltPatterns\fR\&\&. \fIMatchList\fR\& is always returned, that is, a list of \fIMatch\fR\& instead of only one \fIMatch\fR\&\&. Also \fIHaltReason\fR\& is returned\&.
.RE
.LP
\fIExample 1:\fR\&
.LP
.nf

 expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[sequence,{halt,[{nnn,"NNN"}]}])
.fi
.LP
First this tries to match \fI"ABC"\fR\&, and then \fI"XYZ"\fR\&, but if \fI"NNN"\fR\& appears, the function returns \fI{error,{nnn,["NNN"]}}\fR\&\&. If both \fI"ABC"\fR\& and \fI"XYZ"\fR\& are matched, the function returns \fI{ok,[AbcMatch,XyzMatch]}\fR\&\&.
.LP
\fIExample 2:\fR\&
.LP
.nf

 expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[{repeat,2},{halt,[{nnn,"NNN"}]}])
.fi
.LP
This tries to match \fI"ABC"\fR\& or \fI"XYZ"\fR\& twice\&. If \fI"NNN"\fR\& appears, the function returns \fIHaltReason = {nnn,["NNN"]}\fR\&\&.
.LP
Options \fIrepeat\fR\& and \fIsequence\fR\& can be combined to match a sequence multiple times\&.
.RE

.LP
.B
get_data(Connection) -> {ok, Data} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Connection = connection()
.br
Data = [string()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Gets all data received by the Telnet client since the last command was sent\&. Only newline-terminated strings are returned\&. If the last received string has not yet been terminated, the connection can be polled automatically until the string is complete\&.
.LP
The polling feature is controlled by the configuration values \fIpoll_limit\fR\& and \fIpoll_interval\fR\& and is by default disabled\&. This means that the function immediately returns all complete strings received and saves a remaining non-terminated string for a later \fIget_data\fR\& call\&.
.RE

.LP
.B
open(Name) -> {ok, Handle} | {error, Reason}
.br
.RS
.LP
Equivalent to \fIct_telnet:open(Name, telnet)\fR\&\&.
.RE

.LP
.B
open(Name, ConnType) -> {ok, Handle} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Name = target_name()
.br
ConnType = connection_type()
.br
Handle = handle()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Opens a Telnet connection to the specified target host\&.
.RE

.LP
.B
open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}
.br
.RS
.LP
Equivalent to \fIct_telnet:ct_telnet:open(KeyOrName, ConnType, TargetMod, [])\fR\&\&.
.RE

.LP
.B
open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
KeyOrName = Key | Name
.br
Key = atom()
.br
Name = target_name()
.br
ConnType = connection_type()
.br
TargetMod = atom()
.br
Extra = term()
.br
Handle = handle()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Opens a Telnet connection to the specified target host\&.
.LP
The target data must exist in a configuration file\&. The connection can be associated with \fIName\fR\& and/or the returned \fIHandle\fR\&\&. To allocate a name for the target, use one of the following alternatives:
.RS 2
.TP 2
*
\fIct:require/2\fR\& in a test case
.LP
.TP 2
*
A \fIrequire\fR\& statement in the suite information function (\fIsuite/0\fR\&)
.LP
.TP 2
*
A \fIrequire\fR\& statement in a test case information function
.LP
.RE

.LP
If you want the connection to be associated with \fIHandle\fR\& only (if you, for example, need to open multiple connections to a host), use \fIKey\fR\&, the configuration variable name, to specify the target\&. Notice that a connection without an associated target name can only be closed with the \fIHandle\fR\& value\&.
.LP
\fITargetMod\fR\& is a module that exports the functions \fIconnect(Ip, Port, KeepAlive, Extra)\fR\& and \fIget_prompt_regexp()\fR\& for the specified \fITargetType\fR\& (for example, \fIunix_telnet\fR\&)\&.
.LP
For \fItarget_name()\fR\&, see module \fIct\fR\&\&.
.LP
See also \fIct:require/2\fR\&\&.
.RE

.LP
.B
send(Connection, Cmd) -> ok | {error, Reason}
.br
.RS
.LP
Equivalent to \fIct_telnet:send(Connection, Cmd, [])\fR\&\&.
.RE

.LP
.B
send(Connection, Cmd, Opts) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Connection = connection()
.br
Cmd = string()
.br
Opts = [Opt]
.br
Opt = {newline, boolean() | string()}
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Sends a Telnet command and returns immediately\&.
.LP
By default, this function adds "\\n" to the end of the specified command\&. If this is not desired, option \fI{newline,false}\fR\& can be used\&. This is necessary, for example, when sending Telnet command sequences prefixed with character Interpret As Command (IAC)\&. Option \fI{newline,string()}\fR\& can also be used if a different line end than "\\n" is required, for instance \fI{newline,"\\r\\n"}\fR\&, to add both carriage return and newline characters\&.
.LP
The resulting output from the command can be read with \fIct_telnet:get_data/2\fR\& or \fIct_telnet:expect/2,3\fR\&\&.
.RE

.LP
.B
sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}
.br
.RS
.LP
Equivalent to \fIct_telnet:sendf(Connection, CmdFormat, Args, [])\fR\&\&.
.RE

.LP
.B
sendf(Connection, CmdFormat, Args, Opts) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Connection = connection()
.br
CmdFormat = string()
.br
Args = list()
.br
Opts = [Opt]
.br
Opt = {newline, boolean() | string()}
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Sends a Telnet command and returns immediately (uses a format string and a list of arguments to build the command)\&.
.LP
For details, see \fIct_telnet:send/3\fR\&\&.
.RE

.SH "SEE ALSO"

.LP
\fIunix_telnet\fR\&