ADC Home > Reference Library > Reference > Carbon > Networking > URL Access Manager Reference (Not Recommended) >

< Previous PageNext Page > Hide TOC

Legacy Documentclose button

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

Deprecated URL Access Manager Reference (Not Recommended) Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

DisposeURLNotifyUPP

Disposes of a UPP to your data transfer event notification callback. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

void DisposeURLNotifyUPP (
   URLNotifyUPP userUPP
);

Parameters
userUPP

A Universal Procedure Pointer (UPP) to your notification callback function.

Discussion

When you are finished with a UPP to your notification callback function, you should dispose of it by calling the DisposeURLNotifyUPP function.

Special Considerations

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

Availability
Declared In
URLAccess.h

DisposeURLSystemEventUPP

Disposes of a UPP to your system event notification callback. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

void DisposeURLSystemEventUPP (
   URLSystemEventUPP userUPP
);

Parameters
userUPP

A UPP to your system event callback function.

Discussion

When you are finished with a UPP to your system event callback function, you should dispose of it by calling the DisposeURLSystemEventUPP function.

Special Considerations

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

Availability
Declared In
URLAccess.h

InvokeURLNotifyUPP

Invokes your data transfer event notification callback. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus InvokeURLNotifyUPP (
   void *userContext,
   URLEvent event,
   URLCallbackInfo *callbackInfo,
   URLNotifyUPP userUPP
);

Parameters
userContext

A pointer to application-defined storage. The URL Access Manager passes this value in the userContext parameter of your notification callback function. Your application can use this to set up its context when your data transfer event notification callback is called.

event

The data transfer events you want your application to receive. See “Data Transfer Event Constants” for a description of possible values. The URL Access Manager tests the bitmask you pass in the eventRegister parameter of the function URLOpen to determine which events to pass to your callback function. See “Data Transfer Event Mask Constants” for a description of this bitmask.

callbackInfo

A pointer to a structure of type URLCallbackInfo that provides information about the data transfer event to your callback function. The URL Access Manager passes a pointer to this structure in the callbackInfo parameter of your notification callback function.

userUPP

A Universal Procedure Pointer to your data transfer notification callback. For information on how to write this function, see URLNotifyProcPtr.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URL Access Manager calls the InvokeURLNotifyUPP function when you pass a UPP to your callback function in the notifyProc parameter of the function URLOpen, and the data transfer event that you specified in the eventRegister parameter occurs.

Special Considerations

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

Availability
Declared In
URLAccess.h

InvokeURLSystemEventUPP

Invokes your system event notification callback. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus InvokeURLSystemEventUPP (
   void *userContext,
   EventRecord *event,
   URLSystemEventUPP userUPP
);

Parameters
userContext

A pointer to application-defined storage. The URL Access Manager passes this value in the userContext parameter of your system event callback function. Your application can use this to set up its context when your system event notification callback is called.

event

A pointer to an event record that provides information about the system event to your callback function.

userUPP

A Universal Procedure Pointer to your system event notification callback. For information on how to write this function, see URLSystemEventProcPtr.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URL Access Manager calls the InvokeURLSystemEventUPP function when you pass a UPP to your callback function in the eventProc parameter of the functions URLSimpleDownload, URLSimpleUpload, URLDownload, or URLUpload, and a system event occurs while a progress indicator or authentication dialog box is being displayed.

Special Considerations

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

Availability
Declared In
URLAccess.h

NewURLNotifyUPP

Creates a UPP to your data transfer event notification callback. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

URLNotifyUPP NewURLNotifyUPP (
   URLNotifyProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your data transfer event notification callback. For information on how to write your callback, see URLNotifyProcPtr.

Return Value

A UPP to your data transfer event notification callback. You can register your callback by passing this UPP in the notifyProc parameter of the function URLOpen. See the description of the URLNotifyUPP data type.

Discussion

The NewURLNotifyUPP function creates a pointer to your data transfer event notification callback. You pass a pointer to your callback in the notifyProc parameter of the function URLOpen if you want your application to receive data transfer events. Pass a bitmask in the eventRegister parameter of URLOpen indicating which data transfer events you want to receive.

Special Considerations

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

When you are finished with your data transfer event notification callback, you should dispose of the UPP by calling the function DisposeURLNotifyUPP.

Availability
Declared In
URLAccess.h

NewURLSystemEventUPP

Creates a UPP to your system event notification callback. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

URLSystemEventUPP NewURLSystemEventUPP (
   URLSystemEventProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your system event notification callback. For information on how to write your callback, see URLSystemEventProcPtr.

Return Value

A UPP to your system event notification callback. You can register your callback by passing this UPP in the eventProc parameter of the function URLSimpleDownload, URLSimpleUpload, URLDownload, or URLUpload. See the description of the URLSystemEventUPP data type.

Discussion

The NewURLSystemEventUPP function creates a pointer to your system event callback function. You pass a pointer to your callback function in the eventProc parameter of the functions URLSimpleDownload, URLSimpleUpload, URLDownload, and URLUpload if you want update events to be passed to your application while a dialog box is displayed. (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.

Special Considerations

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

When you are finished with your system event notification callback, you should dispose of the UPP by calling the function DisposeURLNotifyUPP.

Availability
Declared In
URLAccess.h

URLAbort

Terminates a data transfer operation. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLAbort (
   URLReference urlRef
);

Parameters
urlRef

A reference to the URL whose data transfer operation you wish to terminate.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLAbort function terminates any data transfer operation started by the functions URLSimpleDownload, URLDownload, URLSimpleUpload, URLUpload, or URLOpen. When your application calls 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.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLDisposeReference

Disposes of the memory associated with a URL reference. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLDisposeReference (
   URLReference urlRef
);

Parameters
urlRef

A reference to the URL whose associated memory you wish to dispose of. You should call the URLDisposeReference function to release the memory occupied by a URL reference when you are finished with it.

Return Value

A result code. See “URL Access Manager Result Codes.”

Special Considerations

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

You must call the URLDisposeReference function to dispose of the reference associated with a URL reference even if the data transfer operation fails. Failure to call URLDisposeReference may result in thread or memory leaks.

Availability
Declared In
URLAccess.h

URLDownload

Downloads data from a URL specified by a URL reference. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLDownload (
   URLReference urlRef,
   FSSpec *destination,
   Handle destinationHandle,
   URLOpenFlags openFlags,
   URLSystemEventUPP eventProc,
   void *userContext
);

Parameters
urlRef

A reference to the URL from which data is to be downloaded. Once you call URLDownload, you cannot use the same reference if you call URLDownload again. Instead, you must create a new URL reference by calling the function URLNewReference.

destination

A pointer to a file specification structure that identifies the file or directory into which data is to be downloaded. If you wish to download data into memory, pass NULL in this parameter and a valid handle in the destinationHandle parameter. If you pass a file specification that does not identify a file or directory, the name of the file or directory specified by the pathname in the urlRef parameter is used. If you pass a file or directory that already exists, and do not specify kURLReplaceExistingFlag in the openFlags parameter, URLDownload creates a new file or directory whose name has a number appended before the extension. For example, if the URL specifies a file named file.txt, URLDownload changes the filename to file1.txt.

destinationHandle

A handle to the destination in memory where you want the data downloaded. Before calling URLDownload, create a zero-sized handle. If you wish to download data into a file or directory, pass NULL in this parameter and a valid file specification in the destination parameter.

openFlags

A bitmask that indicates the data transfer options to use. You can specify any of the following masks for downloading options: kURLReplaceExistingFlag, kURLExpandFileFlag, kURLExpandAndVerifyFlag, kURLDisplayProgressFlag, kURLDisplayAuthFlag, kURLIsDirectoryHintFlag, kURLDoNotTryAnonymousFlag, kURLDebinhexOnlyFlag, kURLNoAutoRedirect, and kURLDirectoryListingFlag. See “Data Transfer Options Mask Constants” for a description of possible values.

eventProc

A Universal Procedure Pointer (UPP) to your system event callback function, if one exists. For information on how to write a system event callback, see URLSystemEventProcPtr. If you want to handle events that occur while a progress indicator or authentication dialog box is being displayed, specify the appropriate mask (either kURLDisplayProgressFlag or kURLDisplayAuthFlag) in the openFlags parameter and pass a UPP to your callback function in this parameter. Pass NULL if you do not want to receive notification of these events. In this case, the URL Access Manager displays a nonmovable modal progress indicator or authentication dialog box.

userContext

A pointer to application-defined storage that will be passed to your system event callback function, if one exists. Your application can use this to set up its context when your system event callback function is called.

Return Value

A result code. See “URL Access Manager Result Codes.” If your application is multi-threaded, and more than one thread calls URLDownload simultaneously, URLDownload returns the result code kURLProgessAlreadyDisplayedError if you specify kURLDisplayProgressFlag in the openFlags parameter and the URL Access Manager is already displaying a progress indicator.

Discussion

The URLDownload function downloads data from a URL specified by a URL reference to a file, directory, or memory. It does not return until the download is complete. If you want to download data from a URL identified by a URL string rather than a reference, call the function URLSimpleDownload. The difference between the two functions is that URLDownload allows you to access other URL Access Manager functions before, after, or during the download. If you want more control over a data transfer operation, call the function URLOpen.

If you wish to download data to a file or directory, pass a valid file specification in the destination parameter. If you instead wish to download data to memory, pass a valid handle in the destinationHandle parameter. If the URL specified in the urlRef parameter points to a file, the file is downloaded regardless of whether the bit specified by the mask constant kURLDirectoryListingFlag or KURLIsDirectoryHintFlag is set in the openFlags parameter.

When URLDownload downloads data from a URL that represents a local file (that is, a URL that begins with file://), the data fork is downloaded but the resource fork is not.

Special Considerations

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

URLDownload yields time to other threads. Your application should call URLDownload from a thread other than the main thread so that other processes have time to run.

Availability
Declared In
URLAccess.h

URLGetBuffer

Obtains the next buffer of data in a download operation. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLGetBuffer (
   URLReference urlRef,
   void **buffer,
   Size *bufferSize
);

Parameters
urlRef

A reference to the URL whose next buffer you wish to obtain.

buffer

On return, a handle to a buffer containing the downloaded data.

bufferSize

On return, a pointer to the number of bytes of data in the buffer.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLGetBuffer function obtains the next buffer of data in a download operation. URLGetBuffer does not enable you to retain or modify the transferred data. If you pass NULL in the fileSpec parameter of the function URLOpen, you should call URLGetBuffer to retrieve data as it is downloaded.

You should call URLGetBuffer repeatedly until URL Access Manager passes the event constant kURLCompletedEvent or kURLAbortInitiatedEvent in the event parameter of your notification callback function, or until the function URLGetCurrentState returns the state constant kURLTransactionComplete or kURLAbortingState. Between calls to URLGetBuffer, you should call the function URLIdle to allow time for the URL Access Manager to refill its buffers.

To determine the number of bytes remaining in the buffer, call the function URLGetDataAvailable. The size returned by URLGetDataAvailable does not include the number of bytes in transit to a buffer, nor does it include the amount of data not yet transferred from the URL.

Special Considerations

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

You should release the returned buffer as soon as possible after a call to URLGetBuffer by calling the function URLReleaseBuffer. This prevents the URL Access Manager from running out of buffers.

Availability
Declared In
URLAccess.h

URLGetCurrentState

Determines the status of a data transfer operation. (Deprecated in Mac OS X v10.4.)

OSStatus URLGetCurrentState (
   URLReference urlRef,
   URLState *state
);

Parameters
urlRef

A reference to the URL whose data transfer state you want to determine.

state

On return, a pointer to the state of data transfer. See “Data Transfer State Constants” for a description of possible values.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLGetCurrentState function determines the current status of a data transfer operation. You may wish to call URLGetCurrentState periodically to monitor the status of a download or upload operation.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLGetDataAvailable

Determines the amount of data currently available for retrieval in a download operation. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLGetDataAvailable (
   URLReference urlRef,
   Size *dataSize
);

Parameters
urlRef

A reference to the URL for which you wish to determine the amount od data currently available for retrieval in a download operation.

dataSize

On return, a pointer to the size (in bytes) of data available for retrieval in a download operation.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLGetDataAvailable function determines the amount of data remaining in the buffer of the URL Access Manager that you will obtain from a call to the function URLGetBuffer. You should only call this function if you passed an invalid destination file to the function URLOpen. This does not include the number of bytes in transit to your buffer, nor does it include the amount of data not yet transferred from the URL Access Manager. To calculate the amount of data remaining to be downloaded, pass the name constant kURLResourceSize in the property parameter of the function URLGetProperty and subtract the amount of data copied.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLGetError

Determines the error code of a failed data transfer operation. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLGetError (
   URLReference urlRef,
   OSStatus *urlError
);

Parameters
urlRef

A reference to the URL whose data transfer operation failed.

urlError

A pointer to a C string representing the name of the error code returned by the failed operation.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLGetError function determines the error code returned when a data transfer operation fails. The error code may be a system error code, a protocol-specific error code, or one of the error codes listed in “URL Access Manager Result Codes.”

Special Considerations

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

Availability
Declared In
URLAccess.h

URLGetFileInfo

Obtains the file type and creator of a file. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLGetFileInfo (
   StringPtr fName,
   OSType *fType,
   OSType *fCreator
);

Parameters
fName

A pointer to a Pascal string representing the name of the file for which you want information.

fType

On return, a pointer to the file type code of the specified filename.

fCreator

On return, a pointer to the file creator code of the specified filename.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLGetFileInfo function obtains the file type and creator codes for a specified filename. The type and creator codes are determined by the Internet configuration mapping table and are based on the filename extension. For example, if you pass the filename "jane.txt", URLGetFileInfo will return ’TEXT' in the type parameter and 'ttxt' in the creator parameter.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLGetProperty

Obtains the value of a URL property. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

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

Parameters
urlRef

A reference to the URL whose property value you want to determine.

property

A pointer to a C string representing the name of the property value you want to determine. For a description of property name constants and their corresponding data types, see “Universal URL Property Name Constants” and “HTTP and HTTPS URL Property Name Constants.”

propertyBuffer

A pointer to a buffer containing the property value you want to obtain. You must also pass the correct data type of the property value you wish to obtain. Before calling URLGetProperty, allocate enough memory in this buffer to contain the property value you wish to obtain. On return, a pointer to a buffer containing the property value. If you do not allocate enough memory for the buffer, URLGetProperty does not pass back the property value in this parameter and returns the result code kURLPropertyBufferTooSmallError.

bufferSize

The size (in bytes) of the buffer pointed to by propertyBuffer. To determine the buffer size, call the function URLGetPropertySize. If the buffer size is too small, URLGetProperty returns the result code kURLPropertyBufferTooSmallError and does not pass back the property value in the propertyBuffer parameter.

Return Value

A result code. See “URL Access Manager Result Codes.” The result code kURLPropertyBufferTooSmallError indicates that you did not allocate enough memory for the buffer in the propertyBuffer parameter. The result code kURLPropertyNotYetKnownError indicates that the value of the property is not yet available.

Discussion

The URLGetProperty function obtains the value of a URL property identified by the property name constant specified in the property parameter.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLGetPropertySize

Determines the size of a URL property. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLGetPropertySize (
   URLReference urlRef,
   const char *property,
   Size *propertySize
);

Parameters
urlRef

A reference to the URL whose property size you want to determine.

property

A pointer to a C string representing the name of the property value whose size you want to determine. For a description of property name constants, see “Universal URL Property Name Constants” and “HTTP and HTTPS URL Property Name Constants.”

propertySize

On return, a pointer to the size (in bytes) of the specified property value. If the size is not available, URLGetPropertySize passes back -1 in this parameter and returns the result code kURLPropertyNotYetKnownError.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLGetProperty function obtains the size of the property value identified by the property name constant passed in the property parameter. For a description of property 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 call the URLGetPropertySize function before calling the function URLGetProperty to determine the size of the buffer containing the property value you wish to obtain. Pass the value passed back in the propertySize parameter in the bufferSize parameter of URLGetProperty.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLGetURLAccessVersion

Determines the version of URL Access Manager installed on the user’s system. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLGetURLAccessVersion (
   UInt32 *returnVers
);

Parameters
returnVers

On return, a pointer to the version number of the URL Access Manager installed on the user’s system.

Return Value

A result code. See “URL Access Manager Result Codes.”

Special Considerations

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

Availability
Declared In
URLAccess.h

URLIdle

Gives the URL Access Manager time to refill its buffers during download operations. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLIdle (
   void
);

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLIdle function gives the URL Access Manager time to refill its buffers during download operations. You should call URLIdle periodically after you call the function URLOpen to allow time for the URL Access Manager to refill its buffers.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLNewReference

Creates a URL reference. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLNewReference (
   const char *url,
   URLReference *urlRef
);

Parameters
url

A pointer to a C string representing the name of the URL you want to create.

urlRef

On return, a pointer to the newly-created URL reference.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLNewReference function creates a URL reference that you can use in subsequent calls to the URL Access Manager. When you no longer need a URL reference, you should dispose of its memory by calling the function URLDisposeReference.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLOpen

Opens a URL and starts an asynchronous download or upload operation. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLOpen (
   URLReference urlRef,
   FSSpec *fileSpec,
   URLOpenFlags openFlags,
   URLNotifyUPP notifyProc,
   URLEventMask eventRegister,
   void *userContext
);

Parameters
urlRef

A reference to the URL to or from which you wish to transfer data. You cannot use the same reference if you call URLOpen again. Instead, you must create a new URL reference by calling the function URLNewReference. If the URL refers to a file, the file is downloaded regardless of whether you specify kURLDirectoryListingFlag or KURLIsDirectoryHintFlag in the openFlags parameter. See “Naming Your Destination File” for more information.

fileSpec

A pointer to a file specification that identifies the file or directory from which data is to be uploaded or downloaded. For upload operations, you must pass a valid file specification. For download operations, you can pass NULL. In this case, you must call the function URLGetBuffer to retrieve the data as it is downloaded. For more information, see the function discussion.

openFlags

A bitmask that indicates the data transfer options to use. You can specify any of the following masks for upload operations: kURLUploadFlag, kURLReplaceExistingFlag, kURLBinHexFileFlag, and kURLDoNotTryAnonymousFlag. You can specify any of the following masks for download operations: kURLReplaceExistingFlag, kURLIsDirectoryHintFlag, kURLDoNotTryAnonymousFlag, kURLDebinhexOnlyFlag, kURLNoAutoRedirect, and kURLDirectoryListingFlag. See “Data Transfer Options Mask Constants” for a description of possible values.

notifyProc

A Universal Procedure Pointer (UPP) to a data transfer event notification callback, as described in URLNotifyProcPtr. You should create a notification callback function if you wish to receive notification of certain data transfer events. In this case, you should also pass a bitmask of the events you wish to receive in the eventRegister parameter. The data transfer events that you receive will vary depending upon whether the destination file you specify is valid. Pass NULL if you do not want to receive notification of data transfer events.

eventRegister

A bitmask that URLOpen will test to determine the data transfer events that you wish to receive notification of. To receive data transfer events, you should also pass a UPP to your callback in the notifyProc parameter. See “Data Transfer Event Mask Constants” for a description of this mask.

userContext

A pointer to application-defined storage that will be passed to your notification callback function. Your application can use this to set up its context when your notification callback function is called.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLOpen function starts a download or upload operation and returns control to your application immediately. For download operations, you do not have to specify a valid destination file. In this case, you should call the function URLGetBuffer repeatedly to get the next buffer of data. Between calls to URLGetBuffer, you should call the function URLIdle to allow time for the URL Access Manager to refill its buffers during download operations. After each call to URLGetBuffer, you call the function URLReleaseBuffer to prevent the URL Access Manager from running out of buffers. You can call the function URLGetDataAvailable to determine the amount of data remaining in the buffer of the URL Access Manager that you will obtain from a call to the function URLGetBuffer.

If you pass a valid destination file, you should not call the functions URLGetBuffer, URLReleaseBuffer, or URLGetDataAvailable.

If you wish to be notified of certain data transfer events, you can specify a data transfer event callback and pass a pointer to it in the URLEventMask parameter of URLOpen. The data transfer events that you receive will vary depending upon whether the destination file you specify is valid. In addition, you should pass a bitmask representing the events you wish to be notified of in the eventRegister parameter.

When URLOpen downloads data from a URL that represents a local file (that is, a URL that begins with file://), the data fork is downloaded but the resource fork is not.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLReleaseBuffer

Releases a buffer. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLReleaseBuffer (
   URLReference urlRef,
   void *buffer
);

Parameters
urlRef

A reference to the URL whose buffer you want to release.

buffer

A pointer to the buffer you want to release.

Return Value

A result code. See “URL Access Manager Result Codes.”

Discussion

The URLReleaseBuffer function releases the buffer obtained by calling the function URLGetBuffer. To prevent the URL Access Manager from running out of buffers, you should call URLReleaseBuffer after each call to URLGetBuffer.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLSetProperty

Sets the value of a URL property. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

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

Parameters
urlRef

A reference to the URL whose property value you want to set.

property

A pointer to a C string representing the name of the property value you want to set. You can only set property values identified by the constants kURLPassword, kURLUserName, kURLHTTPRequestMethod, kURLHTTPRequestHeader, kURLHTTPRequestBody, and kURLHTTPUserAgent. For a description of these property name constants and their corresponding data types, see “Universal URL Property Name Constants” and “HTTP and HTTPS URL Property Name Constants.”

propertyBuffer

A pointer to a buffer containing the data you would like the property to be set to. The data must be of the correct type.

bufferSize

The size (in bytes) of the data you want to set.

Return Value

A result code. See “URL Access Manager Result Codes.” The result code kURLUnsettablePropertyError indicates that a property value cannot be set.

Discussion

The URLSetProperty function enables you to set those property values identified by the following constants: kURLPassword, kURLUserName, kURLPassword, kURLHTTPRequestMethod, kURLHTTPRequestHeader, kURLHTTPRequestBody, and kURLHTTPUserAgent. For a description of these property name constants and their corresponding data types, see “Universal URL Property Name Constants” and “HTTP and HTTPS URL Property Name Constants.”

You may wish to call URLSetProperty before calling the function URLDownload or URLUpload to set a URL property before a data transfer operation.

Special Considerations

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

Availability
Declared In
URLAccess.h

URLSimpleDownload

Downloads data from a URL specified by a character string. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLSimpleDownload (
   const char *url,
   FSSpec *destination,
   Handle destinationHandle,
   URLOpenFlags openFlags,
   URLSystemEventUPP eventProc,
   void *userContext
);

Parameters
url

A pointer to a C string representing the pathname of the URL from which data is to be downloaded. If the pathname specifies a file, the file is downloaded regardless of whether you specify kURLDirectoryListingFlag or KURLIsDirectoryHintFlag in the openFlags parameter.

destination

A pointer to a file specification structure that identifies the file or directory into which data is to be downloaded. If you wish to download data into memory, pass NULL in this parameter and a valid handle in the destinationHandle parameter. If you pass a file specification that does not identify a file or directory, the name of the file or directory specified by the pathname in the url parameter is used. If you pass a file or directory that already exists, and do not specify kURLReplaceExistingFlag in the openFlags parameter, URLSimpleDownload creates a new file or directory whose name has a number appended before the extension. For example, if the URL specifies a file named file.txt, URLSimpleDownload changes the filename to file1.txt.

destinationHandle

A handle to the destination in memory where you want the data downloaded. Before calling URLDownload, create a zero-sized handle. If you wish to download data into a file or directory, pass NULL in this parameter and a valid file specification in the destination parameter.

openFlags

A bitmask that indicates the data transfer options to use. You can specify any of the following masks for downloading options: kURLReplaceExistingFlag, kURLExpandFileFlag, kURLExpandAndVerifyFlag, kURLDisplayProgressFlag, kURLDisplayAuthFlag, kURLIsDirectoryHintFlag, kURLDoNotTryAnonymousFlag, kURLDebinhexOnlyFlag, kURLNoAutoRedirect, and kURLDirectoryListingFlag. See “Data Transfer Options Mask Constants” for a description of possible values.

eventProc

A Universal Procedure Pointer (UPP) to your system event callback function, if one exists. For information on how to write a system event callback, see URLSystemEventProcPtr. If you want to handle events that occur while a progress indicator or authentication dialog box is being displayed, specify the appropriate mask (either kURLDisplayProgressFlag or kURLDisplayAuthFlag) in the openFlags parameter and pass a UPP to your callback function in this parameter. Pass NULL if you do not want to receive notification of these events. In this case, the URL Access Manager displays a nonmovable modal progress indicator or authentication dialog box.

userContext

A pointer to application-defined storage that will be passed to your system event callback function, if one exists. Your application can use this to set up its context when your system event callback function is called.

Return Value

A result code. See “URL Access Manager Result Codes.” If your application is multi-threaded, and more than one thread calls URLSimpleDownload simultaneously, URLSimpleDownload returns the result code kURLProgressAlreadyDisplayedError if you specify kURLDisplayProgressFlag in the openFlags parameter and the URL Access Manager is already displaying a progress indicator.

Discussion

The URLSimpleDownload function downloads data from a URL specified by a pathname to a specified file, directory, or memory. It does not return until the download is complete. If you want to download data from a URL identified by a reference rather than a pathname, call the function URLDownload. The difference between the two functions is that URLDownload allows you to access other URL Access Manager functions before, after, or during the download. If you want more control over a data transfer operation, call the function URLOpen.

If you wish to download data to a file or directory, pass a valid file specification in the destination parameter. If you instead wish to download data to memory, pass a valid handle in the destinationHandle parameter.

When URLSimpleDownload downloads data from a URL that represents a local file (that is, a URL that begins with file://), the data fork is downloaded but the resource fork is not.

Special Considerations

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

URLSimpleDownload yields time to other threads. Your application should call URLSimpleDownload from a thread other than the main thread so that other processes have time to run.

Availability
Declared In
URLAccess.h

URLSimpleUpload

Uploads a file or directory to an FTP URL specified by a character string. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLSimpleUpload (
   const char *url,
   const FSSpec *source,
   URLOpenFlags openFlags,
   URLSystemEventUPP eventProc,
   void *userContext
);

Parameters
url

A pointer to a C string representing the URL to which a file or directory is to be uploaded. If you wish to replace the destination directory of this URL with the file or directory that you pass in the source parameter, terminate the string with a slash character (/), and set the mask constant kURLReplaceExistingFlag in the openFlags parameter. If you specify a name that already exists on the server and do not specify kURLReplaceExistingFlag, URLSimpleUpload returns the result code kURLDestinationExistsError. If you do not specify a name, do not specify kURLReplaceExistingFlag in the openFlags parameter, and the name already exists on the server, the URL Access Manager creates a unique name by appending a number to the original name before the extension, if any. For example, if the URL specifies a file named file.txt, URLSimpleUpload changes the filename to file1.txt. See “Naming Your Destination File” for more information.

source

A pointer to a file specification structure that describes the file or directory you want to upload.

openFlags

A bitmask that indicates the data transfer options to use. You can specify any of the following masks for uploading options: kURLReplaceExistingFlag, kURLBinHexFileFlag, kURLDisplayProgressFlag, kURLDisplayAuthFlag, and kURLDoNotTryAnonymousFlag. See “Data Transfer Options Mask Constants” for a description of possible values.

eventProc

A Universal Procedure Pointer (UPP) to your system event callback function, if one exists. For information on how to write a system event callback, see URLSystemEventProcPtr. If you want to handle events that occur while a progress indicator or authentication dialog box is being displayed, specify the appropriate mask (either kURLDisplayProgressFlag or kURLDisplayAuthFlag) in the openFlags parameter and pass a UPP to your callback function in this parameter. Pass NULL if you do not want to receive notification of these events. In this case, the URL Access Manager displays a nonmovable modal progress indicator or authentication dialog box.

userContext

A pointer to application-defined storage that will be passed to your system event callback function, if one exists. Your application can use this to set up its context when your system event callback function is called.

Return Value

A result code. See “URL Access Manager Result Codes.” The result code kURLDestinationExistsError indicates that you specified a pathname that already exists on the server but did not set the bit specified by the mask constant kURLReplaceExistingFlag in the openFlags parameter. If your application is multi-threaded, and more than one thread calls URLSimpleUpload simultaneously, URLSimpleUpload returns the result code kURLProgessAlreadyDisplayedError if you specify kURLDisplayProgressFlag in the openFlags parameter and the URL Access Manager is already displaying a progress indicator.

Discussion

The URLSimpleUpload function uploads a file or directory to an FTP URL specified by a pathname. It does not return until the upload is complete. If you want to upload data from a URL identified by a reference rather than a pathname, call the function URLUpload. The difference between the two functions is that URLUpload allows you to access other URL Access Manager functions before, after, or during the download. If you want more control over a data transfer operation, call the function URLOpen.

Special Considerations

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

URLSimpleUpload yields time to other threads. Your application should call URLSimpleUpload from a thread other than the main thread so that other processes have time to run.

Availability
Declared In
URLAccess.h

URLUpload

Uploads a file or directory to an FTP URL specified by a URL reference. (Deprecated in Mac OS X v10.4. Use CFNetwork instead; see CFNetwork Programming Guide.)

OSStatus URLUpload (
   URLReference urlRef,
   const FSSpec *source,
   URLOpenFlags openFlags,
   URLSystemEventUPP eventProc,
   void *userContext
);

Parameters
urlRef

A reference to the URL to which a file or directory is to be uploaded. Once you have called URLUpload, you cannot use the same reference again. If you wish to replace the destination directory of this URL with the file or directory that you pass in the source parameter, set the mask constant kURLReplaceExistingFlag in the openFlags parameter. If you specify a name that already exists on the server and do not specify kURLReplaceExistingFlag, URLUpload returns the result code kURLDestinationExistsError. If you do not specify a name, do not specify kURLReplaceExistingFlag in the openFlags parameter, and the name already exists on the server, the URL Access Manager creates a unique name by appending a number to the original name before the extension, if any. For example, if the URL specifies a file named file.txt, URLUpload changes the filename to file1.txt. See “Naming Your Destination File” for more information.

source

A pointer to a file specification structure that describes the file or directory you want to upload.

openFlags

A bitmask that indicates the data transfer options you want used. You can specify any of the following masks for uploading options: kURLReplaceExistingFlag, kURLBinHexFileFlag, kURLDisplayProgressFlag, kURLDisplayAuthFlag, and kURLDoNotTryAnonymousFlag. See “URL Access Manager Reference” for a description of possible values.

eventProc

A Universal Procedure Pointer (UPP) to your system event callback function, if one exists. For information on how to write a system event callback, see URLSystemEventProcPtr. If you want to handle events that occur while a progress indicator or authentication dialog box is being displayed, specify the appropriate mask (either kURLDisplayProgressFlag or kURLDisplayAuthFlag) in the openFlags parameter and pass a UPP to your callback function in this parameter. Pass NULL if you do not want to receive notification of these events. In this case, the URL Access Manager displays a nonmovable modal progress indicator or authentication dialog box.

userContext

A pointer to application-defined storage that will be passed to your system event callback function, if one exists. Your application can use this to set up its context when your system event callback function is called.

Return Value

A result code. See “URL Access Manager Result Codes.” The result code kURLDestinationExistsError indicates that you specified a pathname that already exists on the server but did not specify kURLReplaceExistingFlag in the openFlags parameter. If your application is multi-threaded, and more than one thread calls URLUpload simultaneously, URLUpload returns the result code kURLProgessAlreadyDisplayedError if you specify kURLDisplayProgressFlag in the openFlags parameter and the URL Access Manager is already displaying a progress indicator.

Discussion

The URLUpload function uploads a file or directory to an FTP URL specified by a URL reference. It does not return until the upload is complete. If you want to upload data from a URL identified by a pathname rather than a reference, call the function URLSimpleUpload. The difference between the two functions is that URLUpload allows you to access other URL Access Manager functions before, after, or during the download. If you want more control over a data transfer operation, call the function URLOpen.

Special Considerations

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

URLUpload yields time to other threads. Your application should call URLUpload from a thread other than the main thread so that other processes have time to run.

Availability
Declared In
URLAccess.h

< Previous PageNext Page > Hide TOC

© 2001, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-13)

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.