Secure Shell Protocol  

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 ActiveX control supports both version 1.0 and 2.0 of the protocol.

The following methods are available for use by your application:

Initialize the control and validate the runtime license key for the current process. This method is normally not used if the control is placed on a form in languages such as Visual Basic. However, if the control is being created dynamically using a method similar to CreateObject, then the application must call this method to initialize the component before setting any properties or calling any other methods in the control.

Establish a connection to the server. Once the connection has been established, the other methods in the control may be used to interact with the server.

Disconnect from the server and release any resources that have been allocated for the client session. After this method is called, the client session is no longer valid.

Unload the Windows Sockets library and release any resources that have been allocated for the current process. This is the last method call that the application should make prior to terminating. This is only necessary if the application has previously called the Initialize method.

Input and Output

Once connected to the server, any output generated by the command shell or a program executed on the server will be sent as data for the client to read. Any input to the program is sent by the client and received and processed by the server. The following methods are used:

Reads any output that has been generated by the program executing on the server. If the server closes the connection, this method will return zero after all the data has been read. If the method is successful, it will return the actual number of bytes read.

The ReadLine method reads data from the server up to the specified number of bytes or until an end-of-line character sequence is encountered. Unlike the Read method which reads arbitrary bytes of data, this function is specifically designed to return a single line of text data in a string variable.

The Peek method can be used to examine the data that is available to be read from the internal receive buffer. If there is no data in the receive buffer at that time, a value of zero is returned. The Peek method will never cause the client to block, and so may be safely used with asynchronous connections.

Send data to the server which will be received as input to the program. If the method succeeds, the return value is the number of bytes actually written. This method should always be used when sending binary data to the server.

The WriteLine method writes a line of text to the server and terminates the line with a carriage-return and linefeed control character sequence. Unlike the Write method which sends arbitrary bytes of data to the server, this method is specifically designed to send a single line of text data from a string.

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 sees or interacts with the actual terminal session. The control interface provides methods which can simplify this kind of application, reducing the amount of code needed to process the data stream returned by the server.

This method 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 method's return value. This is a convenience method 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.

This method is used to search for a specific character or sequence of characters in the data stream returned by the server. The control 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.