|
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 that 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 that the client session will be used to issue
a command that is executed on the remote server, and the output
will be returned to the caller. If this option is specified, the
session will not be interactive and no pseudoterminal 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 that 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.
|