Next Page >

Hide TOC

Legacy Document

Important: URL Access Manager is deprecated as of Mac OS X v10.4. You should use CFNetwork instead (as described in CFNetwork Programming Guide).

URL Access Manager Reference (Not Recommended)

Framework	Carbon/Carbon.h
Declared in	URLAccess.h

Overview

Important: URL Access Manager is deprecated as of Mac OS X v10.4. You should use CFNetwork instead (as described in CFNetwork Programming Guide).

CFNetwork provides better reliability and performance and is used by Apple’s own applications. URL Access Manager is no longer being enhanced or improved.

The URL Access Manager is an API that you can use to perform data transfer to and from a URL from within your application. It includes support for automatic decompression of compressed files and for automatic file extraction from Stuffit archives (with version 5.0 of Stuffit).

The URL Access Manager allows you to use any of the following protocols during download operations: File Transfer Protocol (FTP), Hypertext Transfer Protocol (HTTP), secure Hypertext Transfer Protocol (HTTPS), or a URL representing a local file (begins with file://). You might use the latter to test your application on a computer that does not have access to an HTTP or FTP server. For upload operations, you must use an FTP URL.

This document describes the URL Access Manager API through version 2.0.3.

Functions by Task

Getting Information About the URL Access Manager

Creating and Disposing of a URL Reference

Getting and Setting Information About a URL

Performing Simple Data Transfer

Getting More Control Over Data Transfer Operations

Terminating Data Transfer Operations

Getting Data Transfer Information

Working With URL Access Manager Callbacks

Callbacks

URLNotifyProcPtr

Defines a pointer to your notification callback function that handles certain data transfer events that occur during data transfer operations.

typedef OSStatus (*URLNotifyProcPtr)
(
   void * userContext,
   URLEvent event,
   URLCallbackInfo * callbackInfo
);

If you name your function MyURLNotifyProc, you would declare it like this:

OSStatus MyURLNotifyProc (
   void * userContext,
   URLEvent event,
   URLCallbackInfo * callbackInfo
);

Parameters

userContext: A pointer to application-defined storage that your application previously passed to the function URLOpen. Your application can use this to set up its context when your notification callback function is called.
event: The data transfer event that your application wishes to be notified of. See “Data Transfer Event Constants” for a description of possible values. The type of event that can trigger your callback depends on the event mask you passed in the eventRegister parameter of the function URLOpen, and whether you pass a valid file specification in the fileSpec parameter of URLOpen. For more information, see the discussion.
callbackInfo: A pointer to a structure of type URLCallbackInfo. On return, the structure contains information about the data transfer event that occurred. The URL Access Manager passes this information to your callback function via the callbackInfo parameter of the function InvokeURLNotifyUPP.

Return Value

A result code. See “URL Access Manager Result Codes.” Your notification callback function should process the data transfer event and return noErr.

Discussion

Your notification callback function handles certain data transfer events that occur during data transfer operations performed by the function URLOpen. You can define an event notification function and the events for which you want to receive notification only if you do not specify a file in which to store the data for download operations. In order to be notified of these events, you must pass a UPP to your notification callback function in the notifyProc parameter. You indicate the type of data transfer events you want to receive via a bitmask in the eventRegister parameter.

Note that if you pass a valid file specification to URLOpen, your callback function will not be notified of data available and transaction completed events as identified by the constants kURLDataAvailableEvent and kURLTransactionCompleteEvent. If you pass a valid file specification to URLOpen, your callback function notified if any of the following events occur: kURLPercentEvent, kURLPeriodicEvent, kURLPropertyChangedEvent, kURLSystemEvent, kURLInitiatedEvent, kURLResourceFoundEvent, kURLDownloadingEvent, kURLUploadingEvent, kURLAbortInitiatedEvent, kURLCompletedEvent, and kURLErrorOccurredEvent.

When your callback is called, it should process the event immediately and return 0. You may wish your callback function to update its user interface, allocate and deallocate memory, or call the Thread Manager function NewThread.

Special Considerations

Do not call the function URLDisposeReference from your notification callback function. Doing so may cause your application to stop working.

Availability

Available in Mac OS X v10.0 and later.

Declared In

URLAccess.h

URLSystemEventProcPtr

Defines a pointer to your system event notification callback that handles update events that occur while a dialog box is displayed during a data transfer operation.

typedef OSStatus (*URLSystemEventProcPtr)
(
   void * userContext,
   EventRecord * event
);

If you name your function MyURLSystemEventProc, you would declare it like this:

OSStatus MyURLSystemEventProc (
   void * userContext,
   EventRecord * event
);

Parameters

userContext: A pointer to application-defined storage that your application previously passed to the function URLSimpleDownload, URLDownload, URLSimpleUpload, or URLUpload. Your application can use this value to set up its context when the system event callback function is called.
event: A pointer to an event record containing information about the system event that occurred during the data transfer operation.

Return Value

A result code. See “URL Access Manager Result Codes.” Your system event callback function should process the system event and return noErr.

Discussion

You pass a pointer to your callback function in the eventProc parameter of the function URLSimpleDownload, URLSimpleUpload, URLDownload, or URLUpload if you want update events to be passed to your application while a dialog box is displayed by these functions. (In Mac OS X, this is not necessary, since all dialog boxes are moveable). In order for these functions to display a dialog box, you must set the mask constant kURLDisplayProgressFlag or kURLDisplayAuthFlag in the bitmask passed in the openFlags parameter. Call the function NewURLSystemEventUPP to create a UPP to your system event notification callback. If you do not write your own system event notification callback, these functions will display a nonmovable modal dialog box.

Special Considerations

Do not call the function URLDisposeReference from your callback function. Doing so may cause your application to stop working.

Availability

Available in Mac OS X v10.0 and later.

Declared In

URLAccess.h

Data Types

URLCallbackInfo

Contains information about a data transfer event.

struct URLCallbackInfo {
   UInt32 version;
   URLReference urlRef;
   const char * property;
   UInt32 currentSize;
   EventRecord * systemEvent;
};
typedef struct URLCallbackInfo URLCallbackInfo;

Fields

version: The version of this structure. This value is currently 0.
urlRef: A reference to the URL associated with the data transfer event.
property: A pointer to a C string representing the name of the URL property that has changed, if relevant. This field is only valid if a property change event occurs as identified by the event constant kURLPropertyChangedEvent, described in “Data Transfer Event Constants.” or a description of name constants and data types of the corresponding property values, see “Universal URL Property Name Constants” and “HTTP and HTTPS URL Property Name Constants.” You should specify this field if the event involves a change in a property value.
currentSize: The current total size (in bytes) of the data that has been downloaded and processed by the client.
systemEvent: A pointer to an event record containing information about the system event that occurred, if relevant. If the event is not a system event, as identified by the event constant kURLSystemEvent, described in “Data Transfer Event Constants,” this field is not valid.

Discussion

The URLCallbackInfo type represents a structure that contains information about the data transfer event that you want notification of. The URL Access Manager passes a pointer to this structure in the callbackInfo parameter of your notification callback function. For information on how to write a notification callback function, see URLNotifyProcPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

URLAccess.h

URLNotifyUPP

typedef URLNotifyProcPtr URLNotifyUPP;

Discussion

For more information, see the description of the callback function URLNotifyProcPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

URLAccess.h

URLReference

Represents a reference to a URL.

typedef struct OpaqueURLReference * URLReference;

Discussion

The URLReference type represents a reference to an opaque structure that identifies a URL. You should call the function URLNewReference to create a URL reference. The function URLDisposeReference disposes of a URL reference when no longer needed. You pass a reference of this type to URL Access Manager functions that operate on a URL in some way.

Availability

Available in Mac OS X v10.0 and later.

Declared In

URLAccess.h

URLSystemEventUPP

typedef URLSystemEventProcPtr URLSystemEventUPP;

Discussion

For more information, see the description of the callback function URLSystemEventProcPtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

URLAccess.h

Constants

Authentication Type Constant

Represents the default value of the property value identified by the property name constant kURLAuthType.

enum {
   kUserNameAndPasswordFlag = 0x00000001
};

Constants

kUserNameAndPasswordFlag

Represents the default value of the property value identified by the property name constant kURLAuthType, described in “Universal URL Property Name Constants.” This value indicates that both the user name and password are used for authentication.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

Discussion

This constant represents the default value of the authentication type property value. The authentication type property value is identified by the property name constant kURLAuthType, described in “Universal URL Property Name Constants.” If you do not set the kURLAuthType property, the default value will be used for the authentication type. In this case, both the user name and password are used for authentication purposes.

Data Transfer Event Constants

Identify data transfer events that occur during a data transfer operation.

typedef UInt32 URLEvent;
enum {
   kURLInitiatedEvent = kURLInitiatingState,
   kURLResourceFoundEvent = kURLResourceFoundState,
   kURLDownloadingEvent = kURLDownloadingState,
   kURLAbortInitiatedEvent = kURLAbortingState,
   kURLCompletedEvent = kURLCompletedState,
   kURLErrorOccurredEvent = kURLErrorOccurredState,
   kURLDataAvailableEvent = kURLDataAvailableState,
   kURLTransactionCompleteEvent = kURLTransactionCompleteState,
   kURLUploadingEvent = kURLUploadingState,
   kURLSystemEvent = 29,
   kURLPercentEvent = 30,
   kURLPeriodicEvent = 31,
   kURLPropertyChangedEvent = 32
};

Constants

kURLInitiatedEvent

Indicates the function URLOpen has been called but the location specified by the URL reference has not yet been accessed.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLResourceFoundEvent

Indicates that the location specified by the URL reference has been accessed and is valid.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDownloadingEvent

Indicates that a download operation is in progress.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLAbortInitiatedEvent

Indicates that a data transfer operation has been aborted. When your application calls the function URLAbort, the URL Access Manager changes the state returned by the function URLGetCurrentState to kURLAbortingState and passes the constant kURLAbortInitiatedEvent to your notification callback function. When data transfer is terminated, the URL Access Manager changes the state returned by URLGetCurrentState to kURLCompletedState and passes the constant kURLCompletedEvent in the event parameter of your notification callback function.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLCompletedEvent

Indicates that all operations associated with a call to URLOpen have been completed. This includes the successful completion of a download or upload operation or the completion of cleanup work after aborting a download or upload operation. For example, when a data transfer operation is aborted, the URL Access Manager changes the state returned by the function URLGetCurrentState to kURLCompletedState and passes the constant kURLCompletedEvent in the event parameter of your notification callback function.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLErrorOccurredEvent

Indicates that an error occurred during data transfer. If you receive this event, you may wish to call the function URLGetError to determine the nature of the error.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDataAvailableEvent

Indicates that data is available in buffers. If you receive this event, you can call the function URLGetBuffer to obtain the next buffer of data. You may wish to call the function URLGetDataAvailable to determine the amount of data available for retrieval in a download operation. Note that if you pass a valid file specification in the fileSpec parameter of URLOpen, your notification callback function will not be called for data available events.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLTransactionCompleteEvent

Indicates that a download operation is complete because there is no more data to retrieve from buffers. Note that if you pass a valid file specification in the fileSpec parameter of URLOpen, your notification callback function will not be called for transaction completed events.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLUploadingEvent

Indicates that an upload operation is in progress.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLSystemEvent

Indicates that a system event has occurred.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLPercentEvent

Indicates that the size of the data being downloaded is known. In this case, an increment of one percent of the data was transferred into buffers.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLPeriodicEvent

Indicates that a time interval of approximately one quarter of a second has passed.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLPropertyChangedEvent

Indicates that a property such as a filename has become known or changed. In this case, the name of the changed property will be passed to your notification function via the property field of the callbackInfo structure.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

Discussion

The URLEvent enumeration defines constants that identify data transfer events that occur during a data transfer operation performed by URLOpen. In order to be notified of these events, you must pass a UPP to your data transfer notification callback in the notifyProc parameter. You indicate the type of data transfer events you want to receive via a bitmask in the eventRegister parameter. For a description of this bitmask, see “Data Transfer Event Mask Constants.”

Data Transfer Event Mask Constants

Represent a mask that identifies the data transfer events occurring during a data transfer operation that your application wants notification of.

typedef unsigned long URLEventMask;
enum {
   kURLInitiatedEventMask = 1 << (kURLInitiatedEvent - 1),
   kURLResourceFoundEventMask = 1 << (kURLResourceFoundEvent
- 1),
   kURLDownloadingMask = 1 << (kURLDownloadingEvent - 1),
   kURLUploadingMask = 1 << (kURLUploadingEvent - 1),
   kURLAbortInitiatedMask = 1 << (kURLAbortInitiatedEvent
- 1),
   kURLCompletedEventMask = 1 << (kURLCompletedEvent - 1),
   kURLErrorOccurredEventMask = 1 << (kURLErrorOccurredEvent
- 1),
   kURLDataAvailableEventMask = 1 << (kURLDataAvailableEvent
- 1),
   kURLTransactionCompleteEventMask = 1 << (kURLTransactionCompleteEvent
- 1),
   kURLSystemEventMask = 1 << (kURLSystemEvent - 1),
   kURLPercentEventMask = 1 << (kURLPercentEvent - 1),
   kURLPeriodicEventMask = 1 << (kURLPeriodicEvent - 1),
   kURLPropertyChangedEventMask = 1 << (kURLPropertyChangedEvent
- 1),
   kURLAllBufferEventsMask = kURLDataAvailableEventMask + kURLTransactionCompleteEventMask,
   kURLAllNonBufferEventsMask = kURLInitiatedEventMask + kURLDownloadingMask
+ kURLUploadingMask + kURLAbortInitiatedMask + kURLCompletedEventMask
+ kURLErrorOccurredEventMask + kURLPercentEventMask + kURLPeriodicEventMask
+ kURLPropertyChangedEventMask,
   kURLAllEventsMask = 0xFFFFFFFF
};

Constants

kURLInitiatedEventMask

If the bit specified by this mask is set, your notification callback function will be notified when the function URLOpen has been called but the location specified by the URL reference has not yet been accessed.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLResourceFoundEventMask

If the bit specified by this mask is set, your notification callback function will be notified when the location specified by a URL reference has been accessed and is valid.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDownloadingMask

If the bit specified by this mask is set, your notification callback function will be notified when a download operation is in progress.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLUploadingMask

If the bit specified by this mask is set, your notification callback function will be notified when an upload operation is in progress.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLAbortInitiatedMask

If the bit specified by this mask is set, your notification callback function will be notified when a download or upload operation has been aborted. When your application calls the function URLAbort, the URL Access Manager changes the state returned by the function URLGetCurrentState to kURLAbortingState and passes the constant kURLAbortInitiatedEvent to your notification callback function. When data transfer is terminated, the URL Access Manager changes the state returned by URLGetCurrentState to kURLCompletedState and passes the constant kURLCompletedEvent in the event parameter of your notification callback function.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLCompletedEventMask

If the bit specified by this mask is set, your notification callback function will be notified when all operations associated with a call to the function URLOpen have been completed. This indicates either the successful completion of an operation or the completion of cleanup work after aborting the operation. For example, when a data transfer operation is aborted, the URL Access Manager changes the state returned by the function URLGetCurrentState to kURLCompletedState and passes the constant kURLCompletedEvent in the event parameter of your notification callback function.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLErrorOccurredEventMask

If the bit specified by this mask is set, your notification callback function will be notified when an error has occurred. If you receive this event, you may wish to call the function URLGetError to determine the nature of the error.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDataAvailableEventMask

If the bit specified by this mask is set, your notification callback function will be notified when data is available in buffers. If you receive this event, you may wish to call the function URLGetDataAvailable to determine the amount of data available for retrieval in a download operation. Note that if you pass a valid file specification in the fileSpec parameter of the function URLOpen, your notification callback function will not be called for data available events.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLTransactionCompleteEventMask

If the bit specified by this mask is set, your notification callback function will be notified when the operation is complete because there is no more data to retrieve from buffers. Note that if you pass a valid file specification in the fileSpec parameter of the function URLOpen, your notification callback function will not be called for transaction completed events.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLSystemEventMask

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLPercentEventMask

If the bit specified by this mask is set, your notification callback function will be notified when an increment of one percent of the data has been transferred into buffers. This occurs only when the size of the data being transferred is known. This information is useful if you want the URL Access Manager to display a progress indicator.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLPeriodicEventMask

If the bit specified by this mask is set, your notification callback function will be notified when a time interval of approximately one quarter of a second has passed. You can use this event to report the progress of the download operation when the size of the data is unknown or for other processing that you wish to perform at regular intervals.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLPropertyChangedEventMask

If the bit specified by this mask is set, your notification callback function will be notified when the value of a URL property, such as a filename or user name, has become known or changes.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLAllBufferEventsMask

If the bit specified by this mask is set, your notification callback function will be notified when a buffer-related event indicated by the event constants kURLDataAvailableEvent or kURLTransactionCompleteEvent occurred. If you pass a file specification in the fileSpec parameter of the function URLOpen, your notification callback function will not be called for buffer-related events.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLAllNonBufferEventsMask

If the bit specified by this mask is set, your notification callback function will be notified when an event unrelated to a buffer occurred. This includes all events except those represented by the constants kURLDataAvailableEvent and kURLTransactionCompleteEvent.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLAllEventsMask

If the bit specified by this mask is set, your notification callback function will be notified when any of the above data transfer events occur. If you pass a file specification in the fileSpec parameter of the function URLOpen, your notification callback function will not be called for buffer-related events.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

Discussion

The URLEventMask enumeration defines masks that identify the data transfer events occurring during a call to the function URLOpen that your application wants notification of. For a description of data transfer events, see “Data Transfer Event Constants.” You can define an event notification function and the events for which you want to receive notification only if you do not specify a file in which to store the data for downloads. You can indicate which events you want to receive notification of via a bitmask in the eventRegister parameter of URLOpen.

Data Transfer Options Mask Constants

Represent a mask that identifies the data transfer options to use when uploading or downloading data.

typedef UInt32 URLOpenFlags;
enum {
   kURLReplaceExistingFlag = 1 << 0,
   kURLBinHexFileFlag = 1 << 1,
   kURLExpandFileFlag = 1 << 2,
   kURLDisplayProgressFlag = 1 << 3,
   kURLDisplayAuthFlag = 1 << 4,
   kURLUploadFlag = 1 << 5,
   kURLIsDirectoryHintFlag = 1 << 6,
   kURLDoNotTryAnonymousFlag = 1 << 7,
   kURLDirectoryListingFlag = 1 << 8,
   kURLExpandAndVerifyFlag = 1 << 9,
   kURLNoAutoRedirectFlag = 1 << 10,
   kURLDebinhexOnlyFlag = 1 << 11,
   kURLDoNotDeleteOnErrorFlag = 1 << 12,
   kURLResumeDownloadFlag = 1 << 13,
   kURLReservedFlag = (unsigned long) 1 << 31
};

Constants

kURLReplaceExistingFlag

If the bit specified by this mask is set and the destination file or directory exists, the file or directory contents are replaced by the newly downloaded or uploaded data. If this bit is not set and the name of the file is specified and does exist, the URL Access Manager returns the result code kURLDestinationExistsError. If the name of the file or directory is not specified, the file or directory already exists, and the bit specified by this mask is not set, a number is appended to the name before any extension until a unique name is created, and the data is transferred to the new file or directory name without notifying the calling application that the name has changed. In the case of a download operation, your application can check the destination parameter of the functions URLSimpleDownload and URLDownload to obtain the new filename.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLBinHexFileFlag

If the bit specified by this mask is set, the URL Access Manager converts a nontext file that has a resource fork to BinHex format before uploading it.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLExpandFileFlag

If the bit specified by this mask is set, files in BinHex format are decoded. If version 5.0 of the Stuffit Engine is installed in the System Folder, the URL Access Manager uses it to expand the file.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDisplayProgressFlag

If the bit specified by this mask is set, the URL Access Manager displays a nonmovable modal progress indicator during data transfer operations only if you have not provided a system event notification callback. On Mac OS X, dialog boxes will always be moveable. To handle data transfer events that occur while a progress indicator is being displayed, pass a UPP to your data transfer event notification callback in the eventProc parameter of the functions URLSimpleDownload, URLDownload, URLSimpleUpload, and URLUpload.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDisplayAuthFlag

If the bit specified by this mask is set, the URL Access Manager displays a nonmovable modal authentication dialog box when user authentication is required only if you have not provided a system event notification callback. On Mac OS X, dialog boxes will always be moveable. To handle data transfer events that occur while an authentication dialog box is being displayed, pass a UPP to your data transfer event notification callback in the eventProc parameter of the functions URLSimpleDownload, URLDownload, URLSimpleUpload, and URLUpload. If the bit specified by this mask is clear, the user name and password properties of the URL are used for authentication purposes. If these are not set, the URL Access Manager returns the result code kURLAuthenticationError.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLUploadFlag

If the bit specified by this mask is set, the function URLOpen will upload the file or directory to the specified URL.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLIsDirectoryHintFlag

If the bit specified by this mask is set, download operations assume that the URL points to a directory. Note that if you pass a pathname that specifies a file in the url parameter of the function URLSimpleDownload, the file is downloaded regardless of whether you specify kURLDirectoryListingFlag or KURLIsDirectoryHintFlag in the openFlags parameter.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDoNotTryAnonymousFlag

If the bits specified by this mask is set, when FTP authentication occurs, the functions URLSimpleDownload, URLDownload, URLSimpleUpload, URLUpload, and URLOpen will not try to log on anonymously. Instead, they will rely on the setting of the mask constant kURLDisplayAuthFlag. If the bit specified by the kURLDoNotTryAnonymousFlag mask is not set, these functions will first attempt to log on anonymously.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDirectoryListingFlag

If the bit specified by this mask is set, a listing of the directory, rather than the entire directory, is downloaded. If the URL points to a file instead of a directory, the file is downloaded. Note that if you pass a pathname that specifies a file in the url parameter of the function URLSimpleDownload, the file is downloaded regardless of whether you specify kURLDirectoryListingFlag or KURLIsDirectoryHintFlag in the openFlags parameter.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLExpandAndVerifyFlag

If this flag is available (that is, the File Signing shared library is available) and the bit specified by this mask is set, the signature attached to the file is verified. Success indicates that the file was signed by the certificate authority, but the certificate will not be displayed until after the file is downloaded.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLNoAutoRedirectFlag

If the bit specified by this mask is set, if an HTTP request returns a “redirect” status (300, 301, or 302), the transfer will complete without attempting to redirect to the next URL. Otherwise, redirects are followed until actual data is encountered or an error is returned.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDebinhexOnlyFlag

If the bit specified by this mask is set, the internal engine is used to decode files, rather than the external Stuffit Engine, even if Stuffit is installed. This prevents the display of the Stuffit progress user interface. If you set this bit, you must also set the kURLExpandFileFlag mask.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDoNotDeleteOnErrorFlag

Do not delete the downloaded file if an error or abort occurs. This flag applies to downloading only and should be used if interested in later resuming the download.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLResumeDownloadFlag

The passed in file is partially downloaded, attempt to resume it. Currently works for HTTP only. If no FSSpec passed in, this flag will be ignored. Overridden by kURLReplaceExistingFlag.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLReservedFlag

Reserved for internal use.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

Discussion

The URLOpenFlags enumeration defines masks you can use to identify the data transfer options you want used when performing data transfer operations. You pass this mask in the openFlags parameter of the functions URLSimpleDownload, URLDownload, URLSimpleUpload, URLUpload, and URLOpen. The options that you can specify for upload and download operations differ, as do those that you can specify for the low-level function URLOpen. For a description of the options you can specify in each case, see the appropriate function discussions.

Data Transfer State Constants

Identifies the current state of a data transfer operation.

typedef UInt32 URLState;
enum {
   kURLNullState = 0,
   kURLInitiatingState = 1,
   kURLLookingUpHostState = 2,
   kURLConnectingState = 3,
   kURLResourceFoundState = 4,
   kURLDownloadingState = 5,
   kURLDataAvailableState = 0x10 + kURLDownloadingState,
   kURLTransactionCompleteState = 6,
   kURLErrorOccurredState = 7,
   kURLAbortingState = 8,
   kURLCompletedState = 9,
   kURLUploadingState = 10
};

Constants

kURLNullState

Indicates that the function URLOpen has not yet been called.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLInitiatingState

Indicates that the function URLOpen has been called, but the location specified by the URL reference has not yet been accessed. The stream enters this state from the kURLNullState state.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLLookingUpHostState

Indicates that the function URLOpen has been called, and that the host is being looked up. The stream enters this state from the kURLInitiatingState state.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLConnectingState

Indicates that the function URLOpen has been called, and a connection is being made. The stream enters this state from the kURLLookingUpHostState state.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLResourceFoundState

Indicates that the location specified by the URL reference has been accessed and is valid. The stream enters this state from the kURLConnectingState state.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDownloadingState

Indicates that the download operation is in progress but there is currently no data in the buffers. The stream enters this state initially from the kURLResourceFoundState state. During a download operation, the stream’s state may alternate between the kURLDownloadingState and the kURLDataAvailableState states.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLDataAvailableState

Indicates that the download operation is in progress and data is available in the buffers. The stream initially enters this state from the kURLDownloadingState state. During a download operation, the stream’s state may alternate between the kURLDownloadingState and the kURLDataAvailableState states. If the stream is in the data available state, you may want to call the function URLGetDataAvailable to determine the amount of data available for download. If you pass NULL in the fileSpec parameter of the function URLOpen, you will need to call the function URLGetBuffer to obtain the next buffer of data.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLTransactionCompleteState

Indicates that a download or upload operation is complete. The stream can enter this state from the kURLDownloadingState state.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLErrorOccurredState

Indicates that an error occurred during data transfer. The stream can enter this state from any state except the kURLAbortingState state. If the stream is in this state, you may wish to call the function URLGetError to determine the nature of the error.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLAbortingState

Indicates that a download or upload operation is aborting. The stream enters this state from the kURLErrorOccurredState state or as a result of calling the function URLOpen when the stream is in any other state. When your application calls the function URLAbort, the URL Access Manager changes the state returned by the function URLGetCurrentState to kURLAbortingState and passes the constant kURLAbortInitiatedEvent to your notification callback function.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLCompletedState

Indicates that there is no more activity to be performed on this stream. In this case, the data transfer has either completed successfully or been aborted. The stream enters this state from the kURLTransactionCompleteState or the kURLAbortingState state. When data transfer is terminated after a data transfer operation is aborted, the URL Access Manager changes the state returned by URLGetCurrentState to kURLCompletedState and passes the constant kURLCompletedEvent in the event parameter of your notification callback function.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLUploadingState

Indicates that an upload operation is in progress.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

Discussion

The URLState enumeration defines constants that identify the status of a data transfer operation with respect to a URL. The function URLGetCurrentState passes back one of these constants in the state parameter to indicate the status of a data transfer operation. All constants except kURLDataAvailableState and kURLCompletedState can be returned at any time. If you pass a valid file specification in the fileSpec parameter of the function URLOpen, your notification callback function will not be notified of data available and transaction completed states as identified by the constants kURLDataAvailableState and kURLTransactionCompleteState.

HTTP and HTTPS URL Property Name Constants

Identify property values specific to HTTP and HTTPS URLs.

#define kURLHTTPRequestMethod ";URLHTTPRequestMethod"
#define kURLHTTPRequestHeader ";URLHTTPRequestHeader"
#define kURLHTTPRequestBody ";URLHTTPRequestBody"
#define kURLHTTPRespHeader ";URLHTTPRespHeader"
#define kURLHTTPUserAgent ";URLHTTPUserAgent"
#define kURLHTTPRedirectedURL ";URLHTTPRedirectedURL"
#define kURLSSLCipherSuite "URLSSLCipherSuite"

Constants

kURLHTTPRequestMethod

Identifies the HTTP request method property value. You use this name constant to set or obtain a C string that represents the HTTP method to be used in the request. If you are posting a form, you must set this property to the string "POST".

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLHTTPRequestHeader

Identifies the HTTP request header property value. You use this name constant to set or obtain a C string that represents the HTTP header to be used in the request. You may set this property to contain all headers needed for the request. If you are posting a form and have set the properties identified by the name constants kURLHTTPRequestMethod and kURLHTTPRequestBody, you do not need to set the property identified by this tag.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLHTTPRequestBody

Identifies the HTTP request body property value. You use this name constant to set or obtain a buffer of data that represents the HTTP body to be provided in the request. If you set the property identified by this tag but not that identified by the name constant kURLHTTPHeader, a body-length header is automatically added to the request. If you are posting a form, you must set this property to the form data you want sent.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLHTTPRespHeader

Identifies the HTTP response header property value. You use this name constant to obtain a C string that represents the HTTP response header that was received.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLHTTPUserAgent

Identifies the user agent property value. You use this name constant to set or obtain a C string that represents the HTTP user agent string that is embedded in HTTP requests. By default, the URL Access Manager sets the user agent string to "URL Access 1.0 (Macintosh; PPC)".

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLHTTPRedirectedURL

Identifies the redirected URL property value. You use this name constant to obtain a C string that represents the URL that you were redirected to.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLSSLCipherSuite

Identifies the SSL cipher suite property value.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

Discussion

These constants represent Apple-defined name constants that identify property values specific to HTTP and HTTPS URLs. For a description of the name constants that identify property values universal to all URLs, see Universal URL Property Name Constants.

You pass one of these name constants in the property parameter of the functions URLSetProperty and URLGetProperty, respectively, to set or obtain a particular property value. Note that you can only set HTTP and HTTPS property values identified by the constants kURLHTTPRequestMethod , kURLHTTPRequestHeader, kURLHTTPRequestBody, and kURLHTTPUserAgent. You must also pass the correct data type corresponding to the property value in the propertyBuffer parameter of these functions.

Version Notes

Prior to version 2.0.3 of the URL Access Manager, the data type of the property value identified by the name constant kURLHTTPRequestBody was a C string. In 2.0.3 and later, the data type is a buffer of data.

Universal URL Property Name Constants

Identify property values universal to all URLs.

#define kURLURL ";URLString"
#define kURLResourceSize ";URLResourceSize"
#define kURLLastModifiedTime ";URLLastModifiedTime"
#define kURLMIMEType ";URLMIMEType"
#define kURLFileType ";URLFileType"
#define kURLFileCreator ";URLFileCreator"
#define kURLCharacterSet ";URLCharacterSet"
#define kURLResourceName ";URLResourceName"
#define kURLHost ";URLHost"
#define kURLAuthType ";URLAuthType"
#define kURLUserName ";URLUserName"
#define kURLPassword ";URLPassword"
#define kURLStatusString ";URLStatusString"
#define kURLIsSecure ";URLIsSecure"
#define kURLCertificate ";URLCertificate"
#define kURLTotalItems ";URLTotalItems"
#define kURLConnectTimeout "URLConnectTimeout"

Constants

kURLURL

Identifies the name string property value. You use this name constant to obtain a C string that represents the URL.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLResourceSize

Identifies the resource size property value. You use this name constant to obtain a value of type Size that represents the total size of the data at the location specified by the URL.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLLastModifiedTime

Identifies the modification time property value. You use this name constant to obtain a value of type UInt32 that represents the last time the data was modified.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLMIMEType

Identifies the MIME type property value. You use this name constant to obtain a Pascal string that represents the MIME type of the URL.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLFileType

Identifies the file type property value. You use this name constant to set or obtain a value of type OSType that represents the file type as specified in a call to the function URLOpen. If the file type was not specified, kURLFileType obtains the file type compatible with the MIME type.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLFileCreator

Identifies the file creator property value. You use this name constant to set or obtain a value of type OSType that represents the file creator as specified in a call to the function URLOpen. If the file creator was not specified, kURLFileType obtains the file type compatible with the MIME type.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLCharacterSet

Identifies the character set property value. You use this name constant to obtain a Pascal string that represents the character set used by the URL, as returned by the HTTP server.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLResourceName

Identifies the resource name property value. You use this name constant to obtain a Pascal string that represents the name associated with the data to be downloaded.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLHost

Identifies the host property value. You use this name constant to obtain a Pascal string that represents the host on which the data is located.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLAuthType

Identifies the authentication type property value. You use this name constant to obtain a value that represents the type of authentication that the download operation requires. The default authentication type is kUserNameAndPasswordFlag, described in Authentication Type Constant.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLUserName

Identifies the user name property value. You use this name constant to set or obtain a Pascal string that represents the user name used for authentication.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLPassword

Identifies the password property value. You use this name constant to set or obtain a Pascal string that represents the password used for authentication.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLStatusString

Identifies the status property value. You use this name constant to obtain a Pascal string that represents the current status of the data stream. You can use this property to display the status of the data transfer operation.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLIsSecure

Identifies the security property value. You use this name constant to get a Boolean value that indicates whether the download operation is secure.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLCertificate

Identifies the certificate property value. You use this name constant to obtain a buffer of data that represents the certificate provided by a remote server.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLTotalItems

Identifies the total items property value. You use this name constant to obtain a value of type UInt32 that represents the total number of items being uploaded or downloaded.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

kURLConnectTimeout

Identifies the connection timeout property value.

Available in Mac OS X v10.0 and later.

Declared in URLAccess.h.

Discussion

These constants represent Apple-defined name constants that identify property values universal to all URLs. For a description of the name constants that identify property values specific to HTTP and HTTPS URLs, see HTTP and HTTPS URL Property Name Constants.

You pass one of these name constants in the property parameter of the functions URLSetProperty and URLGetProperty, respectively, to set or obtain a particular property value. Note that you can only set the universal property values identified by the constants kURLPassword and kURLUserName. You must also pass the correct data type corresponding to the property value in the propertyBuffer parameter of these functions.

Result Codes

The most common result codes returned by URL Access Manager are listed in the table below. The following result codes may also be returned; noErr (0), nsvErr (-35), fnfErr (-43), paramErr (-50), and dirNFErr (-120).

Result Code	Value	Description
`kURLInvalidURLReferenceError`	-30770	Returned by functions that operate on URL references to indicate that a reference is invalid. Available in Mac OS X v10.0 and later.
`kURLProgressAlreadyDisplayedError`	-30771	Returned by the functions `URLSimpleDownload`, `URLDownload`, `URLSimpleUpload`, and `URLUpload` to indicate that a progress indicator is already displayed. Available in Mac OS X v10.0 and later.
`kURLDestinationExistsError`	-30772	Returned by the functions `URLSimpleUpload` and `URLUpload` to indicate that the destination file already exists. Available in Mac OS X v10.0 and later.
`kURLInvalidURLError`	-30773	Returned by functions that operate on URL strings to indicate that the format of the URL is invalid. Available in Mac OS X v10.0 and later.
`kURLUnsupportedSchemeError`	-30774	Returned by functions that operate on URL strings to indicate that the transfer protocol is not supported. Available in Mac OS X v10.0 and later.
`kURLServerBusyError`	-30775	Indicates a failed data transfer operation. Available in Mac OS X v10.0 and later.
`kURLAuthenticationError`	-30776	Returned by `URLSimpleDownload`, `URLDownload`, `URLSimpleUpload`, and `URLUpload` functions if no authentication dialog box is allowed and the user name and password properties of the URL are set incorrectly or don’t exist. Available in Mac OS X v10.0 and later.
`kURLPropertyNotYetKnownError`	-30777	Returned by the functions `URLGetProperty` and `URLGetPropertySize` to indicate that the value or size of a URL property is not available. Available in Mac OS X v10.0 and later.
`kURLUnknownPropertyError`	-30778	Returned by functions `URLSetProperty`, `URLGetProperty`, and `URLGetPropertySize` to indicate that the property is invalid or undefined. Available in Mac OS X v10.0 and later.
`kURLPropertyBufferTooSmallError`	-30779	Returned by the function `URLGetProperty` to indicate that the buffer is too small to receive the requested property. Available in Mac OS X v10.0 and later.
`kURLUnsettablePropertyError`	-30780	Returned by the function `URLSetProperty` to indicate that the property cannot be set. Available in Mac OS X v10.0 and later.
`kURLInvalidCallError`	-30781	Returned by the functions `URLGetDataAvailable`, `URLGetBuffer`, and `URLReleaseBuffer` to indicate that the call is invalid. Available in Mac OS X v10.0 and later.
`kURLFileEmptyError`	-30783	Indicates a failed data transfer operation. Available in Mac OS X v10.0 and later.
`kURLExtensionFailureError`	-30785	Indicates that your extension failed to load. Available in Mac OS 9 and earlier.
`kURLInvalidConfigurationError`	-30786	Indicates a failed data transfer operation. This is returned when you attempt to upload through an HTTP proxy, since upload through proxies is not supported. Available in Mac OS X v10.0 and later.
`kURLAccessNotAvailableError`	-30787	Returned by the function `URLGetURLAccessVersion` to indicate that the URL Access Manager is not available. Available in Mac OS X v10.0 and later.
`kURL68kNotSupportedError`	-30788	Indicates that URL Access Manager was called from within a 68K context. Available in Mac OS 9 and earlier.

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.