Carbon


URLNotifyProcPtr

Header: URLAccess.h Carbon status: Supported

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

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

You would declare your function like this if you were to name it MyURLNotifyCallback:

OSStatus MyURLNotifyCallback (
    void *userContext, 
    URLEvent event, 
    URLCallbackInfo *callbackInfo
);
Parameter descriptions
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.

function result

A result code. 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.


© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)