Carbon


URLUpload

Header: URLAccess.h Carbon status: Supported

Uploads a file or directory to an FTP URL specified by a URL reference.

OSStatus URLUpload (
    URLReference urlRef, 
    const FSSpec *source, 
    URLOpenFlags openFlags, 
    URLSystemEventUPP eventProc, 
    void *userContext
);
Parameter descriptions
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 “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.

function result

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

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.

VERSION NOTES

In Mac OS 8.6, if the file type of the file to be uploaded is unknown, URLUpload assumes that the file is of type text. In this case, the end-of-line character is changed to the Mac style end-of-line character 0x0d0x0a. In Mac OS 9, when a file of unknown type is uploaded, URLUpload does not assume that it is a text file. Instead, it identifies it as an unknown file type and does not change the end-of-line character.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.


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