FtpConnect Function  
 
HCLIENT WINAPI 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 related options to be used.

Parameters

lpszRemoteHost
A pointer to the name of the server to connect to; this may be a fully-qualified domain name or an IP address.
nRemotePort
The port number the 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 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:
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_FIREWALL 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_NOAUTH This option specifies that the server does not require authentication, or that it requires an alternate authentication method. When this option is used, the client connection is flagged as authenticated as soon as the connection to the server has been established. Note that using this option to bypass authentication may result in subsequent errors when attempting to retrieve a directory listing or transfer a file. It is recommended that you consult the technical reference documentation for the server to determine its specific authentication requirements.
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 server. 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 server. 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_TUNNEL This option specifies that a tunneled TCP connection and/or port-forwarding is being used to establish the connection to the server. This changes the behavior of the client with regards to internal checks of the destination IP address and remote port number, default feature selection and how the connection is established. This option also forces all connections to be outbound and enables the firewall compatibility features in the client.
FTP_OPTION_TRUSTEDSITE This option specifies that the server is trusted. The server certificate will not be validated and the connection will always be permitted. This option only affects connections using either the SSL or TLS protocols.
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.
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.
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.
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_KEEPALIVE option is specified, a background worker thread will be created to monitor the command channel and periodically send NOOP commands to the server if no commands have been sent recently. This can prevent the server from terminating the client connection during idle periods where no commands are being issued. However, it is important to keep in mind that many servers can be configured to also limit the total amount of time a client can be connected to the server, as well as the amount of time permitted between file transfers. If the server does not respond to the NOOP command, this option will be automatically disabled for the remainder of the client session.

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 7, Windows Vista or Windows XP.
Server: Requires Windows Server 2008 or Windows Server 2003.
Header: Include cstools7.h.
Library: Use csftpav7.lib.
Unicode: Implemented as Unicode and ANSI versions.

See Also

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

  
 

Copyright © 2012 Catalyst Development Corporation. All rights reserved.