ADC Home > Reference Library > Reference > Carbon > File Management > Folder Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Folder Manager Functions

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

Deprecated in Mac OS X v10.3

FindFolderExtended

Obtains location information for system-related directories. (Deprecated in Mac OS X v10.3. Use FindFolder instead.)

OSErr FindFolderExtended (
   FSVolumeRefNum vRefNum,
   OSType folderType,
   Boolean createFolder,
   UInt32 flags,
   void *data,
   FSVolumeRefNum *foundVRefNum,
   SInt32 *foundDirID
);

Parameters
foldType
createFolder
flags
Return Value

A result code. See “Folder Manager Result Codes.”

Availability
Declared In
Folders.h

FolderManagerRegisterCallNotificationProcs

Calls the registered Folder Manager notification procs. (Deprecated in Mac OS X v10.3. There is no replacement function.)

OSStatus FolderManagerRegisterCallNotificationProcs (
   OSType message,
   void *arg,
   UInt32 options
);

Parameters
message
options
Return Value

A result code. See “Folder Manager Result Codes.”

Availability
Declared In
Folders.h

FolderManagerRegisterNotificationProc

Registers your notification function with the Folder Manager. (Deprecated in Mac OS X v10.3. There is no replacement function.)

OSErr FolderManagerRegisterNotificationProc (
   FolderManagerNotificationUPP notificationProc,
   void *refCon,
   UInt32 options
);

Parameters
notificationProc

A UPP to your notification function.

refCon

A pointer to client-defined data. This value is passed to your notification function each time it is called.

options

A value specifying registration options. See FolderManagerCallNotificationProcs Options.

Return Value

A result code. See “Folder Manager Result Codes.”

Availability
Declared In
Folders.h

FolderManagerUnregisterNotificationProc

Removes your notification function from the Folder Manager's queue. (Deprecated in Mac OS X v10.3. There is no replacement function.)

OSErr FolderManagerUnregisterNotificationProc (
   FolderManagerNotificationUPP notificationProc,
   void *refCon
);

Parameters
notificationProc

The UPP to your notification function that you passed to the FolderManagerRegisterNotificationProc function.

refCon

A pointer to the same value that you passed to the FolderManagerRegisterNotificationProc function in the refCon parameter.

Return Value

A result code. See “Folder Manager Result Codes.”

Availability
Declared In
Folders.h

FSFindFolderExtended

Locates a system-related folder and returns a reference to the folder. (Deprecated in Mac OS X v10.3. Use FSFindFolder instead.)

OSErr FSFindFolderExtended (
   FSVolumeRefNum vRefNum,
   OSType folderType,
   Boolean createFolder,
   UInt32 flags,
   void *data,
   FSRef *foundRef
);

Parameters
vRefNum

The volume reference number or domain in which you want to locate a folder. To specify the startup disk, use the constant kOnSystemDisk. To specify a domain, use a domain constant such as kUserDomain. See Disk and Domain Constants.

foldType

The type of folder you want to find. See Folder Type Constants.

createFolder

A value of type Boolean, as defined in Create Folder Flags. Pass the constant kCreateFolder to create a folder if it does not already exist; otherwise, pass the constant kDontCreateFolder.

flags

An extended behavior constant. See FSFindFolderExtended Flags.

data

User data which is interpreted differently depending on the constant specified in the flags parameter.

foundRef

A pointer to a FSRef variable. On return, the variable contains a file system reference to the specified folder.

Return Value

A result code. See “Folder Manager Result Codes.”

Discussion

The specified folder might be relocated in future versions of system software; therefore, do not assume the volume that you specify in the vRefNum constant and the volume returned in the file system reference will be the same.

Availability
Declared In
Folders.h

GetFolderDescriptor

Obtains the folder descriptor information for the specified folder type from the global descriptor list. (Deprecated in Mac OS X v10.3. There is no replacement function.)

OSErr GetFolderDescriptor (
   FolderType foldType,
   Size descSize,
   FolderDesc *foldDesc
);

Parameters
foldType

Pass a constant identifying the type of the folder for which you wish to get descriptor information. See Folder Type Constants.

descSize

Pass the size (in bytes) of the folder descriptor structure for which a pointer is passed in the foldDesc parameter. This value is needed in order to determine the version of the structure being used.

foldDesc

Pass a pointer to a folder descriptor structure. On return, the folder descriptor structure contains information from the global descriptor list for the specified folder type.

Return Value

A result code. See “Folder Manager Result Codes.”

Availability
Declared In
Folders.h

ReleaseFolder

Releases the Trash folder in preparation for unmounting a server volume. (Deprecated in Mac OS X v10.3. This function is not needed in Mac OS X.)

OSErr ReleaseFolder (
   FSVolumeRefNum vRefNum,
   OSType folderType
);

Parameters
vRefNum

Pass the volume reference number of the server volume on which you want to release the Trash folder.

folderType

Always pass the kTrashFolderType constant. Other folder types are currently ignored.

Return Value

A result code. See “Folder Manager Result Codes.”

Discussion

When you call FindFolder with the kTrashFolderType constant, it opens a file on a server volume that ensures each server volume user gets a unique Trash folder. Because a server volume’s Trash folder may contain files or folders put there by the user, applications should delete the contents of the server volume’s Trash folder. To do this, before your application unmounts a server volume, your application should call ReleaseFolder, or the UnmountVol request could fail with a fBsyErr result code. ReleaseFolder closes the file FindFolder may have opened and releases the Trash folder on that volume.

Your application should not use this function unless you want to unmount one or more server volumes. Normally, applications should not unmount servers; they should let users use the Finder to unmount volumes. In particular, applications should have no need to release the Trash folder explicitly; rather, unmounting volumes should be left to users to do with the Finder or by restarting.

Availability
Declared In
Folders.h

Deprecated in Mac OS X v10.4

AddFolderRouting

Adds a folder routing structure to the global routing list. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr AddFolderRouting (
   OSType fileType,
   FolderType routeFromFolder,
   FolderType routeToFolder,
   RoutingFlags flags,
   Boolean replaceFlag
);

Parameters
fileType

Pass the OSType of the file to be routed.

routeFromFolder

Pass the folder type of the “from” folder see Folder Type Constants for descriptions of possible values. An item dropped on the folder specified in this parameter will be routed to the folder specified in the routeToFolder parameter.

routeToFolder

The folder type of the “to” folder see Folder Type Constants for descriptions of possible values.

flags

Reserved for future use; pass 0.

replaceFlag

Pass a Boolean value indicating whether you wish to replace a folder routing that already exists. If true, it replaces the folder to which the item is being routed. If false, it leaves the folder to which the item is being routed.

Return Value

A result code. See “Folder Manager Result Codes.” The result code duplicateRoutingErr indicates that a folder routing is already installed with the specified folder type and replaceFlag is false.

Discussion

Your application can use the AddFolderRouting function to specify how the Finder routes a given file type.

Availability
Declared In
Folders.h

FindFolderRouting

Finds the destination folder from a matching folder routing structure for the specified file. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr FindFolderRouting (
   OSType fileType,
   FolderType routeFromFolder,
   FolderType *routeToFolder,
   RoutingFlags *flags
);

Parameters
fileType

Pass the file type specified in the appropriate folder routing structure for the file for which you wish to find a destination folder.

routeFromFolder

Pass the folder type of the “from” folder for which you wish to find a “to” folder see Folder Type Constants for descriptions of possible values. An item dropped on the folder specified in this parameter will be routed to the folder specified in the routeToFolder parameter.

routeToFolder

A pointer to a value of type FolderType. On return, the value is set to the folder type of the destination folder.

flags

Reserved; pass 0.

Return Value

A result code. See “Folder Manager Result Codes.”

Discussion

Both the file type and the folder type specified must match those of a folder routing structure in the global routing list for the FindFolderRouting function to succeed.

Availability
Declared In
Folders.h

GetFolderRoutings

Obtains folder routing information from the global routing list. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr GetFolderRoutings (
   UInt32 requestedRoutingCount,
   UInt32 *totalRoutingCount,
   Size routingSize,
   FolderRouting *theRoutings
);

Parameters
requestedRoutingCount

An unsigned 32-bit value. Pass the number of folder routing structures that can fit in the buffer pointed to by the theRoutings parameter.

totalRoutingCount

A pointer to an unsigned 32-bit value. On return, the value is set to the number of folder routing structures in the global list. If this value is less than or equal to requestedRoutingCount, all folder routing structures were returned to the caller.

routingSize

Pass the size (in bytes) of the FolderRouting structure.

theRoutings

Pass a pointer to an array of FolderRouting structures. On return the structure(s) contain the requested routing information. You may pass null if you do not wish this information.

Return Value

A result code. See “Folder Manager Result Codes.”

Discussion

The folder routing information in the global routing list determines how the Finder routes files.

Availability
Declared In
Folders.h

RemoveFolderRouting

Deletes a folder routing structure from the global routing list. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr RemoveFolderRouting (
   OSType fileType,
   FolderType routeFromFolder
);

Parameters
fileType

Pass the file type value contained in the folder routing structure to be removed.

routeFromFolder

Pass the folder type of the “from” folder see Folder Type Constants for descriptions of possible values.

Return Value

A result code. See “Folder Manager Result Codes.”

Discussion

Both the file type and the folder type specified must match those of an existing folder routing structure for the RemoveFolderRouting function to succeed.

Availability
Declared In
Folders.h

Deprecated in Mac OS X v10.5

FSpDetermineIfSpecIsEnclosedByFolder

Determines whether a file of type FSSpec is enclosed inside a special folder type for the given domain. (Deprecated in Mac OS X v10.5.)

OSErr FSpDetermineIfSpecIsEnclosedByFolder (
   FSVolumeRefNum domainOrVRefNum,
   OSType folderType,
   const FSSpec *inSpec,
   Boolean *outResult
);

Parameters
domainOrVRefNum

The domain or volume reference number to check. For information about the possible domains, see Disk and Domain Constants. You can also pass 0 to check all domains and volumes, or you can pass kOnAppropriateDisk to check the appropriate volume for the specified file.

folderType

The special folder type to check. For information about the possible folder types, see Folder Type Constants.

inSpec

The file for which to search.

outResult

A pointer to a Boolean variable. On return, indicates whether or not the file is enclosed inside the special folder type for the given domain.

Discussion

This function provides an efficient way to check to see if a file (or folder) is inside a special folder for a given domain. A typical use for this function is to determine if a given file is inside the trash on a volume: 

err = FSpDetermineIfSpecIsEnclosedByFolder (kOnAppropriateDisk, kTrashFolderType, &spec, &result);
Availability
Declared In
Folders.h

GetFolderName

Obtains the name of the specified folder. (Deprecated in Mac OS X v10.5.)

OSErr GetFolderName (
   FSVolumeRefNum vRefNum,
   OSType foldType,
   FSVolumeRefNum *foundVRefNum,
   StrFileName name
);

Parameters
vRefNum

Pass the volume reference number (or the constant kOnSystemDisk for the startup disk) of the volume containing the folder for which you wish the name to be identified.

foldType

Pass a constant identifying the type of the folder for which you wish the name to be identified. See Folder Type Constants.

foundVRefNum

On return, a pointer to the volume reference number for the volume containing the folder specified in the foldType parameter.

name

On return, a string containing the title of the folder specified in the foldType and vRefNum parameters.

Return Value

A result code. See “Folder Manager Result Codes.”

Discussion

The GetFolderName function obtains the name of the folder in the folder descriptor, not the name of the folder on the disk. The names may differ for a few special folders such as the System Folder. For relative folders, however, the actual name is always returned. You typically do not need to call this function.

Availability
Declared In
Folders.h

< Previous PageNext Page > Hide TOC

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

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.