/*
**	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-1998 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 "optim.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 "optimend.h"

#endif				/* __MOREDESKTOPMGR__ */
