DOCERR: FtpGetFile & FtpOpenFile Flags Documented Incorrectly

• Microsoft ActiveX SDK 1.0
• Microsoft Internet Client SDK, versions 4.0, 4.01

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."

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

   _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

// A valid FtpOpenFile call that always reads from the wire

                          _T("LoneStarReview.doc"), // lpszFileName
                          GENERIC_READ, // fdwAccess
            FTP_TRANSFER_TYPE_BINARY | INTERNET_FLAG_RELOAD, // dwFlags
                          dwMyFtpContext); // dwContext