DOCERR: FtpGetFile & FtpOpenFile Flags Documented Incorrectly (157607)

SUMMARY

Early editions of the ActiveX SDK documentation for the Win32 Internet API FtpGetFile incorrectly specify the fifth parameter dwFlagsAndAttributes. This parameter should be used only for file attributes. All flags should instead be specified in the sixth parameter, dwFlags.

In addition, these editions of the documentation for FtpOpenFile does not state clearly that you can specify other flags in the fourth parameter, dwFlags.

These errors have been corrected in later editions of the documentation.

MORE INFORMATION

The ActiveX SDK FtpGetFile documentation defines the fifth parameter dwFlagsAndAttributes as follows:

File attributes and flags for the new file. Can be any combination of FILE_ATTRIBUTE_* and INTERNET_FLAG_* file attributes. See CreateFile for further information on FILE_ATTRIBUTE_* attributes, and see InternetOpenUrl for further information on INTERNET_FLAG_* flags.

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