| |
| HCLIENT WINAPI FtpProxyConnect( |
| |
UINT nProxyType, |
|
| |
LPCTSTR lpszProxyHost, |
|
| |
UINT nProxyPort, |
|
| |
LPCTSTR lpszProxyUser, |
|
| |
LPCTSTR lpszProxyPassword, |
|
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
LPSECURITYCREDENTIALS lpCredentials |
|
| ); |
The FtpProxyConnect function establishes a connection
through a proxy server and defines security related options to be used.
Four basic proxy server types are recognized, and the library will
automatically negotiate with the server to establish a connection
through the proxy server to the destination server.
Parameters
- nProxyType
- An identifier which specifies the type of proxy server that is
being connected to. This value must be defined as one of the
following values:
| Constant |
Description |
| FTP_PROXY_NONE |
This value specifies that no proxy server is being used. In
this case, the FtpConnect function is called directly,
ignoring the proxy parameters. |
| FTP_PROXY_USER |
This value specifies that the client is not logged into the
proxy server. The USER command is sent in the format
username@ftpsite followed by the password. This is the format
used with the Gauntlet proxy server. |
| FTP_PROXY_LOGIN |
This value specifies that the client is logged into the
proxy server. The USER command is then sent in the format
username@ftpsite followed by the password. This is the format
used by the InterLock proxy server. |
| FTP_PROXY_OPEN |
This value specifies that the client is not logged into the
proxy server. The OPEN command is sent specifying the host
name, followed by the username and password. |
| FTP_PROXY_SITE |
This value specifies that the client is logged into the
server. The SITE command is sent, specifying the host name,
followed by the username and the password. |
| FTP_PROXY_OTHER |
This special proxy type specifies that another, undefined
proxy server is being used. The client connects to the proxy
host, but does not attempt to authenticate the client. The
application is responsible for negotiating with the proxy
server, typically using the FtpCommand function to send
specific command sequences. |
- lpszProxyHost
- A pointer to the name of the proxy server to connect through;
this may be a fully-qualified domain name or an IP address.
- lpszProxyPort
- The port number the proxy server is listening on; a value of
zero specifies that the default port number should be used.
- lpszProxyUser
- A pointer to the user name used to authenticate the client on
the proxy server. Not all proxy servers require this information;
it is recommended that you consult the proxy server documentation
to determine if a username is required.
- lpszProxyPassword
- A pointer to the password used to authenticate the client on
the proxy server. Not all proxy servers require this information;
it is recommended that you consult the proxy server documentation
to determine if a password is required.
- lpszRemoteHost
- A pointer to the name of the server that you want to
connect to, through the proxy server.
- 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 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 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 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 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_VIRTUALHOST |
This option specifies 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_TRUSTEDSITE |
This option specifies 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 the client should attempt to
establish a secure connection with the server. This option is
the same as specifying FTP_OPTION_SECURE_IMPLICIT which
immediately performs the SSL/TLS protocol negotiation when
the connection is established. |
| FTP_OPTION_SECURE_IMPLICIT |
This option specifies the client should attempt to
immediately establish secure SSL/TLS connection with the server. This
option is typically used when connecting to a server on port
990, which is the default port number used for FTPS. |
| FTP_OPTION_SECURE_EXPLICIT |
This option specifies the client should establish a
standard connection to the server and then use the AUTH command
to negotiate an explicit secure connection. This option is
typically used when connecting to the server on ports other
than 990. |
| FTP_OPTION_SECURE_FALLBACK |
This option specifies the client should permit the use
of less secure cipher suites for compatibility with legacy
servers. If this option is specified, the client will allow
connections using TLS 1.0 and cipher suites that use RC4, MD5
and SHA1. |
| 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 capability 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_KEEPALIVE_DATA |
This option specifies the client should attempt to keep the
control connection active during a file transfer. Normally, when a data
transfer is in progress, no additional commands are issued on
the control channel until the transfer completes. Specifying
this option automatically enables the FTP_OPTION_KEEPALIVE
option and forces the client to continue to issue NOOP commands
during the file transfer. This option only applies to FTP and
FTPS connections and has no effect on connections using SFTP
(SSH). |
| FTP_OPTION_PREFER_IPV6 |
This option specifies the client should prefer the use of
IPv6 if the server hostname can be resolved to both an IPv6 and
IPv4 address. This option is ignored if the local system does
not have IPv6 enabled, or when the hostname can only be resolved
to an IPv4 address. If the server hostname can only be resolved
to an IPv6 address, the client will attempt to establish a
connection using IPv6 regardless if this option has been
specified. |
| FTP_OPTION_FREETHREAD |
This option specifies 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. |
| FTP_OPTION_HIRES_TIMER |
This option specifies the elapsed time for data
transfers should be returned in milliseconds instead of seconds.
This will return more accurate transfer times for smaller files
being uploaded or downloaded using fast network connections. |
| FTP_OPTION_TLS_REUSE |
This option specifies that TLS session reuse should be
enabled for secure connections. This option is only supported on
Windows 8.1 or Windows Server 2012 R2 and later platforms, and it
should only be used when explicitly required by the server. This
option is not compatible with servers built using OpenSSL 1.0.2
and earlier versions which do not provide Extended Master Secret
(EMS) support as outlined in RFC7627. |
- lpCredentials
- A pointer to a SECURITYCREDENTIALS
structure. This parameter should be NULL if the connection is not secure
or when client credentials are not required. Most servers do not require a
client certificate to establish a secure connection. However, if the server
does require a client certificate, the structure members dwSize,
lpszCertStore and lpszCertName must be defined. Undefined
structure members must be initialized to a value of zero or NULL and the
dwSize member must be initialized 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
To prevent this function from blocking the main user interface
thread, the application should create a background worker thread and
establish a connection by calling FtpProxyConnect in
that thread. If the application requires multiple simultaneous
connections, it is recommended you create a worker thread for each
client session.
The username and password that is used to authenticate the client
with the proxy server are not the same as those used to login to the
target server. Once a connection has been established with the proxy
server, the client must call the FtpLogin function to actually
login to the server and begin a file transfer.
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 establish a standard connection to the server and send the AUTH
TLS command to the server. If the server does not accept this command,
it will then send the 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.
Requirements
Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: csftpv10.lib
Unicode: Implemented as Unicode and ANSI versions.
See Also
FtpConnect,
FtpCreateSecurityCredentials,
FtpDeleteSecurityCredentials,
FtpDisconnect,
FtpGetSecurityInformation,
FtpInitialize,
FtpLogin,
FtpSetChannelMode
|
|