You may incorporate this sample code into your applications without restriction, though the sample code has been provided "AS IS" and the responsibility for its operation is 100% yours. However, what you are not permitted to do is to redistribute the source as "DSC Sample Code" after having made changes. If you're going to re-distribute the source, we require that you make it clear in the source that the code was descended from Apple Sample Code, but that you've made changes.
3/20/1997 |
Added
|
3/12/1997 |
Added
|
3/10/1997 |
States are no longer
flags. |
3/9/1997 |
Remodeled states and events. Added
|
3/4/1997 |
Clarification of what happens to the filespec passed in
|
2/28/1997 |
|
2/27/1997 |
Changed post processing flags in
|
2/26/1997 |
|
2/24/1997 |
More errors codes. Changed
open flags. Added
|
2/21/1997 |
Add |
2/20/1997 |
|
2/12/1997 |
first posted |
This call allows the client application to download a file without any additional work. It does not allow to control the progress of the download in any way. The other calls of this API should be used for this purpose.
URLDownload downloads a specified URL to a specified file. This call is synchronous, it will not return until download is complete. It will however yield to other threads.
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 akURLProgressAlreadyDisplayedError
error.To download a URL asynchronously, use the
URLOpen
call instead.
|
|
|
the target URL to be downloaded. |
|
the destination file to download the data to. If this is
an existing file and the
|
|
options for the download. Flag values are:
|
The following errors may be returned:
|
the download completed successfully. |
|
the |
|
the URL that was passed in has an invalid format. |
|
the destination file already exists and the
|
Create a reference to a URL for future use.
|
|
|
the URL this reference should point to. |
|
when the call returns, points to a valid URLReference. |
Disposes of a reference to a URL.
|
|
|
the reference to dispose of. |
Opens a URL for streaming, initiating the download. This call is asynchronous and returns immediately.
If the destination parameter is provided, then the data is automatically downloaded to the file. Otherwise, the client application will retrieve the data as it is downloaded.
This call is asynchronous. To get completion of the call, the client application needs to provide a notification callback routine.
|
|
|
the URL reference to be opened. |
|
the destination file to download the data to. If this
parameter is nil, 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 ). If this
is an existing file and the
If this parameter is provided, the client application
does not have access to buffer
states and
events, not to the
|
|
options for the download. Flag values are:
|
|
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. |
|
a bitmap indicating which events the client application wishes to be notified of. |
|
a user specified value which will be passed in to the callback procedures if any. |
Aborts a URL downloading opened with the
URLOpen
call, terminating the download process.
|
|
|
indicates which URL download should be aborted. |
Gets the amount of data available to retrieve with the
URLGetBuffer
orURLReadBuffer
calls.
|
|
|
the URL reference to get the amount of data available from. |
|
a pointer to the size of the data buffer. On return, the buffer is set to the number of bytes available to retrieve. |
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 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. If the data needs to be modified or retained for a long period of time, the
URLReadBuffer
routine should be used instead.
|
|
|
the URL reference to get the buffer from. |
|
a pointer to a pointer to a memory buffer. Once return, the buffer contains the downloaded data. |
|
a pointer to the length of the buffer. On return, the buffer is set to the number of bytes in the buffer. |
Releases a buffer back to the URL stream.
|
|
|
the URL reference to release the buffer to. |
|
the buffer to release. |
This call fills the client-provided buffer with the requested amount of data. The call returns the amount of data actually returned.
|
|
|
the URL reference to read the buffer from. |
|
the buffer to read to. |
|
the amount of data requested. |
|
the amount of data returned |
The following universal properties are defined and reserved:
Name |
Description |
Type |
* |
---|---|---|---|
|
the URL string. |
|
|
|
the total size of the resource data. |
|
|
|
the last time the data was modified. |
|
|
|
the MIME type of the data. |
|
|
|
the type of the file specified in
|
|
|
|
the creator of the file specified in
|
|
|
|
the character set of the data. |
|
|
|
the name of the resource to be downloaded. |
|
|
|
the host the resource is on. |
|
|
|
the type of authentication information that this download
requires. The default value is
|
|
|
|
the user name to be used for authentification.** |
|
|
|
the password to be used for authentification. |
|
|
|
a string indicating the current status of the stream for optional display. |
|
|
|
indicates whether the download is secure or not. |
|
|
|
the Certificate provided by the remote server. |
|
|
URLSetProperty
routine.
The following HTTP-specific properties are defined and reserved (these properties are only available when the URL scheme is
http
orhttps
):
Name |
Description |
Type |
* |
---|---|---|---|
|
the HTTP method to be used in the request. |
|
X |
|
the HTTP request header. If this property is set, it must contain all needed headers for the request. |
|
|
|
the HTTP request body to be provided in the request. If
this property is set, but not the
|
|
|
|
the HTTP response header. |
|
|
URLSetProperty
routine.
To get properties defined as
const char*
, the client application should first call theURLGetPropertySize
routine to obtain the total size of the property.
Gets a property from the URL stream.
|
|
|
the URL reference to get the property from. |
|
the property to get. This parameter is a null terminated string to allow for extensibility. The previous properties are reserved. |
|
a buffer to put the property value into. |
|
the size of the supplied property buffer. |
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 size and modification time.
|
|
|
the URL reference to get the property size from. |
|
the property to get the size of. This parameter is a null terminated string to allow for extensibility. The previous properties are reserved. |
|
a pointer to the size of the property on return. |
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.
|
|
|
the URL reference to get the property from. |
|
the property to set. This parameter is a null terminated string to allow for extensibility. The previous properties are reserved. |
|
a buffer to read the property value from. |
|
the size of the supplied property buffer. |
Returns the current state of the URL stream. Possible states are:
|
|
|
the download has been initiated.The server has not been
reached yet. This state is only set after the
|
|
the resource is now valid. This state is only set after
the |
|
the download of the resource has started. This state is
only set after the |
|
the download is being aborted. |
|
the download or an abort is now completed. The client application should now dispose of the url reference. |
|
an error has occured. The client application may retrieve
that error by calling the
|
The following states are available if no
file
parameter was provided in theURLOpen
call:
|
data is available to retrieve. |
|
the file downloading is complete. there is no more data available to retrieve. |
|
|
|
the URL reference to get the state from. |
|
the state of the stream. |
Retrieves the first non-trivial error encountered by the URL stream. This may include system errors as well as errors defined in this API.
|
|
|
the URL reference to get the error from. |
|
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):
|
the command completed successfully. |
|
the URL reference that was passed in is invalid. |
|
An invalid parameter was passed in. |
|
the URL that was passed in has an invalid format. |
|
the scheme of the URL is not supported. |
|
the server is currently busy. |
|
authentication with the server has failed. |
|
the destination file already exists and the
|
|
the property passed as a parameter is not defined. |
|
the buffer passed to get the
property is to small. Call
|
|
this property cannot be set
(e.g. |
|
Decompression was requested, but Stuffit Engine is not available. |
|
InternetConfig, which is required, is not available. |
|
the download was cancelled (either by the user or the client application). |
|
the resource file is empty. |
|
the resource is not an existing file on the host. |
This section describe the
notification callback routine
routines that may be provided by the client application. A procedure
pointer to this routine is provided in the
URLOpen
call.
The notification callback routine reports 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:
kURLPropertyChangedEvent
.
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:
|
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. If the total size of the file resource is unknown, then this event will not be reported. |
|
If the client application has registered for this event, the notification callback routine will be called periodically (every 250ms). |
|
this event occurs when the
property indicated by the
|
|
indicates that the corresponding state is now active. |
|
indicates that the corresponding state is now active. |
|
indicates that the corresponding state is now active. |
|
indicates that the corresponding state is now active. |
|
indicates that the corresponding state is now active. |
|
indicates that the corresponding state is now active. |
The following events are available if no
file
parameter was provided in theURLOpen
call:
|
indicates that the corresponding state is now active. |
|
indicates that the corresponding state is now active. |
This routine should always return
noErr
(reserved for future use).
|
|
|
a reference to the URL. |
|
indicates which event is being reported. |
|
the property that has changed, in case the
|
|
the total amount of bytes that have been downloaded from the server. |
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.
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 for in the resource fork of these libraries for a 'STR#' (ID -20440) resource containing the schemes that the extension supports. If a scheme is already supported by the API implementation, the extension overides it.
An extension should implement every routine defined in these specifications except URLDownload. 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.
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 scaning the extensions folder for instance) and know these properties and events behaviors. It is recommended that property names include the third party's name.