/*
** Apple Macintosh Developer Technical Support
**
** A collection of useful high-level Desktop Manager routines.
** If the Desktop Manager isn't available, use the Desktop file
** for 'read' operations.
**
** We do more because we can...
**
** by Jim Luther and Nitin Ganatra, Apple Developer Technical Support Emeriti
**
** File: MoreDesktopMgr.h
**
** Copyright © 1992-1999 Apple Computer, Inc.
** All rights reserved.
**
** You may incorporate this sample code into your applications without
** restriction, though the sample code has been provided "AS IS" and the
** responsibility for its operation is 100% yours. However, what you are
** not permitted to do is to redistribute the source as "DSC Sample Code"
** after having made changes. If you're going to re-distribute the source,
** we require that you make it clear in the source that the code was
** descended from Apple Sample Code, but that you've made changes.
*/
#ifndef __MOREDESKTOPMGR__
#define __MOREDESKTOPMGR__
#include <Types.h>
#include <Files.h>
#include "Optimization.h"
#ifdef __cplusplus
extern "C" {
#endif
/*****************************************************************************/
pascal OSErr DTOpen(ConstStr255Param volName,
short vRefNum,
short *dtRefNum,
Boolean *newDTDatabase);
/* ¦ Open a volume's desktop database and return the desktop database refNum.
The DTOpen function opens a volume's desktop database. It returns
the reference number of the desktop database and indicates if the
desktop database was created as a result of this call (if it was created,
then it is empty).
volName input: A pointer to the name of a mounted volume
or nil.
vRefNum input: Volume specification.
dtRefNum output: The reference number of Desktop Manager's
desktop database on the specified volume.
newDTDatabase output: true if the desktop database was created as a
result of this call and thus empty.
false if the desktop database was already created,
or if it could not be determined if it was already
created.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
paramErr -50 Volume doesn't support this function
extFSErr -58 External file system error - no file
system claimed this call.
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
*/
/*****************************************************************************/
pascal OSErr DTXGetAPPL(ConstStr255Param volName,
short vRefNum,
OSType creator,
Boolean searchCatalog,
short *applVRefNum,
long *applParID,
Str255 applName);
/* ¦ Find an application on a volume that can open a file with a given creator.
The DTXGetAPPL function finds an application (file type 'APPL') with
the specified creator on the specified volume. It first tries to get
the application mapping from the desktop database. If that fails,
then it tries to find an application in the Desktop file. If that
fails and searchCatalog is true, then it tries to find an application
with the specified creator using the File Manager's CatSearch routine.
volName input: A pointer to the name of a mounted volume
or nil.
vRefNum input: Volume specification.
creator input: The file's creator type.
searchCatalog input: If true, search the catalog for the application
if it isn't found in the desktop database.
applVRefNum output: The volume reference number of the volume the
application is on.
applParID output: The parent directory ID of the application.
applName output: The name of the application.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
paramErr -50 No default volume
rfNumErr -51 Reference number invalid
extFSErr -58 External file system error - no file
system claimed this call
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
afpItemNotFound -5012 Information not found
__________
Also see: FSpDTGetAPPL
*/
/*****************************************************************************/
pascal OSErr FSpDTXGetAPPL(ConstStr255Param volName,
short vRefNum,
OSType creator,
Boolean searchCatalog,
FSSpec *spec);
/* ¦ Find an application on a volume that can open a file with a given creator.
The FSpDTXGetAPPL function finds an application (file type 'APPL') with
the specified creator on the specified volume. It first tries to get
the application mapping from the desktop database. If that fails,
then it tries to find an application in the Desktop file. If that
fails and searchCatalog is true, then it tries to find an application
with the specified creator using the File Manager's CatSearch routine.
volName input: A pointer to the name of a mounted volume
or nil.
vRefNum input: Volume specification.
creator input: The file's creator type.
searchCatalog input: If true, search the catalog for the application
if it isn't found in the desktop database.
spec output: FSSpec record containing the application name and
location.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
paramErr -50 No default volume
rfNumErr -51 Reference number invalid
extFSErr -58 External file system error - no file
system claimed this call
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
afpItemNotFound -5012 Information not found
__________
Also see: FSpDTGetAPPL
*/
/*****************************************************************************/
pascal OSErr DTGetAPPL(ConstStr255Param volName,
short vRefNum,
OSType creator,
short *applVRefNum,
long *applParID,
Str255 applName);
/* ¦ Find an application on a volume that can open a file with a given creator.
The DTGetAPPL function finds an application (file type 'APPL') with
the specified creator on the specified volume. It first tries to get
the application mapping from the desktop database. If that fails,
then it tries to find an application in the Desktop file. If that
fails, then it tries to find an application with the specified creator
using the File Manager's CatSearch routine.
volName input: A pointer to the name of a mounted volume
or nil.
vRefNum input: Volume specification.
creator input: The file's creator type.
applVRefNum output: The volume reference number of the volume the
application is on.
applParID output: The parent directory ID of the application.
applName output: The name of the application.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
paramErr -50 No default volume
rfNumErr -51 Reference number invalid
extFSErr -58 External file system error - no file
system claimed this call
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
afpItemNotFound -5012 Information not found
__________
Also see: FSpDTGetAPPL
*/
/*****************************************************************************/
pascal OSErr FSpDTGetAPPL(ConstStr255Param volName,
short vRefNum,
OSType creator,
FSSpec *spec);
/* ¦ Find an application on a volume that can open a file with a given creator.
The FSpDTGetAPPL function finds an application (file type 'APPL') with
the specified creator on the specified volume. It first tries to get
the application mapping from the desktop database. If that fails,
then it tries to find an application in the Desktop file. If that
fails, then it tries to find an application with the specified creator
using the File Manager's CatSearch routine.
volName input: A pointer to the name of a mounted volume
or nil.
vRefNum input: Volume specification.
creator input: The file's creator type.
spec output: FSSpec record containing the application name and
location.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
paramErr -50 No default volume
rfNumErr -51 Reference number invalid
extFSErr -58 External file system error - no file
system claimed this call
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
afpItemNotFound -5012 Information not found
__________
Also see: DTGetAPPL
*/
/*****************************************************************************/
pascal OSErr DTGetIcon(ConstStr255Param volName,
short vRefNum,
short iconType,
OSType fileCreator,
OSType fileType,
Handle *iconHandle);
/* ¦ Get an icon from the desktop database or Desktop file.
The DTGetIcon function retrieves the specified icon and returns it in
a newly created handle. The icon is retrieves from the Desktop Manager
or if the Desktop Manager is not available, from the Finder's Desktop
file. Your program is responsible for disposing of the handle when it is
done using the icon.
volName input: A pointer to the name of a mounted volume
or nil.
vRefNum input: Volume specification.
iconType input: The icon type as defined in Files.h. Valid values are:
kLargeIcon
kLarge4BitIcon
kLarge8BitIcon
kSmallIcon
kSmall4BitIcon
kSmall8BitIcon
fileCreator input: The icon's creator type.
fileType input: The icon's file type.
iconHandle output: A Handle containing the newly created icon.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
paramErr -50 Volume doesn't support this function
rfNumErr -51 Reference number invalid
extFSErr -58 External file system error - no file
system claimed this call
memFullErr -108 iconHandle could not be allocated
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
afpItemNotFound -5012 Information not found
*/
/*****************************************************************************/
pascal OSErr DTSetComment(short vRefNum,
long dirID,
ConstStr255Param name,
ConstStr255Param comment);
/* ¦ Set a file or directory's Finder comment field.
The DTSetComment function sets a file or directory's Finder comment
field. The volume must support the Desktop Manager because you only
have read access to the Desktop file.
vRefNum input: Volume specification.
dirID input: Directory ID.
name input: Pointer to object name, or nil when dirID
specifies a directory that's the object.
comment input: The comment to add. Comments are limited to 200 characters;
longer comments are truncated.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
fnfErr Ð43 File or directory doesnÕt exist
paramErr -50 Volume doesn't support this function
wPrErr Ð44 Volume is locked through hardware
vLckdErr Ð46 Volume is locked through software
rfNumErr Ð51 Reference number invalid
extFSErr -58 External file system error - no file
system claimed this call.
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
__________
Also see: DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
FSpDTGetComment
*/
/*****************************************************************************/
pascal OSErr FSpDTSetComment(const FSSpec *spec,
ConstStr255Param comment);
/* ¦ Set a file or directory's Finder comment field.
The FSpDTSetComment function sets a file or directory's Finder comment
field. The volume must support the Desktop Manager because you only
have read access to the Desktop file.
spec input: An FSSpec record specifying the file or directory.
comment input: The comment to add. Comments are limited to 200 characters;
longer comments are truncated.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
fnfErr Ð43 File or directory doesnÕt exist
wPrErr Ð44 Volume is locked through hardware
vLckdErr Ð46 Volume is locked through software
rfNumErr Ð51 Reference number invalid
paramErr -50 Volume doesn't support this function
extFSErr -58 External file system error - no file
system claimed this call.
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
__________
Also see: DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
FSpDTGetComment
*/
/*****************************************************************************/
pascal OSErr DTGetComment(short vRefNum,
long dirID,
ConstStr255Param name,
Str255 comment);
/* ¦ Get a file or directory's Finder comment field (if any).
The DTGetComment function gets a file or directory's Finder comment
field (if any) from the Desktop Manager or if the Desktop Manager is
not available, from the Finder's Desktop file.
IMPORTANT NOTE: Inside Macintosh says that comments are up to
200 characters. While that may be correct for the HFS file system's
Desktop Manager, other file systems (such as Apple Photo Access) return
up to 255 characters. Make sure the comment buffer is a Str255 or you'll
regret it.
vRefNum input: Volume specification.
dirID input: Directory ID.
name input: Pointer to object name, or nil when dirID
specifies a directory that's the object.
comment output: A Str255 where the comment is to be returned.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
fnfErr -43 File not found
paramErr -50 Volume doesn't support this function
rfNumErr Ð51 Reference number invalid
extFSErr -58 External file system error - no file
system claimed this call.
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
afpItemNotFound -5012 Information not found
__________
Also see: DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
FSpDTGetComment
*/
/*****************************************************************************/
pascal OSErr FSpDTGetComment(const FSSpec *spec,
Str255 comment);
/* ¦ Get a file or directory's Finder comment field (if any).
The FSpDTGetComment function gets a file or directory's Finder comment
field (if any) from the Desktop Manager or if the Desktop Manager is
not available, from the Finder's Desktop file.
IMPORTANT NOTE: Inside Macintosh says that comments are up to
200 characters. While that may be correct for the HFS file system's
Desktop Manager, other file systems (such as Apple Photo Access) return
up to 255 characters. Make sure the comment buffer is a Str255 or you'll
regret it.
spec input: An FSSpec record specifying the file or directory.
comment output: A Str255 where the comment is to be returned.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
fnfErr -43 File not found
paramErr -50 Volume doesn't support this function
rfNumErr Ð51 Reference number invalid
extFSErr -58 External file system error - no file
system claimed this call.
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
afpItemNotFound -5012 Information not found
__________
Also see: DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
DTGetComment
*/
/*****************************************************************************/
pascal OSErr DTCopyComment(short srcVRefNum,
long srcDirID,
ConstStr255Param srcName,
short dstVRefNum,
long dstDirID,
ConstStr255Param dstName);
/* ¦ Copy the file or folder comment from the source to the destination object.
The DTCopyComment function copies the file or folder comment from the
source to the destination object. The destination volume must support
the Desktop Manager because you only have read access to the Desktop file.
srcVRefNum input: Source volume specification.
srcDirID input: Source directory ID.
srcName input: Pointer to source object name, or nil when srcDirID
specifies a directory that's the object.
dstVRefNum input: Destination volume specification.
dstDirID input: Destination directory ID.
dstName input: Pointer to destination object name, or nil when
dstDirID specifies a directory that's the object.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
fnfErr Ð43 File or directory doesnÕt exist
wPrErr Ð44 Volume is locked through hardware
vLckdErr Ð46 Volume is locked through software
paramErr -50 Volume doesn't support this function
rfNumErr Ð51 Reference number invalid
paramErr -50 Volume doesn't support this function
extFSErr -58 External file system error - no file
system claimed this call.
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
afpItemNotFound -5012 Information not found
__________
Also see: FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
FSpDTGetComment
*/
/*****************************************************************************/
pascal OSErr FSpDTCopyComment(const FSSpec *srcSpec,
const FSSpec *dstSpec);
/* ¦ Copy the desktop database comment from the source to the destination object.
The FSpDTCopyComment function copies the desktop database comment from
the source to the destination object. Both the source and the
destination volumes must support the Desktop Manager.
srcSpec input: An FSSpec record specifying the source object.
dstSpec input: An FSSpec record specifying the destination object.
Result Codes
noErr 0 No error
nsvErr -35 Volume not found
ioErr -36 I/O error
fnfErr Ð43 File or directory doesnÕt exist
wPrErr Ð44 Volume is locked through hardware
vLckdErr Ð46 Volume is locked through software
paramErr -50 Volume doesn't support this function
rfNumErr Ð51 Reference number invalid
paramErr -50 Volume doesn't support this function
extFSErr -58 External file system error - no file
system claimed this call.
desktopDamagedErr -1305 The desktop database has become corrupted -
the Finder will fix this, but if your
application is not running with the
Finder, use PBDTReset or PBDTDelete
afpItemNotFound -5012 Information not found
__________
Also see: DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
FSpDTGetComment
*/
/*****************************************************************************/
#ifdef __cplusplus
}
#endif
#include "OptimizationEnd.h"
#endif /* __MOREDESKTOPMGR__ */