![]() |
URLSimpleDownload |
||||
Header: | URLAccess.h | Carbon status: | Supported | |
Downloads data from a URL specified by a character string.
OSStatus URLSimpleDownload ( const char *url, FSSpec *destination, Handle destinationHandle, URLOpenFlags openFlags, URLSystemEventUPP eventProc, void *userContext );
A pointer to a C string representing the pathname of the URL from which data is to be downloaded. If the pathname specifies a file, the file is downloaded regardless of whether you specify kURLDirectoryListingFlag or KURLIsDirectoryHintFlag in the openFlags parameter.
A pointer to a file specification structure that identifies the file or directory into which data is to be downloaded. If you wish to download data into memory, pass NULL in this parameter and a valid handle in the destinationHandle parameter. If you pass a file specification that does not identify a file or directory, the name of the file or directory specified by the pathname in the url parameter is used. If you pass a file or directory that already exists, and do not specify kURLReplaceExistingFlag in the openFlags parameter, URLSimpleDownload creates a new file or directory whose name has a number appended before the extension. For example, if the URL specifies a file named file.txt, URLSimpleDownload changes the filename to file1.txt.
A handle to the destination in memory where you want the data downloaded. Before calling URLDownload, create a zero-sized handle. If you wish to download data into a file or directory, pass NULL in this parameter and a valid file specification in the destination parameter.
A bitmask that indicates the data transfer options to use. You can specify any of the following masks for downloading options: kURLReplaceExistingFlag, kURLExpandFileFlag, kURLExpandAndVerifyFlag, kURLDisplayProgressFlag, kURLDisplayAuthFlag, kURLIsDirectoryHintFlag, kURLDoNotTryAnonymousFlag, kURLDebinhexOnlyFlag, kURLNoAutoRedirect, and kURLDirectoryListingFlag. See
A Universal Procedure Pointer (UPP) to your system event callback function, if one exists. For information on how to write a system event callback, see URLSystemEventProcPtr. If you want to handle events that occur while a progress indicator or authentication dialog box is being displayed, specify the appropriate mask (either kURLDisplayProgressFlag or kURLDisplayAuthFlag) in the openFlags parameter and pass a UPP to your callback function in this parameter. Pass NULL if you do not want to receive notification of these events. In this case, the URL Access Manager displays a nonmovable modal progress indicator or authentication dialog box.
A pointer to application-defined storage that will be passed to your system event callback function, if one exists. Your application can use this to set up its context when your system event callback function is called.
A result code. If your application is multi-threaded, and more than one thread calls URLSimpleDownload simultaneously, URLSimpleDownload returns the result code kURLProgessAlreadyDisplayedError if you specify kURLDisplayProgressFlag in the openFlags parameter and the URL Access Manager is already displaying a progress indicator.
The URLSimpleDownload function downloads data from a URL specified by a pathname to a specified file, directory, or memory. It does not return until the download is complete. If you want to download data from a URL identified by a reference rather than a pathname, call the function URLDownload. The difference between the two functions is that URLDownload allows you to access other URL Access Manager functions before, after, or during the download. If you want more control over a data transfer operation, call the function URLOpen.
If you wish to download data to a file or directory, pass a valid file specification in the destination parameter. If you instead wish to download data to memory, pass a valid handle in the destinationHandle parameter.
When URLSimpleDownload downloads data from a URL that represents a local file (that is, a URL that begins with file:///), the data fork is downloaded but the resource fork is not.
URLSimpleDownload yields time to other threads. Your application should call URLSimpleDownload from a thread other than the main thread so that other processes have time to run.
In Mac OS 8.6, if the file type of the file to be downloaded is unknown, URLSimpleDownload assumes that the file is of type text. In this case, the end-of-line character is changed to the Mac style end-of-line character 0x0d0x0a. In Mac OS 9, when a file of unknown type is downloaded, URLSimpleDownload does not assume that it is a text file. Instead, it identifies it as an unknown file type and does not change the end-of-line character.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)