---

Naming Your Destination File

“Figure 1-1” shows a flowchart illustrating the factors that influence the name of your destination file when performing upload and download operations using the functions URLSimpleDownload, URLDownload, URLSimpleUpload, URLUpload, and URLOpen. These factors include the specification of the name of the destination file or directory, the existence of the destination, and the setting of the kURLReplaceExistingFlag mask in the openFlags parameter.

For upload operations performed by the functions URLSimpleUpload, URLUpload, and URLOpen, if you want to replace the destination file with the one you passed in the fileSpec parameter, set the mask constant kURLReplaceExistingFlag in the openFlags parameter and do not terminate the destination URL with a “/” character. If you specify a URL that doesn’t end with a “/” character, URL Access Manager assumes that the destination is a file, not a directory.

For downloading, the name of the destination file or directory is considered specified if the name field passed in the FSSpec is not empty. For uploading, the name of the destination is considered specified if the path portion of the URL is not terminated by a '/'. If you specify a name that already exists on the server and do not set the mask constant kURLReplaceExistingFlag, the function returns the result code kURLDestinationExistsError. If you do not specify the name of the destination file, do not set the mask constant kURLReplaceExistingFlag, and the destination file already exists on the server, URL Access Manager creates a unique name by appending a number to the original name before the extension, if any. For example, if the URL specifies a file named file.txt, URLOpen changes the filename to file1.txt. If the file exists and the kURLReplaceExistingFlag mask is set, then the file being uploaded will replace the contents of the destination file and retain the name of the destination file. For example, if you wanted to upload the file “sari.mov” and replace the contents of the file specified by the URL “ftp://host/path/lisa.mov”, the file “lisa.mov” existed, and that the kURLReplaceExistingFlag mask was set, the file “sari.mov” would replace “lisa.mov” and the resulting URL would be “ftp://host/path/lisa.mov”.

---