DOCERR: FtpGetFile & FtpOpenFile Flags Documented Incorrectly

MORE INFORMATION

The ActiveX SDK FtpGetFile documentation defines the fifth parameter dwFlagsAndAttributes as follows: This is incorrect. The fifth parameter should be used only for FILE_ATTRIBUTE_* settings applicable to the file written by FtpGetFile. For INTERNET_FLAG_* flags, these should instead be used in the sixth parameter, dwFlags.

For example, FtpGetFile calls that use INTERNET_FLAG_RELOAD to indicate that FTP files should always be received from the wire and not from the cache work incorrectly if this flag is OR'ed into the fifth parameter.

Here is a correct example of where to specify the INTERNET_FLAG_RELOAD flag:

// A valid FtpGetFile call that always reads from the wire
BOOL result = FtpGetFile(hMyFtpSession, // hFtpSession
   _T("ILoveTheInformationSuperhighway.tla"), // lpszRemoteFile
   _T("C:\\Temp\\HereItIs.tla"), // lpszNewFile
   FALSE, // fFailIfExists
   FILE_ATTRIBUTE_NORMAL, // so-called "dwFlagsAndAttributes"
   FTP_TRANSFER_TYPE_BINARY | INTERNET_FLAG_RELOAD, // dwFlags
   dwMyFtpContext); // dwContext
				

Similarly, the FtpOpenFile documentation should indicate that the fourth parameter, dwFlags, can be used to specify any combination of the cache control flags and one of the FTP_TRANSFER_TYPE_* flags. For example, it is legal to do the following:

// A valid FtpOpenFile call that always reads from the wire
BOOL result = FtpOpenFile(hMyFtpSession, // hFtpSession
                          _T("LoneStarReview.doc"), // lpszFileName
                          GENERIC_READ, // fdwAccess
            FTP_TRANSFER_TYPE_BINARY | INTERNET_FLAG_RELOAD, // dwFlags
                          dwMyFtpContext); // dwContext