Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 9 - Desktop Manager / Desktop Manager Reference

Routines

This section describes the low-level routines for using the desktop database.

All low-level routines exchange parameters with your application through a parameter block. When calling a low-level routine, you pass a pointer to the parameter block. See the chapter "File Manager" in Inside Macintosh: Files for a description of the standard fields in a parameter block.

IMPORTANT

Clear all fields (other than input fields) in the parameter block that you pass to Desktop Manager routines.

Three Desktop Manager functions--namely, PBDTGetPath, PBDTOpenInform, and PBDTCloseDown--run synchronously only. All other Desktop Manager routines can run either asynchronously or synchronously. There are three versions of each of these routines. The first version takes two parameters: a pointer to the parameter block, and a Boolean value that determines whether the routine is run asynchronously (TRUE) or synchronously (FALSE). Here, for example, is the first version of a routine that retrieves the user's comment stored for a file or a directory:

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

The second version does not take a second parameter; instead, it adds the suffix "Async" to the name of the routine.

FUNCTION PBDTGetCommentAsync (paramBlock: DTPBPtr): OSErr;

Similarly, the third version of the routine does not take a second parameter; instead, it adds the suffix "Sync" to the name of the routine.

FUNCTION PBDTGetCommentSync (paramBlock: DTPBPtr): OSErr;

All routines in this section are documented using the first version only. Note, however, that the second and third versions of these routines do not use the glue code that the first versions use and are therefore more efficient.

IMPORTANT

All of the Desktop Manager routines may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt. Your application should not call Desktop Manager routines at interrupt time.

Because you cannot use the Desktop Manager functions on a disk that does not have a desktop database, call PBHGetVolParms to verify that the target disk has a desktop database before calling any of the Desktop Manager functions. (For a description of the PBHGetVolParms function and the bHasDesktopMgr bit that you should check, see the chapter "File Manager" in Inside Macintosh: Files.)

WARNING

Although routines that set information in and get information from the desktop database are described in this section, you should never use these routines to change, add to, or remove any information from the desktop database. Manipulating the desktop database is likely to wreak havoc on your users' systems.

Assembly-Language Note

You can invoke each of the Desktop Manager routines with a macro that has the same name as the routine, preceded by an underscore. These macros, however, aren't really trap macros. Instead, they expand to invoke the trap macro _HFSDispatch. The File Manager determines which routine to execute from the routine selector, an integer placed in register D0. The routine selectors appear in "Assembly-Language Summary" beginning on page 9-34.

---

Subtopics

Locating, Opening, and Closing the Desktop Database

Reading the Desktop Database

Adding to the Desktop Database

Deleting Entries From the Desktop Database

Manipulating the Desktop Database Itself