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.