|
The Secure Shell (SSH) protocol enables an application to establish
a secure, interactive terminal session with a server, or execute
commands remotely on the server, with the output of the command
returned to the client. The SocketTools library supports both version
1.0 and 2.0 of the protocol.
The first step that your application must take is to initialize the
library, then establish a connection to the server and authenticate the
client. The following functions are available for use by your
application:
SshInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call the application
makes before calling the other SSH API functions.
SshConnect
Establish a connection to the server. This function will return a
handle to a client session which is used in subsequent calls to the
SSH API.
SshDisconnect
Disconnect from the server and release any resources that have been
allocated for the client session. After this function is called, the
client handle is no longer valid.
SshUninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
function call that the application should make prior to
terminating.
Connection Options
The SSH protocol has a number of advanced options which can be
specified when establishing a connection. To provide additional
information to the connection function, the
SSHOPTIONDATA
structure is used. The three most commonly used options specify
if the connection will be used for an interactive terminal session
or to execute a command on the server, and if a proxy server should
be used when connecting to the server:
SSH_OPTION_TERMINAL
This option specifies the client session will use terminal
emulation and the SSHOPTIONDATA structure specifies the
characteristics of the virtual terminal. This enables the caller to
specify the dimensions of the virtual display (in columns and rows)
and the type of terminal that will be emulated. If this option is
omitted, the session will default to a virtual display that is 80
columns, 25 rows.
SSH_OPTION_COMMAND
This option specifies the client session will be used to issue a
command that is executed on the server, and the output will be
returned to the caller. If this option is specified, the session will
not be interactive and no pseudo-terminal is created for the client.
The szCommandLine member of the SSHOPTIONDATA structure specifies the
command string that will be sent to the server.
SSH_OPTION_PROXYSERVER
This option specifies the client should establish a connection
through a proxy server. The two protocols that are supported are
SSH_PROXY_HTTP and SSH_PROXY_TELNET, which specifies the protocol
that the proxy connection is created through. The proxy-related
members of the SSHOPTIONDATA structure should be set to the
appropriate values.
Input and Output
Once your application has connected to the server, any output
generated by a program on the server will be sent as data for you to
read. Any input to the program is sent by your application and received
and processed by the server. The following functions are used:
SshPeek
Reads any data that has been sent by the server and copies it to the
buffer provided by the caller, but it does not remove the data from
the internal receive buffer. This function can be used to examine the
contents of the receive buffer and make decisions about how to
process the data.
SshRead
Reads any data that has been sent by the server and copies it to a
byte array buffer provided by your application. If the server closes
the connection, the function will return a value of zero and the
client can disconnect from the server at that point.
SshReadLine
Reads a line of text from the server, and returns it as a null
terminated string. This function is useful for reading output from
the server one line at a time. The function recognizes both UNIX and
Windows end-of-line conventions, and will cause the application to
block until a complete line of text has been read.
SshWrite
Send data to the server which will be received as input to the
program. Your application provides the function with a byte array
buffer that contains the data, and an integer value that specifies
the number of bytes in the buffer.
SshWriteLine
Send data to the server as a line of text, terminated with a
carriage-return and newline character. Note that your application
should not specify the end-of-line characters, they are automatically
sent to the server. This function will cause the application to block
until the complete line of text has been written.
Command Processing
The SSH protocol can be used to connect to a server, log in and
execute one or more commands, process the output from those commands
and display it to an end-user using a graphical interface. The user
never needs to see or interact with the actual terminal session. The
SSH API provides functions which can simplify this kind of application,
reducing the amount of code needed to process the data stream returned
by the server.
SshExecute
This function executes a command on a server and copies the output to
a user-specified buffer, with the exit code for the remote program as
the function's return value. This is a convenience function that
enables you to execute a remote command in a single call, without
having to write the code to establish the connection and read the
output.
SshGetExitCode
This function returns the exit code for the program that was
executing on the server. It should be called after all of the data
has been read and the server has closed the connection, which is
indicated by the SshRead function returning a value of zero.
SshSearch
This function is used to search for a specific character or sequence
of characters in the data stream returned by the server. The library
will accumulate all of the data received up to the point where the
character sequence is encountered. This can be used to capture all of
the output from a command, or search for specific results returned by
the command as it executes on the server.
|