Retired Document
Important: This sample code may not represent best practices for current development. The project may use deprecated symbols and illustrate technologies and techniques that are no longer recommended.
MoreDesktopMgr.h
/* |
File: MoreDesktopMgr.h |
Description: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... |
Author: JL & NG |
Copyright: Copyright: © 1992-1999 by Apple Computer, Inc. |
all rights reserved. |
Disclaimer: 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. |
Change History (most recent first): |
6/25/99 Updated for Metrowerks Codewarror Pro 2.1(KG) |
*/ |
#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__ */ |
Copyright © 2003 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2003-03-13