Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: More Macintosh Toolbox /: Chapter 9 - Desktop Manager

Summary of the Desktop Manager

Pascal Summary

Constants

CONST 
      {for mapping icons to ioIconType in the desktop database}
      kLargeIcon                    = 1;        {'ICN#'}
      kLarge4BitIcon                = 2;        {'icl4'}
      kLarge8BitIcon                = 3;        {'icl8'}
      kSmallIcon                    = 4;        {'ics#'}
      kSmall4BitIcon                = 5;        {'ics4'}
      kSmall8BitIcon                = 6;        {'ics8'}
      
      {for allocating storage for icon data in the desktop database}
      kLargeIconSize                = 256;      {'ICN#'}
      kLarge4BitIconSize            = 512;      {'icl4'}
      kLarge8BitIconSize            = 1024;     {'icl8'}
      kSmallIconSize                = 64;       {'ics#'}
      kSmall4BitIconSize            = 128;      {'ics4'}
      kSmall8BitIconSize            = 256;      {'ics8'}

Data Types

TYPE  DTPBPtr = ^DTPBRec;
      DTPBRec =                     {parameter block for desktop database}
      RECORD
         qLink:            QElemPtr;      {next queue entry}
         qType:            Integer;       {queue type}
         ioTrap:           Integer;       {routine trap}
         ioCmdAddr:        Ptr;           {routine address}
         ioCompletion:     ProcPtr;       {completion routine}
         ioResult:         OSErr;         {result code}
         ioNamePtr:        StringPtr;     {file, directory, or volume name}
         ioVRefNum:        Integer;       {volume reference number}
         ioDTRefNum:       Integer;       {desktop database reference number}
         ioIndex:          Integer;       {index into icon list}
         ioTagInfo:        LongInt;       {tag information}
         ioDTBuffer:       Ptr;           {data buffer}
         ioDTReqCount:     LongInt;       {requested length of data}
         ioDTActCount:     LongInt;       {actual length of data}
         filler1:          SignedByte;    {unused}
         ioIconType:       SignedByte;    {icon type}
         filler2:          Integer;       {unused}
         ioDirID:          LongInt;       {parent directory ID}
         ioFileCreator:    OSType;        {file creator}
         ioFileType:       OSType;        {file type}
         ioFiller3:        LongInt;       {unused}
         ioDTLgLen:        LongInt;       {logical length of desktop }
                                          { database}
         ioDTPyLen:        LongInt;       {physical length of desktop }
                                          { database}
         ioFiller4:                       {unused}
                           ARRAY[1..14] OF Integer;
         ioAPPLParID:      LongInt        {parent directory ID of }
                                          { application}
      END;
      DTPBPtr = ^DTPBRec;                 {pointer to desktop }
                                          { parameter block}

Routines

Locating, Opening, and Closing the Desktop Database

FUNCTION PBDTGetPath       (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTOpenInform    (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTCloseDown     (paramBlock: DTPBPtr): OSErr;

Reading the Desktop Database

FUNCTION PBDTGetIcon       (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTGetIconAsync  (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTGetIconSync   (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTGetIconInfo   (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTGetIconInfoAsync
                           (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTGetIconInfoSync
                           (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTGetAPPL       (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTGetAPPLAsync  (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTGetAPPLSync   (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTGetComment    (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTGetCommentAsync
                           (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTGetCommentSync
                           (paramBlock: DTPBPtr): OSErr;

Adding to the Desktop Database

FUNCTION PBDTAddIcon       (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTAddIconAsync  (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTAddIconSync   (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTAddAPPL       (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTAddAPPLAsync  (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTAddAPPLSync   (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTSetComment    (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTSetCommentAsync
                           (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTSetCommentSync
                           (paramBlock: DTPBPtr): OSErr;

Deleting Entries From the Desktop Database

FUNCTION PBDTRemoveAPPL    (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTRemoveAPPLAsync
                           (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTRemoveAPPLSync
                           (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTRemoveComment (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTRemoveCommentAsync
                           (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTRemoveCommentSync
                           (paramBlock: DTPBPtr): OSErr;

Manipulating the Desktop Database Itself

FUNCTION PBDTFlush         (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTFlushAsync    (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTFlushSync     (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTGetInfo       (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTGetInfoAsync  (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTGetInfoSync   (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTReset         (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTResetAsync    (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTResetSync     (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTDelete        (paramBlock: DTPBPtr; async: Boolean): OSErr;
FUNCTION PBDTDeleteAsync   (paramBlock: DTPBPtr): OSErr;
FUNCTION PBDTDeleteSync    (paramBlock: DTPBPtr): OSErr;

C Summary

Constants

enum {
      /*for mapping icons to ioIconType in the desktop database*/
      kLargeIcon                    = 1,     /*'ICN#'*/
      kLarge4BitIcon                = 2,     /*'icl4'*/
      kLarge8BitIcon                = 3,     /*'icl8'*/
      kSmallIcon                    = 4,     /*'ics#'*/
      kSmall4BitIcon                = 5,     /*'ics4'*/
      kSmall8BitIcon                = 6,     /*'ics8'*/
      
      /*for allocating storage for icon data in the desktop database*/
      kLargeIconSize                = 256,   /*'ICN#'*/
      kLarge4BitIconSize            = 512,   /*'icl4'*/
      kLarge8BitIconSize            = 1024,  /*'icl8'*/
      kSmallIconSize                = 64,    /*'ics#'*/
      kSmall4BitIconSize            = 128,   /*'ics4'*/
      kSmall8BitIconSize            = 256    /*'ics8'*/
};

Data Types

struct DTPBRec {           /*parameter block for desktop database*/ 
   ParamBlockHeader 
   short    ioDTRefNum;                      /*desktop refnum*/
   short    ioIndex;                         /*index into icon list*/
   long     ioTagInfo;                       /*tag information*/
   Ptr      ioDTBuffer;                      /*data buffer*/
   long     ioDTReqCount;                    /*requested length of data*/
   long     ioDTActCount;                    /*actual length of data*/
   char     ioFiller1;                       /*unused*/
   char     ioIconType;                      /*icon type*/
   short    ioFiller2;                       /*unused*/
   long     ioDirID;                         /*parent directory ID*/
   OSType   ioFileCreator;                   /*file creator*/
   OSType   ioFileType;                      /*file type*/
   long     ioFiller3;                       /*unused*/
   long     ioDTLgLen;                       /*logical length of */
                                             /* desktop database*/
   long     ioDTPyLen;                       /*physical length of desktop */
                                             /* database*/
   short    ioFiller4[14];                   /*unused*/
   long     ioAPPLParID;                     /*parent directory ID of */
                                             /* application*/
};
typedef struct DTPBRec DTPBRec;
typedef DTPBRec *DTPBPtr;

Routines

Locating, Opening, and Closing the Desktop Database

pascal OSErr PBDTGetPath     (DTPBPtr paramBlock);
pascal OSErr PBDTOpenInform
                             (DTPBPtr paramBlock);
pascal OSErr PBDTCloseDown   (DTPBPtr paramBlock);

Reading the Desktop Database

pascal OSErr PBDTGetIcon     (DTPBPtr paramBlock, Boolean async);
pascal OSErr PBDTGetIconAsync 
                             (DTPBPtr paramBlock);
pascal OSErr PBDTGetIconSync 
                             (DTPBPtr paramBlock);
pascal OSErr PBDTGetIconInfo
                             (DTPBPtr paramBlock, Boolean async);
pascal OSErr PBDTGetIconInfoAsync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTGetIconInfoSync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTGetAPPL     (DTPBPtr paramBlock, Boolean async);
pascal OSErr PBDTGetAPPLAsync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTGetAPPLSync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTGetComment
                             (DTPBPtr paramBlock, Boolean async); 
pascal OSErr PBDTGetCommentAsync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTGetCommentSync
                             (DTPBPtr paramBlock);

Adding to the Desktop Database

pascal OSErr PBDTAddIcon     (DTPBPtr paramBlock, Boolean async); 
pascal OSErr PBDTAddIconAsync 
                             (DTPBPtr paramBlock);
pascal OSErr PBDTAddIconSync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTAddAPPL     (DTPBPtr paramBlock, Boolean async); 
pascal OSErr PBDTAddAPPLAsync 
                             (DTPBPtr paramBlock);
pascal OSErr PBDTAddAPPLSync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTSetComment
                             (DTPBPtr paramBlock, Boolean async);
pascal OSErr PBDTSetCommentAsync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTSetCommentSync
                             (DTPBPtr paramBlock);

Deleting Entries From the Desktop Database

pascal OSErr PBDTRemoveAPPL
                             (DTPBPtr paramBlock, Boolean async);
pascal OSErr PBDTRemoveAPPLAsync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTRemoveAPPLSync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTRemoveComment
                             (DTPBPtr paramBlock, Boolean async);
pascal OSErr PBDTRemoveCommentAsync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTRemoveCommentSync
                             (DTPBPtr paramBlock);

Manipulating the Desktop Database Itself

pascal OSErr PBDTFlush       (DTPBPtr paramBlock, Boolean async);
pascal OSErr PBDTFlushAsync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTFlushSync   (DTPBPtr paramBlock);
pascal OSErr PBDTGetInfo     (DTPBPtr paramBlock, Boolean async);
pascal OSErr PBDTGetInfoAsync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTGetInfoSync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTReset       (DTPBPtr paramBlock, Boolean async);
pascal OSErr PBDTResetAsync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTResetSync   (DTPBPtr paramBlock);
pascal OSErr PBDTDelete      (DTPBPtr paramBlock, Boolean async);
pascal OSErr PBDTDeleteAsync
                             (DTPBPtr paramBlock);
pascal OSErr PBDTDeleteSync
                             (DTPBPtr paramBlock);

Assembly-Language Summary

Data Structures

Desktop Parameter Block
--> 12 ioCompletion long completion routine
\xAE 16 ioResult word result code
--> 18 ioNamePtr long pointer to file, directory, or volume name
--> 22 ioVRefNum word volume reference number
\xA5 24 ioDTRefNum word desktop database reference number
--> 26 ioIndex word index into icon list; or number of files in database
\xA5 28 ioTagInfo long tag information
--> 32 ioDTBuffer long pointer to icon data
--> 36 ioDTReqCount long requested size of icon data buffer
\xAE 40 ioDTActCount long actual size of icon definition
\xA5 44 ioIconType byte icon's type
\xA5 48 ioDirID long parent directory
--> 52 ioFileCreator long file creator
\xA5 56 ioFileType long file type
\xAE 64 ioDTLgLen long logical length of database files
\xAE 68 ioDTPyLen long physical length of database files
\xAE 100 ioAPPLParID long application's parent directory

Trap Macros

Trap Macros Requiring Routine Selectors

_HFSDispatch

Selector	Routine
$0020	PBDTGetPath
$0021	PBDTCloseDown
$0022	PBDTAddIcon
$0023	PBDTGetIcon
$0024	PBDTGetIconInfo
$0025	PBDTAddAPPL
$0026	PBDTRemoveAPPL
$0027	PBDTGetAPPL
$0028	PBDTSetComment
$0029	PBDTRemoveComment
$002A	PBDTGetComment
$002B	PBDTFlush
$002C	PBDTReset
$002D	PBDTGetInfo
$002E	PBDTOpenInform
$002F	PBDTDelete

Result Codes

noErr	0	No error
nsvErr	-35	No such volume
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	Parameter error; use `PBDTGetPath`
rfNumErr	-51	Reference number invalid
extFSErr	-58	External file system--file system identifier is nonzero
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
afpIconTypeError	-5030	Sizes of new icon and one it replaces don't match

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

-->	12	ioCompletion	long	completion routine
\xAE	16	ioResult	word	result code
-->	18	ioNamePtr	long	pointer to file, directory, or volume name
-->	22	ioVRefNum	word	volume reference number
\xA5	24	ioDTRefNum	word	desktop database reference number
-->	26	ioIndex	word	index into icon list; or number of files in database
\xA5	28	ioTagInfo	long	tag information
-->	32	ioDTBuffer	long	pointer to icon data
-->	36	ioDTReqCount	long	requested size of icon data buffer
\xAE	40	ioDTActCount	long	actual size of icon definition
\xA5	44	ioIconType	byte	icon's type
\xA5	48	ioDirID	long	parent directory
-->	52	ioFileCreator	long	file creator
\xA5	56	ioFileType	long	file type
\xAE	64	ioDTLgLen	long	logical length of database files
\xAE	68	ioDTPyLen	long	physical length of database files
\xAE	100	ioAPPLParID	long	application's parent directory