HCLIENT FtpConnect(
	LPCTSTR lpszRemoteHost,
	UINT nRemotePort,
	LPCTSTR lpszUserName,
	LPCTSTR lpszPassword,
	UINT nTimeout,
	DWORD dwOptions,
	LPSECURITYCREDENTIALS lpCredentials,
);

The FtpConnect function establishes a connection with the specified server, and defines security-relation options to be used.

Parameters

lpszRemoteHost

A pointer to the name of the remote host to connect to; this may be a fully-qualified domain name, or an IP address.

nRemotePort

The port number the remote server is listening on; a value of zero specifies that the default port number should be used. For standard connections, the default port number is 21. For secure connections, the default port number is 990.

lpszUserName

Points to a null-terminated string that specifies the user name to be used to authenticate the current client session. If this parameter is NULL or an empty string, then the login is considered to be anonymous. Note that anonymous logins are not supported for secure connections using the SSH protocol.

lpszPassword

Points to a null-terminated string that specifies the password to be used to authenticate the current client session. This parameter may be NULL or an empty string if no password is required for the specified user, or if no username has been specified.

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
FTP_OPTION_PASSIVE	This option specifies that the client should attempt to establish the data connection with the server. When the client uploads or downloads a file, normally the server establishes a second connection back to the client which is used to transfer the file data. However, if the local system is behind a firewall or a NAT router, the server may not be able to create the data connection and the transfer will fail. By specifying this option, it forces the client to establish an outbound data connection with the server. It is recommended that applications use passive mode whenever possible.
FTP_OPTION_NATROUTER	This option specifies that the client should always use the host IP address to establish the data connection with the server, not the address returned by the server in response to the PASV command. This option may be necessary if the server is behind a router that performs Network Address Translation (NAT) and it returns an unreachable IP address for the data connection. If this option is specified, it will also enable passive mode data transfers.
FTP_OPTION_NATROUTER	This option specifies that the client should always use the host IP address to establish the data connection with the server, not the address returned by the server in response to the PASV command. This option may be necessary if the server is behind a router that performs Network Address Translation (NAT) and it returns an unreachable IP address for the data connection. If this option is specified, it will also enable passive mode data transfers.
FTP_OPTION_KEEPALIVE	This option specifies that the client should attempt to keep the connection with the server active for an extended period of time. It is important to note that regardless of this option, the server may still choose to disconnect client sessions that are holding the command channel open but are not performing file transfers.
FTP_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. This option has no effect on standard or secure connections using SSL.
FTP_OPTION_NOPWDNUL	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. This option has no effect on standard or secure connections using SSL.
FTP_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. This option has no effect on standard or secure connections using SSL.
FTP_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. This option has no effect on standard or secure connections using SSL.
FTP_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. This option has no effect on standard or secure connections using SSL.
FTP_OPTION_VIRTUALHOST	This option specifies that the server supports virtual hosting, where multiple domains are hosted by a server using the same external IP address. If this option is enabled, the client will send the HOST command to the server upon establishing a connection.
FTP_OPTION_VERIFY	This option specifies that file transfers should be automatically verified after the transfer has completed. If the server supports the XMD5 command, the transfer will be verified by calculating an MD5 hash of the file contents. If the server does not support the XMD5 command, but does support the XCRC command, the transfer will be verified by calculating a CRC32 checksum of the file contents. If neither the XMD5 or XCRC commands are supported, the transfer is verified by comparing the size of the file. Automatic file verification is only performed for binary mode transfers because of the end-of-line conversion that may occur when text files are uploaded or downloaded.
FTP_OPTION_SECURE	This option specifies that the client should attempt to establish a secure connection with the server. Note that the server must support secure connections using either the SSL or TLS protocol. This option is only available in the Secure Editions of SocketTools.
FTP_OPTION_SECURE_EXPLICIT	This option specifies that the client should use the AUTH command to negotiate an explicit secure connection. Some servers may only require this when connecting to the server on ports other than 990. This option is only available in the Secure Editions of SocketTools.
FTP_OPTION_SECURE_SHELL	This option specifies that the client should use the Secure Shell (SSH) protocol to establish the connection. This option will automatically be selected if the connection is established using port 22, the default port for SSH. This option is only available in the Secure Editions of SocketTools.
FTP_OPTION_FREETHREAD	This option specifies that the handle returned by this function may be used by any thread, and is not limited to the thread which created it. The application is responsible for ensuring that access to the handle is synchronized across multiple threads.

lpCredentials

Pointer to credentials structure SECURITYCREDENTIALS. This parameter is only used if FTP_OPTION_SECURE is specified for the connection. This parameter may be NULL, in which case no client credentials will be provided to the server. If client credentials are required, the fields dwSize, lpszCertStore, and lpszCertName must be defined, while other fields may be left undefined. Set dwSize to the size of the SECURITYCREDENTIALS structure.

Return Value

If the function succeeds, the return value is a handle to a client session. If the function fails, the return value is INVALID_CLIENT. To get extended error information, call FtpGetLastError.

Remarks

If the FTP_OPTION_SECURE_EXPLICIT option is specified, the client will first send an AUTH TLS command to the server. If the server does not accept this command, it will then send an AUTH SSL command. If both commands are rejected by the server, an explicit SSL session cannot be established. By default, both the command and data channels will be encrypted when a secure connection is established. To change this, use the FtpSetChannelMode function.

The dwOptions argument can be used to specify the threading model that is used by the library when a connection is established. By default, the handle is initially attached to the thread that created it. From that point on, until the it is released, only the owner may call functions using that handle. The ownership of the handle may be transferred from one thread to another using the FtpAttachThread function.

Specifying the FTP_OPTION_FREETHREAD option enables any thread to call any function using the handle, regardless of which thread created it. It is important to note that this option disables certain internal safety checks which are performed by the library and may result in unexpected behavior unless access to the handle is synchronized. If one thread calls a function in the library, it must ensure that no other thread will call another function at the same time using the same handle.

Example

// The Ipswitch WS_FTP server accepts the AUTH command to establish
// an explicit SSL session on the default FTP port     

hClient = FtpConnect(lpszRemoteHost,
                     FTP_PORT_DEFAULT,
                     lpszUserName,
                     lpszPassword,
                     FTP_TIMEOUT,
                     FTP_OPTION_SECURE_EXPLICIT,
                     NULL);      

// When the GlobalSCAPE Secure FTP server is configured in implicit
// authorization mode, it negotiates a secure session as soon as the
// connection is established and does not require a command      

hClient = FtpConnect(lpszRemoteHost,
                     FTP_PORT_SECURE,
                     lpszUserName,
                     lpszPassword,
                     FTP_TIMEOUT,
                     FTP_OPTION_SECURE_IMPLICIT,
                     NULL);
      

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 csftpav6.lib.
Unicode: Implemented as Unicode and ANSI versions.

See Also

FtpAsyncConnect, FtpAsyncProxyConnect, FtpCreateSecurityCredentials, FtpDeleteSecurityCredentials, FtpDisconnect, FtpGetSecurityInformation, FtpInitialize, FtpProxyConnect, FtpSetChannelMode

Copyright © 2008 Catalyst Development Corporation. All rights reserved.