.TH ct_telnet 3erl "common_test 1.6.1" "" "Erlang Module Definition"
.SH NAME
ct_telnet \- Common Test specific layer on top of telnet client ct_telnet_client.erl.
.SH DESCRIPTION
.LP
Common Test specific layer on top of telnet client ct_telnet_client\&.erl
.LP
Use this module to set up telnet connections, send commands and perform string matching on the result\&. See the \fIunix_telnet\fR\& manual page for information about how to use ct_telnet, and configure connections, specifically for unix hosts\&.
.LP
The following default values are defined in ct_telnet:
.LP
.nf

   Connection timeout = 10 sec (time to wait for connection)
   Command timeout = 10 sec (time to wait for a command to return)
   Max no of reconnection attempts = 3
   Reconnection interval = 5 sek (time to wait in between reconnection attempts)
   Keep alive = true (will send NOP to the server every 10 sec if connection is idle)
.fi
.LP
These parameters can be altered 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}]}.
.fi
.LP
\fIMillisec = integer(), N = integer()\fR\&
.LP
Enter the \fItelnet_settings\fR\& term in a configuration file included in the test and ct_telnet will retrieve the information automatically\&. Note that \fIkeep_alive\fR\& may be specified per connection if required\&. See \fIunix_telnet\fR\& for details\&.
.SH "DATA TYPES"

.RS 2
.TP 2
.B
\fIconnection() = handle() | {target_name() (see module ct), connection_type()} | target_name() (see module ct)\fR\&:

.TP 2
.B
\fIconnection_type() = telnet | ts1 | ts2\fR\&:

.TP 2
.B
\fIhandle() = handle() (see module ct_gen_conn)\fR\&:

.RS 2
.LP
Handle for a specific telnet connection\&.
.RE

.TP 2
.B
\fIprompt_regexp() = string()\fR\&:

.RS 2
.LP
A regular expression which matches all possible prompts for a specific type of target\&. The regexp must not have any groups i\&.e\&. when matching, re:run/3 shall return a list with one single element\&.
.RE

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

.RS 3
Connection = connection() (see module ct_telnet)
.br
.RE
.RE
.RS
.LP
Close the telnet connection and stop the process managing it\&.
.LP
A connection may be associated with a target name and/or a handle\&. If \fIConnection\fR\& has no associated target name, it may only be closed with the handle value (see the \fIopen/4\fR\& function)\&.
.RE

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

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

.RS 3
Connection = connection() (see module ct_telnet)
.br
Cmd = string()
.br
Timeout = integer()
.br
Data = [string()]
.br
.RE
.RE
.RS
.LP
Send a command via telnet and wait for prompt\&.
.RE

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

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

.RS 3
Connection = connection() (see module ct_telnet)
.br
CmdFormat = string()
.br
Args = list()
.br
Timeout = integer()
.br
Data = [string()]
.br
.RE
.RE
.RS
.LP
Send a telnet command and wait for prompt (uses a format string and list of arguments to build the command)\&.
.RE

.LP
.B
cont_log(Str, Args) -> term() 
.br
.RS
.RE

.LP
.B
end_log() -> term() 
.br
.RS
.RE

.LP
.B
expect(Connection, Patterns) -> term()
.br
.RS
.LP
Equivalent to \fBexpect(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() (see module ct_telnet)
.br
Patterns = Pattern | [Pattern]
.br
Pattern = string() | {Tag, string()} | prompt | {prompt, Prompt}
.br
Prompt = string()
.br
Tag = term()
.br
Opts = [Opt]
.br
Opt = {timeout, Timeout} | repeat | {repeat, N} | sequence | {halt, HaltPatterns} | ignore_prompt
.br
Timeout = 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
Get data from telnet and wait for the expected pattern\&.
.LP
\fIPattern\fR\& can be a POSIX regular expression\&. If more than one pattern is given, the function returns when the first match is found\&.
.LP
\fIRxMatch\fR\& is a list of matched strings\&. It looks like this: \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 no \fIN\fR\&\&. Subexpressions are denoted with \&'(\&' \&')\&' in the regular expression
.LP
If a \fITag\fR\& is given, the returned \fIMatch\fR\& will also include the matched \fITag\fR\&\&. Else, only \fIRxMatch\fR\& is returned\&.
.LP
The function will always return when a prompt is found, unless the \fIignore_prompt\fR\& options is used\&.
.LP
The \fItimeout\fR\& option indicates that the function shall return if the telnet client is idle (i\&.e\&. if no data is received) for more than \fITimeout\fR\& milliseconds\&. Default timeout is 10 seconds\&.
.LP
The \fIrepeat\fR\& option indicates that the pattern(s) shall be matched multiple times\&. If \fIN\fR\& is given, the pattern(s) will be matched \fIN\fR\& times, and the function will return with \fIHaltReason = done\fR\&\&.
.LP
The \fIsequence\fR\& option indicates that all patterns shall be matched in a sequence\&. A match will not be concluded untill all patterns are matched\&.
.LP
Both \fIrepeat\fR\& and \fIsequence\fR\& can be interrupted by one or more \fIHaltPatterns\fR\&\&. When \fIsequence\fR\& or \fIrepeat\fR\& is used, there will always be a \fIMatchList\fR\& returned, i\&.e\&. a list of \fIMatch\fR\& instead of only one \fIMatch\fR\&\&. There will also be a \fIHaltReason\fR\& returned\&.
.LP
\fIExamples:\fR\&
.br
\fIexpect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],\fR\& \fI[sequence,{halt,[{nnn,"NNN"}]}])\&.\fR\&
.br
will try to match "ABC" first and then "XYZ", but if "NNN" appears the function will return \fI{error,{nnn,["NNN"]}}\fR\&\&. If both "ABC" and "XYZ" are matched, the function will return \fI{ok,[AbcMatch,XyzMatch]}\fR\&\&.
.LP
\fIexpect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],\fR\& \fI[{repeat,2},{halt,[{nnn,"NNN"}]}])\&.\fR\&
.br
will try to match "ABC" or "XYZ" twice\&. If "NNN" appears the function will return with \fIHaltReason = {nnn,["NNN"]}\fR\&\&.
.LP
The \fIrepeat\fR\& and \fIsequence\fR\& options can be combined in order to match a sequence multiple times\&.
.RE

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

.RS 3
Connection = connection() (see module ct_telnet)
.br
Data = [string()]
.br
.RE
.RE
.RS
.LP
Get all data which has been received by the telnet client since last command was sent\&.
.RE

.LP
.B
open(Name) -> {ok, Handle} | {error, Reason}
.br
.RS
.LP
Equivalent to \fBopen(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() (see module ct_telnet)
.br
Handle = handle() (see module ct_telnet)
.br
.RE
.RE
.RS
.LP
Open a telnet connection to the specified target host\&.
.RE

.LP
.B
open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}
.br
.RS
.LP
Equivalent to \fBopen(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() (see module ct)
.br
ConnType = connection_type()
.br
TargetMod = atom()
.br
Extra = term()
.br
Handle = handle()
.br
.RE
.RE
.RS
.LP
Open a telnet connection to the specified target host\&.
.LP
The target data must exist in a configuration file\&. The connection may be associated with either \fIName\fR\& and/or the returned \fIHandle\fR\&\&. To allocate a name for the target, use \fIct:require/2\fR\& in a test case, or use a \fIrequire\fR\& statement in the suite info function (\fIsuite/0\fR\&), or in a test case info function\&. If you want the connection to be associated with \fIHandle\fR\& only (in case you need to open multiple connections to a host for example), simply use \fIKey\fR\&, the configuration variable name, to specify the target\&. Note that a connection that has no associated target name can only be closed with the handle value\&.
.LP
\fITargetMod\fR\& is a module which exports the functions \fIconnect(Ip,Port,KeepAlive,Extra)\fR\& and \fIget_prompt_regexp()\fR\& for the given \fITargetType\fR\& (e\&.g\&. \fIunix_telnet\fR\&)\&.
.RE

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

.RS 3
Connection = connection() (see module ct_telnet)
.br
Cmd = string()
.br
.RE
.RE
.RS
.LP
Send a telnet command and return immediately\&.
.LP
The resulting output from the command can be read with \fIget_data/1\fR\& or \fIexpect/2/3\fR\&\&.
.RE

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

.RS 3
Connection = connection() (see module ct_telnet)
.br
CmdFormat = string()
.br
Args = list()
.br
.RE
.RE
.RS
.LP
Send a telnet command and return immediately (uses a format string and a list of arguments to build the command)\&.
.RE

.SH "SEE ALSO"

.LP
\fBunix_telnet\fR\&
.SH AUTHORS
.LP

.I
<>