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.

Symbols

Releasing and Retaining Printing Objects

func PMRelease(PMObject?)

Releases a printing object by decrementing its reference count.

func PMRetain(PMObject?)

Retains a printing object by incrementing its reference count.

Creating and Using Page Format Objects

func PMCopyPageFormat(PMPageFormat, PMPageFormat)

Copies the settings from one page format object into another.

func PMSessionDefaultPageFormat(PMPrintSession, PMPageFormat)

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

func PMSessionValidatePageFormat(PMPrintSession, PMPageFormat, UnsafeMutablePointer<DarwinBoolean>?)

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

func PMSessionCreatePageFormatList(PMPrintSession, PMPrinter?, UnsafeMutablePointer<Unmanaged<CFArray>?>)

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

Accessing Data in Page Format Objects

func PMSetPageFormatExtendedData(PMPageFormat, OSType, UInt32, UnsafeMutableRawPointer)

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

func PMGetPageFormatPaper(PMPageFormat, UnsafeMutablePointer<PMPaper>)

Obtains the paper associated with a page format object.

func PMPageFormatGetPrinterID(PMPageFormat, UnsafeMutablePointer<Unmanaged<CFString>?>)

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

func PMGetOrientation(PMPageFormat, UnsafeMutablePointer<PMOrientation>)

Obtains the current setting for page orientation.

func PMSetOrientation(PMPageFormat, PMOrientation, Bool)

Sets the page orientation for printing.

func PMGetScale(PMPageFormat, UnsafeMutablePointer<Double>)

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

func PMSetScale(PMPageFormat, Double)

Sets the scaling factor for the page and paper rectangles.

func PMGetAdjustedPageRect(PMPageFormat, UnsafeMutablePointer<PMRect>)

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

func PMGetAdjustedPaperRect(PMPageFormat, UnsafeMutablePointer<PMRect>)

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

func PMGetUnadjustedPageRect(PMPageFormat, UnsafeMutablePointer<PMRect>)

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

func PMGetUnadjustedPaperRect(PMPageFormat, UnsafeMutablePointer<PMRect>)

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

Creating and Using Print Settings Objects

func PMSessionDefaultPrintSettings(PMPrintSession, PMPrintSettings)

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

func PMSessionValidatePrintSettings(PMPrintSession, PMPrintSettings, UnsafeMutablePointer<DarwinBoolean>?)

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

func PMCopyPrintSettings(PMPrintSettings, PMPrintSettings)

Copies the settings from one print settings object into another.

Accessing Data in Print Settings Objects

func PMGetFirstPage(PMPrintSettings, UnsafeMutablePointer<UInt32>)

Obtains the number of the first page to be printed.

func PMSetFirstPage(PMPrintSettings, UInt32, Bool)

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

func PMGetLastPage(PMPrintSettings, UnsafeMutablePointer<UInt32>)

Obtains the number of the last page to be printed.

func PMSetLastPage(PMPrintSettings, UInt32, Bool)

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

func PMSetPageRange(PMPrintSettings, UInt32, UInt32)

Sets the valid range of pages that can be printed.

func PMGetCopies(PMPrintSettings, UnsafeMutablePointer<UInt32>)

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

func PMSetCopies(PMPrintSettings, UInt32, Bool)

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

func PMGetCollate(PMPrintSettings, UnsafeMutablePointer<DarwinBoolean>)

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

func PMSetCollate(PMPrintSettings, Bool)

Specifies whether the job collate option is selected.

func PMPrintSettingsSetValue(PMPrintSettings, CFString, CFTypeRef?, Bool)

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

func PMPrintSettingsCopyAsDictionary(PMPrintSettings, UnsafeMutablePointer<Unmanaged<CFDictionary>?>)

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

Creating Printing Session Objects

func PMCreateSession(UnsafeMutablePointer<PMPrintSession>)

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

Accessing Data in Printing Session Objects

func PMSessionGetDataFromSession(PMPrintSession, CFString, UnsafeMutablePointer<Unmanaged<CFTypeRef>?>)

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

func PMSessionSetDataInSession(PMPrintSession, CFString, CFTypeRef)

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

func PMSessionGetCurrentPrinter(PMPrintSession, UnsafeMutablePointer<PMPrinter>)

Obtains the current printer associated with a printing session.

func PMSessionSetCurrentPMPrinter(PMPrintSession, PMPrinter)

Changes the current printer for a printing session.

func PMSessionGetCGGraphicsContext(PMPrintSession, UnsafeMutablePointer<Unmanaged<CGContext>?>)

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

func PMSessionError(PMPrintSession)

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

func PMSessionSetError(PMPrintSession, OSStatus)

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

Creating and Using Paper Objects

Accessing Data in Paper Objects

func PMPaperGetWidth(PMPaper, UnsafeMutablePointer<Double>)

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

func PMPaperGetHeight(PMPaper, UnsafeMutablePointer<Double>)

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

func PMPaperGetMargins(PMPaper, UnsafeMutablePointer<PMPaperMargins>)

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

func PMPaperGetPrinterID(PMPaper, UnsafeMutablePointer<Unmanaged<CFString>?>)

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

Print Loop Functions

func PMSessionBeginCGDocumentNoDialog(PMPrintSession, PMPrintSettings, PMPageFormat)

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

func PMSessionBeginPageNoDialog(PMPrintSession, PMPageFormat?, UnsafePointer<PMRect>?)

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

func PMSessionEndPageNoDialog(PMPrintSession)

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

Creating Printer Objects

func PMServerLaunchPrinterBrowser(PMServer?, CFDictionary?)

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

func PMPrinterCreateFromPrinterID(CFString)

Creates a printer object from a print queue identifier.

Accessing Information About a Printer

func PMPrinterCopyHostName(PMPrinter, UnsafeMutablePointer<Unmanaged<CFString>>)

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

func PMPrinterCopyPresets(PMPrinter, UnsafeMutablePointer<Unmanaged<CFArray>?>)

Obtains a list of print settings presets for a printer.

func PMPrinterGetDriverCreator(PMPrinter, UnsafeMutablePointer<OSType>)

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

func PMPrinterGetDriverReleaseInfo(PMPrinter, UnsafeMutablePointer<VersRec>)

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

func PMPrinterGetID(PMPrinter)

Returns the unique identifier of a printer.

func PMPrinterGetLanguageInfo(PMPrinter, UnsafeMutablePointer<PMLanguageInfo>)

Obtains information about the imaging language for the specified printer.

func PMPrinterGetLocation(PMPrinter)

Returns the location of a printer.

func PMPrinterGetMakeAndModelName(PMPrinter, UnsafeMutablePointer<Unmanaged<CFString>?>)

Obtains the manufacturer and model name of the specified printer.

func PMPrinterGetMimeTypes(PMPrinter, PMPrintSettings?, UnsafeMutablePointer<Unmanaged<CFArray>?>)

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

func PMPrinterGetName(PMPrinter)

Returns the human-readable name of a printer.

func PMPrinterGetOutputResolution(PMPrinter, PMPrintSettings, UnsafeMutablePointer<PMResolution>)

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

func PMPrinterSetOutputResolution(PMPrinter, PMPrintSettings, UnsafePointer<PMResolution>)

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

func PMPrinterGetPrinterResolutionCount(PMPrinter, UnsafeMutablePointer<UInt32>)

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

func PMPrinterGetIndexedPrinterResolution(PMPrinter, UInt32, UnsafeMutablePointer<PMResolution>)

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

func PMPrinterGetState(PMPrinter, UnsafeMutablePointer<PMPrinterState>)

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

func PMPrinterSetDefault(PMPrinter)

Sets the default printer for the current user.

func PMPrinterIsDefault(PMPrinter)

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

func PMPrinterIsFavorite(PMPrinter)

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

func PMPrinterIsPostScriptCapable(PMPrinter)

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

func PMPrinterIsRemote(PMPrinter, UnsafeMutablePointer<DarwinBoolean>)

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

Submitting a Print Job to a Printer

func PMPrinterPrintWithFile(PMPrinter, PMPrintSettings, PMPageFormat?, CFString?, CFURL)

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

func PMPrinterPrintWithProvider(PMPrinter, PMPrintSettings, PMPageFormat?, CFString, CGDataProvider)

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

Accessing PostScript Printer Description Files

func PMCopyAvailablePPDs(PMPPDDomain, UnsafeMutablePointer<Unmanaged<CFArray>?>)

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

func PMCopyLocalizedPPD(CFURL, UnsafeMutablePointer<Unmanaged<CFURL>?>)

Obtains a localized PostScript printer description (PPD) file.

func PMCopyPPDData(CFURL, UnsafeMutablePointer<Unmanaged<CFData>?>)

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

Printing with PostScript Data

func PMCGImageCreateWithEPSDataProvider(CGDataProvider?, CGImage)

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

func PMPrinterWritePostScriptToURL(PMPrinter, PMPrintSettings, PMPageFormat?, CFString?, CFURL, CFURL)

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

Using PDF Workflow Items

func PMWorkflowCopyItems(UnsafeMutablePointer<Unmanaged<CFArray>?>)

Obtains an array of the available PDF workflow items.

func PMWorkflowSubmitPDFWithOptions(CFURL, CFString?, UnsafePointer<Int8>?, CFURL)

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

func PMWorkflowSubmitPDFWithSettings(CFURL, PMPrintSettings, CFURL)

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

Data Types

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.

PMServer

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

Constants

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.

PMDuplexMode

Constants that specify duplex mode settings.

PMOrientation

Constants that specify page orientation.

PDF Workflow Dictionary Keys

Constants that specify the keys in a PDF workflow dictionary.

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.

User Cancellation Constant

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

Result Codes

This table lists the result codes defined for Core Printing.

var kPMGeneralError: Int

An unspecified error occurred.

var kPMOutOfScope: Int

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

var kPMNoDefaultPrinter: Int

The user has not specified a default printer.

var kPMNotImplemented: Int

The function is not implemented.

var kPMNoSuchEntry: Int

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

var kPMInvalidPrintSettings: Int

Your application passed an invalid print settings object.

var kPMInvalidPageFormat: Int

Your application passed an invalid page format object.

var kPMValueOutOfRange: Int

Your application passed an out-of-range value.

var kPMLockIgnored: Int

The lock value was ignored.

var kPMInvalidPrintSession: Int

Your application passed an invalid printing session object.

var kPMInvalidPrinter: Int

Your application passed an invalid printer object.

var kPMObjectInUse: Int

The specified object is in use.

var kPMInvalidIndex: Int

An array index is invalid.

var kPMStringConversionFailure: Int

An internal error occurred while converting a string.

var kPMXMLParseError: Int

An error occurred while parsing XML data.

var kPMInvalidJobTemplate: Int

An internal error occurred while creating a job template.

var kPMInvalidPrinterInfo: Int

The printer information is invalid.

var kPMInvalidConnection: Int

The printer connection type is invalid.

var kPMInvalidKey: Int

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

var kPMInvalidValue: Int

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

var kPMInvalidAllocator: Int

The specified memory allocator is invalid.

var kPMInvalidTicket: Int

The job ticket is invalid.

var kPMInvalidItem: Int

The item being added to a ticket is invalid.

var kPMInvalidType: Int

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

var kPMInvalidReply: Int

A remote server or client sent an invalid reply.

var kPMInvalidFileType: Int

The file type is invalid.

var kPMInvalidObject: Int

The object is invalid.

var kPMInvalidPaper: Int

Your application passed an invalid paper object.

var kPMInvalidCalibrationTarget: Int

The dictionary specifying a printer calibration target is invalid.

var kPMInvalidPreset: Int

Your application passed an invalid preset object.