| |
| 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
with an FTP 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 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 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_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
proxy 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_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
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 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.
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, FtpConnect, FtpCreateSecurityCredentials,
FtpDeleteSecurityCredentials,
FtpDisconnect, FtpGetSecurityInformation,
FtpInitialize, FtpLogin, FtpSetChannelMode
|
|