Important: The information in this document is obsolete and should not be used for new development.
RoutinesThis 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.
Three Desktop Manager functions--namely,
- Clear all fields (other than input fields) in the parameter block that you pass to Desktop Manager routines.
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.
Because you cannot use the Desktop Manager functions on a disk that does not have a desktop database, call
- 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.
PBHGetVolParmsto verify that the target disk has a desktop database before calling any of the Desktop Manager functions. (For a description of the
PBHGetVolParmsfunction and the
bHasDesktopMgrbit that you should check, see the chapter "File Manager" in Inside Macintosh: Files.)
- 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.
- 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