Carbon


URLOpen

Header: URLAccess.h Carbon status: Supported

Opens a URL and starts an asynchronous download or upload operation.

OSStatus URLOpen (
    URLReference urlRef, 
    FSSpec *fileSpec, 
    URLOpenFlags openFlags, 
    URLNotifyUPP notifyProc, 
    URLEventMask eventRegister, 
    void *userContext
);
Parameter descriptions
urlRef

A reference to the URL to or from which you wish to transfer data. You cannot use the same reference if you call URLOpen again. Instead, you must create a new URL reference by calling the function URLNewReference. If the URL refers to a file, the file is downloaded regardless of whether you specify kURLDirectoryListingFlag or KURLIsDirectoryHintFlag in the openFlags parameter. See “Naming Your Destination File” for more information.

fileSpec

A pointer to a file specification that identifies the file or directory from which data is to be uploaded or downloaded. For upload operations, you must pass a valid file specification. For download operations, you can pass NULL. In this case, you must call the function URLGetBuffer to retrieve the data as it is downloaded. For more information, see the function discussion.

openFlags

A bitmask that indicates the data transfer options to use. You can specify any of the following masks for upload operations: kURLUploadFlag, kURLReplaceExistingFlag, kURLBinHexFileFlag, and kURLDoNotTryAnonymousFlag. You can specify any of the following masks for download operations: kURLReplaceExistingFlag, kURLIsDirectoryHintFlag, kURLDoNotTryAnonymousFlag, kURLDebinhexOnlyFlag, kURLNoAutoRedirect, and kURLDirectoryListingFlag. See “Data Transfer Options Mask Constants” for a description of possible values.

notifyProc

A Universal Procedure Pointer (UPP) to a data transfer event notification callback, as described in URLNotifyProcPtr. You should create a notification callback function if you wish to receive notification of certain data transfer events. In this case, you should also pass a bitmask of the events you wish to receive in the eventRegister parameter. The data transfer events that you receive will vary depending upon whether the destination file you specify is valid. Pass NULL if you do not want to receive notification of data transfer events.

eventRegister

A bitmask that URLOpen will test to determine the data transfer events that you wish to receive notification of. To receive data transfer events, you should also pass a UPP to your callback in the notifyProc parameter. See “Data Transfer Event Mask Constants” for a description of this mask.

userContext

A pointer to application-defined storage that will be passed to your notification callback function. Your application can use this to set up its context when your notification callback function is called.

function result

A result code.

DISCUSSION

The URLOpen function starts a download or upload operation and returns control to your application immediately. For download operations, you do not have to specify a valid destination file. In this case, you should call the function URLGetBuffer repeatedly to get the next buffer of data. Between calls to URLGetBuffer, you should call the function URLIdle to allow time for the URL Access Manager to refill its buffers during download operations. After each call to URLGetBuffer, you call the function URLReleaseBuffer to prevent the URL Access Manager from running out of buffers. You can call the function URLGetDataAvailable to determine the amount of data remaining in the buffer of the URL Access Manager that you will obtain from a call to the function URLGetBuffer.

If you pass a valid destination file, you should not call the functions URLGetBuffer, URLReleaseBuffer, or URLGetDataAvailable.

If you wish to be notified of certain data transfer events, you can a data transfer event callback and pass a pointer to it in the URLEventMask parameter of URLOpen. The data transfer events that you receive will vary depending upon whether the destination file you specify is valid. In addition, you should pass a bitmask representing the events you wish to be notified of in the eventRegister parameter.

When URLOpen 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.

VERSION NOTES

In Mac OS 8.6, if the file type of the file to be uploaded or downloaded is unknown, URLOpen 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 uploaded or downloaded, URLOpen 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.

AVAILABILITY

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)