INT SshExecute(
	LPCTSTR lpszRemoteHost,
	UINT nRemotePort,
	LPCTSTR lpszUserName,
	LPCTSTR lpszPassword,
	LPCTSTR lpszCommandLine,
	UINT nTimeout,
	DWORD dwOptions,
	LPVOID lpvBuffer,		// pointer to buffer which will contain the command output
	LPDWORD lpdwLength,
	LPSECURITYCREDENTIALS lpCredentials
);

The SshExecute function executes a command on the server and returns the output in the specified buffer.

Parameters

lpszRemoteHost

A pointer to a null-terminated string which specifies the name of the remote host. This may either be a fully-qualified domain name, or an IP address. This parameter cannot be NULL.

nRemotePort

The port number the remote server is listening on. A value of zero specifies that the default port number 22 should be used.

lpszUserName

A pointer to a null-terminated string which specifies the user name which will be used to authenticate the client session.

lpszPassword

A pointer to a null-terminated string which specifies the password which will be used to authenticate the client session.

nTimeout

The number of seconds that the client will wait for a response before failing the operation; a value of zero indicates that the client should wait an indefinite period of time.

dwOptions

A bitmask which specifies one or more options. This parameter is constructed by using a bitwise operator with any of the following values:

Constant	Description
SSH_OPTION_NONE	No options specified. A standard terminal session will be established with the default terminal type.
SSH_OPTION_KEEPALIVE	This option specifies that the library should attempt to maintain an idle client session for long periods of time. This option is only necessary if you expect that the connection will be held open for more than two hours.
SSH_OPTION_NOPTY	This option specifies that a pseudoterminal (PTY) should not be created for the client session. This option is automatically set if the SSH_OPTION_COMMAND option has been specified.
SSH_OPTION_NOSHELL	This option specifies that a command shell should not be used when executing a command on the remote host.
SSH_OPTION_NOAUTHRSA	This option specifies that RSA authentication should not be used with SSH-1 connections. This option is ignored with SSH-2 connections and should only be specified if required by the remote host.
SSH_OPTION_NOPWDNULL	This options specifies that the user password cannot be terminated with a null byte. This option is ignored with SSH-2 connections and should only be specified if required by the remote host.
SSH_OPTION_NOREKEY	This option specifies that the client should never attempt a repeat key exchange with the server. Some SSH servers do not support rekeying the session, and this can cause the client to become non-responsive or abort the connection after being connected for an hour.
SSH_OPTION_COMPATSID	This compatibility option changes how the session ID is handled during public key authentication with older SSH servers. This option should only be specified when connecting to servers that use OpenSSH 2.2.0 or earlier versions.
SSH_OPTION_COMPATHMAC	This compatibility option changes how the HMAC authentication codes are generated. This option should only be specified when connecting to servers that use OpenSSH 2.2.0 or earlier versions.

lpvBuffer

A pointer to a byte buffer which will contain the data transferred from the remote server, or a pointer to a global memory handle which will reference the data when the function returns.

lpdwLength

A pointer to an unsigned long integer which should be initialized to the maximum number of bytes that can be copied to the buffer specified by the lpvBuffer parameter. If the lpvBuffer parameter points to a global memory handle, the length value should be initialized to zero. When the function returns, this value will be updated with the actual length of the file that was downloaded.

lpCredentials

A pointer to a SECURITYCREDENTIALS structure which specifies additional security-related information required to establish the connection. This parameter may be NULL, in which case default values will be used. Note that the dwSize member must be initialized to the size of the SECURITYCREDENTIALS structure that is being passed to the function.

Return Value

If the function succeeds, the return value is the exit code from the program that was executed on the server. If the function fails, the return value is SSH_ERROR. To get extended error information, call SshGetLastError.

Remarks

The SshExecute function is used to execute a command on a remote host, read the output from that command and copy it into a local buffer. This function cannot be used if the connection to the server must be established through a proxy server; if a proxy server must be used, then you should use the SshConnect function to establish the connection, and then use either the SshRead or SshReadLine functions to read the output.

This function may be used in one of two ways, depending on the needs of the application. The first method is to pre-allocate a buffer large enough to store the command output. In this case, the lpvBuffer parameter will point to the buffer that was allocated, the value that the lpdwLength parameter points to should be initialized to the size of that buffer.

The second method that can be used is have the lpvBuffer parameter point to a global memory handle which will contain the output when the function returns. In this case, the value that the lpdwLength parameter points to must be initialized to zero. It is important to note that the memory handle returned by the function must be freed by the application, otherwise a memory leak will occur. See the example code below.

When the command output is being read from the server, this function will automatically convert the data to match the end-of-line convention used on the Windows platform. This is useful when executing a command on a UNIX based system where the end-of-line is indicated by a single linefeed, while on Windows it is a carriage-return and linefeed pair. If the output contains embedded nulls or escape sequences, then this conversion will not be performed.

This function will cause the current thread to block until the command completes or a timeout occurs.

Example

HGLOBAL hgblBuffer = (HGLOBAL)NULL;
LPBYTE lpBuffer = (LPBYTE)NULL;
DWORD cbBuffer = 0;

// Execute a command on the server and return the data into block
// of global memory allocated by the GlobalAlloc function; the handle
// to this memory will be returned in the hgblBuffer parameter
nResult = SshExecute(lpszHostName,
                     SSH_PORT_DEFAULT,
                     lpszUserName,
                     lpszPassword,
                     lpszCommandLine,
                     SSH_TIMEOUT,
                     SSH_OPTION_NONE,
                     &hgblBuffer,
                     &cbBuffer,
                     NULL);

if (nResult != SSH_ERROR)
{
    // Lock the global memory handle, returning a pointer to the
    // resource data
    lpBuffer = (LPBYTE)GlobalLock(hgblBuffer);
    
    // After the data has been used, the handle must be unlocked
    // and freed, otherwise a memory leak will occur
    GlobalUnlock(hgblBuffer);
    GlobalFree(hgblBuffer);
}

Requirements

Client: Requires Windows Vista, Windows XP or Windows 2000 Professional.
Server: Requires Windows Server 2008, Windows Server 2003 or Windows 2000 Server.
Header: Include cstools6.h.
Library: Use cstshav6.lib.
Unicode: Implemented as Unicode and ANSI versions.

See Also

SshConnect, SshGetExitCode, SshRead, SshReadLine, SshWrite, SshWriteLine, SECURITYCREDENTIALS, SSHOPTIONDATA

Copyright © 2008 Catalyst Development Corporation. All rights reserved.