CSshClient::Execute

CSshClient::Execute Method

INT Execute(

LPCTSTR lpszRemoteHost,

UINT nRemotePort,

LPCTSTR lpszUserName,

LPCTSTR lpszPassword,

LPCTSTR lpszCommandLine,

UINT nTimeout,

DWORD dwOptions,

HGLOBAL* lphgblBuffer,

LPDWORD lpdwLength

);

INT Execute(

LPCTSTR lpszRemoteHost,

UINT nRemotePort,

LPCTSTR lpszUserName,

LPCTSTR lpszPassword,

LPCTSTR lpszCommandLine,

UINT nTimeout,

DWORD dwOptions,

LPBYTE lpBuffer,

LPDWORD lpdwLength

);

INT Execute(

LPCTSTR lpszRemoteHost,

UINT nRemotePort,

LPCTSTR lpszUserName,

LPCTSTR lpszPassword,

LPCTSTR lpszCommandLine,

UINT nTimeout,

DWORD dwOptions,

CString& strBuffer

);

The Execute method executes a command on the server and returns the output in the specified buffer.

Parameters

lpszRemoteHost

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

nRemotePort

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

lpszUserName

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

lpszPassword

A pointer to a 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 from the server before failing the current operation.

dwOptions

An unsigned integer that specifies one or more options. This parameter is constructed by using a bitwise operator with any of the following values:

Value 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 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 server.

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 server.

SSH_OPTION_NOPWDNULL This option specifies the user password cannot be terminated with a null character. This option is ignored with SSH-2 connections and should only be specified if required by the server.

SSH_OPTION_NOREKEY This option specifies 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.

lpBuffer, lphgblBuffer or strBuffer

A pointer to a byte buffer which will contain the data transferred from the server, or a pointer to a global memory handle which will reference the data when the function returns. If the application is using MFC, then a CString variable may also be specified, in which case the data is returned in the string

lpdwLength

A pointer to an unsigned 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 Execute method is used to execute a command on a server, read the output from that command and copy it into a local buffer. This method 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 Connect method to establish the connection, and then use either the Read or ReadLine methods to read the output.

This method 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 lpBuffer 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 lphgblBuffer 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 method 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 method 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 = sshClient.Execute(strHostName,
                            SSH_PORT_DEFAULT,
                            strUserName,
                            strPassword,
                            strCommandLine,
                            SSH_TIMEOUT,
                            SSH_OPTION_NONE,
                            &hgblBuffer,
                            &cbBuffer);

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

Minimum Desktop Platform: Windows 7 Service Pack 1
Server: Requires Windows Server 2003 or Windows 2000 Server.
Header File: cstools11.h
Import Library: cstshv11.lib
Unicode: Implemented as Unicode and ANSI versions

Parameters

Return Value

Remarks

Example

Requirements

See Also