/*
File: PMPrinterModule.h
Contains: Mac OS X Printing Manager Printer Module Interfaces.
Version: QuickTime 7.3
Copyright: (c) 2007 (c) 1999-2001 by Apple Computer, Inc., all rights reserved
Bugs?: For bug reports, consult the following page on
the World Wide Web:
http://developer.apple.com/bugreporter/
*/
#ifndef __CFSTRING__
#include <CFString.h>
#endif
#ifndef __PMTICKET__
#include <PMTicket.h>
#endif
#ifndef __PMPLUGINHEADER__
#include <PMPluginHeader.h>
#endif
#ifndef __PMERRORS__
#include <PMErrors.h>
#endif
#ifndef __PMRASTER__
#include <PMRaster.h>
#endif
/* context ID for PM Modules */
#if PRAGMA_ONCE
#pragma once
#endif
#ifdef __cplusplus
extern "C" {
#endif
#if PRAGMA_IMPORT
#pragma import on
#endif
#if PRAGMA_STRUCT_ALIGN
#pragma options align=mac68k
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(push, 2)
#elif PRAGMA_STRUCT_PACK
#pragma pack(2)
#endif
typedef struct OpaquePMContext* PMContext;
/* Opaque types for image access: */
typedef struct OpaquePMDrawingCtx* PMDrawingCtx;
typedef struct OpaquePMImageRef* PMImageRef;
/* Type ID, interface ID for the IOM CFPlugin */
#define kPModuleTypeIDStr "5D69ED5E-D5B5-11D3-9EFF-00050209D9C1"
#define kPModuleIntfIDStr "5EDEC4FA-D5B5-11D3-AAF2-00050209D9C1"
/* PM API version numbers (see PMPluginHeader.h for the meaning of these defintions) */
enum {
kPMBuildVersionMajor = 1,
kPMBuildVersionMinor = 0,
kPMBaseVersionMajor = 1,
kPMBaseVersionMinor = 0
};
/*
Keys for the printer browser specification dictionary. This CFDictionary,
created by the printer module, provides a printer browser module with the
information it needs to browse for a given type of printer over its
connection type, and to display it in PrintCenter's Browser Window.
kPMPrinterBrowserKindKey corresponds to a CFStringRef to a human-readable
printer type string that can be displayed in the browser view. For a printer
driven by Apple's PostScript printer module over an AppleTalk connection,
this would be the string "PostScript printer".
kPMPrinterBrowserInfoKey corresponds to a CFTypeRef to connection-specific
information used to look up a particular kind of printer over a given IO
connection. A PostScript printer module supporting AppleTalk might specify
the NBP lookup string "LaserWriter".
kPMPrinterBrowserIconKey corresponds to a CFDataRef to the icon family data
for the printer icon to be displayed in the browser view. The family data
are entirely contained within the CFDataRef; i.e., it is *not* a handle.
kPMPrinterBrowserDeviceIDKey corresponds to a CFStringRef to a USB/Firewire
IEEE-1284 DeviceID string. e.g., "COMMAND SET: PostScript;" or
"MFG: Hewlett-Packard; MDL: DeskJet 935C;"
*/
#define kPMPrinterBrowserKindKey CFSTR("Printer Browser Kind")
#define kPMPrinterBrowserInfoKey CFSTR("Printer Browser Info")
#define kPMPrinterBrowserIconsKey CFSTR("Printer Browser Icons")
#define kPMPrinterBrowserDeviceIDKey CFSTR("Printer Browser DeviceID")
enum {
kPMBrowserInfoNumValues = 4
};
/* Status and Error notification: */
/*
* PMNotificationProcPtr
*
* Discussion:
* A callback routine used for reporting printing status and errors
* during a print job Event is constructed with known keys defined
* below and passed to the printing manager in notificationDict
* notificationReplyDict is used for blocking recoverable errors to
* indicate user action
*/
typedef CALLBACK_API_C( OSStatus , PMNotificationProcPtr )(const void *jobContext, CFDictionaryRef notificationDict, CFDictionaryRef *notificationReplyDict);
/*
* Discussion:
* Status and error event codes and keys reported by the printer
* module (used in PMNotificationProc)
*/
enum {
/*
* non-error printer status
*/
kPMEventPrinterStatus = 4000,
/*
* a fatal printing error has occurred. The Printer Module MUST stop
* printing and return immediately after sending this event.
*/
kPMEventErrorOccurred = 4001,
/*
* an auto-recoverable error occurred. The PM SHOULD keep trying to
* print the job without waiting for any user action. If the PM
* detects that the condition is cleared, it MUST send a
* kPMEventRecoverableErrorCleared event, otherwise the condition
* alert will not get cleared
*/
kPMEventRecoverableErrorOccurred = 4002,
/*
* auto-recoverable error has been cleared, the job is continued
* automatically and without user intervention. This event causes
* the condition alert to close and the job state to change to
* "printing".
*/
kPMEventRecoverableErrorCleared = 4003
};
/* Event keys used in notification dictionaries */
#define kPMEventCodeKey CFSTR("com.apple.printing.EventCode")
/* CFNumber (SInt32) containing the event code (above) */
#define kPMErrorCodeKey CFSTR("com.apple.printing.ErrorCode")
/* CFNumber (SInt32) containing the error code (i.e., OSStatus) */
#define kPMErrorExplanationKey CFSTR("com.apple.printing.ErrorExplanation")
/* CFString containing the text that shows up as bold text in the error/status alert */
#define kPMErrorTextKey CFSTR("com.apple.printing.ErrorText")
/* CFString containing the text that shows up as regular text in the error/status alert */
#define kPMEventContextKey CFSTR("com.apple.printing.EventContext")
/* CFNumber (SInt32) containing a context value. Used primarily to match a "cleared error" event with a prior "recoverable error" event */
/* prototypes for callback routines used for accessing print data */
typedef CALLBACK_API_C( OSStatus , PMJobStreamOpenProcPtr )(const void * jobContext);
typedef CALLBACK_API_C( OSStatus , PMJobStreamReadWriteProcPtr )(const void *jobContext, void *buffPtr, UInt32 *size);
typedef CALLBACK_API_C( OSStatus , PMJobStreamGetPosProcPtr )(const void *jobContext, UInt32 *markerPos);
typedef CALLBACK_API_C( OSStatus , PMJobStreamSetPosProcPtr )(const void *jobContext, SInt16 posMode, UInt32 markerPos);
typedef CALLBACK_API_C( OSStatus , PMJobStreamGetNextBandProcPtr )(const void *jobContext, PMRasterBand *pmRasterBand);
/* the printing manager maintains this struct of callback procs for printer module data access */
struct PMJobStreamProcs {
CFIndex version;
PMJobStreamOpenProcPtr PMJobStreamOpenProc;
PMJobStreamReadWriteProcPtr PMJobStreamReadProc;
PMJobStreamReadWriteProcPtr PMJobStreamWriteProc;
PMJobStreamGetPosProcPtr PMJobStreamGetPosProc;
PMJobStreamSetPosProcPtr PMJobStreamSetPosProc;
PMJobStreamGetPosProcPtr PMJobStreamGetEOFProc;
};
typedef struct PMJobStreamProcs PMJobStreamProcs;
/* prototypes for callback routines used for communication with the device/connection */
typedef CALLBACK_API_C( OSStatus , GetConnInfoProcPtr )(const void *jobContext, CFStringRef *connectionType, CFStringRef *pbmPath);
typedef CALLBACK_API_C( OSStatus , PMIOOpenProcPtr )(const void * jobContext);
typedef CALLBACK_API_C( OSStatus , PMIOReadProcPtr )(const void *jobContext, Ptr buffer, UInt32 *size, Boolean *eoj);
typedef CALLBACK_API_C( OSStatus , PMIOWriteProcPtr )(const void *jobContext, Ptr buffer, UInt32 *size, Boolean eoj);
typedef CALLBACK_API_C( OSStatus , PMIOStatusProcPtr )(const void *jobContext, CFStringRef *status);
typedef CALLBACK_API_C( OSStatus , PMIOGetAttributeProcPtr )(const void *jobContext, CFStringRef attribute, CFTypeRef *result);
typedef CALLBACK_API_C( OSStatus , PMIOSetAttributeProcPtr )(const void *jobContext, CFStringRef attribute, CFTypeRef data);
typedef CALLBACK_API_C( OSStatus , PMIOCloseProcPtr )(const void * jobContext);
/*
* PMIOProcs
*
* Discussion:
* The printing manager maintains this struct of callback procs for
* printer module communication with the device
*/
struct PMIOProcs {
CFIndex version;
/*
* Get connection type string and Printer Browser Module path
*/
GetConnInfoProcPtr GetConnInfoProc;
/*
* Open connection with target printer
*/
PMIOOpenProcPtr PMIOOpenProc;
/*
* Read data from printer
*/
PMIOReadProcPtr PMIOReadProc;
/*
* Write data to printer. Data is not buffered no matter how small
* the buffer is. Therefore, it is recommended that the PM do its own
* buffering before this call is made.
*/
PMIOWriteProcPtr PMIOWriteProc;
/*
* Get status from the printer if any
*/
PMIOStatusProcPtr PMIOStatusProc;
/*
* Get the value for a particular IOM attribute (see PMIOModule.h for
* a list of attributes)
*/
PMIOGetAttributeProcPtr PMIOGetAttributeProc;
/*
* Set a value for a particular IOM attribute (see PMIOModule.h for a
* list of attributes)
*/
PMIOSetAttributeProcPtr PMIOSetAttributeProc;
/*
* Close connection with printer.
*/
PMIOCloseProcPtr PMIOCloseProc;
};
typedef struct PMIOProcs PMIOProcs;
typedef CALLBACK_API_C( OSStatus , PMCreatePrinterBrowserModuleInfoProcPtr )(CFStringRef connectionType, CFArrayRef *printerBrowserInfo);
typedef CALLBACK_API_C( OSStatus , PMInitializeProcPtr )(CFDataRef printerAddress, const void *jobContext, const PMIOProcs *pmIOProcs, PMNotificationProcPtr pmNotificationProc, PMContext *printerModuleContext);
typedef CALLBACK_API_C( OSStatus , PMCreatePrintingDialogExtensionsPathsProcPtr )(PMContext printerModuleContext, CFArrayRef *pdePaths);
typedef CALLBACK_API_C( OSStatus , PMCreatePrinterTicketsProcPtr )(PMContext printerModuleContext, PMTicketRef *printerInfo, PMTemplateRef *jobTemplate);
typedef CALLBACK_API_C( OSStatus , PMBeginJobProcPtr )(PMContext printerModuleContext, const void *jobContext, PMTicketRef jobTicket, PMTicketRef *converterSetup);
typedef CALLBACK_API_C( OSStatus , PMPrintJobProcPtr )(PMContext printerModuleContext, const void *jobContext, PMTicketRef jobTicket, const PMJobStreamProcs *inDataProcs);
typedef CALLBACK_API_C( OSStatus , PMPrintPageProcPtr )(PMContext printerModuleContext, const void *jobContext, PMTicketRef jobTicket, PMJobStreamGetNextBandProcPtr pmJobStreamGetNextBandProc);
typedef CALLBACK_API_C( OSStatus , PMImageAccessProcPtr )(PMContext printerModuleContext, const void *jobContext, CFStringRef grafBase, PMDrawingCtx drawingCtx, PMImageRef imageRef, PMImageRef *outImageRefPtr);
typedef CALLBACK_API_C( OSStatus , PMCancelJobProcPtr )(PMContext printerModuleContext, const void *jobContext);
typedef CALLBACK_API_C( OSStatus , PMEndJobProcPtr )(PMContext printerModuleContext, const void *jobContext);
typedef CALLBACK_API_C( OSStatus , PMTerminateProcPtr )(PMContext *printerModuleContext, const void *jobContext);
/*
* PMProcs
*
* Discussion:
* Contains the function pointers required to be exported by a
* Printer Module.
*/
struct PMProcs {
/*
* The plugin header is required with all plugins and must proceed
* object's layout.
*/
PMPlugInHeader pluginHeader;
/*
* For a given connection type in 'connectionType', returns a ticket
* containing printer browser information about the supported
* printers that can be browsed for on that connection. If the
* connection is not supported by the Printer Module,
* kPMUnsupportedConnection error is returned.
*/
PMCreatePrinterBrowserModuleInfoProcPtr CreatePrinterBrowserModuleInfo;
/*
* Create a new instance of the Printer Module and place it's
* reference in 'printerModuleContext'. Few input parameters are
* passed via this API that the PM should store in its local context
* block for use during the session; such as: printerAddress,
* jobContext (used in callbacks), pmIOProcs (used for communicating
* with the device, and pmNotificationProc (used for reporting status
* and errors).
*/
PMInitializeProcPtr Initialize;
/*
* Return one or more paths of this Printer Module's Print Dialog
* Extension(s) relative to base path /Library/Printers/
*/
PMCreatePrintingDialogExtensionsPathsProcPtr CreatePrintingDialogExtensionsPaths;
/*
* Returns printer module's template and printerinfo tickets to the
* caller. A PrinterInfo ticket holds capability and product ID
* information whereas a Template holds range and default information
* about various print settings
*/
PMCreatePrinterTicketsProcPtr CreatePrinterTickets;
/*
* Called by the Printing Manager to initiate a job. This function is
* intended as a "setup" function, so all the information needed to
* set up for printing is supplied: jobTicket has the control
* parameters for this job, as defined by the application and user;
* converterSetp allows the PM to setup a converter via standard
* ticket tags.
*/
PMBeginJobProcPtr BeginJob;
/*
* Begin sending print data to the printer. The Printing Manager
* calls this API when page boundaries in the job can not be
* determined (i.e PM specific format). inDataProcs contains
* callbacks to access the print data; see PMJobStreamProcs
* definitions above for more info on the callback routines.
*/
PMPrintJobProcPtr PrintJob;
/*
* Send only a specific page to the printer. The PM needs to process
* the data and make it ready for the printer hardware.
* PMJobStreamGetNextBandProc is a callback to get the next available
* band data.
*/
PMPrintPageProcPtr PrintPage;
/*
* This API is called when an image is encountered during conversion.
* This allows the Printer Module to access and modify the image
* data (imageRef) and drawing context before the image is rasterized
* into the page bands. Modified image should be returned in
* outImageRefPtr.
*/
PMImageAccessProcPtr ImageAccess;
/*
* Cancel the currently printing job. This function may be called
* while the PM is executing code in PrintJob or PrintPage.
*/
PMCancelJobProcPtr CancelJob;
/*
* Finish up the previously printed job.
*/
PMEndJobProcPtr EndJob;
/*
* Dispose of the current PM session data allocated in Initialize.
*/
PMTerminateProcPtr Terminate;
};
typedef struct PMProcs PMProcs;
/* PM interface is an object containing addresses to the module's entry points: */
struct PMInterface {
const PMProcs * vtable;
};
typedef struct PMInterface PMInterface;
typedef const PMInterface * PMInterfaceRef;
/*
Paper names must all be ISO or PPD standard names, so we've defined constants here for
developers to use in their code, mostly to make things more readable.
*/
#define USExecutiveEnvelope CFSTR("Executive")
#define Envelope9 CFSTR("na-number-9-envelope")
#define Envelope10 CFSTR("na-number-10-envelope")
#define Envelope10x15 CFSTR("na-10x15-envelope")
#define EnvelopeB4 CFSTR("iso-b4-envelope")
#define EnvelopeB5 CFSTR("iso-b5-envelope")
#define EnvelopeC3 CFSTR("iso-c3-envelope")
#define EnvelopeC4 CFSTR("iso-c4-envelope")
#define EnvelopeC5 CFSTR("iso-c5-envelope")
#define EnvelopeC6 CFSTR("iso-c6-envelope")
#define Envelope6x9 CFSTR("na-6x9-envelope")
#define Envelope7x9 CFSTR("na-7x9-envelope")
#define Envelope9x11 CFSTR("na-9x11-envelope")
#define Envelope9x12 CFSTR("na-9x12-envelope")
#define Envelope10x13 CFSTR("na-10x13-envelope")
#define Envelope10x14 CFSTR("na-10x14-envelope")
#define EnvelopeMonarch CFSTR("monarch-envelope")
#define EnvelopeLong CFSTR("iso-designated-long-envelope")
#define Invoice CFSTR("invoice")
#define USLetter CFSTR("na-letter")
#define USLegal CFSTR("na-legal")
#define Ledger CFSTR("ledger")
#define Folio CFSTR("folio")
#define Quarto CFSTR("quarto")
#define A0 CFSTR("iso-a0")
#define A1 CFSTR("iso-a1")
#define A2 CFSTR("iso-a2")
#define A3 CFSTR("iso-a3")
#define A4 CFSTR("iso-a4")
#define A5 CFSTR("iso-a5")
#define A6 CFSTR("iso-a6")
#define A7 CFSTR("iso-a7")
#define A8 CFSTR("iso-a8")
#define A9 CFSTR("iso-a9")
#define B0 CFSTR("iso-b0")
#define B1 CFSTR("iso-b1")
#define B2 CFSTR("iso-b2")
#define B3 CFSTR("iso-b3")
#define B4 CFSTR("iso-b4")
#define B5 CFSTR("iso-b5")
#define B6 CFSTR("iso-b6")
#define B7 CFSTR("iso-b7")
#define B8 CFSTR("iso-b8")
#define B9 CFSTR("iso-b9")
#define B10 CFSTR("iso-b10")
#define JISB0 CFSTR("jis-b0")
#define JISB1 CFSTR("jis-b1")
#define JISB2 CFSTR("jis-b2")
#define JISB3 CFSTR("jis-b3")
#define JISB4 CFSTR("jis-b4")
#define JISB5 CFSTR("jis-b5")
#define JISB7 CFSTR("jis-b7")
#define JISB8 CFSTR("jis-b8")
#define JISB9 CFSTR("jis-b9")
#define JISB10 CFSTR("jis-b10")
#define ASize CFSTR("a")
#define BSize CFSTR("b")
#define CSize CFSTR("c")
#define DSize CFSTR("d")
#define ESize CFSTR("e")
#define iso10 CFSTR("iso-10")
/* A string to define the default paper name. See sample code for usage.*/
#define DefaultPaper CFSTR("DefaultPaperSize")
#if PRAGMA_STRUCT_ALIGN
#pragma options align=reset
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(pop)
#elif PRAGMA_STRUCT_PACK
#pragma pack()
#endif
#ifdef PRAGMA_IMPORT_OFF
#pragma import off
#elif PRAGMA_IMPORT
#pragma import reset
#endif
#ifdef __cplusplus
}
#endif