-spec close(Connection) -> ok | {error, Reason}
               when Connection :: connection(), Reason :: already_closed | term().

Closes the Telnet connection and stops the process managing it.

A connection can be associated with a target name and/or a handle. If Connection has no associated target name, it can only be closed with the handle value (see ct_telnet:open/4).

-spec cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}
             when Connection :: connection(), Cmd :: iodata(), Data :: string(), Reason :: term().

Equivalent to cmd(Connection, Cmd, []).

-spec cmd(Connection, Cmd, Opts) -> {ok, Data} | {error, Reason}
             when
                 Connection :: connection(),
                 Cmd :: iodata(),
                 Opts :: [{timeout, Timeout} | send_option()] | Timeout,
                 Timeout :: integer(),
                 Data :: string(),
                 Reason :: term().

Sends a command through Telnet and waits for prompt.

By default, this function adds "\n" to the end of the specified command. If this is not desired, use option {newline,false}. This is necessary, for example, when sending Telnet command sequences prefixed with character Interpret As Command (IAC). Option {newline,string()} can also be used if a different line end than "\n" is required, for instance {newline,"\r\n"}, to add both carriage return and newline characters.

Option timeout specifies how long the client must wait for prompt. If the time expires, the function returns {error,timeout}. For information about the default value for the command timeout, see the list of default values in the beginning of this module.

-spec cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}
              when
                  Connection :: connection(),
                  CmdFormat :: io:format(),
                  Args :: [term()],
                  Data :: string(),
                  Reason :: term().

Equivalent to cmdf(Connection, CmdFormat, Args, []).

-spec cmdf(Connection, CmdFormat, Args, Opts) -> {ok, Data} | {error, Reason}
              when
                  Connection :: connection(),
                  CmdFormat :: io:format(),
                  Args :: [term()],
                  Opts :: [{timeout, Timeout} | send_option()] | Timeout,
                  Timeout :: integer(),
                  Data :: string(),
                  Reason :: term().

Sends a Telnet command and waits for prompt (uses a format string and a list of arguments to build the command).

For details, see ct_telnet:cmd/3.

-spec expect(Connection, Patterns) ->
                {ok, Match} | {ok, Match, HaltReason} | {error, Reason} | no_return()
                when
                    Connection :: connection(),
                    Patterns :: Pattern | [Pattern],
                    Pattern :: PatternString | {Tag, PatternString},
                    Tag :: term(),
                    PatternString :: unicode:charlist(),
                    Match :: MatchResult | [MatchResult],
                    MatchResult ::
                        [CaptureData | {Tag, CaptureData}] | [[CaptureData | {Tag, CaptureData}]],
                    CaptureData ::
                        string() | {error, string(), binary()} | {incomplete, string(), binary()},
                    HaltReason :: MatchResult,
                    Reason :: term().

Equivalent to expect(Connection, Patterns, []).

-spec expect(Connection, Patterns, Opts) ->
                {ok, Match} | {ok, Match, HaltReason} | {error, Reason} | no_return()
                when
                    Connection :: connection(),
                    Patterns :: Pattern | [Pattern],
                    Pattern :: PatternString | {Tag, PatternString},
                    Tag :: term(),
                    PatternString :: unicode:charlist(),
                    Opts :: [Option],
                    Option ::
                        {idle_timeout, non_neg_integer()} |
                        {total_timeout, non_neg_integer()} |
                        ignore_prompt | no_prompt_check | wait_for_prompt | repeat |
                        {repeat, non_neg_integer()} |
                        sequence |
                        {halt, Patterns},
                    Match :: MatchResult | [MatchResult],
                    MatchResult ::
                        [CaptureData | {Tag, CaptureData}] | [[CaptureData | {Tag, CaptureData}]],
                    CaptureData ::
                        string() | {error, string(), binary()} | {incomplete, string(), binary()},
                    HaltReason :: MatchResult,
                    Reason :: term().

Gets data from Telnet and waits for the expected pattern.

Pattern can be a POSIX regular expression. The function returns when a pattern is successfully matched (at least one, in the case of multiple patterns).

RxMatch is a list of matched strings. It looks as follows [FullMatch, SubMatch1, SubMatch2, ...], where FullMatch is the string matched by the whole regular expression, and SubMatchN is the string that matched subexpression number N. Subexpressions are denoted with '(' ')' in the regular expression.

If a Tag is specified, the returned Match also includes the matched Tag. Otherwise, only RxMatch is returned.

Options:

• idle_timeout - Indicates that the function must return if the Telnet client is idle (that is, if no data is received) for more than IdleTimeout milliseconds. Default time-out is 10 seconds.

• total_timeout - Sets a time limit for the complete expect operation. After TotalTimeout milliseconds, {error,timeout} is returned. Default is infinity (that is, no time limit).

• ignore_prompt | no_prompt_check - >The function returns when a prompt is received, even if no pattern has yet been matched, and {error,{prompt,Prompt}} is returned. However, this behavior can be modified with option ignore_prompt or option no_prompt_check, which tells expect to return only when a match is found or after a time-out.

• ignore_prompt - ct_telnet ignores any prompt found. This option is useful if data sent by the server can include a pattern matching prompt regexp (as returned by TargedMod:get_prompt_regexp/0), but is not to not cause the function to return.

• no_prompt_check - ct_telnet does not search for a prompt at all. This is useful if, for example, Pattern itself matches the prompt.

• wait_for_prompt - Forces ct_telnet to wait until the prompt string is received before returning (even if a pattern has already been matched). This is equal to calling expect(Conn, Patterns++[{prompt,Prompt}], [sequence|Opts]). Notice that option idle_timeout and total_timeout can abort the operation of waiting for prompt.

• repeat | repeat, N - The pattern(s) must be matched multiple times. If N is specified, the pattern(s) are matched N times, and the function returns HaltReason = done. This option can be interrupted by one or more HaltPatterns. MatchList is always returned, that is, a list of Match instead of only one Match. Also HaltReason is returned.

• sequence - 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 HaltPatterns. MatchList is always returned, that is, a list of Match instead of only one Match. Also HaltReason is returned.

Example 1:

expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[sequence,{halt,[{nnn,"NNN"}]}])

First this tries to match "ABC", and then "XYZ", but if "NNN" appears, the function returns {error,{nnn,["NNN"]}}. If both "ABC" and "XYZ" are matched, the function returns {ok,[AbcMatch,XyzMatch]}.

Example 2:

expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[{repeat,2},{halt,[{nnn,"NNN"}]}])

This tries to match "ABC" or "XYZ" twice. If "NNN" appears, the function returns HaltReason = {nnn,["NNN"]}.

Options repeat and sequence can be combined to match a sequence multiple times.

-spec get_data(Connection) -> {ok, Data} | {error, Reason}
                  when Connection :: connection(), Data :: string(), Reason :: term().

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.

The polling feature is controlled by the configuration values poll_limit and poll_interval 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 get_data call.

-spec open(Name) -> {ok, Handle} | {error, Reason}
              when Name :: atom(), Handle :: handle(), Reason :: term().

Equivalent to open(Name, telnet).

-spec open(Name, ConnType) -> {ok, Handle} | {error, Reason}
              when Name :: atom(), ConnType :: connection_type(), Handle :: handle(), Reason :: term().

Opens a Telnet connection to the specified target host.

-spec open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}
              when
                  KeyOrName :: atom(),
                  ConnType :: connection_type(),
                  TargetMod :: module(),
                  Handle :: handle(),
                  Reason :: term().

Equivalent to open(KeyOrName, ConnType, TargetMod, KeyOrName).

-spec open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle} | {error, Reason}
              when
                  KeyOrName :: atom(),
                  ConnType :: connection_type(),
                  TargetMod :: module(),
                  Extra :: term(),
                  Handle :: handle(),
                  Reason :: term().

Opens a Telnet connection to the specified target host.

The target data must exist in a configuration file. The connection can be associated with Name and/or the returned Handle. To allocate a name for the target, use one of the following alternatives:

• ct:require/2 in a test case
• A require statement in the suite information function (suite/0)
• A require statement in a test case information function

If you want the connection to be associated with Handle only (if you, for example, need to open multiple connections to a host), use Key, the configuration variable name, to specify the target. Notice that a connection without an associated target name can only be closed with the Handle value.

TargetMod is a module that exports the functions connect(Ip, Port, KeepAlive, Extra) and get_prompt_regexp() for the specified TargetType (for example, unix_telnet).

For target_name(), see module ct.

See also ct:require/2.

-spec send(Connection, Cmd) -> ok | {error, Reason}
              when Connection :: connection(), Cmd :: iodata(), Reason :: term().

Equivalent to send(Connection, Cmd, []).

-spec send(Connection, Cmd, Opts) -> ok | {error, Reason}
              when
                  Connection :: connection(), Cmd :: iodata(), Opts :: [send_option()], Reason :: term().

Sends a Telnet command and returns immediately.

By default, this function adds "\n" to the end of the specified command. If this is not desired, option {newline,false} can be used. This is necessary, for example, when sending Telnet command sequences prefixed with character Interpret As Command (IAC). Option {newline,string()} can also be used if a different line end than "\n" is required, for instance {newline,"\r\n"}, to add both carriage return and newline characters.

The resulting output from the command can be read with ct_telnet:get_data/2 or ct_telnet:expect/2,3.

-spec sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}
               when
                   Connection :: connection(),
                   CmdFormat :: io:format(),
                   Args :: [term()],
                   Reason :: term().

Equivalent to sendf(Connection, CmdFormat, Args, []).

-spec sendf(Connection, CmdFormat, Args, Opts) -> ok | {error, Reason}
               when
                   Connection :: connection(),
                   CmdFormat :: io:format(),
                   Args :: [term()],
                   Opts :: [send_option()],
                   Reason :: term().

Sends a Telnet command and returns immediately (uses a format string and a list of arguments to build the command).

For details, see ct_telnet:send/3.