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