---

How Coercion Handlers are Installed and Dispatched

Coercion handling works by a process that is similar to the one described previously for dispatching Apple events to Apple event handlers:

• You write coercion handler functions to coerce data between types that your application works with but that are not handled by a default coercion handler.

• Your application registers coercion handlers with the Apple Event Manager for all the descriptor data types it can convert between. A handler may handle just one type of coercion or multiple types. To specify multiple types, you use the constant typeWildCard.

• The Apple Event Manager creates an application coercion handler dispatch table for your application. The dispatch table maps the descriptor types your application can coerce to the coercion handlers it provides.

  The Apple Event Manager also creates a system coercion dispatch handler, described below, for the default coercion handlers.

• When the Apple Event Manager needs to perform a coercion in your application, it goes through these steps until the coercion is handled:

  • It looks for a coercion handler in your application coercion dispatch table.

  • It looks for a coercion handler in your system coercion dispatch table, which includes the default coercions described in Table C-2.

    Note: Default coercion handlers may be installed lazily, as they are needed.

  • If it can’t find an appropriate coercion handler, it returns the result code errAECoercionFail.

Although your application can have both a system coercion dispatch table and an application dispatch table, you should generally install all coercion handlers in the application coercion dispatch table. For Carbon applications running in Mac OS 8 or Mac OS 9, a handler in the system coercion dispatch table could reside in the system heap, where it would be available to other applications. However, your application should not install a handler in a system coercion dispatch table with the goal that the handler will get called when other applications perform coercions—this won’t necessarily work in Mac OS 8 or Mac OS 9 and will not work in Mac OS X.

---