The UploadFile method provides a convenient way for an
application to upload a file in a single function call. Based on the
connection information specified in the URL, it will connect to the
server, authenticate the session and then upload the file to the
server. The URL must be complete, and specify either a standard or
secure HTTP scheme:
[http|https]://[username : password] @] hostname [:port] / [path / ...] [filename]
If no user name and password is provided, then the client session
will be authenticated as an anonymous user. If a path is specified as
part of the URL, then function will attempt to change the current
working directory. Note that the path in an HTTP URL is relative to
the home directory of the user account and is not an absolute path
starting at the root directory on the server. The URL scheme will
always determine if the connection is secure, not the option. In
other words, if the "http" scheme is used and the
HTTP_OPTION_SECURE option is specified, that option will be ignored.
To establish a secure connection, the "https" scheme must
be specified.
Not all web servers permit files to be uploaded and some may
require that specific configuration changes be made to the server in
order to support this functionality. Consult your server's technical
reference documentation to see if it supports the PUT command, and if
so, what must be done to enable it. It may be required that the URL
specify a username and password to upload a file.
If your application requests a HTTP/2 connection and the server
only accepts earlier versions of the protocol, the client will attempt
to automatically downgrade the request to HTTP/1.1. If a connection
using an earlier version of the protocol cannot be established, the
method will fail and return a value of zero.
The lpStatus parameter can be used by the application to
determine the final status of the transfer, including the total
number of bytes copied, the amount of time elapsed and other
information related to the transfer process. If this information
isn't needed, then this parameter may be specified as NULL.
The lpEventProc parameter specifies a pointer to a
function which will be periodically called during the file transfer
process. This can be used to check the status of the transfer by
calling GetTransferStatus and then update the program's user
interface. For example, the callback function could calculate the
percentage for how much of the file has been transferred and then
update a progress bar control. The dwParam parameter is used
in conjunction with the event handler and specifies a user-defined
value that is passed to the callback function. One common use in a
C++ program is to pass the this pointer as the value, and then
cast it back to an object pointer inside the callback function. If no
event handler is required, then a NULL pointer can be specified as
the value for lpEventProc and the dwParam parameter
will be ignored.
The UploadFile method is designed to provide a simpler
interface for uploading a file. However, complex connections such as
those using a proxy server or a secure connection which uses a client
certificate will require the program to establish the connection
using Connect and then use PutFile to upload the file.
If the server does not support the PUT command, you may be able to
upload files using the PostFile method. Refer to that method
for more information.