---

Printing Plug-in Interfaces Reference

Overview

As printer vendors and application developers extend the printing capabilities of their hardware and software products, they need a way to extend the Mac OS X printing system to make new printing features available to their customers. To address this need, Mac OS X has introduced the printing plug-in —a component architecture based on Core Foundation Plug-in Services. There are four types of printing plug-ins in Mac OS X:

• I/O modules are used by the printing system to communicate with a printer using a standard transport-layer interface, such as AppleTalk or TCP/IP.

• Printer browsers provide a way for people to discover available local and network printers.

• Printer modules are used by the printing system to convert the graphics content in a print job for output to a specific printer or family of printers.

• Printing dialog extensions provide a way for people to view and change the settings for a set of related printing features. The user interface of a printing dialog extension is a pane in one of the printing dialogs.

This reference document is relevant for anyone writing a plug-in that provides support for printing.

If you’re writing a printing dialog extension, you should refer to this document as you implement the required callback functions. For conceptual information about printing dialog extensions, see Extending Printing Dialogs.

Functions

PMCreateLocalizedPaperSizeCFString

Returns a text description of the physical dimensions of the paper specified in a paper information ticket. The unit of measure is based on the current language and script system.

CFStringRef PMCreateLocalizedPaperSizeCFString (
   PMTicketRef listofPaperTickets,
   UInt16 paperToUse
);

Parameters

listofPaperTickets

A ticket that contains a list of paper information tickets. Typically you would obtain this list ticket from a printer module template ticket.

paperToUse

A one-based index that specifies an entry in a list ticket.Upon entering, this parameter should specify a valid entry in listofPaperTickets.

Return Value

A text description of the physical dimensions of the paper specified in a paper information ticket. Numeric values are localized to English or metric measure, based on the current language and script system. The caller assumes ownership of the string and is responsible for releasing it. The return value NULL indicates that the function failed to create the string.

Discussion

The name PMCreateLocalizedPaperSizeCFString suggests that this function does some additional localization, but that is misleading. This function takes an array of paper information tickets and an index, finds the desired paper information ticket, and simply calls PMCreatePaperSizeCFString to get the physical paper size.

Availability

• Available in Mac OS X version 10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrintingDialogExtensionsDeprecated.h

PMCreatePaperSizeCFString

Returns a text description of the physical dimensions of the paper specified in a paper information ticket. The unit of measure is based on the current language and script system.

CFStringRef PMCreatePaperSizeCFString (
   PMTicketRef selectedPaper
);

Parameters

selectedPaper

A paper information ticket. Typically you would obtain this ticket from a page format ticket, or possibly from a printer module template ticket.

Return Value

A text description of the physical dimensions of the paper specified in a paper information ticket. Numeric values are localized to English or metric measure, based on the current language and script system. The caller assumes ownership of the string, and is responsible for releasing it. The return value NULL indicates that the function failed to create the string.

Availability

• Available in Mac OS X version 10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrintingDialogExtensionsDeprecated.h

Callbacks by Task

Printing Plug-in Callbacks

The three callback functions described in this section are used by the printing system to manage a printing plug-in after it is loaded. Printing plug-ins (except for printer browsers) are required to implement these functions.

• PMPluginRetainProcPtr
• PMPluginReleaseProcPtr
• PMPluginGetAPIVersionProcPtr

Printing Dialog Extension Callbacks

The callback functions described in this section must be implemented by all printing dialog extensions.

• PMPDEPrologueProcPtr
• PMPDEInitializeProcPtr
• PMPDESyncProcPtr
• PMPDEGetSummaryTextProcPtr
• PMPDEOpenProcPtr
• PMPDECloseProcPtr
• PMPDETerminateProcPtr

Printer Module Callbacks

The callback functions described in this section must be implemented by all printer modules.

• GetConnInfoProcPtr
• PMBeginJobProcPtr
• PMCancelJobProcPtr
• PMCreatePrinterBrowserModuleInfoProcPtr
• PMCreatePrinterTicketsProcPtr
• PMCreatePrintingDialogExtensionsPathsProcPtr
• PMEndJobProcPtr
• PMImageAccessProcPtr
• PMInitializeProcPtr
• PMIOCloseProcPtr
• PMIOGetAttributeProcPtr
• PMIOOpenProcPtr
• PMIOReadProcPtr
• PMIOSetAttributeProcPtr
• PMIOStatusProcPtr
• PMIOWriteProcPtr
• PMJobStreamGetNextBandProcPtr
• PMJobStreamGetPosProcPtr
• PMJobStreamOpenProcPtr
• PMJobStreamReadWriteProcPtr
• PMJobStreamSetPosProcPtr
• PMNotificationProcPtr
• PMPrintJobProcPtr
• PMPrintPageProcPtr
• PMTerminateProcPtr

Printer Browser Module Callbacks

The callback functions described in this section must be implemented by all printer browser modules.

• PMCOMAddRefProcPtr
• PMCOMQueryInterfaceProcPtr
• PMCOMReleaseProcPtr
• PMPrBrowserAPIVersionProcPtr
• PMPrBrowserGetLookupSpecProcPtr
• PMPrBrowserGetSelectedPrintersProcPtr
• PMPrBrowserInitializeProcPtr
• PMPrBrowserPrologueProcPtr
• PMPrBrowserResizeProcPtr
• PMPrBrowserSelectionStatusProcPtr
• PMPrBrowserSyncProcPtr
• PMPrBrowserSyncRequestProcPtr
• PMPrBrowserTerminateProcPtr
• PMPrBrowserWorksetPrintersProcPtr

I/O Module Callbacks

The callback functions described in this section must be implemented by all I/O modules.

• PMIOModuleCloseProcPtr
• PMIOModuleGetAttributeProcPtr
• PMIOModuleGetConnectionInfoProcPtr
• PMIOModuleInitializeProcPtr
• PMIOModuleOpenProcPtr
• PMIOModuleReadProcPtr
• PMIOModuleSetAttributeProcPtr
• PMIOModuleStatusProcPtr
• PMIOModuleTerminateProcPtr
• PMIOModuleWriteProcPtr

Callbacks

GetConnInfoProcPtr

typedef OSStatus(* GetConnInfoProcPtr) (
   const void *jobContext,
   CFStringRef *connectionType,
   CFStringRef *pbmPath
);

If you name your function MyGetConnInfoCallback, you would declare it like this:

OSStatus MyGetConnInfoCallback (
   const void *jobContext,
   CFStringRef *connectionType,
   CFStringRef *pbmPath
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMBeginJobProcPtr

typedef OSStatus(* PMBeginJobProcPtr) (
   PMContext printerModuleContext,
   const void *jobContext,
   PMTicketRef jobTicket,
   PMTicketRef *converterSetup
);

If you name your function MyPMBeginJobCallback, you would declare it like this:

OSStatus MyPMBeginJobCallback (
   PMContext printerModuleContext,
   const void *jobContext,
   PMTicketRef jobTicket,
   PMTicketRef *converterSetup
);

PMCancelJobProcPtr

typedef OSStatus(* PMCancelJobProcPtr) (
   PMContext printerModuleContext,
   const void *jobContext
);

If you name your function MyPMCancelJobCallback, you would declare it like this:

OSStatus MyPMCancelJobCallback (
   PMContext printerModuleContext,
   const void *jobContext
);

PMCOMAddRefProcPtr

typedef UInt32(* PMCOMAddRefProcPtr) (
   void *thisPointer
);

If you name your function MyPMCOMAddRefCallback, you would declare it like this:

UInt32 MyPMCOMAddRefCallback (
void *thisPointer
);

PMCOMQueryInterfaceProcPtr

typedef SInt32(* PMCOMQueryInterfaceProcPtr) (
   void *thisPointer,
   CFUUIDBytes iid,
   void **ppv
);

If you name your function MyPMCOMQueryInterfaceCallback, you would declare it like this:

SInt32 MyPMCOMQueryInterfaceCallback (
void *thisPointer,
CFUUIDBytes iid,
void **ppv
);

PMCOMReleaseProcPtr

typedef UInt32(* PMCOMReleaseProcPtr) (
   void *thisPointer
);

If you name your function MyPMCOMReleaseCallback, you would declare it like this:

UInt32 MyPMCOMReleaseCallback (
void *thisPointer
);

PMCreatePrinterBrowserModuleInfoProcPtr

typedef OSStatus(* PMCreatePrinterBrowserModuleInfoProcPtr) (
   CFStringRef connectionType,
   CFArrayRef *printerBrowserInfo
);

If you name your function MyPMCreatePrinterBrowserModuleInfoCallback, you would declare it like this:

OSStatus MyPMCreatePrinterBrowserModuleInfoCallback (
   CFStringRef connectionType,
   CFArrayRef *printerBrowserInfo
);

PMCreatePrinterTicketsProcPtr

typedef OSStatus(* PMCreatePrinterTicketsProcPtr) (
   PMContext printerModuleContext,
   PMTicketRef *printerInfo,
   PMTemplateRef *jobTemplate
);

If you name your function MyPMCreatePrinterTicketsCallback, you would declare it like this:

OSStatus MyPMCreatePrinterTicketsCallback (
   PMContext printerModuleContext,
   PMTicketRef *printerInfo,
   PMTemplateRef *jobTemplate
);

PMCreatePrintingDialogExtensionsPathsProcPtr

typedef OSStatus(* PMCreatePrintingDialogExtensionsPathsProcPtr)  (
   PMContext printerModuleContext,
   CFArrayRef *pdePaths
);

If you name your function MyPMCreatePrintingDialogExtensionsPathsCallback, you would declare it like this:

OSStatus MyPMCreatePrintingDialogExtensionsPathsCallback (
   PMContext printerModuleContext,
   CFArrayRef *pdePaths
);

PMEndJobProcPtr

typedef OSStatus(* PMEndJobProcPtr) (
   PMContext printerModuleContext,
   const void *jobContext
);

If you name your function MyPMEndJobCallback, you would declare it like this:

OSStatus MyPMEndJobCallback (
   PMContext printerModuleContext,
   const void *jobContext
);

PMImageAccessProcPtr

typedef OSStatus(* PMImageAccessProcPtr) (
   PMContext printerModuleContext,
   const void *jobContext,
   CFStringRef grafBase,
   PMDrawingCtx drawingCtx,
   PMImageRef imageRef,
   PMImageRef *outImageRefPtr
);

If you name your function MyPMImageAccessCallback, you would declare it like this:

OSStatus MyPMImageAccessCallback (
   PMContext printerModuleContext,
   const void *jobContext,
   CFStringRef grafBase,
   PMDrawingCtx drawingCtx,
   PMImageRef imageRef,
   PMImageRef *outImageRefPtr
);

PMInitializeProcPtr

typedef OSStatus(* PMInitializeProcPtr) (
   CFDataRef printerAddress,
   const void *jobContext,
   const PMIOProcs *pmIOProcs,
   const PMNotificationProcPtr pmNotificationProc,
   PMContext *printerModuleContext
);

If you name your function MyPMInitializeCallback, you would declare it like this:

OSStatus MyPMInitializeCallback (
   CFDataRef printerAddress,
   const void *jobContext,
   const PMIOProcs *pmIOProcs,
   const PMNotificationProcPtr pmNotificationProc,
   PMContext *printerModuleContext
);

PMIOCloseProcPtr

typedef OSStatus(* PMIOCloseProcPtr) (
   const void *jobContext
);

If you name your function MyPMIOCloseCallback, you would declare it like this:

OSStatus MyPMIOCloseCallback (
   const void *jobContext
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMIOGetAttributeProcPtr

typedef OSStatus(* PMIOGetAttributeProcPtr) (
   const void *jobContext,
   CFStringRef attribute,
   CFTypeRef *result
);

If you name your function MyPMIOGetAttributeCallback, you would declare it like this:

OSStatus MyPMIOGetAttributeCallback (
   const void *jobContext,
   CFStringRef attribute,
   CFTypeRef *result
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMIOModuleCloseProcPtr

typedef OSStatus(* PMIOModuleCloseProcPtr) (
   IOMContext ioModuleContext,
   Boolean abort
);

If you name your function MyCallback, you would declare it like this:

OSStatus MyCallback (
IOMContext ioModuleContext,
Boolean abort
);

PMIOModuleGetAttributeProcPtr

typedef OSStatus(* PMIOModuleGetAttributeProcPtr) (
   IOMContext ioModuleContext,
   CFStringRef attribute,
   CFTypeRef *result
);

If you name your function MyCallback, you would declare it like this:

OSStatus MyCallback (
IOMContext ioModuleContext,
CFStringRef attribute,
CFTypeRef *result
);

PMIOModuleGetConnectionInfoProcPtr

typedef OSStatus(* PMIOModuleGetConnectionInfoProcPtr) (
   CFStringRef *connectionType,
   CFStringRef *pbmPath
);

If you name your function MyCallback, you would declare it like this:

OSStatus MyCallback (
CFStringRef *connectionType,
CFStringRef *pbmPath
);

PMIOModuleInitializeProcPtr

typedef OSStatus(* PMIOModuleInitializeProcPtr) (
   CFDataRef printerAddress,
   IOMContext *ioModuleContextPtr
);

If you name your function MyCallback, you would declare it like this:

OSStatus MyCallback (
CFDataRef printerAddress,
IOMContext *ioModuleContextPtr
);

PMIOModuleOpenProcPtr

typedef OSStatus(* PMIOModuleOpenProcPtr) (
   IOMContext ioModuleContext,
   PMTicketRef jobTicket,
   UInt32 *bufferSize
);

If you name your function MyCallback, you would declare it like this:

OSStatus MyCallback (
IOMContext ioModuleContext,
PMTicketRef jobTicket,
UInt32 *bufferSize
);

PMIOModuleReadProcPtr

typedef OSStatus(* PMIOModuleReadProcPtr) (
   IOMContext ioModuleContext,
   Ptr buffer,
   UInt32 *size,
   Boolean *eoj
);

If you name your function MyCallback, you would declare it like this:

OSStatus MyCallback (
IOMContext ioModuleContext,
Ptr buffer,
UInt32 *size,
Boolean *eoj
);

PMIOModuleSetAttributeProcPtr

typedef OSStatus(* PMIOModuleSetAttributeProcPtr) (
   IOMContext ioModuleContext,
   CFStringRef attribute,
   CFTypeRef data
);

If you name your function MyCallback, you would declare it like this:

OSStatus MyCallback (
IOMContext ioModuleContext,
CFStringRef attribute,
CFTypeRef data
);

PMIOModuleStatusProcPtr

typedef OSStatus(* PMIOModuleStatusProcPtr) (
   IOMContext ioModuleContext,
   CFStringRef *status
);

If you name your function MyCallback, you would declare it like this:

OSStatus MyCallback (
IOMContext ioModuleContext,
CFStringRef *status
);

PMIOModuleTerminateProcPtr

typedef OSStatus(* PMIOModuleTerminateProcPtr) (
   IOMContext *ioModuleContextPtr
);

If you name your function MyCallback, you would declare it like this:

OSStatus MyCallback (
IOMContext *ioModuleContextPtr
);

PMIOModuleWriteProcPtr

typedef OSStatus(* PMIOModuleWriteProcPtr) (
   IOMContext ioModuleContext,
   Ptr buffer,
   UInt32 *size,
   Boolean eoj
);

If you name your function MyCallback, you would declare it like this:

OSStatus MyCallback (
IOMContext ioModuleContext,
Ptr buffer,
UInt32 *size,
Boolean eoj
);

PMIOOpenProcPtr

typedef OSStatus(* PMIOOpenProcPtr) (
   const void *jobContext
);

If you name your function MyPMIOOpenCallback, you would declare it like this:

OSStatus MyPMIOOpenCallback (
   const void *jobContext
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMIOReadProcPtr

typedef OSStatus(* PMIOReadProcPtr) (
   const void *jobContext,
   Ptr buffer,
   UInt32 *size,
   Boolean *eoj
);

If you name your function MyPMIOReadCallback, you would declare it like this:

OSStatus MyPMIOReadCallback (
   const void *jobContext,
   Ptr buffer,
   UInt32 *size,
   Boolean *eoj
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMIOSetAttributeProcPtr

typedef OSStatus(* PMIOSetAttributeProcPtr) (
   const void *jobContext,
   CFStringRef attribute,
   CFTypeRef data
);

If you name your function MyPMIOSetAttributeCallback, you would declare it like this:

OSStatus MyPMIOSetAttributeCallback (
   const void *jobContext,
   CFStringRef attribute,
   CFTypeRef data
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMIOStatusProcPtr

typedef OSStatus(* PMIOStatusProcPtr) (
   const void *jobContext,
   CFStringRef *status
);

If you name your function MyPMIOStatusCallback, you would declare it like this:

OSStatus MyPMIOStatusCallback (
   const void *jobContext,
   CFStringRef *status
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMIOWriteProcPtr

typedef OSStatus(* PMIOWriteProcPtr) (
   const void *jobContext,
   Ptr buffer,
   UInt32 *size,
   Boolean eoj
);

If you name your function MyPMIOWriteCallback, you would declare it like this:

OSStatus MyPMIOWriteCallback (
   const void *jobContext,
   Ptr buffer,
   UInt32 *size,
   Boolean eoj
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMJobStreamGetNextBandProcPtr

typedef OSStatus(* PMJobStreamGetNextBandProcPtr) (
   const void *jobContext,
   PMRasterBand *pmRasterBand
);

If you name your function MyPMJobStreamGetNextBandCallback, you would declare it like this:

OSStatus MyPMJobStreamGetNextBandCallback (
   const void *jobContext,
   PMRasterBand *pmRasterBand
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMJobStreamGetPosProcPtr

typedef OSStatus(* PMJobStreamGetPosProcPtr) (
   const void *jobContext,
   UInt32 *markerPos
);

If you name your function MyPMJobStreamGetPosCallback, you would declare it like this:

OSStatus MyPMJobStreamGetPosCallback (
   const void *jobContext,
   UInt32 *markerPos
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMJobStreamOpenProcPtr

typedef OSStatus(* PMJobStreamOpenProcPtr) (
   const void *jobContext
);

If you name your function MyPMJobStreamOpenCallback, you would declare it like this:

OSStatus MyPMJobStreamOpenCallback (
   const void *jobContext
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMJobStreamReadWriteProcPtr

typedef OSStatus(* PMJobStreamReadWriteProcPtr) (
   const void *jobContext,
   void *buffPtr,
   UInt32 *size
);

If you name your function MyPMJobStreamReadWriteCallback, you would declare it like this:

OSStatus MyPMJobStreamReadWriteCallback (
   const void *jobContext,
   void *buffPtr,
   UInt32 *size
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMJobStreamSetPosProcPtr

typedef OSStatus(* PMJobStreamSetPosProcPtr) (
   const void *jobContext,
   SInt16 posMode,
   UInt32 markerPos
);

If you name your function MyPMJobStreamSetPosCallback, you would declare it like this:

OSStatus MyPMJobStreamSetPosCallback (
   const void *jobContext,
   SInt16 posMode,
   UInt32 markerPos
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMNotificationProcPtr

typedef OSStatus(* PMNotificationProcPtr) (
   const void *jobContext,
   CFDictionaryRef notificationDict,
   CFDictionaryRef *notificationReplyDict
);

If you name your function MyPMNotificationCallback, you would declare it like this:

OSStatus MyPMNotificationCallback (
   const void *jobContext,
   CFDictionaryRef notificationDict,
   CFDictionaryRef *notificationReplyDict
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterModuleDeprecated.h

PMPDECloseProcPtr

typedef OSStatus(* PMPDECloseProcPtr) (
   PMPDEContext context
);

If you name your function MyPMPDEClose, you would declare it like this:

OSStatus MyPMPDEClose (
   PMPDEContext context
);

Parameters

context

A pointer to a custom data structure that contains state information shared among the functions in a printing dialog extension. This is the same context defined by the prologue function—see PMPDEPrologueProcPtr.

Return Value

A result code.

Discussion

If your pane is visible, your close function is called when the user

• switches to another pane (including the Summary pane)

• changes printers

• dismisses the dialog by clicking Preview, Print, or Save

If your pane is visible and the user cancels the dialog, your close function is not called. The close function is not required to provide any services, and does not return any information to the caller.

PMPDEGetSummaryTextProcPtr

typedef OSStatus(* PMPDEGetSummaryTextProcPtr) (
   PMPDEContext context,
   CFArrayRef *titleArray,
   CFArrayRef *summaryArray
);

If you name your function MyPMPDEGetSummary, you would declare it like this:

OSStatus MyPMPDEGetSummary (
   PMPDEContext context,
   CFArrayRef *titleArray,
   CFArrayRef *summaryArray
);

Parameters

context

A pointer to a custom data structure that contains state information shared among the functions in a printing dialog extension. This is the same context defined by the prologue function—see PMPDEPrologueProcPtr.

titleArray

A pointer to an array of strings that contain brief, localized descriptions of the settings in your user interface. The array and strings must be Core Foundation types.

On entry, the array is undefined. Before returning, you should assign an array of type CFArrayRef. The printing system assumes ownership of the array and is responsible for releasing it.

If your printing dialog extension does not supply summary text—or your user interface does not have any settings—you should assign NULL before returning.

summaryArray

A pointer to an array of strings that contain brief, localized descriptions of the current values of the settings in your user interface. The array and strings must be Core Foundation types.

On entry, the array is undefined. Before returning, you should assign an array of type CFArrayRef. The printing system assumes ownership of the array and is responsible for releasing it.

If your printing dialog extension does not supply summary text—or your user interface does not have any settings—you should assign NULL before returning.

Return Value

A result code.

Discussion

Whenever a user switches to the Summary pane in a printing dialog, the printing system calls the summary function of each active printing dialog extension.

The printing system expects titleArray and summaryArray to be in a one-to-one correspondence. Here’s a formal description of what that means. Your user interface has associated with it n pairs of strings, each pair consisting of textual descriptions of a single setting and its current value. The two arrays are in a one-to-one correspondence if for all k from 0 to n-1, the strings titleArray[k] and summaryArray[k] form a valid pair.

PMPDEInitializeProcPtr

typedef OSStatus(* PMPDEInitializeProcPtr) (
   PMPDEContext context,
   PMPDEFlags *flags,
   PMPDERef ref,
   ControlRef embedderUserPane,
   PMPrintSession printSession
);

If you name your function MyPMPDEInitialize, you would declare it like this:

OSStatus MyPMPDEInitialize (
   PMPDEContext context,
   PMPDEFlags *flags,
   PMPDERef ref,
   ControlRef embedderUserPane,
   PMPrintSession printSession
);

Parameters

context

A pointer to a custom data structure that contains state information shared among the functions in a printing dialog extension. This is the same context defined by the prologue function—see PMPDEPrologueProcPtr.

flags

A pointer to an integer flag that provides information about the capabilities of your printing dialog extension. On entry, the flag is undefined. Before returning, your initialization function should assign a valid feature request flag. For information about the defined flags, see “PDE Feature Flags.”

ref

Reserved for future use.

embedderUserPane

The control provided by the printing system to host the user interface of your printing dialog extension. This parameter is a standard Carbon user pane—a root control into which your printing dialog extension embeds the various controls and other elements in your user interface.

Before returning, your initialization function should create static user interface elements—such as controls, icons, and images—and embed them in the user pane provided by the printing system. You should position the user interface elements with respect to the coordinate system of the dialog window, and make them visible. You should also set the initial values of your controls, based on either your default settings or previous settings saved by the user. Do not modify the user pane itself.

If any user interface elements require special handling, you can install Carbon event handlers for them. For example, the Duplex pane in the Print dialog uses an event handler to enable or disable the two binding selection buttons, based on the current checkbox setting.

Do not do any custom drawing at this time, since the user pane is still invisible. If the user decides to display your user interface, the printing system makes it visible and the Control Manager automatically draws your static elements.

printSession

A pointer to a print session object. This is the same print session created by the application prior to displaying the dialog. You can use this parameter to gain access to one of the specialized printing tickets, such as page format or print settings.

Return Value

A result code.

Discussion

If the printing system calls your initialization function, you can safely assume that your prologue function was called first.

If your initialization function returns a nonzero status code, the printing system does not call your summary function.

PMPDEOpenProcPtr

typedef OSStatus(* PMPDEOpenProcPtr) (
   PMPDEContext context
);

If you name your function MyPMPDEOpen, you would declare it like this:

OSStatus MyPMPDEOpen (
   PMPDEContext context
);

Parameters

context

A pointer to a custom data structure that contains state information shared among the functions in a printing dialog extension. This is the same context defined by the prologue function—see PMPDEPrologueProcPtr.

Return Value

A result code.

Discussion

If the user selects your pane for display in the dialog, your open function is called immediately before the pane is made visible.

An open function is not required to provide any services, and does not return any information to the caller.

PMPDEPrologueProcPtr

typedef OSStatus(* PMPDEPrologueProcPtr) (
   PMPDEContext *context,
   OSType *creator,
   CFStringRef *userOptionKind,
   CFStringRef *title,
   UInt32 *maxH,
   UInt32 *maxV
);

If you name your function MyPMPDEPrologue, you would declare it like this:

OSStatus MyPMPDEPrologue (
   PMPDEContext *context,
   OSType *creator,
   CFStringRef *userOptionKind,
   CFStringRef *title,
   UInt32 *maxH,
   UInt32 *maxV
);

Parameters

context

A pointer to a custom data structure that contains state information shared among the functions in a printing dialog extension. On entry, the caller’s PMPDEContext variable is undefined. Before returning, your prologue function should assign a new context, or NULL to indicate that no context exists.

The printing system does not assume ownership of memory used for a context, so your printing dialog extension should release it when it is no longer needed. Typically this is done in your termination function.

creator

Reserved for future use.

userOptionKind

A pointer to a string that contains a unique identifier for the pane implemented by your printing dialog extension. The printing system uses this identifier to determine whether your printing dialog extension implements an Apple-defined pane, or a custom pane defined by you. On entry, the string is undefined. Before returning, your prologue function should assign the appropriate identifier.

If your printing dialog extension implements or overrides an Apple-defined pane, assign one of the identifiers listed in “PDE Pane Kind Identifiers.” If your printing dialog extension implements a custom pane, assign a Core Foundation string that contains your own custom identifier.

By convention, a custom identifier takes the form <domain>.print.pde.<signature>, where <domain> is your vendor-specific domain and <signature> is a short name or signature for the pane you are implementing.

The printing system does not assume ownership of this string, so your printing dialog extension should release it when it is no longer needed.

title

A pointer to a string that contains the localized title of the pane implemented by your printing dialog extension. The printing system displays this title in two places—the pane selection pop-up menu and the Summary pane.

On entry, the string is undefined. Before returning, your prologue function should assign a Core Foundation string containing the localized title.

If you are implementing an Apple-defined pane, the printing system may ignore your localized title and use an Apple-defined title instead.

Your printing dialog extension retains ownership of the string, and you should release it when it is no longer needed. Typically this is done in your terminate function.

maxH

A pointer to a value that represents the maximum number of horizontal pixels your user interface requires. When your user interface is made visible, the printing system might use this value to adjust the width of the dialog.

On entry, the value is undefined. Before returning, your prologue function should assign the maximum horizontal extent of your user interface in pixels.

maxV

A pointer to a value that represents the maximum number of vertical pixels your user interface requires. When your user interface is made visible, the printing system uses this value to adjust the height of the dialog.

On entry, the value is undefined. Before returning, your prologue function should assign the maximum vertical extent of your user interface in pixels.

Return Value

A result code.

Discussion

When the printing system displays a printing dialog, it calls the prologue function for each registered dialog extension.

If your prologue function returns a nonzero status code, the printing system does not include your pane in the dialog, and does not call your terminate function. In this circumstance, your prologue function should release any allocated memory or resources before exiting.

While the dialog is open, if some user action causes the printing system to scan for plug-ins again—choosing a different printer, for example—then your prologue function is called again.

PMPDESyncProcPtr

typedef OSStatus(* PMPDESyncProcPtr) (
   PMPDEContext context,
   PMPrintSession printSession,
   Boolean reinitializePlugIn
);

If you name your function MyPMPDESync, you would declare it like this:

OSStatus MyPMPDESync (
   PMPDEContext context,
   PMPrintSession printSession,
   Boolean reinitializePlugIn
);

Parameters

context

A pointer to a custom data structure that contains state information shared among the functions in a printing dialog extension. This is the same context defined by the prologue function—see PMPDEPrologueProcPtr.

printSession

A pointer to a printing session object. Your synchronization function should use this parameter to gain access to the job ticket its uses to save user interface settings. These settings are stored as extended data in either the print settings ticket (for Print dialog extensions) or the page format ticket (for Page Setup dialog extensions).

reinitializePlugIn

A Boolean value that indicates which synchronization operation to perform. If the value is true, you should locate and retrieve the ticket settings and use them to update your user interface settings. If the value is false, you should use your current user interface settings to update the ticket settings.

Return Value

A result code.

Discussion

The printing system calls your synchronization function at certain times—in response to user actions—to update either the user interface or the ticket. Also, your printing dialog extension can call your synchronization function directly. For example, your initialization function may need to synchronize your user interface to its default settings.

Here are some calling conditions where the reinitializePlugin parameter might be true:

• Your own intialization function wants to synchronize your user interface to its default settings.

• The printing system wants you to initialize your user interface from the print settings ticket associated with a different printer.

Here are some calling conditions where the reinitializePlugin parameter might be false:

• Your user interface is visible, and the user tries to switch to another pane.

• The user saves the current dialog settings.

• The user clicks the Preview button or the Print button.

You may want to check the validity of the current settings in your pane at this time, to avoid recording invalid or inconsistent settings in a job ticket. To prevent the user from switching to another pane until a problem is corrected, return the result code kPMDontSwitchPDEError.

PMPDETerminateProcPtr

typedef OSStatus(* PMPDETerminateProcPtr) (
   PMPDEContext context,
   OSStatus status
);

If you name your function MyPMPDETerminate, you would declare it like this:

OSStatus MyPMPDETerminate (
   PMPDEContext context,
   OSStatus status
);

Parameters

context

A pointer to a custom data structure that contains state information shared among the functions in a printing dialog extension. This is the same context defined by the prologue function—see PMPDEPrologueProcPtr.

status

Reserved for future use to indicate the conditions under which the user dismissed the dialog.

Return Value

A result code.

Discussion

The printing system calls your termination function when the printing system decides to tear down or rebuild the dialog, or when your pane is no longer needed.

Unless your prologue function returns a nonzero status code, your termination function is always called when the user dismisses the dialog.

Your termination function is also called if your printing feature is no longer relevant—for example, if your feature applies only to postscript printers and the user switches to a raster printer from within the dialog.

Your termination function should release Core Foundation objects, deallocate your context block, and perform any other actions necessary before your user interface is reinitialized or unloaded.

PMPluginGetAPIVersionProcPtr

typedef OSStatus(* PMPluginGetAPIVersionProcPtr) (
   PMPlugInHeaderInterface *obj,
   PMPlugInAPIVersion *versionPtr
);

If you name your function MyPMPluginGetAPIVersion, you would declare it like this:

OSStatus MyPMPluginGetAPIVersion (
   PMPlugInHeaderInterface *obj,
   PMPlugInAPIVersion *versionPtr
);

Parameters

obj

A pointer to a generic instance of a plug-in interface. You may ignore this parameter, as it isn’t useful here.

versionPtr

A pointer to a data structure supplied by the caller for version information about your printing plug-in. Before returning, you should provide the correct version information for your plug-in by assigning version constants to the fields in this structure.

Return Value

A result code.

PMPluginReleaseProcPtr

Defines a pointer to the retain function in a printing plug-in interface. Your custom retain function increments the reference count of an instance of one of these interfaces.

typedef OSStatus (*PMPluginReleaseProcPtr) (
   PMPlugInHeaderInterface **objPtr
);

If you name your function MyPMPluginRelease, you would declare it like this:

OSStatus MyPMPluginRelease (
   PMPlugInHeaderInterface **objPtr
);

Parameters

objPtr

The address of a pointer to a generic instance of a plug-in interface. Before returning, your retain function should decrement the reference count of the instance, and assign NULL to the pointer whose address is provided by this parameter. If the reference count reaches zero, you should delete the instance and any related storage.

Return Value

A result code.

PMPluginRetainProcPtr

typedef OSStatus (*PMPluginRetainProcPtr) (
   PMPlugInHeaderInterface *obj
);

If you name your function MyPMPluginRetain, you would declare it like this:

OSStatus MyPMPluginRetain (
   PMPlugInHeaderInterface *obj
);

Parameters

obj

A pointer to a generic instance of a plug-in interface. Before returning, your retain function should increment the reference count of the instance.

Return Value

A result code.

PMPrBrowserAPIVersionProcPtr

typedef UInt32(* PMPrBrowserAPIVersionProcPtr) ();

If you name your function MyPMPrBrowserAPIVersionCallback, you would declare it like this:

UInt32 MyPMPrBrowserAPIVersionCallback ();

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrBrowserGetLookupSpecProcPtr

typedef OSStatus(* PMPrBrowserGetLookupSpecProcPtr) (
   PMPrBrowserRef ref,
   UInt32 specIndex,
   CFDictionaryRef *lookupSpec
);

If you name your function MyPMPrBrowserGetLookupSpecCallback, you would declare it like this:

OSStatus MyPMPrBrowserGetLookupSpecCallback) (
   PMPrBrowserRef ref,
   UInt32 specIndex,
   CFDictionaryRef *lookupSpec
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrBrowserGetSelectedPrintersProcPtr

typedef OSStatus(* PMPrBrowserGetSelectedPrintersProcPtr) (
   PMPrBrowserContext context,
   CFArrayRef *printers
);

If you name your function MyPMPrBrowserGetSelectedPrintersCallback, you would declare it like this:

OSStatus MyPMPrBrowserGetSelectedPrintersCallback (
PMPrBrowserContext context,
CFArrayRef *printers
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrBrowserInitializeProcPtr

typedef OSStatus(* PMPrBrowserInitializeProcPtr) (
   PMPrBrowserContext context,
   PMPrBrowserRef ref,
   PMPrBrowserCallbacks *callbacks,
   ControlRef pbUserPaneCtlHdl,
   UInt32 numLookupSpecs
);

If you name your function MyPMPrBrowserInitializeCallback, you would declare it like this:

OSStatus MyPMPrBrowserInitializeCallback (
PMPrBrowserContext context,
PMPrBrowserRef ref,
PMPrBrowserCallbacks *callbacks,
ControlRef pbUserPaneCtlHdl,
UInt32 numLookupSpecs
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrBrowserPrologueProcPtr

typedef OSStatus(* PMPrBrowserPrologueProcPtr) (
   PMPrBrowserContext *context,
   PMPrBrowserFlags prologueFlags,
   CFStringRef *title,
   UInt32 *minH,
   UInt32 *minV,
   UInt32 *maxH,
   UInt32 *maxV
);

If you name your function MyPMPrBrowserPrologueCallback, you would declare it like this:

OSStatus MyPMPrBrowserPrologueCallback (
PMPrBrowserContext *context,
PMPrBrowserFlags prologueFlags,
CFStringRef *title,
UInt32 *minH,
UInt32 *minV,
UInt32 *maxH,
UInt32 *maxV
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrBrowserResizeProcPtr

typedef OSStatus(* PMPrBrowserResizeProcPtr) (
   PMPrBrowserContext context,
   const Rect *frameRect
);

If you name your function MyPMPrBrowserResizeCallback, you would declare it like this:

OSStatus MyPMPrBrowserResizeCallback (
PMPrBrowserContext context,
const Rect *frameRect
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrBrowserSelectionStatusProcPtr

typedef OSStatus(* PMPrBrowserSelectionStatusProcPtr) (
   PMPrBrowserRef ref,
   Boolean selected,
   Boolean addNow
);

If you name your function MyPMPrBrowserSelectionStatusCallback, you would declare it like this:

OSStatus MyPMPrBrowserSelectionStatusCallback (
PMPrBrowserRef ref,
Boolean selected,
Boolean addNow
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrBrowserSyncProcPtr

typedef OSStatus(* PMPrBrowserSyncProcPtr) (
   PMPrBrowserContext context
);

If you name your function MyPMPrBrowserSyncCallback, you would declare it like this:

OSStatus MyPMPrBrowserSyncCallback (
PMPrBrowserContext context
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrBrowserSyncRequestProcPtr

typedef OSStatus(* PMPrBrowserSyncRequestProcPtr) (
   PMPrBrowserRef ref
);

If you name your function MyPMPrBrowserSyncRequestCallback, you would declare it like this:

OSStatus MyPMPrBrowserSyncRequestCallback (
PMPrBrowserRef ref
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrBrowserTerminateProcPtr

typedef OSStatus(* PMPrBrowserTerminateProcPtr) (
   PMPrBrowserContext context,
   OSStatus status
);

If you name your function MyPMPrBrowserTerminateCallback, you would declare it like this:

OSStatus MyPMPrBrowserTerminateCallback (
PMPrBrowserContext context,
OSStatus status
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrBrowserWorksetPrintersProcPtr

typedef OSStatus(* PMPrBrowserWorksetPrintersProcPtr) (
   PMPrBrowserContext context,
   CFArrayRef printers
);

If you name your function MyPMPrBrowserWorksetPrintersCallback, you would declare it like this:

OSStatus MyPMPrBrowserWorksetPrintersCallback (
PMPrBrowserContext context,
CFArrayRef printers
);

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

Declared In

PMPrinterBrowsers.h

PMPrintJobProcPtr

typedef OSStatus(* PMPrintJobProcPtr) (
   PMContext printerModuleContext,
   const void *jobContext,
   PMTicketRef jobTicket,
   const PMJobStreamProcs *inDataProcs
);

If you name your function MyPMPrintJobCallback, you would declare it like this:

OSStatus MyPMPrintJobCallback (
   PMContext printerModuleContext,
   const void *jobContext,
   PMTicketRef jobTicket,
   const PMJobStreamProcs *inDataProcs
);

PMPrintPageProcPtr

typedef OSStatus(* PMPrintPageProcPtr) (
   PMContext printerModuleContext,
   const void *jobContext,
   PMTicketRef jobTicket,
   const PMJobStreamGetNextBandProcPtr pmJobStreamGetNextBandProc
);

If you name your function MyPMPrintPageCallback, you would declare it like this:

OSStatus MyPMPrintPageCallback (
   PMContext printerModuleContext,
   const void *jobContext,
   PMTicketRef jobTicket,
   const PMJobStreamGetNextBandProcPtr pmJobStreamGetNextBandProc
);

PMTerminateProcPtr

typedef OSStatus(* PMTerminateProcPtr) (
   PMContext *printerModuleContext,
   const void *jobContext
);

If you name your function MyPMTerminateCallback, you would declare it like this:

OSStatus MyPMTerminateCallback (
   PMContext *printerModuleContext,
   const void *jobContext
);

Data Types

Printing Plug-in Data Types

PMPlugInHeader

Defines the table of callback functions in the printing plug-in interface.

struct PMPlugInHeader
   {
   OSStatus (*Retain) (
   PMPlugInHeaderInterface *obj
   );
   
   OSStatus (*Release) (
   PMPlugInHeaderInterface **objPtr
   );
   
   OSStatus (*GetAPIVersion) (
   PMPlugInHeaderInterface *obj,
   PMPlugInAPIVersion *versionPtr
   );
};
typedef struct PMPlugInHeader PMPlugInHeader;

Fields

Retain

A pointer to a function that satisfies the requirements for a printing plug-in retain function, as described in PMPluginRetainProcPtr.

Release

A pointer to a function that satisfies the requirements for a printing plug-in release function, as described in PMPluginReleaseProcPtr.

GetAPIVersion

A pointer to a function that satisfies the requirements for a printing plug-in version function, as described in PMPluginGetAPIVersionProcPtr.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

PMPluginHeader.h

PMPlugInHeaderInterface

Defines a generic instance of the PMPlugInHeader interface—the printing system passes a parameter of this type when calling the three interface functions.

struct PMPlugInHeaderInterface {
   const PMPlugInHeader *vtable;
};
typedef struct PMPlugInHeaderInterface PMPlugInHeaderInterface;

Fields

vtable

A pointer to the function table for an implementation of the PMPlugInHeader interface.

Discussion

When the printing system calls one of the three functions in the PMPlugInHeader interface, a pointer to this generic data type is supplied as a parameter. It’s really the address of the plug-in instance supplied by your query interface function (see Core Foundation Plug-in Services).

To gain access to your instance data—including the field that holds the reference count—you need to cast this pointer to the actual instance type defined in your plug-in.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

PMPluginHeader.h

PMPlugInAPIVersion

Contains PMPlugInHeader interface version information that printing plug-ins must provide to the printing system.

struct PMPlugInAPIVersion {
   UInt32 buildVersionMajor;
   UInt32 buildVersionMinor;
   UInt32 baseVersionMajor;
   UInt32 baseVersionMinor;
};

Fields

buildVersionMajor

An integer value that specifies the major component of the API version with which the plug-in was compiled.

buildVersionMinor

An integer value that specifies the minor component of the API version with which the plug-in was compiled.

baseVersionMajor

An integer value that specifies the major component of the base API version with which this plug-in is forward compatible.

baseVersionMinor

An integer value that specifies the minor component of the base API version with which this plug-in is forward compatible.

Printing Dialog Extension Data Types

PlugInIntfVTable

Defines the table of callback functions in the printing dialog extension plug-in interface.

struct PlugInIntfVTable
   {
   PMPlugInHeader plugInHeader;
   
   OSStatus (*Prologue) (
   PMPDEContext *context,
   OSType *creator,
   CFStringRef *userOptionKind,
   CFStringRef *title,
   UInt32 *maxH,
   UInt32 *maxV
   );
   
   OSStatus (*Initialize) (
   PMPDEContext context,
   PMPDEFlags *flags,
   PMPDERef ref,
   ControlRef embedderUserPane,