| Mac OS X header: | Carbon/Carbon.h |
| Mac OS 9 header: | URLAccess.h |
| Getting More Control Over Data Transfer Operations Functions | |
| URLOpen | Opens a URL and starts an asynchronous download or upload operation. |
| URLGetDataAvailable | Determines the amount of data currently available for retrieval in a download operation. |
| URLGetBuffer | Obtains the next buffer of data in a download operation. |
| URLReleaseBuffer | Releases a buffer. |
URLOpen |
| 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
);
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.
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.
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.
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.
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.
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.
A result code.
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 specify 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.
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.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
URLGetDataAvailable |
| Carbon status: | Supported |
Determines the amount of data currently available for retrieval in a download operation.
OSStatus URLGetDataAvailable (
URLReference urlRef,
Size *dataSize
);
A reference to the URL for which you wish to determine the amount od data currently available for retrieval in a download operation.
On return, a pointer to the size (in bytes) of data available for retrieval in a download operation.
A result code.
The URLGetDataAvailable function determines the amount of data remaining in the buffer of the URL Access Manager that you will obtain from a call to the function URLGetBuffer. You should only call this function if you passed an invalid destination file to the function URLOpen. 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.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
URLGetBuffer |
| Carbon status: | Supported |
Obtains the next buffer of data in a download operation.
OSStatus URLGetBuffer (
URLReference urlRef,
void **buffer,
Size *bufferSize
);
A reference to the URL whose next buffer you wish to obtain.
On return, a handle to a buffer containing the downloaded data.
On return, a pointer to the number of bytes of data in the buffer.
A result code.
The URLGetBuffer function obtains the next buffer of data in a download operation. URLGetBuffer does not enable you to retain or modify the transferred data. If you pass NULL in the fileSpec parameter of the function URLOpen, you should call URLGetBuffer to retrieve data as it is downloaded.
You should call URLGetBuffer repeatedly until URL Access Manager passes the event constant kURLCompletedEvent or kURLAbortInitiatedEvent in the event parameter of your notification callback function, or until the function URLGetCurrentState returns the state constant kURLTransactionComplete or kURLAbortingState. Between calls to URLGetBuffer, you should call the function URLIdle to allow time for the URL Access Manager to refill its buffers.
To determine the number of bytes remaining in the buffer, call the function URLGetDataAvailable. The size returned by URLGetDataAvailable does not include the number of bytes in transit to a buffer, nor does it include the amount of data not yet transferred from the URL.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
You should release the returned buffer as soon as possible after a call to URLGetBuffer by calling the function URLReleaseBuffer. This prevents the URL Access Manager from running out of buffers.
URLReleaseBuffer |
| Carbon status: | Supported |
Releases a buffer.
OSStatus URLReleaseBuffer (
URLReference urlRef,
void *buffer
);
A reference to the URL whose buffer you want to release.
A pointer to the buffer you want to release.
A result code.
The URLReleaseBuffer function releases the buffer obtained by calling the function URLGetBuffer. To prevent the URL Access Manager from running out of buffers, you should call URLReleaseBuffer after each call to URLGetBuffer.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2001 Apple Computer, Inc. (Last Updated July 21, 2001)