Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 9 - Desktop Manager / Desktop Manager Reference

Routines / Reading the Desktop Database

PBDTGetIcon

To retrieve an icon definition, use the PBDTGetIcon function.

FUNCTION PBDTGetIcon (paramBlock: DTPBPtr; async: Boolean): OSErr;

paramBlock

A pointer to a desktop parameter block.

async

A Boolean value that specifies asynchronous (TRUE) or synchronous (FALSE) execution.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
\xAE	ioResult	OSErr	The result code of the function.
-->	ioDTRefNum	Integer	The desktop database reference number.
-->	ioTagInfo	LongInt	Reserved; must be set to 0.
-->	ioDTBuffer	Ptr	A pointer to a buffer to hold the icon's data.
-->	ioDTReqCount	LongInt	The requested size of the icon's bitmap.
\xAE	ioDTActCount	LongInt	The actual size of the icon's bitmap.
-->	ioIconType	SignedByte	The icon type.
-->	ioFileCreator	OSType	The icon's file creator.
-->	ioFileType	OSType	The icon's file type.

DESCRIPTION

The PBDTGetIcon function returns the bitmap for an icon that represents a file of a given type and creator. (For example, to get the icon for a file of file type 'SFWR' created by the application with a signature of 'WAVE', specify these two values in ioFileType and ioFileCreator.) You pass a pointer to a buffer for the icon bitmap in the ioDTBuffer field. The bitmap is returned in this buffer. You specify the desktop database in ioDTRefNum, the file creator in ioFileCreator, and the file type in ioFileType. For the icon type in ioIconType, specify a constant from the
following list:

Constant	Value	Corresponding resource type	Description
kLargeIcon	1	'ICN#'	Large black-and-white icon with mask
kLarge4BitIcon	2	'icl4'	Large 4-bit color icon
kLarge8BitIcon	3	'icl8'	Large 8-bit color icon
kSmallIcon	4	'ics#'	Small black-and-white icon with mask
kSmall4BitIcon	5	'ics4'	Small 4-bit color icon
kSmall8BitIcon	6	'ics8'	Small 8-bit color icon

The value you supply in ioDTReqCount is the size in bytes of the buffer that you've allocated for the icon's bitmap pointed to by ioDTBuffer; this value depends on the icon type. Be sure to allocate enough storage for the icon data; 1024 bytes is the largest amount required for any icon in System 7. You can use constants to indicate the amount of memory you have provided for the icon's data. The following list shows these constants and, for each icon type, shows the amount of bytes you should allocate.

Constant	Value (bytes)	Corresponding resource type	Description
kLargeIconSize	256	'ICN#'	Large black-and-white icon with mask
kLarge4BitIconSize	512	'icl4'	Large 4-bit color icon
kLarge8BitIconSize	1024	'icl8'	Large 8-bit color icon
kSmallIconSize	64	'ics#'	Small black-and-white icon with mask
kSmall4BitIconSize	128	'ics4'	Small 4-bit color icon
kSmall8BitIconSize	256	'ics8'	Small 8-bit color icon

The value in ioDTActCount reflects the size of the bitmap actually retrieved. If ioDTActCount is larger than ioDTReqCount, only the amount of data allowed
by ioDTReqCount is valid.

RESULT CODES

noErr	0	No error
ioErr	-36	I/O error
rfNumErr	-51	Reference number invalid
extFSErr	-58	External file system--file system identifier is nonzero
afpItemNotFound	-5012	Information not found