URL Access APIs

---

History

Warning and Disclaimer: URL Access calls are implemented using Power PC-only features, and will fail if they are run from a 68K context. This is true whether they are invoked directly from a 68K application, or from a library ultimately linked to a 68K application.

---

Table of Contents

URLSimpleDownload

URLDownload

URLDownloadWithSigner

URLSimpleUpload

URLUpload

URL Reference Routines

• URLNewReference
• URLDisposeReference

Progressive Downloading and Uploading Routines

• URLOpen
• URLAbort
• URLGetDataAvailable
• URLGetBuffer
• URLReleaseBuffer

URL Information Routines

• Properties
• URLGetProperty
• URLGetPropertySize
• URLSetProperty

Utility Routines

• URLGetCurrentState
• URLGetError

Callback Routines

• Introduction
• Notification Callback

URLSimpleDownload (top of page)

This call allows the client application to download a file without any additional work. It does not allow the client to control the progress of the download in any way. The progressive calls of this API should be used if greater control is needed.

URLDownload downloads a given URL to a given FSSpec. This call is synchronous. It will not return until the download is complete. It will however yield to other threads. We recommend that this call is made from a thread other than the main thread of your application. If not, other processes will not get time until the call is complete.

The client application may wish to have a progress bar dialog displayed during the download. Because the dialog is modal, there may only be one progress bar displayed at a time. If this routine is called with the kURLDisplayProgressFlag set while a progress bar is already displayed, then the call will return with a kURLProgressAlreadyDisplayedError error.

To specify the name of the resulting file or directory, pass a fully specified FSSpec. To use the original name, leave the FSSpec name field empty. If you specify a name that already exists on the system and do not specify the kURLReplaceExistingFlag, URLDownload will return with kURLDestinationExistsError. If the name is not specified, the destination exists, and the kURLReplaceExistingFlag is not set, a unique name will be created by appending a number to the original name.

To download a URL asynchronously, use the URLOpen call instead.

extern OSStatus URLSimpleDownload(

const char* url, FSSpec *destination, Handle destinationHandle URLOpenFlags openFlags, URLSystemEventProcPtr eventProc, void* userContext);

url	the target URL to be downloaded.
destination	the destination file or directory to download the data to. If this is an existing file or directory and the kURLReplaceExistingFileFlag is not set, then this parameter returns with a changed filename.
destinationHandle	if you want to download the data into memory instead of a fileSpec, allocate a handle of at least one byte and pass it in here.
openFlags	options for the download. Flag values are: kURLReplaceExistingFlag: indicates whether to delete an existing file or directory. If this flag is not set and the download is made to an existing file then a new name is used and the destination parameter is updated. The client application will not be notified of a change in the destination parameter. kURLExpandFileFlag: indicates whether to attempt to decrompress and/or decode the downloaded file(s) (requires Stuffit Engine™). kURLDisplayProgressFlag: indicates whether a modal progress dialog is to be displayed during the download. A client application may only have one download active with this flag set at a given time. kURLDisplayAuthFlag: indicates whether a modal authentication dialog is to be displayed if needed. kURLIsDirectoryHintFlag: If you know the URL points toa directory, set this flag. Makes URLAccess more efficient. kURLDoNotTryAnonymousFlag: If you want the user to be required to log in to an FTP server, set this flag and URL Access will not try anonymous login first. kURLDirectoryListingFlag: If you do not want to download the entire directory, but simply want a directory listing, set this flag. kURLExpandAndVerifyFlag: indicates whether to attempt to decompress and/or decode the downloaded file, and then to attempt to verify it. Verification will succeed it the file was signed with Apple Signer, or the iSign programming interfaces, before it was compressed/encoded. At this time, signing and verification are only supported for Developer Certificates.
eventProc	If supplied, routine will be called to communicate system events to the calling application. If it is not supplied, the progress bar and authentication dialogs (if requested) will be non-movable modal. If supplies, dialogs will be movable modal.
userContext	a user specified value which will be passed in to the system event callback.

URLDownload (top of page)

This call is very similar to URLSimpleDownload except that it takes a URLReference instead of a string.

extern OSStatus URLDownload(

URLReferece urlRef, FSSpec *destination, Handle destinationHandle URLOpenFlags openFlags, URLSystemEventProcPtr eventProc, void* userContext);

urlRef	the URLReference to be downloaded. Before calling URLDownload you should set any properties of the URLReference that need to be set.
destination	the destination file or directory to download the data to. If this is an existing file or directory and the kURLReplaceExistingFileFlag is not set, then this parameter returns with a changed filename.
destinationHandle	if you want to download the data into memory instead of a fileSpec, allocate a handle of at least one byte and pass it in here.
openFlags	options for the download. Flag values are: kURLReplaceExistingFlag: indicates whether to delete an existing file or directory. If this flag is not set and the download is made to an existing file then a new name is used and the destination parameter is updated. The client application will not be notified of a change in the destination parameter. kURLExpandFileFlag: indicates whether to attempt to decrompress and/or decode the downloaded file(s) (requires Stuffit Engine™). kURLDisplayProgressFlag: indicates whether a modal progress dialog is to be displayed during the download. A client application may only have one download active with this flag set at a given time. kURLDisplayAuthFlag: indicates whether a modal authentication dialog is to be displayed if needed. kURLIsDirectoryHintFlag: If you know the URL points toa directory, set this flag. Makes URLAccess more efficient. kURLDoNotTryAnonymousFlag: If you want the user to be required to log in to an FTP server, set this flag and URL Access will not try anonymous login first. kURLDirectoryListingFlag: If you do not want to download the entire directory, but simply want a directory listing, set this flag. kURLExpandAndVerifyFlag: indicates whether to attempt to decompress and/or decode the downloaded file, and then to attempt to verify it. Verification will succeed it the file was signed with Apple Signer, or the iSign programming interfaces, before it was compressed/encoded. At this time, signing and verification are only supported for Developer Certificates.
eventProc	If supplied, routine will be called to communicate system events to the calling application. If it is not supplied, the progress bar and authentication dialogs (if requested) will be non-movable modal. If supplies, dialogs will be movable modal.
userContext	a user specified value which will be passed in to the system event callback.

URLDownloadWithSigner (top of page)

This call is identical to URLDownload, except that it takes an additional parameter, a pointer to a SecSignerRef. Please see the documentation on Macintosh File Signing (the iSign architecture) for additional information.

extern OSStatus URLDownload(

URLReferece urlRef, FSSpec *destination, Handle destinationHandle URLOpenFlags openFlags, URLSystemEventProcPtr eventProc, void* userContext, SecSignerRef *signer);

urlRef	the URLReference to be downloaded. Before calling URLDownloadWithSigner you should set any properties of the URLReference that need to be set.
destination	the destination file or directory to download the data to. If this is an existing file or directory and the kURLReplaceExistingFileFlag is not set, then this parameter returns with a changed filename.
destinationHandle	if you want to download the data into memory instead of a fileSpec, allocate a handle of at least one byte and pass it in here.
openFlags	options for the download. Flag values are: kURLReplaceExistingFlag: indicates whether to delete an existing file or directory. If this flag is not set and the download is made to an existing file then a new name is used and the destination parameter is updated. The client application will not be notified of a change in the destination parameter. kURLExpandFileFlag: indicates whether to attempt to decrompress and/or decode the downloaded file(s) (requires Stuffit Engine™). kURLDisplayProgressFlag: indicates whether a modal progress dialog is to be displayed during the download. A client application may only have one download active with this flag set at a given time. kURLDisplayAuthFlag: indicates whether a modal authentication dialog is to be displayed if needed. kURLIsDirectoryHintFlag: If you know the URL points toa directory, set this flag. Makes URLAccess more efficient. kURLDoNotTryAnonymousFlag: If you want the user to be required to log in to an FTP server, set this flag and URL Access will not try anonymous login first. kURLDirectoryListingFlag: If you do not want to download the entire directory, but simply want a directory listing, set this flag. kURLExpandAndVerifyFlag: indicates whether to attempt to decompress and/or decode the downloaded file, and then to attempt to verify it. Verification will succeed it the file was signed with Apple Signer, or the iSign programming interfaces, before it was compressed/encoded. At this time, signing and verification are only supported for Developer Certificates.
eventProc	If supplied, routine will be called to communicate system events to the calling application. If it is not supplied, the progress bar and authentication dialogs (if requested) will be non-movable modal. If supplied, dialogs will be movable modal.
userContext	a user specified value which will be passed in to the system event callback.
signer	a pointer to a SecSignerRef. If kURLExpandAndVerifyFlag is specified, the SecSignerRef will point to information about the signer, including the corresponding chain of digital certificates used to sign the file, when the call to URLDownloadWithSigner returns. This information can be retrieved by the iSign APIs. If the signer parameter is nil, no information about the signer is retrieved.

URLSimpleUpload (top of page)

This call allows the client application to upload a file or directory without any additional work. It does not allow control of the progress of the upload in any way. The progressive calls of this API should be used for more control. URLUpload only supports ftp URLs.

URLUpload uploads the given FSSpec to the given URL. This call is synchronous. It will not return until the upload is complete. It will however, yield to other threads. We recommend that this call is made from a thread other than the main thread of your application. If not, other processes will not get time until the call is complete.

The client application may wish to have a progress bar dialog displayed during the download. There may only be one progress bar displayed at a time. If this routine is called with the kURLDisplayProgressFlag set while a progress bar is already displayed, then the call will return with kURLProgressAlreadyDisplayedError.

To specify the name of the resulting file or directory, pass a fully specified URL that does not end in '/'. This tells URL Access that the URL is fully specified as opposed to pointing to the destination directory only. To use the original name, pass in the path to the destination directory and terminate it with a '/'. If you specify a name that already exists on the server and do not specify the kURLReplaceExistingFlag, URLUpload will return with kURLDestinationExistsError. If the name is not specified, the destination exists, and the kURLReplaceExistingFlag is not set, a unique name will be created by appending a number to the original name.

To upload to a URL asynchronously, use the URLOpen call instead.

extern OSStatus URLSimpleUpload(

char* url, const FSSpec *source, URLOpenFlags openFlags, URLSystemEventProcPtr eventProc, void* userContext);

url	the destination URL.
source	the source file spec.
openFlags	options for the upload. Flag values are: kURLReplaceExistingFlag: indicates whether to delete an existing file or directory. If this flag is not set and the upload is made to an existing file then a new name is used. The client application will not be notified of a change in the URL. kURLBinHexFileFlag: indicates whether to attempt to binhex the uploaded file(s) (requires Stuffit Engine™) before uploading. Only non-text files with resource forks will be binhexed. kURLDisplayProgressFlag: indicates whether a modal progress dialog is to be displayed during the upload. A client application may only have one upload active with this flag set at a given time. kURLDisplayAuthFlag: indicates whether a modal authentication dialog is to be displayed if needed. kURLDoNotTryAnonymousFlag: If you want the user to be required to log in to the FTP server, set this flag and URL Access will not try anonymous login first.
eventProc	If supplied, routine will be called to communicate system events to the calling application. If it is not supplied, the progress bar and authentication dialogs (if requested) will be non-movable modal. If supplies, dialogs will be movable modal.
userContext	a user specified value which will be passed in to the system event callback.

URLUpload (top of page)

This call is very similar to URLSimpleDownload except that it takes a URLReference instead of a string.

extern OSStatus URLSimpleUpload(

URLReference urlRef, const FSSpec *source, URLOpenFlags openFlags, URLSystemEventProcPtr eventProc, void* userContext);

urlRef	the URLReference to be downloaded. Before calling URLDownload you should set any properties of the URLReference that need to be set.
source	the source file spec.
openFlags	options for the upload. Flag values are: kURLReplaceExistingFlag: indicates whether to delete an existing file or directory. If this flag is not set and the upload is made to an existing file then a new name is used. The client application will not be notified of a change in the URL. kURLBinHexFileFlag: indicates whether to attempt to binhex the uploaded file(s) (requires Stuffit Engine™) before uploading. Only non-text files with resource forks will be binhexed. kURLDisplayProgressFlag: indicates whether a modal progress dialog is to be displayed during the upload. A client application may only have one upload active with this flag set at a given time. kURLDisplayAuthFlag: indicates whether a modal authentication dialog is to be displayed if needed. kURLDoNotTryAnonymousFlag: If you want the user to be required to log in to the FTP server, set this flag and URL Access will not try anonymous login first.
eventProc	If supplied, routine will be called to communicate system events to the calling application. If it is not supplied, the progress bar and authentication dialogs (if requested) will be non-movable modal. If supplies, dialogs will be movable modal.
userContext	a user specified value which will be passed in to the system event callback.

URL Reference Routines (top of page)

URLNewReference (top of page)

Create a reference to a URL for future use.

extern OSStatus URLNewReference(

const char* url, URLReference *urlRef);

url	the URL this reference should point to.
urlRef	when the call returns, points to a valid URLReference.

URLDisposeReference (top of page)

Disposes of a reference to a URL.

extern OSStatus URLDisposeReference(

URLReference urlRef);

urlRef

the reference to dispose of.

Streaming Routines (top of page)

URLOpen (top of page)

Opens a URL for streaming, initiating a download or upload. This call is asynchronous and returns immediately.

If the file parameter is provided for a download, then the data is automatically downloaded to the file spec. Otherwise, the client application must retrieve the data as it is downloaded. If you are downloading an entire directory, you must supply a file spec. You cannot retrieve the data yourself.

The file parameter must be provided for an upload, and the data is automatically uploaded from the file. If you are uploading an entire directory, you must provide a file spec for the directory. There is not way to provide the data yourself.

To get completion of the call, the client application needs to provide a notification callback routine or can poll status using the URLGetCurrentState call.

extern OSStatus URLOpen (

URLReference urlRef, FSSpec* fileSpec, URLOpenFlags openFlags, URLNotifyProcPtr notifyProc, URLEventMask eventRegister, void* userContext);

urlRef	the URL reference to be opened.
fileSpec	the destination/source file spec. If this parameter is nil and a file is being downloaded, the client application will be retrieving the downloaded data. Otherwise, the data will be downloaded to the destination file and the client application will not receive any data event (see notification ). This parameter must be specified to upload or download a directory. If this parameter is provided, the client application does not have access to buffer states and events, not to the URLGetBuffer, URLReleaseBuffer or URLGetDataAvailable routines.
openFlags	options for the transaction. See URLDownload and URLUpload for values.
notifyProc	a notification proc ptr. This procedure is called to report events that have been registered through the eventRegister parameter. It may report downloading events such as starting of the download or completion, or indicate that a property has changed such as status string or last modification time.
eventRegister	a bitmap indicating which events the client application wishes to be notified of.
userContext	a user specified value which will be passed in to the notification routine.

URLAbort (top of page)

Aborts a URL download or upload started with the URLOpen call, terminating the process.

extern OSStatus URLAbort(

URLReference urlRef);

urlRef

indicates which URL download or upload should be aborted.

URLGetDataAvailable (top of page)

Gets the amount of data available to retrieve with the URLGetBuffer call. Only available for downloading files.

extern OSStatus URLGetDataAvailable(

URLReference urlRef, Size *dataSize);

urlRef	the URL reference to get the amount of data available from.
dataSize	a pointer to the size of the data buffer. On return, the buffer is set to the number of bytes available to retrieve.

URLGetBuffer (top of page)

Gets a buffer from the URL download. The client should always release a buffer obtained through this call. The call returns the amount of data obtained. This routine may not return all the data available and the client application may need to call it multiple times to retrieve all the available data.

The buffer returned must not be modified (it is read-only) or the system may crash.

This call allows data to be retrieved by the client application without copying data. The client however should release the buffer as soon as possible to avoid congestion at the lower system level.

Only available for downloading files.

extern OSStatus URLGetBuffer(

URLReference urlRef, void** buffer, Size *bufferSize);

urlRef	the URL reference to get the buffer from.
buffer	a pointer to a pointer to a memory buffer. On return, the buffer contains the downloaded data.
bufferSize	a pointer to the length of the buffer. On return, bufferSize is set to the number of bytes in the buffer.

URLReleaseBuffer (top of page)

Releases a buffer back to the URL stream. Only available for downloading files.

extern OSStatus URLReleaseBuffer(

URLReference urlRef, void* buffer);

urlRef	the URL reference to release the buffer to.
buffer	the buffer to release.

---

URL Information Routines (top of page)

Properties

Properties provide information about the URL or the resource the URL points to. They may change during the download (from unknown to some value or from one value to another value). When this happends, a kURLPropertyChangedEvent will be issued.

The following universal properties are defined and reserved:

Name	Description	Type	*
kURLURL	the URL string.	char*
kURLResourceSize	the total size of the resource data. For directories, this will be the total size of all files before expanding/compressing.	UInt32
kURLLastModifiedTime	the last time the data was modified.	UInt32
kURLMIMEType	the MIME type of the data.	Str255
kURLFileType	the type of the file specified in URLOpen. If this property is not set, it will guessed based on the MIME type.	OSType	X
kURLFileCreator	the creator of the file specified in URLOpen. If this property is not set, it will guessed based on the MIME type.	OSType	X
kURLCharacterSet	the character set of the data.	Str255
kURLResourceName	the name of the resource currently being uploaded or downloaded.	Str255
kURLHost	the host the resource is on.	Str255
kURLAuthType	the type of authentication information that this operation requires. The default value is kURLUserNameAndPasswordAuthType.	UInt32
kURLUserName	the user name used or to be used for authentication. If the username and password are not set and authentication is required by the server, an authentication dialog will be displayed. If the client requested no authentication dialog and the username and password are not set or are incorrect, a kURLAuthenticationError will be set/returned.	Str63	X
kURLPassword	the password to be used for authentication. See above for more info.	Str63	X
kURLStatusString	a string indicating the current status of the stream for optional display.	Str255
kURLIsSecure	indicates whether the transaction is secure or not.	Boolean
kURLCertificate	the certificate provided by the remote server. Only valid for https.	char*
kURLNumItems	the total number of items to be uploaded or downloaded.	UInt32

*: these properties may be set using the URLSetProperty routine.

The following HTTP-specific properties are defined and reserved (these properties are only available when the URL scheme is http or https):

Name	Description	Type	*
kURLHTTPRequestMethod	the HTTP method to be used in the request.	char*	X
kURLHTTPRequestHeader	the HTTP request header. If this property is set, it must contain all needed headers for the request.	char*	X
kURLHTTPRequestBody	the HTTP request body to be provided in the request. If this property is set, but not the kURLHTTPHeader property, then a body-length header will be automatically added to the request.	char*	X
kURLHTTPRespHeader	the HTTP response header.	char*

*: these properties may be set using the URLSetProperty routine.

To get properties defined as const char*, the client application should first call the URLGetPropertySize routine to obtain the total size of the property.

URLGetProperty (top of page)

Gets a property from the URL stream.

extern OSStatus URLGetProperty(

URLReference urlRef, const char* property, void* propertyBuffer, Size bufferSize);

urlRef	the URL reference to get the property from.
property	the property to get. This parameter is a null terminated string to allow for extensibility. The previous properties are reserved.
propertyBuffer	a buffer to put the property value into.
bufferSize	the size of the supplied property buffer.

URLGetPropertySize (top of page)

Returns the size of a property if it is known at that point. Otherwise it will return -1. Some properties do not need to be queried for size such as resource size and modification date.

extern OSStatus URLGetPropertySize(

URLReference urlRef, const char* property, Size *propertySize);

urlRef	the URL reference to get the property size from.
property	the property to get the size of. This parameter is a null terminated string to allow for extensibility. The previous properties are reserved.
propertyBuffer	a pointer to the size of the property on return.

URLSetProperty (top of page)

Sets a property from the URL stream. Some properties may not be set such as size and URL string.

To clear a property, it should be set with an empty string.

extern OSStatus URLSetProperty(

URLReference urlRef, const char* property, void* propertyBuffer, Size bufferSize);

urlRef	the URL reference to get the property from.
property	the property to set. This parameter is a null terminated string to allow for extensibility. The previous properties are reserved.
propertyBuffer	a buffer to read the property value from.
bufferSize	the size of the supplied property buffer.

---

Utility Routines (top of page)

URLGetCurrentState (top of page)

Returns the current state of the URL stream. Possible states are:

kURLNullState	URLOpen has not been called yet.
kURLInitiatingState	the download has been initiated.The server has not been reached yet. This state is only set after the kURLNullState state.
kURLLookingUpHostState	the client system is using the Domain Name Service (DNS) to resolve the name of the host. This state is only set after the kURLInitiatingState state. Also, this state is optional, since not all URLs will go through it (for example, a file:// URL).
kURLConnectingState	the client system is establishing a connection to the remote server. This state is only set after the kURLInitiatingState state, and if there is one, after the kURLLookingUpHostState state. This state is optional, since not all URLs will go through it (for example, a file:// URL).
kURLResourceFoundState	the resource has been found. This state is only set after the kURLInitiatingState state, and if there is one, kURLConnectingState state.
kURLDownloadingState	the download of the resource has started. This state is only set after the kURLResourceFoundState state.
kURLAbortingState	the download is being aborted.
kURLTransactionCompleteState	the download or an abort is now completed. The client application should now dispose of the url reference.
kURLErrorOccurredState	an error has occured. The client application may retrieve that error by calling the URLGetError routine. Once an error is reported, the download is aborted automatically.
kURLUploadingState	the upload has started.

The following states are available if no fileSpec parameter was provided in the URLOpen call:

kURLDataAvailableState	data is available to retrieve.
kURLDownloadCompleteState	the file downloading is complete. there is no more data available to retrieve.

extern OSStatus URLGetCurrentState(

URLReference urlRef, URLState *state);

urlRef	the URL reference to get the state from.
state	the state of the stream.

URLGetError (top of page)

Retrieves the first non-trivial error encountered by the URL stream. This may include system errors as well as errors defined in this API.

extern OSStatus URLGetError(

URLReference urlRef, OSStatus *urlError);

urlRef	the URL reference to get the error from.
urlError	a pointer to the first non-trivial error encountered by the URL stream.

The following errors are defined in these specifications and may also be returned by any of the calls defined (except URLDownload):

kURLInvalidURLReferenceError	the URL reference that was passed in is invalid.
kURLProgressAlreadyDisplayedError	the client already has an upload or download running with progress displayed.
kURLDestinationExistsError	a destination name was specified that already exists and the client indicated not to replace existing.
kURLInvalidURLError	the URL that was passed in has an invalid format.
kURLUnsupportedSchemeError	the scheme of the URL is not supported.
kURLServerBusyError	the server is currently busy.
kURLAuthenticationError	authentication with the server has failed.
kURLUnkownPropertyError	the property passed as a parameter is not defined.
kURLPropertyBufferTooSmallError	the buffer passed to get the property is to small. Call URLGetPropertySize to get the exact size of that property.
kURLUnsettablePropertyError	this property cannot be set (e.g. kURLHost).
kURLNoInternetConfigError	InternetConfig, which is required, is not available.
kURLFileEmptyError	the source file is empty.
kURLInvalidCallError	a call was made that does not apply to the current transaction (e.g. calling URLGetDataAvailable when an upload is being performed).
kURLExtensionFailureError	this call was meant to be handled by an extension but the extension did not support it.
kURLInvalidConfigurationError	The user's configuration does not support performing the transaction (e.g. downloading an FTP directory with a proxy on).
kURLAccessNotAvailableError	URL Access is not available on this system.

---

Callback Routines (top of page)

Introduction (top of page)

This section describes the callback routines that may be provided by the client application. There are two types of routines, one used for monitoring an operation when streaming is being used (Notification Callback), the other used to communicate system events to the client application when a synchronous call (URLUpload or URLDownload) is being used (System Event Callback).

Notification Callback (top of page)

The notification callback routine reports URL events that may be usefull to the client application for displaying progress information or retrieving the downloaded data (when no destination has been specified in the URLOpen call). The client application may register for the notification of only the events it needs (by providing the eventRegister parameter in the URLOpen call).

For example:

• If the client application only displays a progress bar (with no size information) and is downloading to a file, it need not register for kURLPropertyChangedEvent.
• If the client application does not have any user interface, it need not register for kURLPercentEvent.

This routine is called to notify the client application of events it has registered for or to regularly provide download data size. Possible events are:

kURLPercentEvent	if the client application has registered for this event, the notification callback routine will be called every time a new percent of data has been downloaded or uploaded. If the total size of the file resource is unknown, then this event will not be reported.
kURLPeriodicEvent	if the client application has registered for this event, the notification callback routine will be called periodically (every 250ms).
kURLPropertyChangedEvent	this event occurs when the property indicated by the changed parameter has changed. A property that was unknown and is now known is said to have changed.
kURLSystemEvent	this event is used to pass an EventRecord to the calling app for processing.
kURLInitiatedEvent	indicates that the corresponding state is now active.
kURLResourceFoundEvent	indicates that the corresponding state is now active.
kURLDownloadingEvent	indicates that the corresponding state is now active.
kURLUploadingEvent	indicates that the corresponsing state is now active
kURLAbortInitiatedEvent	indicates that the corresponding state is now active.
kURLCompletedEvent	indicates that the corresponding state is now active.
kURLErrorOccurredEvent	indicates that the corresponding state is now active.

The following events are available if no file parameter was provided in the URLOpen call and a download is being performed:

kURLDataAvailableEvent	indicates that the corresponding state is now active.
kURLDownloadCompleteEvent	indicates that the corresponding state is now active.

This routine should always return noErr (reserved for future use).

typedef OSStatus (*URLNotifyProcPtr)(

UInt32 userContext, URLEvent event, URLCallbackInfo *callbackInfo);

userContext	the user context that was passed in to URLOpen.
event	indicates which event is being reported.
callbackInfo	A structure containing event-relevant information: version - the version of the callbackInfo structure urlRef - a reference to the URL the event pertains to property - the property that has changed, in case the event parameter is kURLPropertyChangedEvent. This parameter is a null terminated string to allow for extensibility. If this property is not defined in this API and the client application does not understand it, it should ignore this event. currentSize - the total amount of bytes that have been downloaded from or uploaded to the server. systemEvent - the EventRecord to be processed.

System Event Callback (top of page)

The system event callback is used to communicate system events to the client application when progress or authentication is being displayed. If you request progress or authentication UI and do not provide this parameter, the dialogs will be modal.

When this routine is called, your application should process the event as you would normally.

typedef void (*URLSystemEventCBProcPtr)(

void* userContext, URLReference urlRef, EventRecord *event);

userContext	the user context that was passed in to URLDownload or URLUpload.
urlRef	a reference to the URL.
event	the System event to be processed.

---

Extensions (top of page)

Introduction (top of page)

This API may be extended to support additional schemes or to overide existing schemes. This section describes how a third-party can implment an extension. In this section "API implementation" refers to the implmentation of the API described in these specifications.

Implementation (top of page)

An extension is implemented as a shared library with a 'sbwx' creator type. It should be placed in the extension folder. When the API implementation shared library is initialized, it scans the extension folder for creator type 'sbwx' libraries. If any is found, it then looks in the resource fork of these libraries for a 'STR#' (ID -20902) resource containing the schemes that the extension supports. If a scheme is already supported by the API implementation, the extension overides it.

Behaviors (top of page)

An extension should implement every routine defined in these specifications except URLDownload and URLUpload. Their behavior should fully comply to these specifications. In particular, it should support all universal properties and all events.

An extension may not use a routine, return value, parameter, property or event with a different intent than the one described in these specifications.

Extension properties and events (top of page)

An extension may support additional properties and events. To take advantage of them, a client application will need to know that the extension is available (by scanning the extensions folder for instance) and know these properties' and events' behaviors. It is recommended that property names include the third party's name.