Developer --> Technical Publications

     


Controlling Data Transfer

The URL Access Manager provides the low-level function URLOpen for more control over data transfer operations than can be achieved using the high-level functions described in Performing Simple Data Transfer. URLOpen is an asynchronous function, meaning that it returns control to your application immediately, not upon completion.

When you call URLOpen to perform an upload operation, you must specify a valid destination file. For download operations, you do not have to specify a valid destination file.

If you do not specify a valid destination file, there are several functions that you may wish to call to get information about the download operation being performed by URLOpen . To retrieve data as it is downloaded, call the function URLGetBuffer . Note that you cannot retain or modify the retrieved data. You should call URLGetBuffer repeatedly until the download is complete. This is marked by a kURLCompletedEvent or kURLErrorOccurredEvent event, or the state constants kURLCompletedState or kURLErrorOccurredState returned by the function URLGetCurrentState . 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 may wish to call the function URLGetDataAvailable to determine the number of bytes remaining to be handed off from the URL Access Manager to your application. Calling this function tells you how much data you will obtain by a call to URLGetBuffer (that is, how much data is remaining in the buffer of the URL Access Manager). This does not include the number of bytes in transit to your buffer, nor does it include the amount of data not yet transferred from the URL Access Manager. To calculate the amount of data remaining to be downloaded, pass the name constant kURLResourceSize in the property parameter of the function URLGetProperty and subtract the amount of data copied.

Note that URLGetBuffer , URLReleaseBuffer , and URLGetDataAvailable only provide useful information if you specified an invalid destination file for a download operation performed by URLOpen .

You can specify the data transfer options that URLOpen should use by passing the appropriate bitmask in the openFlags parameter. For upload operations, the options you can specify to URLOpen include whether to replace an existing file, decode an encoded file, specify that URL is a directory, or download a directory listing instead of the contents of a file or directory. For download operations, you can set any of the following masks: kURLReplaceExistingFlag , kURLExpandFileFlag , kURLExpandAndVerifyFlag , kURLDisplayProgressFlag , kURLDisplayAuthFlag , kURLIsDirectoryHintFlag , kURLDoNotTryAnonymousFlag , or kURLDirectoryListingFlag .

If you wish to be notified of certain data transfer events, you can write your own data transfer event callback function and pass a pointer to it in the URLEventMask parameter of URLOpen . The data transfer events that you can receive depend on 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. You can then manipulate the data or write it to the destination of your choice.


© 2000 Apple Computer, Inc. (Last Updated 20 July 2000)