Core Printing

Overview

Core Printing is a C API that Mac apps and command line tools can use to perform printing tasks that don’t display a user interface. Core Printing defines a set of opaque types and a rich set of operations on instances of these types. The Core Printing opaque types include:

  • PMPrintSession for general information about a print job

  • PMPrintSettings for print job parameters

  • PMPageFormat for the page format of a printed document

  • PMPaper for information about a type of paper

  • PMPrinter for information about a printer

In Carbon applications, Core Printing is used together with Carbon Printing to implement printing features. For more information about Carbon Printing, see Carbon Printing Reference.

In Cocoa applications, Core Printing can be used to extend the functionality in the Cocoa printing classes. The NSPrintInfo class provides direct access to some Core Printing objects.

Topics

Releasing and Retaining Printing Objects

PMRelease

Releases a printing object by decrementing its reference count.

PMRetain

Retains a printing object by incrementing its reference count.

Creating and Using Page Format Objects

PMCreatePageFormat

Creates a new page format object.

PMCreatePageFormatWithPMPaper

Creates a page format object with a specified paper.

PMCopyPageFormat

Copies the settings from one page format object into another.

PMSessionDefaultPageFormat

Assigns default parameter values to a page format object used in the specified printing session.

PMSessionValidatePageFormat

Updates the values in a page format object and validates them against the current formatting printer.

PMSessionCreatePageFormatList

Obtains a list of page format objects, each of which describes a paper size available on the specified printer.

PMPageFormatCreateDataRepresentation

Creates a data representation of a page format object.

PMPageFormatCreateWithDataRepresentation

Creates a page format object from a data representation.

PMFlattenPageFormat

Flattens a page format object into a Memory Manager handle for storage in a user document.

PMFlattenPageFormatToCFData

Flattens a page format object into a Core Foundation data object for storage in a user document.

PMFlattenPageFormatToURL

Flattens a page format object into a file for storage in a user document.

PMUnflattenPageFormat

Rebuilds a page format object from a Memory Manager handle that contains flattened page format data.

PMUnflattenPageFormatWithCFData

Rebuilds a page format object from a Core Foundation data object that contains flattened page format data.

PMUnflattenPageFormatWithURL

Rebuilds a page format object from a file system URL that contains flattened page format data.

Accessing Data in Page Format Objects

PMGetPageFormatExtendedData

Obtains extended page format data previously stored by your application.

PMSetPageFormatExtendedData

Stores your application-specific data in a page format object.

PMGetPageFormatPaper

Obtains the paper associated with a page format object.

PMPageFormatGetPrinterID

Obtains the identifier of the formatting printer for a page format object.

PMGetOrientation

Obtains the current setting for page orientation.

PMSetOrientation

Sets the page orientation for printing.

PMGetResolution

Obtains the current application’s drawing resolution.

PMSetResolution

Sets the application drawing resolution.

PMGetScale

Obtains the scaling factor currently applied to the page and paper rectangles.

PMSetScale

Sets the scaling factor for the page and paper rectangles.

PMGetAdjustedPageRect

Obtains the imageable area or page rectangle, taking into account orientation, application drawing resolution, and scaling settings.

PMSetAdjustedPageRect

Requests a particular page size, adjusted for the current rotation, resolution, or scaling settings.

PMGetAdjustedPaperRect

Obtains the rectangle defining the paper size, taking into account orientation, application drawing resolution, and scaling settings.

PMGetUnadjustedPageRect

Obtains the imageable area or page rectangle, unaffected by orientation, resolution, or scaling.

PMGetUnadjustedPaperRect

Obtains the paper rectangle, unaffected by rotation, resolution, or scaling.

PMSetUnadjustedPaperRect

Requests a particular paper size, unaffected by rotation, resolution, or scaling.

Creating and Using Print Settings Objects

PMCreatePrintSettings

Creates a new print settings object.

PMSessionDefaultPrintSettings

Assigns default parameter values to a print settings object for the specified printing session.

PMSessionValidatePrintSettings

Validates a print settings object within the context of the specified printing session.

PMPrintSettingsCreateDataRepresentation

Creates a data representation of a print settings object.

PMPrintSettingsCreateWithDataRepresentation

Creates a print settings object from a data representation.

PMFlattenPrintSettings

Flattens a print settings object into a Memory Manager handle for storage in a user document.

PMFlattenPrintSettingsToCFData

Flattens a print settings object into a Core Foundation data object for storage in a user document.

PMFlattenPrintSettingsToURL

Flattens a print settings object into a URL for storage in a user document.

PMUnflattenPrintSettings

Rebuilds a print settings object from a Memory Manager handle that contains flattened print settings data.

PMUnflattenPrintSettingsWithCFData

Rebuilds a print settings object from a Core Foundation data object that contains flattened print settings data.

PMUnflattenPrintSettingsWithURL

Rebuilds a print settings object from a file that contains flattened print settings data.

PMCopyPrintSettings

Copies the settings from one print settings object into another.

PMPrintSettingsToOptions

Converts print settings into a CUPS options string.

PMPrintSettingsToOptionsWithPrinterAndPageFormat

Converts print settings and page format data into a CUPS options string for a specified printer.

Accessing Data in Print Settings Objects

PMGetPrintSettingsExtendedData

Obtains extended print settings data previously stored by your application.

PMSetPrintSettingsExtendedData

Stores your application-specific data in a print settings object.

PMGetFirstPage

Obtains the number of the first page to be printed.

PMSetFirstPage

Sets the default page number of the first page to be printed.

PMGetLastPage

Obtains the number of the last page to be printed.

PMSetLastPage

Sets the page number of the last page to be printed.

PMGetPageRange

Obtains the valid range of pages that can be printed.

PMSetPageRange

Sets the valid range of pages that can be printed.

PMPrintSettingsGetJobName

Obtains the name of a print job.

PMPrintSettingsSetJobName

Specifies the name of a print job.

PMGetCopies

Obtains the number of copies that the user requests to be printed.

PMSetCopies

Sets the initial value for the number of copies to be printed.

PMGetCollate

Obtains a Boolean value that indicates whether the job collate option is selected.

PMSetCollate

Specifies whether the job collate option is selected.

PMGetDuplex

Obtains the selected duplex mode.

PMSetDuplex

Sets the duplex mode.

PMPrintSettingsGetValue

Obtains the value of a setting in a print settings object.

PMPrintSettingsSetValue

Stores the value of a setting in a print settings object.

PMPrintSettingsCopyAsDictionary

Creates a dictionary that contains the settings in a print settings object.

PMPrintSettingsCopyKeys

Obtains the keys for items in a print settings object.

PMGetJobNameCFString

Obtains the name of the print job.

PMSetJobNameCFString

Specifies the name of a print job.

Creating Printing Session Objects

PMCreateSession

Creates and initializes a printing session object and creates a context for printing operations.

Accessing Data in Printing Session Objects

PMSessionGetDataFromSession

Obtains application-specific data previously stored in a printing session object.

PMSessionSetDataInSession

Stores your application-specific data in a printing session object.

PMSessionGetCurrentPrinter

Obtains the current printer associated with a printing session.

PMSessionSetCurrentPrinter

Changes the current printer for a printing session to a printer specified by name.

PMSessionSetCurrentPMPrinter

Changes the current printer for a printing session.

PMSessionGetDocumentFormatGeneration

Obtains the spool file formats that can be generated for the specified printing session.

PMSessionSetDocumentFormatGeneration

Requests a specified spool file format and supplies the graphics context type to use for drawing pages within the print loop.

PMSessionGetCGGraphicsContext

Obtains the Quartz graphics context for the current page in a printing session.

PMSessionGetGraphicsContext

Obtains the graphics context for the current page in a printing session.

PMSessionError

Obtains the result code for any error returned by the printing session.

PMSessionSetError

Sets the value of the current result code for the specified printing session.

PMSessionGeneral

Maintains compatibility with the PrGeneral function in the classic Printing Manager.

Using Printer Presets

PMPresetCopyName

Obtains the localized name for a preset.

PMPresetCreatePrintSettings

Creates a print settings object with settings that correspond to a preset.

PMPresetGetAttributes

Obtains the attributes of a preset.

Creating and Using Paper Objects

PMPaperCreate

Creates a paper object.

PMPaperCreateCustom

Creates a custom paper object.

PMPaperIsCustom

Returns a Boolean value indicating whether a specified paper is a custom paper.

Accessing Data in Paper Objects

PMPaperGetID

Obtains the identifier of a paper object.

PMPaperGetName

Obtains the name for a given paper.

PMPaperGetWidth

Obtains the width of the sheet of paper represented by a paper object.

PMPaperGetHeight

Obtains the height of the sheet of paper represented by a paper object.

PMPaperGetMargins

Obtains the margins describing the unprintable area of the sheet represented by a paper object.

PMPaperCreateLocalizedName

Obtains the localized name for a given paper.

PMPaperGetPrinterID

Obtains the printer ID of the printer to which a given paper corresponds.

PMPaperGetPPDPaperName

Obtains the PPD paper name for a given paper.

Print Loop Functions

PMSessionBeginCGDocumentNoDialog

Begins a print job that draws into a Quartz graphics context and suppresses the printing status dialog.

PMSessionBeginDocumentNoDialog

Begins a print job that, by default, draws into a QuickDraw graphics port, and suppresses the printing status dialog.

PMSessionBeginPageNoDialog

Starts a new page for printing in the specified printing session and suppresses the printing status dialog.

PMSessionEndPageNoDialog

Indicates the end of drawing the current page for the specified printing session.

PMSessionSetIdleProc

Installs an idle callback function in your print loop.

Accessing the Print Job Destination

PMSessionSetDestination

Sets the destination location, format, and type for a print job.

PMSessionGetDestinationType

Obtains the output destination for a print job.

PMSessionCopyDestinationFormat

Obtains the destination format for a print job.

PMSessionCopyDestinationLocation

Obtains a destination location for a print job.

PMSessionCopyOutputFormatList

Obtains an array of destination formats supported by the current print destination.

Creating Printer Objects

PMServerLaunchPrinterBrowser

Launches the printer browser to browse the printers available for a print server.

PMServerCreatePrinterList

Creates a list of printers available to a print server.

PMSessionCreatePrinterList

Creates a list of printers available in the specified printing session.

PMPrinterCreateFromPrinterID

Creates a printer object from a print queue identifier.

PMCreateGenericPrinter

Creates a generic printer object.

Accessing Information About a Printer

PMPrinterCopyDescriptionURL

Obtains the URL of the description file for a given printer.

PMPrinterCopyDeviceURI

Obtains the device URI of a given printer.

PMPrinterCopyHostName

Obtains the name of the server hosting the print queue for a given printer.

PMPrinterCopyPresets

Obtains a list of print settings presets for a printer.

PMPrinterGetCommInfo

Obtains information about the communication channel for a printer.

PMPrinterGetDescriptionURL

Obtains a reference to the specified printer’s description file.

PMPrinterGetDeviceURI

Obtains a copy of a printer's device URI.

PMPrinterGetDriverCreator

Obtains the creator of the driver associated with the specified printer.

PMPrinterGetDriverReleaseInfo

Obtains version information for the driver associated with the specified printer.

PMPrinterGetID

Returns the unique identifier of a printer.

PMPrinterGetLanguageInfo

Obtains information about the imaging language for the specified printer.

PMPrinterGetLocation

Returns the location of a printer.

PMPrinterGetMakeAndModelName

Obtains the manufacturer and model name of the specified printer.

PMPrinterGetMimeTypes

Obtains a list of MIME content types supported by a printer using the specified print settings.

PMPrinterGetName

Returns the human-readable name of a printer.

PMPrinterGetOutputResolution

Obtains the printer hardware output resolution for the specified print settings.

PMPrinterSetOutputResolution

Sets the print settings to reflect the specified printer hardware output resolution.

PMPrinterGetPaperList

Obtains the list of papers available for a printer.

PMPrinterGetPrinterResolution

Obtains a resolution setting for the specified printer.

PMPrinterGetPrinterResolutionCount

Obtains the number of resolution settings supported by the specified printer.

PMPrinterGetIndexedPrinterResolution

Obtains a resolution setting based on an index into the range of settings supported by the specified printer.

PMPrinterGetState

Obtains the current state of the print queue for a printer.

PMPrinterSetDefault

Sets the default printer for the current user.

PMPrinterIsDefault

Returns a Boolean value indicating whether a printer is the default printer for the current user.

PMPrinterIsFavorite

Returns a Boolean value indicating whether a printer is in the user’s list of favorite printers.

PMPrinterIsPostScriptCapable

Returns a Boolean value indicating whether a printer is PostScript capable.

PMPrinterIsPostScriptPrinter

Determines whether a printer is a PostScript printer.

PMPrinterIsRemote

Indicates whether a printer is hosted by a remote print server.

Submitting a Print Job to a Printer

PMPrinterPrintWithFile

Submits a print job to a specified printer using a file that contains print data.

PMPrinterPrintWithProvider

Submits a print job to a specified printer using a Quartz data provider to obtain the print data.

Accessing PostScript Printer Description Files

PMCopyAvailablePPDs

Obtains the list of PostScript printer description (PPD) files in a PPD domain.

PMCopyLocalizedPPD

Obtains a localized PostScript printer description (PPD) file.

PMCopyPPDData

Obtains the uncompressed PPD data for a PostScript printer description (PPD) file.

Printing with PostScript Data

PMCGImageCreateWithEPSDataProvider

Creates an image that references both the PostScript contents of EPS data and a preview (proxy) image for the data.

PMPrinterWritePostScriptToURL

Converts an input file of the specified MIME type to printer-ready PostScript for a destination printer.

PMSessionPostScriptBegin

Puts the current printer driver into PostScript mode, ready to accept PostScript data instead of QuickDraw data.

PMSessionPostScriptData

Passes PostScript data, referenced by a pointer, to the current printer driver.

PMSessionPostScriptEnd

Restores the current driver to QuickDraw mode, ready to accept QuickDraw data instead of PostScript data.

PMSessionPostScriptFile

Passes the PostScript data, contained in a file, to the current printer driver.

PMSessionPostScriptHandle

Passes the PostScript data, referenced by a Memory Manager handle, to the current printer driver.

PMSessionSetPSInjectionData

Specifies a set of PostScript code injection points and the PostScript data to be injected.

Using PDF Workflow Items

PMWorkflowCopyItems

Obtains an array of the available PDF workflow items.

PMWorkflowSubmitPDFWithOptions

Submits a PDF file for workflow processing using the specified CUPS options string.

PMWorkflowSubmitPDFWithSettings

Submits a PDF file for workflow processing using the specified print settings.

Matching Color With ColorSync

PMSetProfile

Embeds a color profile during printing.

PMSessionEnableColorSync

Enables use of a custom ColorSync profile previously set by the function PMSetProfile.

PMSessionDisableColorSync

Disables use of a custom ColorSync profile previously enabled by the function PMSessionEnableColorSync.

Converting and Saving Old Print Records

PMSessionConvertOldPrintRecord

Creates new page format and print settings objects from an old-style print record created for the classic Printing Manager.

PMSessionMakeOldPrintRecord

Creates an old-style print record from page format and print settings objects.

Creating, Calling, and Deleting Universal Procedure Pointers

NewPMIdleUPP

Creates a new universal procedure pointer (UPP) to an idle callback.

InvokePMIdleUPP

Calls an idle callback.

DisposePMIdleUPP

Disposes of a universal procedure pointer (UPP) to an idle callback.

Legacy Core Printing Functions

PMBegin

Prepares Core Printing for use.

PMConvertOldPrintRecord

Creates a new PMPageFormat object and a new PMPrintSettings object from a print record created by the classic Printing Manager.

PMDefaultPageFormat

Assigns default parameter values to an existing PMPageFormat object, for the current printer.

PMDefaultPrintSettings

Assigns default parameter values to a PMPrintSettings object.

PMDisableColorSync

Disables ColorSync color matching for the current page.

PMDisposePageFormat

Releases memory previously allocated for a PMPageFormat object.

PMDisposePrintSettings

Releases memory previously allocated for a PMPrintSettings object.

PMEnableColorSync

Enables ColorSync color matching for the current page.

PMEnd

Closes Core Printing and releases its allocated memory.

PMError

Obtains the result code from the last printing function called by your application.

PMGeneral

Maintains compatibility with the PrGeneral function in the classic Printing Manager.

PMGetDestination

Obtains the output destination of a print job.

PMGetDriverCreator

Obtains the creator of the driver associated with the current printer.

PMGetDriverReleaseInfo

Obtains release information for the driver associated with the current printer.

PMGetGrafPtr

Obtains the printing port from an opaque printing context.

PMGetIndexedPrinterResolution

Obtains a resolution setting based on an index into the range of settings supported by the current printer.

PMGetJobName

Obtains the name of the print job.

PMGetLanguageInfo

Obtains information about the current printer’s imaging language.

PMGetPhysicalPageSize

Obtains the size of the imageable area in points, unaffected by rotation, resolution, or scaling.

PMGetPhysicalPaperSize

Obtains the size of the paper in points, unaffected by rotation, resolution, or scaling.

PMGetPrinterResolution

Obtains the resolution setting for the current printer according to the tag parameter.

PMGetPrinterResolutionCount

Obtains the number of resolution settings supported by the current printer.

PMIsPostScriptDriver

Reports whether the current printer driver supports the PostScript language.

PMNewPageFormat

Creates a new PMPageFormat object.

PMNewPrintSettings

Creates a new PMPrintSettings object.

PMMakeOldPrintRecord

Creates an old-style print record from a PMPageFormat and a PMPrintSettings object.

PMPostScriptBegin

Puts the current driver into PostScript mode, ready to accept PostScript data instead of QuickDraw data.

PMPostScriptData

Passes PostScript data, referenced by a pointer, to the current printer driver.

PMPostScriptEnd

Restores the current driver to QuickDraw mode, ready to accept QuickDraw data instead of PostScript data.

PMPostScriptFile

Passes PostScript data, contained in a file, to the current printer driver.

PMPostScriptHandle

Passes PostScript data, referenced by a handle, to the current printer driver.

PMSessionGetDocumentFormatSupported

Obtains the spool file formats that are accepted by the current printer driver.

PMSessionIsDocumentFormatSupported

Reports whether the current printer driver supports a specified spool file format.

PMGetColorMode

Obtains the color mode for the print job.

PMSetColorMode

Sets the desired color mode for the print job.

PMSetError

Sets the value of the current result code.

PMSetIdleProc

Installs an idle callback function in your print loop.

PMSetJobName

Specifies the name of the print job.

PMSetPhysicalPaperSize

Requests a particular paper size, unaffected by rotation, resolution, or scaling.

PMValidatePageFormat

Obtains a valid PMPageFormat object.

PMValidatePrintSettings

Obtains a valid PMPrintSettings object.

Callbacks

PMIdleProcPtr

Defines a pointer to an idle function.

Data Types

PMDialog

An opaque type that represents a custom printing dialog.

PMIdleUPP

A type that defines a universal procedure pointer to an idle callback.

PMLanguageInfo

A data structure that contains level, version, and release information for the imaging language used by a printer driver.

PMObject

The base type for all the opaque types used in Core Printing.

PMPageFormat

An opaque type that stores the settings in the Page Setup dialog.

PMPaper

An opaque type that stores information about the paper used in a print job.

PMPaperMargins

A data structure that specifies the unprintable area of a paper object.

PMPreset

An opaque type that stores information about a named preset available for a print job.

PMPrinter

An opaque type that represents a printer.

PMPrintSession

An opaque type that stores information about a print job.

PMPrintSettings

An opaque type that stores the settings in the Print dialog.

PMRect

A data structure that describes a rectangle using four double-precision coordinates.

PMResolution

A data structure that contains printing resolution information.

PMServer

An opaque type that identifies a local or remote print server.

PMPrintContext

An opaque type that describes the graphics environment for printing a document.

PMColorMode

A type that specifies color modes to use for printing.

Constants

Data Not Wanted Constants

Constants your application can use to indicate it does not need certain types of data returned by various printing functions.

PMDataFormat

Constants that specify the format of the data representation created with the functions PMPageFormatCreateDataRepresentation and PMPrintSettingsCreateDataRepresentation.

PMDestinationType

Constants that specify a destination for a print job.

Document Format Strings

Constants that specify the document format for a print job.

PMDuplexMode

Constants that specify duplex mode settings.

Graphics Context Types

Constants that specify the graphics context for a print job.

PMOrientation

Constants that specify page orientation.

PDF Workflow Dictionary Keys

Constants that specify the keys in a PDF workflow dictionary.

PostScript Injection Dictionary Keys

Constants that specify keys for PostScript injection dictionary entries.

PostScript Page Injection Options

Constants that specify PostScript injection options.

PostScript Injection Placement Options

Constants that specify where in the print job to inject PostScript code.

PostScript Injection Sections

Constants that specify keys for PostScript injection section values.

PostScript Injection Subsections

Constants that specify PostScript injection values for the subsection key.

PMPPDDomain

Constants that specify the domains for PostScript printer description (PPD) files.

Print All Pages Constant

A constant that specifies that all pages of a document should be printed.

PMQualityMode

Constants that specify standard options for print quality.

PMPrinterState

Constants that specify the current state of a print queue.

Printer Description Types

Constants that specify printer description types.

Tag Constants

Constants that specify values, such as minimum and maximum values, that your application can pass to or obtain from printing functions.

User Cancellation Constant

A constant that specifies an error value that indicates the user canceled a printing operation.

Color Modes

Constants that specify a color mode to use for printing.

Result Codes

This table lists the result codes defined for Core Printing.

kPMGeneralError

An unspecified error occurred.

kPMOutOfScope

Your application called this function out of sequence with other printing functions.

kPMNoDefaultPrinter

The user has not specified a default printer.

kPMNotImplemented

The function is not implemented.

kPMNoSuchEntry

There is no entry to match your application’s request.

kPMInvalidPrintSettings

Your application passed an invalid print settings object.

kPMInvalidPageFormat

Your application passed an invalid page format object.

kPMValueOutOfRange

Your application passed an out-of-range value.

kPMInvalidPrintSession

Your application passed an invalid printing session object.

kPMInvalidPrinter

Your application passed an invalid printer object.

kPMObjectInUse

The specified object is in use.

kPMInvalidIndex

An array index is invalid.

kPMStringConversionFailure

An internal error occurred while converting a string.

kPMXMLParseError

An error occurred while parsing XML data.

kPMInvalidJobTemplate

An internal error occurred while creating a job template.

kPMInvalidPrinterInfo

The printer information is invalid.

kPMInvalidConnection

The printer connection type is invalid.

kPMInvalidKey

The key in a ticket, job template, or dictionary is invalid.

kPMInvalidValue

The value in a ticket, job template, or dictionary is missing.

kPMInvalidAllocator

The specified memory allocator is invalid.

kPMInvalidTicket

The job ticket is invalid.

kPMInvalidItem

The item being added to a ticket is invalid.

kPMInvalidType

The data type in a ticket, job template, or dictionary is not the expected type.

kPMInvalidReply

A remote server or client sent an invalid reply.

kPMInvalidFileType

The file type is invalid.

kPMInvalidObject

The object is invalid.

kPMInvalidPaper

Your application passed an invalid paper object.

kPMInvalidCalibrationTarget

The dictionary specifying a printer calibration target is invalid.

kPMInvalidPreset

Your application passed an invalid preset object.