ADC Home > Reference Library > Reference > Graphics & Imaging > Printing > Core Printing Reference >

Next Page > Hide TOC

Core Printing Reference

Framework
ApplicationServices/ApplicationServices.h
Declared in
PMCore.h
PMCoreDeprecated.h
PMDefinitions.h
PMDefinitionsDeprecated.h

Overview

Core Printing is a C API that Mac OS X applications 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:

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.

Note: Core Printing is available to 64-bit applications, except for functions, data types, and constants that have been deprecated.

Functions by Task

Releasing and Retaining Printing Objects

Creating and Using Page Format Objects

Accessing Data in Page Format Objects

Creating and Using Print Settings Objects

Accessing Data in Print Settings Objects

Creating Printing Session Objects

Accessing Data in Printing Session Objects

Using Printer Presets

Creating and Using Paper Objects

Accessing Data in Paper Objects

Print Loop Functions

Accessing the Print Job Destination

Creating Printer Objects

Accessing Information About a Printer

Submitting a Print Job to a Printer

Accessing PostScript Printer Description Files

Printing with PostScript Data

Using PDF Workflow Items

Matching Color With ColorSync

Converting and Saving Old Print Records

Creating, Calling, and Deleting Universal Procedure Pointers

Legacy Core Printing Functions

Functions

PMCGImageCreateWithEPSDataProvider

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

CGImageRef PMCGImageCreateWithEPSDataProvider (
   CGDataProviderRef epsDataProvider,
   CGImageRef epsPreview
);

Parameters
epsDataProvider

A Quartz data provider that supplies the PostScript contents of the EPS file. The EPS data must begin with the EPSF required header and bounding box DSC (Document Structuring Conventions) comments.

epsPreview

A Quartz image that serves as the proxy image for the EPS file. When the image returned by this function is rendered onscreen or sent to a printer that cannot render PostScript, this proxy image is drawn instead.

Return Value

An image capable of rendering either the EPS content or the proxy image, depending upon the capabilities of the destination printer.

Discussion

It is likely that data will not be read from the EPS data provider until after this function returns. You should be careful not to free the underlying EPS data until the data provider's release function is invoked. Similarly, do not free the preview image data until the image data provider's release function is invoked. You are responsible for releasing the data providers for the EPS image and the EPS preview image.

Note that in Mac OS X v10.3 and later, Quartz can convert EPS data into PDF data. Using this feature and then using Quartz to draw the resulting PDF data may produce superior results for your application. See CGPSConverter Reference for details.

Availability
Declared In
PMCore.h

PMCopyAvailablePPDs

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

OSStatus PMCopyAvailablePPDs (
   PMPPDDomain domain,
   CFArrayRef *ppds
);

Parameters
domain

The PPD domain to search. See “PostScript Printer Description File Domains” for a description of the constants you can use to specify the domain.

ppds

A pointer to your CFArrayRef variable. On return, the variable refers to a Core Foundation array of PPD files in the specified domain. Each element in the array is a Core Foundation URL object that specifies the location of a PPD file or a compressed PPD file. You are responsible for releasing the array. If the specified domain is not valid, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMCopyLocalizedPPD

Obtains a localized PostScript printer description (PPD) file.

OSStatus PMCopyLocalizedPPD (
   CFURLRef ppd,
   CFURLRef *localizedPPD
);

Parameters
ppd

A Core Foundation URL object for a PPD file. You can obtain a PPD URL using the function PMCopyAvailablePPDs.

localizedPPD

A pointer to your CFURLRef variable. On return, the variable refers to a Core Foundation URL object. The URL specifies the location of a PPD file or a compressed PPD file that has been localized for the current user's language preference. You are responsible for releasing the URL. If the ppd parameter is not valid, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

To access the data in the PPD file, you can use the function PMCopyPPDData.

Special Considerations

In Mac OS X v10.5 and later, the printing system supports globalized PPD files as defined in CUPS version 1.2 and later. A globalized PPD file contains multiple localizations within a single file. If a globalized PPD file exists, this function returns the URL to this file and it is up to the application to obtain the correct localized data. For more information, see CUPS PPD Extensions.

Availability
Declared In
PMCore.h

PMCopyPageFormat

Copies the settings from one page format object into another.

OSStatus PMCopyPageFormat (
   PMPageFormat formatSrc,
   PMPageFormat formatDest
);

Parameters
formatSrc

The page format object to duplicate.

formatDest

The page format object to receive the copied settings. On return, this object contains the same settings as the formatSrc object.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMCopyPPDData

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

OSStatus PMCopyPPDData (
   CFURLRef ppd,
   CFDataRef *data
);

Parameters
ppd

A URL for a PPD or compressed PPD file. You can obtain a PPD URL using the function PMCopyAvailablePPDs or PMCopyLocalizedPPD.

data

A pointer to your CFDataRef variable. On return, the variable refers to a Core Foundation data object containing the uncompressed PPD data from the specified PPD file. You are responsible for releasing the data object. If the ppd parameter does not reference a PPD file, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMCopyPrintSettings

Copies the settings from one print settings object into another. 

OSStatus PMCopyPrintSettings (
   PMPrintSettings settingSrc,
   PMPrintSettings settingDest
);

Parameters
settingSrc

The print settings object to duplicate.

settingDest

The print settings object to receive the copied settings. On return, this object contains the same settings as the settingSrc object.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMCreateGenericPrinter

Creates a generic printer object.

OSStatus PMCreateGenericPrinter (
   PMPrinter *printer
);

Parameters
printer

A pointer to your PMPrinter variable. On return, the variable refers to a new printer object that represents the generic formatting printer. You are responsible for releasing the printer object with the function PMRelease.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function provides a way to create a PMPrinter object that represents the generic formatting printer.

Availability
Declared In
PMCore.h

PMCreatePageFormat

Creates a new page format object.

OSStatus PMCreatePageFormat (
   PMPageFormat *pageFormat
);

Parameters
pageFormat

A pointer to your PMPageFormat variable. On return, the variable refers to a new page format object. You are responsible for releasing the page format object with the function PMRelease.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function allocates memory for a new page format object in your application’s memory space and sets its reference count to 1. The new page format object is empty and unusable until you call PMSessionDefaultPageFormat or PMCopyPageFormat.

Availability
Related Sample Code
Declared In
PMCore.h

PMCreatePageFormatWithPMPaper

Creates a page format object with a specified paper.

OSStatus PMCreatePageFormatWithPMPaper (
   PMPageFormat *pageFormat,
   PMPaper paper
);

Parameters
pageFormat

A pointer to your PMPageFormat variable. On return, the variable refers to a new page format object that represents the specified paper. You are responsible for releasing the page format object with the function PMRelease.

paper

The type of paper for the new page format object.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMCreatePrintSettings

Creates a new print settings object.

OSStatus PMCreatePrintSettings (
   PMPrintSettings *printSettings
);

Parameters
printSettings

A pointer to your PMPrintSettings variable. On return, the variable refers to a new print settings object. You are responsible for releasing the print settings object with the function PMRelease.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function allocates memory for a new print settings object in your application’s memory space and sets its reference count to 1. The new print settings object is empty and unusable until you call PMSessionDefaultPrintSettings or PMCopyPrintSettings.

Availability
Related Sample Code
Declared In
PMCore.h

PMCreateSession

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

OSStatus PMCreateSession (
   PMPrintSession *printSession
);

Parameters
printSession

A pointer to your PMPrintSession variable. On return, the variable refers to a new printing session object. You are responsible for releasing the printing session object with the function PMRelease.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function allocates memory for a new printing session object in your application’s memory space and sets its reference count to 1. The new printing session object is initialized with information that the printing system uses for a print job.

Availability
Related Sample Code
Declared In
PMCore.h

PMGetAdjustedPageRect

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

OSStatus PMGetAdjustedPageRect (
   PMPageFormat pageFormat,
   PMRect *pageRect
);

Parameters
pageFormat

The page format object whose adjusted page rectangle you want to obtain.

pageRect

A pointer to your PMRect structure. On return, the structure contains the current imageable area, in points, taking into account scaling, rotation, and application resolution settings. The page rectangle is the area of the page to which an application can draw. The coordinates for the upper-left corner of the page rectangle are (0,0). See Supporting Printing in Your Carbon Application for more information on page and paper rectangles.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Before using this function, you must call PMSessionValidatePageFormat to ensure that the values for the adjusted page rectangle correctly account for scaling, rotation, and application resolution settings.

Availability
Related Sample Code
Declared In
PMCore.h

PMGetAdjustedPaperRect

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

OSStatus PMGetAdjustedPaperRect (
   PMPageFormat pageFormat,
   PMRect *paperRect
);

Parameters
pageFormat

The page format object whose adjusted paper rectangle you want to obtain.

paperRect

A pointer to your PMRect structure. On return, the structure describes the current paper size, in points, taking into account scaling, rotation, and application resolution settings. The coordinates of the upper-left corner of the paper rectangle are specified relative to the page rectangle. The coordinates of the upper-left corner of the page rectangle are always (0,0), which means the coordinates of the upper-left corner of the paper rectangle are always negative or (0,0). See Supporting Printing in Your Carbon Application for more information on page and paper rectangles.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Before using this function, you must call the function PMSessionValidatePageFormat to ensure that the values for the adjusted paper rectangle correctly account for scaling, rotation, and application resolution settings.

Availability
Declared In
PMCore.h

PMGetCollate

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

OSStatus PMGetCollate (
   PMPrintSettings printSettings,
   Boolean *collate
);

Parameters
printSettings

The print settings object you’re querying to determine whether the job collate option is selected.

collate

A pointer to your Boolean variable. On return, true if the job collate option is selected; otherwise, false.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

The Collated checkbox is displayed in the Copies & Pages pane of the Print dialog. This option determines how printed material is organized. For example, if you have a document that is three pages long and you are printing multiple copies with the Collated option selected, the job prints pages 1, 2, and 3 in that order and then repeats. However, if the Collated option is not selected and you’re printing multiple copies of those same three pages, the job prints copies of page 1, then copies of page 2, and finally copies of page 3.

Availability
See Also
Declared In
PMCore.h

PMGetCopies

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

OSStatus PMGetCopies (
   PMPrintSettings printSettings,
   UInt32 *copies
);

Parameters
printSettings

The print settings object whose number of copies you want to obtain.

copies

A pointer to your UInt32 variable. On return, the variable contains the number of copies requested by the user.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
See Also
Declared In
PMCore.h

PMGetDuplex

Obtains the selected duplex mode.

OSStatus PMGetDuplex (
   PMPrintSettings printSettings,
   PMDuplexMode *duplexSetting
);

Parameters
printSettings

The print settings object whose duplex mode you want to obtain.

duplexSetting

A pointer to your PMDuplexMode variable. On return, the variable contains the duplex mode setting in the current print job. Possible values include:

  • kPMDuplexNone (one-sided printing)

  • kPMDuplexNoTumble (two-sided printing)

  • kPMDuplexTumble (two-sided printing with tumbling)

See “Duplex Modes” for a full description of the duplex mode constants.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Duplex printing is a print job that prints on both sides of the paper. The Two-Sided printing control is displayed in the Layout pane of the Print dialog.

Availability
Declared In
PMCore.h

PMGetFirstPage

Obtains the number of the first page to be printed.

OSStatus PMGetFirstPage (
   PMPrintSettings printSettings,
   UInt32 *first
);

Parameters
printSettings

The print settings object whose first page number you want to obtain.

first

A pointer to your UInt32 variable. On return, the variable contains the page number of the first page to print. The default first page number is 1.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You can use this function to obtain the page number entered by the user in the From field of the Print dialog. If the user selects the All button, the function returns a value of 1. If the user did not enter a value, the function returns the value of the previous call to PMSetFirstPage, if any, or the default value of 1.

Availability
See Also
Related Sample Code
Declared In
PMCore.h

PMGetLastPage

Obtains the number of the last page to be printed.

OSStatus PMGetLastPage (
   PMPrintSettings printSettings,
   UInt32 *last
);

Parameters
printSettings

The print settings object whose last page number you want to obtain.

last

A pointer to your UInt32 variable. On return, the variable contains the page number of the last page to print.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You use this function to obtain the page number entered by the user in the To field of the Print dialog. If the user did not enter a value, the function returns the value of the previous call to PMSetLastPage, if any, or a default value.

You should not look for the constant kPMPrintAllPages. That constant is used only with the PMSetLastPage and PMSetPageRange functions to specify a last page. It is not returned by the PMGetLastPage function.

Availability
See Also
Related Sample Code
Declared In
PMCore.h

PMGetOrientation

Obtains the current setting for page orientation.

OSStatus PMGetOrientation (
   PMPageFormat pageFormat,
   PMOrientation *orientation
);

Parameters
pageFormat

The page format object whose orientation you want to obtain.

orientation

A pointer to your PMOrientation variable. On return, the variable contains a constant value indicating the page orientation. Supported values are:

  • kPMPortrait

  • kPMLandscape

  • kPMReversePortrait (supported in Mac OS X v10.5 and later)

  • kPMReverseLandscape

See “Page Orientation Constants” for a complete description of the page orientation constants.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
See Also
Declared In
PMCore.h

PMGetPageFormatExtendedData

Obtains extended page format data previously stored by your application.

OSStatus PMGetPageFormatExtendedData (
   PMPageFormat pageFormat,
   OSType dataID,
   UInt32 *size,
   void *extendedData
);

Parameters
pageFormat

The page format object that contains your extended data.

dataID

A 4-character code that identifies your data. This is typically your application’s creator code. If your creator code is outside the ASCII 7-bit character range 0x20–0x7F, you need to use a different 4-character code.

size

A pointer to a value that specifies the size of the buffer you have allocated for the extended page format data. On return, this variable contains the number of bytes read into the buffer or the size of the extended data. You can pass the constant kPMDontWantSize if you do not need this information. (See “Data Not Wanted Constants” for more information.)

extendedData

A pointer to a buffer to receive the extended data. Pass the constant kPMDontWantData if you do not want to read the data. (See “Data Not Wanted Constants” for more information.)

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Your application typically needs to call the function PMGetPageFormatExtendedData two times in order to retrieve the extended page format data. The first time, pass the constant kPMDontWantData in the parameter extendedData to obtain the buffer size required for the extended data. Then allocate the buffer and call the function a second time to read the extended data into your buffer.

If you write a printing dialog extension for your application that stores data in the page format object, you use the function PMGetPageFormatExtendedData to retrieve the data associated with it.

Availability
See Also
Declared In
PMCore.h

PMGetPageFormatPaper

Obtains the paper associated with a page format object.

OSStatus PMGetPageFormatPaper (
   PMPageFormat format,
   PMPaper *paper
);

Parameters
pageFormat

The page format object whose paper you want to obtain.

paper

A pointer to your PMPaper variable. On return, the variable refers to a paper object that represents the paper associated with the specified page format. You should not release the paper object without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMGetPageRange

Obtains the valid range of pages that can be printed.

OSStatus PMGetPageRange (
   PMPrintSettings printSettings,
   UInt32 *minPage,
   UInt32 *maxPage
);

Parameters
printSettings

The print settings object whose page range you want to obtain.

minPage

A pointer to your UInt32 variable. On return, the variable contains the minimum page number allowed.

maxPage

A pointer to your UInt32 variable. On return, the variable contains the maximum page number allowed.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

The page range returned by the function PMGetPageRange is independent of the first and last page values returned by PMGetFirstPage and PMGetLastPage. See PMSetPageRange for more information.

Availability
See Also
Declared In
PMCore.h

PMGetPrintSettingsExtendedData

Obtains extended print settings data previously stored by your application.

OSStatus PMGetPrintSettingsExtendedData (
   PMPrintSettings printSettings,
   OSType dataID,
   UInt32 *size,
   void *extendedData
);

Parameters
printSettings

The print settings object whose extended data you want to obtain.

dataID

The unique 4-character code of the data to retrieve. This is typically your application’s creator code. However, if your creator code is outside the ASCII 7-bit character range 0x20–0x7F, you need to use a different 4-character code.

size

A pointer to a value that specifies the size of the buffer you have allocated for the extended print settings data. On return, this variable contains the number of bytes read into the buffer or the size of the extended data. You can pass the constant kPMDontWantSize if you do not need this information. (See “Data Not Wanted Constants” for more information.)

extendedData

A pointer to a buffer to receive the extended data. Pass the constant kPMDontWantData if you do not want to read the data. (See “Data Not Wanted Constants” for more information.)

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Your application typically needs to call PMGetPrintSettingsExtendedData two times in order to retrieve the extended print settings data. The first time, pass the constant kPMDontWantData in the extendedData parameter to obtain the buffer size required for the extended data. Then allocate the buffer and call the function a second time to read the extended data into your buffer.

You may find it easier to use the functions PMPrintSettingsSetValue and PMPrintSettingsGetValue to store and retrieve user-defined data in a print settings object. If you use these functions, make sure that the custom keys you define for your private data do not conflict with other print settings keys.

Availability
See Also
Declared In
PMCore.h

PMGetScale

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

OSStatus PMGetScale (
   PMPageFormat pageFormat,
   double *scale
);

Parameters
pageFormat

The page format object whose scaling factor you want to obtain.

scale

A pointer to your double-precision variable. On return, the variable contains the scaling factor expressed as a percentage. For example, a value of 100.0 means 100 percent (that is, no scaling); a value of 50.0 means 50 percent scaling.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
See Also
Declared In
PMCore.h

PMGetUnadjustedPageRect

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

OSStatus PMGetUnadjustedPageRect (
   PMPageFormat pageFormat,
   PMRect *pageRect
);

Parameters
pageFormat

The page format object whose unadjusted page rectangle you want to obtain.

pageRect

A pointer to your PMRect data structure. On return, the structure contains the size of the page rectangle, in points. The page rectangle is the area of the page to which an application can draw. The coordinates for the upper-left corner of the page rectangle are (0,0). See Supporting Printing in Your Carbon Application for more information on page and paper rectangles.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMGetUnadjustedPaperRect

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

OSStatus PMGetUnadjustedPaperRect (
   PMPageFormat pageFormat,
   PMRect *paperRect
);

Parameters
pageFormat

The page format object whose unadjusted paper rectangle you want to obtain.

paperRect

A pointer to your PMRect data structure. On return, the structure contains the physical size of the paper, in points. The coordinates of the upper-left corner of the paper rectangle are specified relative to the page rectangle. The coordinates of the upper-left corner of the page rectangle are always (0,0), which means the coordinates of the upper-left corner of the paper rectangle are always negative or (0,0). See Supporting Printing in Your Carbon Application for more information on page and paper rectangles.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMPageFormatCreateDataRepresentation

Creates a data representation of a page format object.

OSStatus PMPageFormatCreateDataRepresentation (
   PMPageFormat pageFormat,
   CFDataRef *data,
   PMDataFormat format
);

Parameters
pageFormat

The page format object to convert.

data

A pointer to your CFDataRef variable. On return, the variable refers to a new Core Foundation data object that contains a representation of the specified page format object in the specified data format. You are responsible for releasing the data object.

format

A constant that specifies the format of the data representation. Supported values are:

  • kPMDataFormatXMLDefault (compatible with all Mac OS X versions)

  • kPMDataFormatXMLMinimal (approximately 3-5 times smaller; compatible with Mac OS X v10.5 and later)

  • kPMDataFormatXMLCompressed (approximately 20 times smaller; compatible with Mac OS X v10.5 and later)

See “Data Representation Formats” for a full description of these formats.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function is typically used to convert a page format object into a data representation suitable for storage in a user document. For information about using a Core Foundation data object, see CFData Reference.

Before calling this function, you should call the function PMSessionValidatePageFormat to make sure the page format object contains valid values.

Availability
See Also
Declared In
PMCore.h

PMPageFormatCreateWithDataRepresentation

Creates a page format object from a data representation.

OSStatus PMPageFormatCreateWithDataRepresentation (
   CFDataRef data,
   PMPageFormat *pageFormat
);

Parameters
data

The data representation of a page format object. The data representation must have been previously created with the function PMPageFormatCreateDataRepresentation.

pageFormat

A pointer to your PMPageFormat variable. On return, the variable refers to a new page format object that contains the information stored in the specified data object. You are responsible for releasing the page format object with the function PMRelease.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function is typically used to convert a data representation stored in a user document back into a page format object. For information about creating a Core Foundation data object from raw data, see CFData Reference.

After calling this function, you should call the function PMSessionValidatePageFormat to make sure the page format object contains valid values.

Availability
See Also
Declared In
PMCore.h

PMPageFormatGetPrinterID

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

OSStatus PMPageFormatGetPrinterID (
   PMPageFormat pageFormat,
   CFStringRef *printerID
);

Parameters
pageFormat

The page format object whose printer identifier you want to obtain.

printerID

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string that contains the identifier of the formatting printer for the specified page format object. If the page format object does not have that information, the variable is set to NULL. You should not release the string without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Page format objects can be created a number of different ways and some of them do not require a specific printer. If the printer ID is known, the printer is displayed in the Page Setup dialog’s Format for pop-up menu. If the printer ID is not known, the default formatting printer is the generic Any Printer. The printing system provides default page and paper sizes for the generic printer.

Availability
Declared In
PMCore.h

PMPaperCreateCustom

Creates a custom paper object.

OSStatus PMPaperCreateCustom (
   PMPrinter printer,
   CFStringRef id,
   CFStringRef name,
   double width,
   double height,
   const PMPaperMargins *margins,
   PMPaper *paperP
);

Parameters
printer

A printer for which the specified paper size is appropriate.

id

A unique identifier for this custom paper. For example, you could create a UUID string and use it as the unique identifier.

name

The name to display to the user for this custom paper.

width

The width of the paper, in points.

height

The height of the paper, in points.

margins

A pointer to a PMPaperMargins structure that specifies the unprintable margins of the paper, in points. The four values in the structure specify the top, left, bottom, and right imageable area margins of the paper.

paperP

A pointer to your PMPaper variable. On return, the variable refers to a new custom paper object. You are responsible for releasing the paper object with the function PMRelease.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function creates a custom paper object appropriate for the specified printer. Custom papers are treated differently than built-in papers by the printing system. To obtain one of the available built-in papers for a given printer, you can use the function PMPrinterGetPaperList.

Availability
Declared In
PMCore.h

PMPaperCreateLocalizedName

Obtains the localized name for a given paper.

OSStatus PMPaperCreateLocalizedName (
   PMPaper paper,
   PMPrinter printer,
   CFStringRef *paperName
);

Parameters
paper

The paper whose localized name you want to obtain.

printer

The printer for which the localization should be performed.

paperName

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string that contains the localized name of the paper. This name is appropriate to display in the user interface. If an error occurs, the variable is set to NULL. You are responsible for releasing the string.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Not all printers have the same way of referring to a given paper. Generally, if you want to obtain the name of a paper, you want to localize the paper name for a particular printer. For example, if you were displaying a list of papers for a given printer, you would want the paper names to be localized for that printer.

Special Considerations

In Mac OS X v10.5 and later, Apple recommends using this function instead of PMPaperGetName.

Availability
Declared In
PMCore.h

PMPaperGetHeight

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

OSStatus PMPaperGetHeight (
   PMPaper paper,
   double *paperHeight
);

Parameters
paper

The paper whose height you want to obtain.

paperHeight

A pointer to your double-precision variable. On return, the variable contains the height of the specified paper, in points.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMPaperGetID

Obtains the identifier of a paper object.

OSStatus PMPaperGetID (
   PMPaper paper,
   CFStringRef *paperID
);

Parameters
paper

The paper whose identifier you want to obtain.

paperID

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string containing the unique identifier for this paper. You should not release the string without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMPaperGetMargins

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

OSStatus PMPaperGetMargins (
   PMPaper paper,
   PMPaperMargins *paperMargins
);

Parameters
paper

The paper whose margins you want to obtain.

paperMargins

A pointer to your PMPaperMargins structure. On return, the structure contains the unprintable margins of the specified paper, in points. The four values in the structure specify the top, left, bottom, and right imageable area margins of the paper.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMPaperGetName

Obtains the name for a given paper.

OSStatus PMPaperGetName (
   PMPaper paper,
   CFStringRef *paperName
);

Parameters
paper

The paper whose name you want to obtain.

paperName

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string containing the name for this paper. This name identifies the paper in the user interface. You should not release the string without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Special Considerations

This function does not necessarily return a paper name that’s localized for a given printer. In Mac OS X v10.5 and later, instead of using this function, Apple recommends using the function PMPaperCreateLocalizedName.

Availability
Declared In
PMCore.h

PMPaperGetPPDPaperName

Obtains the PPD paper name for a given paper.

OSStatus PMPaperGetPPDPaperName (
   PMPaper paper,
   CFStringRef *paperName
);

Parameters
paper

The paper whose PPD paper name you want to obtain.

paperName

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string that contains the PPD paper name for the specified paper. If an error occurs, the variable is set to NULL. You should not release the string without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

The Mac OS X printing system uses a PostScript Printer Description (PPD) file to describe a given printer and print queue for that printer. The PPD paper name is the name that uniquely identifies a given paper for the printer to which the paper corresponds. To obtain a list of papers for a given printer, use the function PMPrinterGetPaperList.

Availability
Declared In
PMCore.h

PMPaperGetPrinterID

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

OSStatus PMPaperGetPrinterID (
   PMPaper paper,
   CFStringRef *printerID
);

Parameters
paper

The paper whose printer ID you want to obtain.

printerID

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string that contains the printer ID for the specified paper. If an error occurs, the variable is set to NULL. You should not release the string without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Not all papers have a printer ID associated with them. If the printer ID is known, the printer is displayed in the Page Setup dialog’s Format for pop-up menu. If the printer ID is not known, the default formatting printer is the generic Any Printer. The printing system provides default paper sizes for the generic printer.

Availability
Declared In
PMCore.h

PMPaperGetWidth

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

OSStatus PMPaperGetWidth (
   PMPaper paper,
   double *paperWidth
);

Parameters
paper

The paper whose width you want to obtain.

paperWidth

A pointer to your double-precision variable. On return, the variable contains the width of the specified paper, in points.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMPaperIsCustom

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

Boolean PMPaperIsCustom (
   PMPaper paper
);

Parameters
paper

The paper you’re querying to determine whether it’s a custom paper.

Return Value

If true, the specified paper is a custom paper; otherwise, false.

Discussion

You can create a custom paper with the function PMPaperCreateCustom.

Availability
Declared In
PMCore.h

PMPresetCopyName

Obtains the localized name for a preset.

OSStatus PMPresetCopyName (
   PMPreset preset,
   CFStringRef *name
);

Parameters
preset

The preset object whose localized name you want to obtain. You can use the function PMPrinterCopyPresets to obtain the presets for a given printer.

paperID

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string containing the localized name of the specified preset. You are responsible for releasing the string.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMPresetCreatePrintSettings

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

OSStatus PMPresetCreatePrintSettings (
   PMPreset preset,
   PMPrintSession session,
   PMPrintSettings *printSettings
);

Parameters
preset

The preset whose settings you want to obtain. You can use the function PMPrinterCopyPresets to obtain the presets for a given printer.

session

The session you use to present the Print dialog.

printSettings

A pointer to your PMPrintSettings variable. On return, the variable refers to a print settings object with settings that correspond to the specified preset. You are responsible for releasing the print settings object with the function PMRelease.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMPresetGetAttributes

Obtains the attributes of a preset.

OSStatus PMPresetGetAttributes (
   PMPreset preset,
   CFDictionaryRef *attributes
);

Parameters
preset

The preset whose attributes you want to obtain. You can use the function PMPrinterCopyPresets to obtain the presets for a given printer.

attributes

A pointer to your CFDictionaryRef variable. On return, the variable refers to a Core Foundation dictionary containing the attributes of the specified preset, or NULL if the attributes could not be obtained. For more information about these attributes, see the Discussion. You should not release this dictionary without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

A preset has associated with it a dictionary containing the preset identifier, the localized name, and a description of the environment for which the preset is intended. In addition to these standard attributes, the preset you specify may contain additional attributes that reflect custom print settings.

Availability
Declared In
PMCore.h

PMPrinterCopyDescriptionURL

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

OSStatus PMPrinterCopyDescriptionURL (
   PMPrinter printer,
   CFStringRef descriptionType,
   CFURLRef *fileURL
);

Parameters
printer

The printer whose description file you want to obtain.

descriptionType

A constant that specifies the desired printer description file type. Currently, you must pass the constant kPMPPDDescriptionType.

fileURL

A pointer to your CFURLRef variable. On return, the variable refers to a Core Foundation URL that specifies the location of the file that contains a description of the specified printer. You are responsible for releasing the URL. If an error occurs, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You can use this function to locate the PostScript printer description (PPD) file for a printer.

Availability
Declared In
PMCore.h

PMPrinterCopyDeviceURI

Obtains the device URI of a given printer.

OSStatus PMPrinterCopyDeviceURI (
   PMPrinter printer,
   CFURLRef *deviceURI
);

Parameters
printer

The printer whose device URI you want to obtain.

deviceURI

A pointer to your CFURLRef variable. On return, the variable refers to a Core Foundation URL that specifies the printer's device URI. You are responsible for releasing the URL. If an error occurs, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

The device URI of a printer describes how to communicate with the device. For some devices, it also includes a unique identifier for the device.

Availability
Related Sample Code
Declared In
PMCore.h

PMPrinterCopyHostName

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

OSStatus PMPrinterCopyHostName (
   PMPrinter printer,
   CFStringRef *hostNameP
);

Parameters
printer

The printer whose print queue host name you want to obtain.

hostNameP

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string containing the name of the specified printer’s server. You are responsible for releasing the string.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function is typically used to obtain the name of the computer that hosts a shared printer, possibly for display in a user interface. In Mac OS X v10.5 and later, the typical way that users browse and communicate with a shared printer creates a local print queue and PMPrinterCopyHostName for such a print queue will return the name of the local host.

Availability
Declared In
PMCore.h

PMPrinterCopyPresets

Obtains a list of print settings presets for a printer.

OSStatus PMPrinterCopyPresets (
   PMPrinter printer,
   CFArrayRef *presetList
);

Parameters
printer

The printer whose presets you want to obtain.

presetList

A pointer to your CFArrayRef variable. On return, the variable refers to a Core Foundation array containing the presets for the specified printer. Each element in the array is an object of type PMPreset. You are responsible for releasing the array.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

A printer may have associated with it a list of preset settings. Each setting is optimized for a particular printing situation. This function returns all of the presets for a given printer. To obtain more information about a particular preset, you can use the function PMPresetGetAttributes. To create a print settings object that contains the settings of a preset, call PMPresetCreatePrintSettings.

Availability
Declared In
PMCore.h

PMPrinterCreateFromPrinterID

Creates a printer object from a print queue identifier.

PMPrinter PMPrinterCreateFromPrinterID (
   CFStringRef printerID
);

Parameters
printerID

The unique identifier of a print queue.

Return Value

A new printer object, or NULL if no print queue is available with the specified identifier. You are responsible for releasing the printer object with the function PMRelease.

Discussion

This function is typically used to re-create a printer object using the print queue ID obtained by a call to PMPrinterGetID at an earlier time. If the print queue is deleted after obtaining the ID, this function returns NULL for that ID.

Availability
See Also
Declared In
PMCore.h

PMPrinterGetCommInfo

Obtains information about the communication channel for a printer.

OSStatus PMPrinterGetCommInfo (
   PMPrinter printer,
   Boolean *supportsTransparentP,
   Boolean *supportsEightBitP
);

Parameters
printer

The printer whose information you want to obtain.

supportsTransparentP

A pointer to your Boolean variable. On return, true indicates that the communication channel to the specified printer supports bytes in the range 0x0–0x1F; otherwise, false.

supportsEightBitP

A pointer to your Boolean variable. On return, true indicates that the communication channel to the specified printer supports bytes in the range 0x80–0xFF; otherwise, false.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function is typically relevant only to PostScript printers. All PostScript printers, regardless of what communications channel is used to send data to them, support data in the range 0x20–0x7F. Many communications channels can support data outside this range. You can use this function to determine whether the communications channel to the specified printer also supports bytes in the ranges 0x0–0x1F and 0x80–0xFF.

Availability
Declared In
PMCore.h

PMPrinterGetDriverCreator

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

OSStatus PMPrinterGetDriverCreator (
   PMPrinter printer,
   OSType *creator
);

Parameters
printer

The printer whose driver creator you want to obtain.

creator

On return, the 4-byte creator code of the driver (for example, 'APPL' for an Apple printer driver).

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function is not recommended because it makes your application driver-dependent.

Availability
Declared In
PMCore.h

PMPrinterGetDriverReleaseInfo

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

OSStatus PMPrinterGetDriverReleaseInfo (
   PMPrinter printer,
   VersRec *release
);

Parameters
printer

The printer whose driver version you want to obtain.

release

A pointer to your VersRec data structure. On return, the structure contains the driver’s short and long version strings and country code.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function is not recommended because it makes your application driver-dependent. If you do use this function, you must call it between the creation and release of a printing session. See the function PMCreateSession.

Availability
Declared In
PMCore.h

PMPrinterGetID

Returns the unique identifier of a printer.

CFStringRef PMPrinterGetID (
   PMPrinter printer
);

Parameters
printer

The printer whose identifier you want to obtain.

Return Value

The identifier of the specified printer. You should not release the string without first retaining it. If the specified printer is not valid, this function returns NULL.

Discussion

You can use the function PMPrinterGetID to capture information about a printer for later use. To create a printer object from a printer ID returned by this function, use the function PMPrinterCreateFromPrinterID.

Availability
Related Sample Code
Declared In
PMCore.h

PMPrinterGetIndexedPrinterResolution

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

OSStatus PMPrinterGetIndexedPrinterResolution (
   PMPrinter printer,
   UInt32 index,
   PMResolution *resolutionP
);

Parameters
printer

The printer whose resolution you want to obtain.

index

An index into the range of resolution settings supported by the specified printer. Index values begin at 1.

res

A pointer to your PMResolution data structure. On return, the structure contains the printer resolution setting associated with the index value.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. Before you call this function, you must call the function PMPrinterGetPrinterResolutionCount to obtain the number of resolution settings supported by the specified printer.

Availability
Declared In
PMCore.h

PMPrinterGetLanguageInfo

Obtains information about the imaging language for the specified printer.

OSStatus PMPrinterGetLanguageInfo (
   PMPrinter printer,
   PMLanguageInfo *info
);

Parameters
printer

The printer whose imaging language information you want to obtain.

info

A pointer to your PMLanguageInfo data structure. On return, the structure contains the printer’s language level, version, and release information. The format of the returned data uses the syntax of the PostScript language.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

The function PMPrinterGetLanguageInfo is useful only for PostScript printers. You must call this function between the creation and release of a printing session.

Availability
Declared In
PMCore.h

PMPrinterGetLocation

Returns the location of a printer.

CFStringRef PMPrinterGetLocation (
   PMPrinter printer
);

Parameters
printer

The printer whose location you want to obtain.

Return Value

The location of the specified printer. You should not release the string without first retaining it. If the printer is not valid, this function returns NULL.

Discussion

The location of a printer is specified when a user creates a print queue for the printer. In some cases, the printing system automatically determines the location. For example, the location may be set to “Local Zone”. The user creating the print queue can also set the location.

Availability
Related Sample Code
Declared In
PMCore.h

PMPrinterGetMakeAndModelName

Obtains the manufacturer and model name of the specified printer.

OSStatus PMPrinterGetMakeAndModelName (
   PMPrinter printer,
   CFStringRef *makeAndModel
);

Parameters
printer

The printer whose manufacturer and model name you want to obtain.

makeAndModel

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string containing the manufacturer and model name of the specified printer. You should not release the string without first retaining it. If an error occurs, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Related Sample Code
Declared In
PMCore.h

PMPrinterGetMimeTypes

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

OSStatus PMPrinterGetMimeTypes (
   PMPrinter printer,
   PMPrintSettings settings,
   CFArrayRef *mimeTypes
);

Parameters
printer

The printer whose supported MIME types you want to obtain.

settings

The print settings for the print job. The print settings object contains the job destination, which affects the available types. This parameter may be NULL.

mimeTypes

A pointer to your CFArrayRef variable. On return, the variable refers to a Core Foundation array containing the MIME types supported by the specified printer. Each element in the array is a Core Foundation string. You should not release the array without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function retrieves the types of data that can be submitted to a printer with the specified print settings; for example, application/pdf. This function is typically used in conjunction with the function PMPrinterPrintWithFile.

Availability
Declared In
PMCore.h

PMPrinterGetName

Returns the human-readable name of a printer.

CFStringRef PMPrinterGetName (
   PMPrinter printer
);

Parameters
printer

The printer whose name you want to obtain.

Return Value

The name of the specified printer. This name identifies the printer in the user interface. You should not release the string without first retaining it.

Availability
Related Sample Code
Declared In
PMCore.h

PMPrinterGetOutputResolution

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

OSStatus PMPrinterGetOutputResolution (
   PMPrinter printer,
   PMPrintSettings printSettings,
   PMResolution *resolutionP
);

Parameters
printer

The printer whose output resolution you want to obtain.

printSettings

The print settings you want to use.

resolutionP

A pointer to your PMResolution structure. On return, the structure contains the output resolution of the specified printer in pixels per inch.

Return Value

A result code. If the resolution cannot be reliably determined, this function returns an error.

Discussion

Some printers allow programmatic control of their hardware output resolution on a print job basis. The hardware resolution is determined by the combination of printer and print settings used for the print job. This function returns the best guess as to what printer resolution setting will be used for the destination print job.

Most applications do not need to use this function because they draw the same content regardless of the destination device. For those few applications that do adjust their drawing based on the output device, they should only do so when the print job destination is kPMDestinationPrinter or kPMDestinationFax. You can use the function PMSessionGetDestinationType to determine the destination for a print job.

This function should be used after displaying the Print dialog to the user so that it correctly reflects changes in print settings performed prior to printing.

Availability
See Also
Declared In
PMCore.h

PMPrinterGetPaperList

Obtains the list of papers available for a printer.

OSStatus PMPrinterGetPaperList (
   PMPrinter printer,
   CFArrayRef *paperList
);

Parameters
printer

The printer whose paper list you want to obtain.

paperList

A pointer to your CFArrayRef variable. On return, the variable refers to a Core Foundation array containing the paper list for the specified printer. Each element in the array is an object of type PMPaper. You should not release the array without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function obtains a list of the papers that a given printer claims to support. The paper list does not include any custom paper sizes that may be available.

Availability
Declared In
PMCore.h

PMPrinterGetPrinterResolutionCount

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

OSStatus PMPrinterGetPrinterResolutionCount (
   PMPrinter printer,
   UInt32 *countP
);

Parameters
printer

The printer whose number of resolution settings you want to obtain.

count

A pointer to your UInt32 variable. On return, the variable contains the number of resolutions that are supported for the specified printer.

Return Value

A result code. The result code kPMNotImplemented indicates that the printer driver does not support multiple resolution settings.

Availability
Declared In
PMCore.h

PMPrinterGetState

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

OSStatus PMPrinterGetState (
   PMPrinter printer,
   PMPrinterState *state
);

Parameters
printer

The printer whose queue state you want to obtain.

state

A pointer to your PMPrinterState variable. On return, the variable contains a constant that indicates the current state of the print queue for the specified printer. Supported values are:

  • kPMPrinterIdle (queue is idle)

  • kPMPrinterProcessing (queue is processing a job)

  • kPMPrinterStopped (queue is stopped)

See “Print Queue States” for a complete description of these constants.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Related Sample Code
Declared In
PMCore.h

PMPrinterIsDefault

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

Boolean PMPrinterIsDefault (
   PMPrinter printer
);

Parameters
printer

The printer you’re querying to determine whether it is the default printer.

Return Value

If true, the specified printer is the default printer for the current user; otherwise, false.

Discussion

The default printer is the printer selected by default in the Print dialog.

Availability
Related Sample Code
Declared In
PMCore.h

PMPrinterIsFavorite

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

Boolean PMPrinterIsFavorite (
   PMPrinter printer
);

Parameters
printer

The printer you’re looking for in the favorite printer list.

Return Value

If true, the specified printer is in the user’s list of favorite printers; otherwise, false.

Availability
Related Sample Code
Declared In
PMCore.h

PMPrinterIsPostScriptCapable

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

Boolean PMPrinterIsPostScriptCapable (
   PMPrinter printer
);

Parameters
printer

The printer you’re querying to determine whether it’s PostScript capable.

Return Value

If true, the specified printer is a PostScript capable printer; otherwise, false.

Discussion

A printer that is PostScript capable is not necessarily a PostScript printer. The Mac OS X printing system can render PostScript content on non-PostScript printers.

Availability
Declared In
PMCore.h

PMPrinterIsPostScriptPrinter

Determines whether a printer is a PostScript printer.

OSStatus PMPrinterIsPostScriptPrinter (
   PMPrinter printer,
   Boolean *isPSPrinter
);

Parameters
printer

The printer you’re querying to determine whether it’s a PostScript printer.

isPSPrinter

A pointer to your Boolean variable. On return, true indicates that the specified printer is a PostScript printer; otherwise, false.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

A printer is a PostScript printer if the printer driver takes PostScript directly.

Availability
Declared In
PMCore.h

PMPrinterIsRemote

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

OSStatus PMPrinterIsRemote (
   PMPrinter printer,
   Boolean *isRemoteP
);

Parameters
printer

The printer you’re querying to determine whether it is hosted by a remote print server.

isRemoteP

A pointer to your Boolean variable. On return, true indicates that the printer is hosted by a remote print server; otherwise, false.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

If this function returns true, the printer is hosted by a remote print server and the printer can be considered a shared printer.

In Mac OS X, the typical way that users create a print queue for a shared printer is by browsing. Print queues for shared printers that are created by browsing are marked as remote queues, and PMPrinterIsRemote returns true for such printers. However, expert users can create a local queue for a remote printer manually, and such a printer does not appear to be remote printer.

Whether a printer is remote is derived from the CUPS printer-type attribute for the print queue.

Availability
Related Sample Code
Declared In
PMCore.h

PMPrinterPrintWithFile

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

OSStatus PMPrinterPrintWithFile (
   PMPrinter printer,
   PMPrintSettings settings,
   PMPageFormat format,
   CFStringRef mimeType,
   CFURLRef fileURL
);

Parameters
printer

The destination printer.

settings

The print settings for the print job.

format

The physical page size and orientation with which the document should be printed. This parameter can be NULL.

mimeType

The MIME type of the data to be printed. If this parameter is NULL, the MIME type will be determined automatically. You can obtain a list of the MIME types supported by a given printer using the function PMPrinterGetMimeTypes.

fileURL

The URL of the file that supplies the print data.

Return Value

A result code. See “Core Printing Result Codes.” If the specified printer cannot handle the file's MIME type, a non-zero error code is returned.

Discussion

This function can fail if the specified printer cannot handle the file’s MIME type. Use the function PMPrinterGetMimeTypes to check whether a MIME type is supported.

Availability
See Also
Declared In
PMCore.h

PMPrinterPrintWithProvider

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

OSStatus PMPrinterPrintWithProvider (
   PMPrinter printer,
   PMPrintSettings settings,
   PMPageFormat format,
   CFStringRef mimeType,
   CGDataProviderRef provider
);

Parameters
printer

The destination printer.

settings

The print settings for the print job.

format

The physical page size and orientation with which the document should be printed. This parameter can be NULL.

mimeType

The MIME type of the data to be printed. This parameter cannot be NULL. If you want automatic typing, use the function PMPrinterPrintWithFile instead. You can obtain a list of the MIME types supported by a given printer using the function PMPrinterGetMimeTypes.

provider

The data provider that supplies the print data.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function can fail if the specified printer cannot handle the data provider’s MIME type. Use the function PMPrinterGetMimeTypes to check whether a MIME type is supported.

Special Considerations

In Mac OS X v10.4 and earlier, this function is not implemented and returns the error code –1 when called. You can write your print data to a file and use PMPrinterPrintWithFile instead.

Availability
See Also
Declared In
PMCore.h

PMPrinterSetDefault

Sets the default printer for the current user.

OSStatus PMPrinterSetDefault (
   PMPrinter printer
);

Parameters
printer

The printer to set as the default printer.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

The default printer is the printer selected by default in the Print dialog.

This function is rarely used. Most applications do not set the default printer directly, but instead let the user choose the default printer in the Print & Fax preference pane of System Preferences.

Availability
Declared In
PMCore.h

PMPrinterSetOutputResolution

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

OSStatus PMPrinterSetOutputResolution (
   PMPrinter printer,
   PMPrintSettings printSettings,
   const PMResolution *resolutionP
);

Parameters
printer

The printer whose output resolution you want to change.

printSettings

The print settings object used for the print job.

resolutionP

A pointer to a PMResolution structure that specifies the desired resolution in pixels per inch.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Some printers allow programmatic control of their hardware output resolution on a print job basis. The hardware resolution is determined by the combination of printer and print settings used for the print job. This function configures the print settings to the closest resolution setting that can be used for the destination print job. Note that not all printers allow control of their resolution setting.

This function is rarely used. Most applications do not set the output resolution but instead use the setting supplied by the user in the Print dialog.

Availability
See Also
Declared In
PMCore.h

PMPrinterWritePostScriptToURL

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

OSStatus PMPrinterWritePostScriptToURL (
   PMPrinter printer,
   PMPrintSettings settings,
   PMPageFormat format,
   CFStringRef mimeType,
   CFURLRef sourceFileURL,
   CFURLRef destinationFileURL
);

Parameters
printer

The destination printer for which printer-ready PostScript will be generated.

settings

The print settings for the print job.

format

The page format specifying the physical page size and orientation on which the document should be printed.

mimeType

The MIME type of the file to be printed. If you pass NULL, the file is typed automatically. You can obtain a list of the MIME types supported by a given printer using the function PMPrinterGetMimeTypes.

sourceFileURL

A URL specifying the input file to be converted to printer-ready PostScript data. Only file-based URLs are supported.

destinationFileURL

A URL specifying the destination file to be created. If the file already exists, it will be overwritten. Only file-based URLs are supported.

Return Value

A result code. If the printing system cannot convert the input MIME type to PostScript, this function fails and returns an error.

Discussion

This function is synchronous; the conversion of the input file to PostScript is performed before the function returns. This can take a significant amount of time for longer documents. You may want to perform this operation on a thread other than the main application thread or fork a separate process for this purpose.

Availability
Declared In
PMCore.h

PMPrintSettingsCopyAsDictionary

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

OSStatus PMPrintSettingsCopyAsDictionary (
   PMPrintSettings printSettings,
   CFDictionaryRef *settingsDictionary
);

Parameters
printSettings

The print settings object with the desired settings.

settingsDictionary

A pointer to your CFDictionaryRef variable. On return, the variable refers to a Core Foundation dictionary that contains the settings in the specified print settings object. Some of the keys in this dictionary are currently defined in PMTicket.h; other keys are user-defined. You are responsible for releasing the dictionary. If an error occurs, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Most developers have no need to use this function. However, one way this function might be useful would be to enumerate all the entries in a print settings object for inspection.

Availability
Declared In
PMCore.h

PMPrintSettingsCopyKeys

Obtains the keys for items in a print settings object.

OSStatus PMPrintSettingsCopyKeys (
   PMPrintSettings printSettings,
   CFArrayRef *settingsKeys
);

Parameters
printSettings

The print settings object with the desired keys.

settingsKeys

A pointer to your CFArrayRef variable. On return, the variable refers to a Core Foundation array that contains the keys for items in the specified print settings object. Each of these keys may be passed to the function PMPrintSettingsGetValue to obtain a value. You are responsible for releasing the array. If an error occurs, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function provides an array of the keys in a print settings object. You could get the values for the keys in the array with PMPrintSettingsGetValue, or use the keys to look up the values in the dictionary returned by PMPrintSettingsCopyAsDictionary.

Availability
Declared In
PMCore.h

PMPrintSettingsCreateDataRepresentation

Creates a data representation of a print settings object.

OSStatus PMPrintSettingsCreateDataRepresentation (
   PMPrintSettings printSettings,
   CFDataRef *data,
   PMDataFormat format
);

Parameters
printSettings

The print settings object to convert.

data

A pointer to your CFDataRef variable. On return, the variable refers to a new Core Foundation data object that contains a representation of the specified print settings object in the specified data format. You are responsible for releasing the data object.

format

A constant that specifies the format of the data representation. Supported values are:

  • kPMDataFormatXMLDefault (compatible with all Mac OS X versions)

  • kPMDataFormatXMLMinimal (approximately 3-5 times smaller; compatible with Mac OS X v10.5 and later)

  • kPMDataFormatXMLCompressed (approximately 20 times smaller; compatible with Mac OS X v10.5 and later)

See “Data Representation Formats” for a full description of these formats.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function is typically used to convert a print settings object into a data representation suitable for storage in a user document. For information about using a Core Foundation data object, see CFData Reference.

Before calling this function, you should call the function PMSessionValidatePrintSettings to make sure the print settings object contains valid values.

Apple recommends that you do not reuse the print settings information if the user prints the document again. The information supplied by the user in the Print dialog should pertain to the document only while the document prints, so there is no need to save the print settings object.

Availability
See Also
Declared In
PMCore.h

PMPrintSettingsCreateWithDataRepresentation

Creates a print settings object from a data representation.

OSStatus PMPrintSettingsCreateWithDataRepresentation (
   CFDataRef data,
   PMPrintSettings *printSettings
);

Parameters
data

The data representation of a print settings object. The data representation must have been previously created with the function PMPrintSettingsCreateDataRepresentation.

printSettings

A pointer to your PMPrintSettings variable. On return, the variable refers to a new print settings object that contains the printing information stored in the specified data object. You are responsible for releasing the print settings object with the function PMRelease.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function is typically used to convert a data representation stored in a user document back into a print settings object. For information about creating a Core Foundation data object from raw data, see CFData Reference.

After calling this function, you should call the function PMSessionValidatePrintSettings to make sure the print settings object contains valid values.

Availability
See Also
Declared In
PMCore.h

PMPrintSettingsGetJobName

Obtains the name of a print job.

OSStatus PMPrintSettingsGetJobName (
   PMPrintSettings printSettings,
   CFStringRef *name
);

Parameters
printSettings

The print settings for the current print job.

name

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string containing the name of the print job. This is the same job name you set using the function PMPrintSettingsSetJobName. You should not release the string without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
See Also
Declared In
PMCore.h

PMPrintSettingsGetValue

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

OSStatus PMPrintSettingsGetValue (
   PMPrintSettings printSettings,
   CFStringRef key,
   CFTypeRef *value
);

Parameters
printSettings

The print settings object you want to access.

key

A string constant that specifies the key for the desired setting. Some keys are currently defined in PMTicket.h; other keys are user-defined.

value

A pointer to your Core Foundation variable. On return, the variable refers to a Core Foundation object that corresponds to the specified key. If no corresponding object exists, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function, together with the function PMPrintSettingsSetValue, makes it possible to access print settings directly.

Availability
See Also
Declared In
PMCore.h

PMPrintSettingsSetJobName

Specifies the name of a print job.

OSStatus PMPrintSettingsSetJobName (
   PMPrintSettings printSettings,
   CFStringRef name
);

Parameters
printSettings

The print settings object whose job name you want to set.

name

The new name for the print job.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

If you’re using the Print dialog, you should call this function before presenting the dialog. You are strongly encouraged to create a print job name that’s meaningful to the user and use this function to set the name; this produces the best user experience. If you do not specify the print job name, the printing system creates an appropriate job name for you.

If you call this function after initiating a print job, the change is ignored for the current job.

Availability
See Also
Declared In
PMCore.h

PMPrintSettingsSetValue

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

OSStatus PMPrintSettingsSetValue (
   PMPrintSettings printSettings,
   CFStringRef key,
   CFTypeRef value,
   Boolean locked
);

Parameters
printSettings

The print settings object you want to update.

key

A string constant that specifies the key for the desired setting. Some keys are currently defined in PMTicket.h; other keys are user-defined.

value

A Core Foundation object that corresponds to the specified key. If you pass NULL, any existing setting for the specified key is removed.

locked

If true, the item being set should be locked; otherwise, false. Currently, you should always pass false.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function makes it possible to add, change, or remove print settings directly. Print settings are stored as key-value pairs. The keys are Core Foundation strings and the corresponding values are Core Foundation objects.

You can use this function to store user-defined data in a print settings object. You should make sure that the custom keys you define for your private data do not conflict with any other keys in the object. Each data item you store needs to be a Core Foundation object. You can use the function PMPrintSettingsGetValue to retrieve your private data.

If you call this function after initiating a print job (for example, by calling PMSessionBeginCGDocument), the change is ignored for the current job.

Availability
See Also
Declared In
PMCore.h

PMPrintSettingsToOptions

Converts print settings into a CUPS options string.

OSStatus PMPrintSettingsToOptions (
   PMPrintSettings settings,
   char **options
);

Parameters
settings

The print settings to convert.

options

A pointer to a C string. On return, a CUPS options string describing the print settings, or NULL if the print settings could not be converted. The function allocates storage for the string. You are responsible for freeing the storage.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function creates a CUPS options string that captures the data in the specified print settings object. In Mac OS X v10.5 and later, Apple recommends that you use the PMPrintSettingsToOptionsWithPrinterAndPageFormat function instead.

Availability
Declared In
PMCore.h

PMPrintSettingsToOptionsWithPrinterAndPageFormat

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

OSStatus PMPrintSettingsToOptionsWithPrinterAndPageFormat (
   PMPrintSettings settings,
   PMPrinter printer,
   PMPageFormat pageFormat,
   char **options
);

Parameters
settings

The print settings to convert.

printer

The printer to use for converting the print settings. This parameter must not be NULL.

pageFormat

The page format to convert, or NULL to specify default page format data.

options

A pointer to a C string. On return, a CUPS option string with the specified print settings and page format data, or NULL if the data could not be converted. The function allocates storage for the string. You are responsible for freeing the storage.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function creates a CUPS options string for the destination printer that captures the data in the specified print settings and page format objects. For example, you could pass this string to the function PMWorkflowSubmitPDFWithOptions to submit a PDF file for workflow processing. You could also use the options string to run a CUPS filter directly.

Availability
Declared In
PMCore.h

PMRelease

Releases a printing object by decrementing its reference count.

OSStatus PMRelease (
   PMObject object
);

Parameters
object

The printing object you want to release.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Your application should use the PMRelease function to release any printing objects it creates or retains. When an object’s reference count reaches 0, the object is deallocated.

For example, to terminate a printing session created with the function PMCreateSession, pass the associated PMPrintSession object to PMRelease. To release printing objects created with the functions PMCreatePageFormat and PMCreatePrintSettings, pass the associated PMPageFormat and PMPrintSettings objects to PMRelease.

Availability
See Also
Related Sample Code
Declared In
PMCore.h

PMRetain

Retains a printing object by incrementing its reference count.

OSStatus PMRetain (
   PMObject object
);

Parameters
object

The printing object you want to retain.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You should retain a printing object when you receive it from elsewhere (that is, you did not create or copy it) and you want it to persist. If you retain a printing object, you are responsible for releasing it. (See PMRelease.) You can use the function PMRetain to increment a printing object’s reference count so that multiple threads or routines can use the object without the risk of another thread or routine deallocating the object.

Availability
See Also
Declared In
PMCore.h

PMServerCreatePrinterList

Creates a list of printers available to a print server.

OSStatus PMServerCreatePrinterList (
   PMServer server,
   CFArrayRef *printerList
);

Parameters
server

The print server whose printers you want to obtain. To specify the local print server, pass the constant kPMServerLocal. Currently, you may specify only the local print server.

printerList

A pointer to your CFArrayRef variable. On return, the variable refers to a Core Foundation array containing the printers available to the specified print server. Each element in the array is a PMPrinter object. You are responsible for releasing the array.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Related Sample Code
Declared In
PMCore.h

PMServerLaunchPrinterBrowser

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

OSStatus PMServerLaunchPrinterBrowser (
   PMServer server,
   CFDictionaryRef options
);

Parameters
server

The print server to browse. Pass kPMServerLocal to specify the local print server. Currently, you may specify only the local print server.

options

This parameter is reserved for future use. At the present time, pass NULL. Passing NULL presents the printer browser in the default fashion.

Return Value

A result code. See “Core Printing Result Codes.” If you specify a server whose printers cannot be browsed, this function returns the error code kPMInvalidParameter.

Discussion

This function displays the standard printer browser to allow the user to create a new print queue.

Availability
Declared In
PMCore.h

PMSessionBeginCGDocumentNoDialog

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

OSStatus PMSessionBeginCGDocumentNoDialog (
   PMPrintSession printSession,
   PMPrintSettings printSettings,
   PMPageFormat pageFormat
);

Parameters
printSession

The printing session that provides a context for the new print job.

printSettings

The print settings to use for the new print job.

pageFormat

The page format to use for the new print job.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function starts a print job that draws directly into a Quartz graphics context and should be called within your application’s print loop. This function is similar to the function PMSessionBeginCGDocument except that the printing status dialog is suppressed.

You must call PMSessionBeginCGDocumentNoDialog between the creation and release of a printing session. See the function PMCreateSession. If you present a printing dialog before you call PMSessionBeginCGDocumentNoDialog, when calling this function you should use the same PMPrintSession object you used to present the dialog.

Before you call PMSessionBeginCGDocumentNoDialog, you should call PMSessionValidatePrintSettings and PMSessionValidatePageFormat to make sure the specified print settings and page format objects are updated and valid. After you call PMSessionBeginCGDocumentNoDialog, if you call a function that changes the specified print settings or page format object, the change is ignored for the current print job.

During the print job, the caller cannot obtain a Quickdraw graphics port for the printing session but can only obtain a Quartz graphics context. As a result, this function should be used in conjunction with PMSessionGetCGGraphicsContext instead of PMSessionGetGraphicsContext.

This function must be called before its corresponding End function (PMSessionEndDocumentNoDialog). If the function PMSessionBeginCGDocumentNoDialog returns noErr, you must later call the End function, even if errors occur within the scope of the Begin and End functions.

The printing system automatically handles printing multiple copies. Your application does not need to perform any tasks other than specifying the number of copies in the printing session.

Availability
Declared In
PMCore.h

PMSessionBeginPageNoDialog

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

OSStatus PMSessionBeginPageNoDialog (
   PMPrintSession printSession,
   PMPageFormat pageFormat,
   const PMRect *pageFrame
);

Parameters
printSession

The printing session that provides a context for the print job.

pageFormat

The page format for the new page. If you pass NULL, the printing system uses the page format you passed to PMSessionBeginCGDocumentNoDialog.

pageFrame

You should pass NULL, as this parameter is currently unsupported.

Return Value

A result code. If the user cancels the print job, this function returns kPMCancel.

Discussion

This function is similar to the function PMSessionBeginPage except that the function PMSessionBeginPageNoDialog suppresses the printing status dialog. You must call this function between the creation and release of a printing session. See the function PMCreateSession. You must call the functions PMSessionBeginPageNoDialog and PMSessionEndPageNoDialog within the scope of calls to the Begin print job function (PMSessionBeginCGDocumentNoDialog) and the End print job function (PMSessionEndDocumentNoDialog).

You should call the function PMSessionError immediately before you call PMSessionBeginPageNoDialog. If PMSessionError returns an error, then you should not call the function PMSessionBeginPageNoDialog. Because PMSessionBeginPage also initializes the printing graphics context, your application should not make assumptions about the state of the context (for example, the current font) between successive pages. After each call to PMSessionBeginPageNoDialog, your application should call PMSessionGetCGGraphicsContext to obtain the current printing context.

If the function PMSessionBeginPageNoDialog returns noErr, you must later call the function PMSessionEndPageNoDialog, even if errors occur within the scope of PMSessionBeginPageNoDialog and PMSessionEndPageNoDialog.

The printing system automatically handles printing multiple copies. Your application does not need to perform any tasks other than specifying the number of copies in the printing session.

Special Considerations

Prior to Mac OS X v10.5, the pageFormat parameter is ignored. In Mac OS X v10.5 and later, the printing system supports multiple orientations within a print job. When you call this function and supply a page format, the orientation specified in the page format is used for the current page. Other settings in the page format, such as paper size or scaling, are ignored.

Availability
Declared In
PMCore.h

PMSessionCopyDestinationFormat

Obtains the destination format for a print job.

OSStatus PMSessionCopyDestinationFormat (
   PMPrintSession printSession,
   PMPrintSettings printSettings,
   CFStringRef *destFormatP
);

Parameters
printSession

The printing session that provides a context for the print job.

printSettings

The print settings object for the print job whose destination format you want to obtain.

destFormatP

A pointer to your CFStringRef variable. On return, the variable refers to a Core Foundation string that contains the destination format for the print job. You are responsible for releasing the string. Currently, there are two possible values: kPMDocumentFormatPDF or kPMDocumentFormatPostScript.

If an error occurs, the variable is set to NULL. If the function executes without error and the variable is set to NULL, the print job is set to use the default destination format.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

Availability
Declared In
PMCore.h

PMSessionCopyDestinationLocation

Obtains a destination location for a print job.

OSStatus PMSessionCopyDestinationLocation (
   PMPrintSession printSession,
   PMPrintSettings printSettings,
   CFURLRef *destLocationP
);

Parameters
printSession

The printing session that provides a context for the print job.

printSettings

The print settings for the print job whose destination location you want to obtain.

destLocationP

A pointer to your CFURLRef variable. On return, the variable refers to a Core Foundation URL that specifies the destination location of the print job. You are responsible for releasing the URL. If NULL is returned and the function executes without error (result code is noErr), the print job uses the default destination location for the current destination type. If an error occurs, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

Some destination types define a specific kind of destination location for a print job. For example, the destination type kPMDestinationFile uses a file system URL to specify where a new file should be created for the print job’s output.

Availability
Declared In
PMCore.h

PMSessionCopyOutputFormatList

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

OSStatus PMSessionCopyOutputFormatList (
   PMPrintSession printSession,
   PMDestinationType destType,
   CFArrayRef *documentFormatP
);

Parameters
printSession

The printing session that provides a context for the print job. The printer associated with this session is queried for the MIME types it supports.

destType

A destination type that specifies the destination for which you want to obtain valid destination formats. See “Destination Types” for a list of the possible destination types a print job can have.

documentFormatP

A pointer to your CFArrayRef variable. On return, the variable refers to a Core Foundation array that contains a list of destination formats that can be generated for the current print destination. See “Document Format Strings” for a list of some of the output formats that can be returned.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

Availability
Declared In
PMCore.h

PMSessionCreatePageFormatList

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

OSStatus PMSessionCreatePageFormatList (
   PMPrintSession printSession,
   PMPrinter printer,
   CFArrayRef *pageFormatList
);

Parameters
printSession

The current printing session.

printer

The printer whose list of page sizes you want to enumerate.

pageFormatList

A pointer to your CFArrayRef variable. On return, the variable refers to a Core Foundation array that contains the page format (PMPageFormat) objects associated with the specified printer. You are responsible for releasing the array. Each page format object describes a paper size available for the specified printer. If the function fails, then on return the array is NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

You can use this function to find the available sheet sizes (and the imageable area for them) for a given printer. After you obtain the page format list, you can call the function PMGetUnadjustedPaperRect for each page format object in the list to obtain the sheet rectangle size. Once you find the paper size you want, call PMGetUnadjustedPageRect to obtain the imageable area for that paper size.

Availability
Declared In
PMCore.h

PMSessionCreatePrinterList

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

OSStatus PMSessionCreatePrinterList (
   PMPrintSession printSession,
   CFArrayRef *printerList,
   CFIndex *currentIndex,
   PMPrinter *currentPrinter
);

Parameters
printSession

The printing session whose printer list you want to obtain.

printerList

A pointer to your CFArrayRef variable. On return, the variable refers to a Core Foundation array containing a list of printers available in the specified printing session. Each element in the array is a Core Foundation string that contains a printer’s name as shown in the user interface. You are responsible for releasing the array.

currentIndex

A pointer to your CFIndex variable. On return, the variable contains a value specifying where the current printer is in the printer list.

currentPrinter

A pointer to your PMPrinter variable. On return, the variable refers to a printer object that represents the current printer. You should not release the printer object without first retaining it. If the printer is the generic printer, the variable is set to NULL.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

You can call the function PMSessionCreatePrinterList to obtain a valid printer name to pass to the function PMSessionSetCurrentPrinter.

Special Considerations

In Mac OS X v10.2 and later, Apple recommends using the function PMServerCreatePrinterList instead. PMServerCreatePrinterList doesn’t require a PMSession object; it can be called at any time. It also works directly with PMPrinter objects.

Availability
See Also
Declared In
PMCore.h

PMSessionDefaultPageFormat

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

OSStatus PMSessionDefaultPageFormat (
   PMPrintSession printSession,
   PMPageFormat pageFormat
);

Parameters
printSession

The printing session for the specified page format object.

pageFormat

The page format object to which you want to assign default values.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call the function PMSessionDefaultPageFormat between the creation and release of the printing session. See the function PMCreateSession.

Availability
Related Sample Code
Declared In
PMCore.h

PMSessionDefaultPrintSettings

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

OSStatus PMSessionDefaultPrintSettings (
   PMPrintSession printSession,
   PMPrintSettings printSettings
);

Parameters
printSession

The printing session for the specified print settings object.

printSettings

The print settings object to which you want to assign default values.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call the function PMSessionDefaultPrintSettings between the creation and release of a printing session. See the function PMCreateSession.

Availability
Related Sample Code
Declared In
PMCore.h

PMSessionEndDocumentNoDialog

Ends a print job started by calling the function PMSessionBeginCGDocumentNoDialog or PMSessionBeginDocumentNoDialog.

OSStatus PMSessionEndDocumentNoDialog (
   PMPrintSession printSession
);

Parameters
printSession

The current printing session. On return, the printing session is no longer valid; however, you must still call the function PMRelease to release the object.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function is similar to the function PMSessionEndDocument except that the printing status dialog is suppressed.

This function is used to end a print job, and it should be called within your application’s print loop after the call to the function PMSessionEndPageNoDialog and before releasing the printing session. The same printing session that is created by the function PMCreateSession for the Print dialog should be used for the print loop.

The function PMSessionEndDocumentNoDialog must be called after its corresponding Begin function (PMSessionBeginCGDocumentNoDialog or PMSessionBeginDocumentNoDialog). If the Begin function returns noErr, the function PMSessionEndDocument must be called, even if errors occur within the scope of the Begin and End functions. You should not call PMSessionEndDocumentNoDialog if the Begin function returns an error.

Availability
Declared In
PMCore.h

PMSessionEndPageNoDialog

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

OSStatus PMSessionEndPageNoDialog (
   PMPrintSession printSession
);

Parameters
printSession

The printing session that provides a context for the print job.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

This function is similar to the function PMSessionEndPage except that the printing status dialog is suppressed.

You must call this function between the creation and release of a printing session. See the function PMCreateSession. You must call the functions PMSessionBeginPageNoDialog and PMSessionEndPageNoDialog within the scope of calls to the Begin print job function (PMSessionBeginCGDocumentNoDialog) and the End print job function (PMSessionEndDocumentNoDialog).

If the function PMSessionBeginPageNoDialog returns noErr, you must later call the function PMSessionEndPageNoDialog, even if errors occur within the scope of PMSessionBeginPageNoDialog and PMSessionEndPageNoDialog. You should not call PMSessionEndPageNoDialog if PMSessionBeginPageNoDialog returns an error.

Availability
Declared In
PMCore.h

PMSessionError

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

OSStatus PMSessionError (
   PMPrintSession printSession
);

Parameters
printSession

The printing session whose last error you want to obtain.

Return Value

A result code. See “Core Printing Result Codes.” The constant kPMCancel indicates the user canceled the current print job.

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

The PMSessionError function returns the last printing session error, not the last error from a printing function (PMxxx). Because most printing functions return a result code, the PMSessionError function is not required for general error checking. However, you can use PMSessionError in your print loop to determine if the user cancels the current print job or if any other errors occur during printing that are not explicitly returned by one of the other calls. For example, if the user clicks the Cancel button in the status dialog or presses Command-period on the keyboard, this function returns the constant kPMCancel. If this or any other error is encountered during the print loop, your application should call the appropriate functions (for example, PMSessionEndPage and PMSessionEndDocument) to exit the print loop before your application reports the error.

Availability
Related Sample Code
Declared In
PMCore.h

PMSessionGetCGGraphicsContext

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

OSStatus PMSessionGetCGGraphicsContext (
   PMPrintSession printSession,
   CGContextRef *context
);

Parameters
printSession

The printing session whose Quartz graphics context you want to obtain.

context

A pointer to your CGContextRef variable. On return, the variable refers to the Quartz graphics context for the current page in the specified printing session. The context’s origin is at the lower-left corner of the sheet of paper, not the imageable area. You should not release the context without first retaining it. The context is valid only for the current page; you should not retain it beyond the end of the page.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

If you’re using Quartz 2D to draw the content for a print job, after each call to PMSessionBeginPage you should call PMSessionGetCGGraphicsContext to obtain the Quartz graphics context for the current page. Note that before you can use the function PMSessionGetCGGraphicsContext, you must have called PMSessionBeginCGDocument or PMSessionBeginCGDocumentNoDialog instead of PMSessionBeginDocument or PMSessionBeginDocumentNoDialog.

Availability
Declared In
PMCore.h

PMSessionGetCurrentPrinter

Obtains the current printer associated with a printing session.

OSStatus PMSessionGetCurrentPrinter (
   PMPrintSession printSession,
   PMPrinter *currentPrinter
);

Parameters
printSession

The printing session whose printer you want to obtain.

currentPrinter

A pointer to your PMPrinter variable. On return, the variable refers to the printer associated with the specified printing session. The printer object is valid as long as the printing session is valid or the current printer hasn’t changed. You should not release this object without first retaining it.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

Availability
See Also
Declared In
PMCore.h

PMSessionGetDataFromSession

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

OSStatus PMSessionGetDataFromSession (
   PMPrintSession printSession,
   CFStringRef key,
   CFTypeRef *data
);

Parameters
printSession

The printing session whose data you want to obtain.

key

The key that uniquely identifies the data to be retrieved. You specify this key when you store the data using the function PMSessionSetDataInSession.

data

A pointer to your CFTypeRef variable. On return, the variable refers to the data retrieved from the printing session.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

Availability
See Also
Declared In
PMCore.h

PMSessionGetDestinationType

Obtains the output destination for a print job.

OSStatus PMSessionGetDestinationType (
   PMPrintSession printSession,
   PMPrintSettings printSettings,
   PMDestinationType *destTypeP
);

Parameters
printSession

The printing session that provides a context for the print job. This must be the same printing session used for the Print dialog. The printing session contains the preview setting, which can override the destination type in the print settings.

printSettings

The print settings for the print job whose destination you want to obtain.

destTypeP

A pointer to your PMDestinationType variable. On return, the variable contains the destination type for the specified print job. Possible values include:

  • kPMDestinationPrinter (output to a printer)

  • kPMDestinationFile (output to a file)

  • kPMDestinationFax (output to a fax)

  • kPMDestinationPreview (output to print preview)

  • kPMDestinationProcessPDF (output to a PDF workflow option)

See “Destination Types” for a complete description of the destination type constants.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

All of the destination types are stored in the print settings object except for kPMDestinationPreview, which is stored in the printing session object. If the destination type is set as preview, the preview setting overrides the destination set in the print settings object.

Availability
Declared In
PMCore.h

PMSessionSetCurrentPMPrinter

Changes the current printer for a printing session.

OSStatus PMSessionSetCurrentPMPrinter (
   PMPrintSession session,
   PMPrinter printer
);

Parameters
session

The printing session whose printer you want to change.

printer

The new printer for the printing session.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

Availability
See Also
Declared In
PMCore.h

PMSessionSetDataInSession

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

OSStatus PMSessionSetDataInSession (
   PMPrintSession printSession,
   CFStringRef key,
   CFTypeRef data
);

Parameters
printSession

The printing session in which you want to store application-specific data.

key

A key that uniquely identifies the data being added. This key is required to retrieve the data using the function PMSessionGetDataFromSession.

data

The data to be stored in the printing session.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

Availability
See Also
Declared In
PMCore.h

PMSessionSetDestination

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

OSStatus PMSessionSetDestination (
   PMPrintSession printSession,
   PMPrintSettings printSettings,
   PMDestinationType destType,
   CFStringRef destFormat,
   CFURLRef destLocation
);

Parameters
printSession

The printing session that provides a context for the print job.

printSettings

The print settings for the print job whose destination you want to set.

destType

The destination type for the print job associated with the specified printing session and print settings. Possible values include:

  • kPMDestinationPrinter (output to a printer)

  • kPMDestinationFile (output to a file)

  • kPMDestinationFax (output to a fax)

  • kPMDestinationPreview (output to print preview)

  • kPMDestinationProcessPDF (output to a PDF workflow option)

See “Destination Types” for a complete description of destination types you can specify.

destFormat

The MIME type to be generated for the specified destination type. Pass NULL if you want to use the default format for the specified destination type. To obtain a list of valid formats for a given destination type, use the function PMSessionCopyOutputFormatList.

destLocation

A reference to a Core Foundation URL that specifies a destination location. You can provide this if the destination type supports a destination location. Otherwise, pass NULL. For example, if the destination type is a file (kPMDestinationFile) you can supply a file system URL to specify where the file resides.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You can use the function PMSessionSetDestination when you want to send print output to a file without requiring user interaction. You must call this function between the creation and release of a printing session. See the function PMCreateSession.

Availability
Declared In
PMCore.h

PMSessionSetError

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

OSStatus PMSessionSetError (
   PMPrintSession printSession,
   OSStatus printError
);

Parameters
printSession

The printing session whose result code you want to set.

printError

The result code you want to set. This result code is returned by the PMSessionError function.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

You can use this function to terminate a printing session if your application encounters any errors inside the print loop. Typically, this function is used by an application’s idle function. The idle function isn’t called in Mac OS X, so this usage is not available.

Availability
Declared In
PMCore.h

PMSessionValidatePageFormat

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

OSStatus PMSessionValidatePageFormat (
   PMPrintSession printSession,
   PMPageFormat pageFormat,
   Boolean *result
);

Parameters
printSession

The printing session for the specified page format object.

pageFormat

The page format object to validate.

result

A pointer to your Boolean variable. On return, true if the function set the page format object to default values; otherwise, false.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of the printing session. See the function PMCreateSession.

The function PMSessionValidatePageFormat validates the page format object against the current formatting printer. The formatting printer is displayed in the Format for pop-up menu in the Page Setup dialog. The default formatting printer is the generic Any Printer. If the page format object contains values that are not valid for the formatting printer, the page format object is set to default values and the result parameter is set to true.

Validating a page format object also causes calculated fields (such as the adjusted paper and page rectangles) to be updated based on the changed settings (such as resolution, scaling, and page orientation). If the page format object contains values that are valid for the formatting printer but need to be updated, the result parameter is set to false.

After you call any function that makes changes to a page format object (such as PMSetOrientation), you should call the function PMSessionValidatePageFormat to validate the page format object before using that object.

Availability
Related Sample Code
Declared In
PMCore.h

PMSessionValidatePrintSettings

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

OSStatus PMSessionValidatePrintSettings (
   PMPrintSession printSession,
   PMPrintSettings printSettings,
   Boolean *result
);

Parameters
printSession

The printing session for the specified print settings object.

printSettings

The print settings object to validate.

result

A pointer to your Boolean variable. On return, true if any parameters changed, or false if no parameters changed.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You must call this function between the creation and release of a printing session. See the function PMCreateSession.

Availability
Related Sample Code
Declared In
PMCore.h

PMSetCollate

Specifies whether the job collate option is selected.

OSStatus PMSetCollate (
   PMPrintSettings printSettings,
   Boolean collate
);

Parameters
printSettings

The print settings object whose job collate option you want to set.

collate

If true, the job collate option is selected; if false the option is not selected.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

The Collated checkbox is displayed in the Copies & Pages pane of the Print dialog. This option determines how printed material is organized. For example, if you have a document that is three pages long and you are printing multiple copies with the Collated option selected, the job prints pages 1, 2, and 3 in that order and then repeats. However, if the Collated option is not selected and you’re printing multiple copies of those same three pages, the job prints copies of page 1, then copies of page 2, and finally copies of page 3.

If you call this function after initiating a print job, the change is ignored for the current job.

Availability
See Also
Declared In
PMCore.h

PMSetCopies

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

OSStatus PMSetCopies (
   PMPrintSettings printSettings,
   UInt32 copies,
   Boolean lock
);

Parameters
printSettings

The print settings object you want to initialize.

copies

The initial value of the number of copies to print.

lock

The lock state of the setting. Locking is not supported at this time.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

If you call this function after initiating a print job, the change is ignored for the current job.

Availability
See Also
Declared In
PMCore.h

PMSetDuplex

Sets the duplex mode.

OSStatus PMSetDuplex (
   PMPrintSettings printSettings,
   PMDuplexMode duplexSetting
);

Parameters
printSettings

The print settings object whose duplex mode you want to set.

duplexSetting

The new duplex mode setting. Possible values include:

  • kPMDuplexNone (one-sided printing)

  • kPMDuplexNoTumble (two-sided printing)

  • kPMDuplexTumble (two-sided printing with tumbling)

See “Duplex Modes” for a full description of the constants you can use to specify the new setting.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Duplex printing is a print job that prints on both sides of the paper. Two-Sided printing controls are displayed in the Layout pane of the Print dialog. Note that not all printers support duplex printing. This function specifies a setting that might not be available on a given destination.

If you call this function after initiating a print job, the change is ignored for the current job.

Availability
See Also
Declared In
PMCore.h

PMSetFirstPage

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

OSStatus PMSetFirstPage (
   PMPrintSettings printSettings,
   UInt32 first,
   Boolean lock
);

Parameters
printSettings

The print settings object whose first page number you want to set.

first

The page number of the first page to print. This value appears in the From field of the Print dialog.

lock

The lock state of the setting. Locking is not supported at this time.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Typically, this function isn’t used. In Mac OS X, if you call the function PMSetPageRange and then call PMSetFirstPage or PMSetLastPage using the same page range you specified for PMSetPageRange, then the Print dialog shows the From button selected. If you use the constant kPMPrintAllPages to set the page range with the function PMSetPageRange, then the Print dialog opens with the All button selected regardless of whether you also call PMSetFirstPage or PMSetLastPage.

If you call this function after initiating a print job, the change is ignored for the current job.

Availability
See Also
Related Sample Code
Declared In
PMCore.h

PMSetLastPage

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

OSStatus PMSetLastPage (
   PMPrintSettings printSettings,
   UInt32 last,
   Boolean lock
);

Parameters
printSettings

The print settings object whose last page number you want to set.

last

The page number of the last page to print. This value appears in the To field of the Print dialog. Pass the constant kPMPrintAllPages to print the entire document.

lock

The lock state of the setting. Locking is not supported at this time.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

Typically, you call this function after the Print dialog is displayed to indicate the number of the last page number to be printed. In Mac OS X, setting the last page provides information used by the progress dialog that is shown during printing.

If you call the function PMSetPageRange and then call PMSetFirstPage or PMSetLastPage using the same page range you specified for PMSetPageRange, then the Print dialog shows the From button selected. If you use the constant kPMPrintAllPages to set the page range with the function PMSetPageRange, then the Print dialog opens with the All button selected regardless of whether you also call PMSetFirstPage or PMSetLastPage.

If you call this function after initiating a print job, the change is ignored for the current job.

Availability
See Also
Related Sample Code
Declared In
PMCore.h

PMSetOrientation

Sets the page orientation for printing.

OSStatus PMSetOrientation (
   PMPageFormat pageFormat,
   PMOrientation orientation,
   Boolean lock
);

Parameters
pageFormat

The page format object whose page orientation you want to set.

orientation

A constant specifying the desired page orientation. Supported values are:

  • kPMPortrait

  • kPMLandscape

  • kPMReversePortrait (Mac OS X v10.5 and later)

  • kPMReverseLandscape

See “Page Orientation Constants” for a full description of the values you can use to specify page orientation.

lock

The lock state of the setting. You should pass kPMUnlocked. Locking is not supported at this time.

Return Value

A result code. See “Core Printing Result Codes.”

Special Considerations

In Mac OS X 10.4 and earlier, if you want to set the page orientation you need to call this function before initiating the print job (for example, by calling PMSessionBeginCGDocument). The page orientation you set applies to the entire print job. In Mac OS X 10.5 and later, you can use this function to change the orientation of an individual page in a print job by passing the updated page format to PMSessionBeginPage or PMSessionBeginPageNoDialog.

Availability
See Also
Declared In
PMCore.h

PMSetPageFormatExtendedData

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

OSStatus PMSetPageFormatExtendedData (
   PMPageFormat pageFormat,
   OSType dataID,
   UInt32 size,
   void *extendedData
);

Parameters
pageFormat

The page format object in which to store your extended data.

dataID

A 4-character code that identifies your data. This is typically your application’s creator code. If your creator code is outside the ASCII 7-bit character range 0x20–0x7F, you need to use a different 4-character code.

size

The size, in bytes, of the data to be stored in the page format object.

extendedData

A pointer to the application-specific data you want to store in the page format object.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You can retrieve the data you store with the function PMSetPageFormatExtendedData by calling the function PMGetPageFormatExtendedData.

Availability
See Also
Declared In
PMCore.h

PMSetPageRange

Sets the valid range of pages that can be printed.

OSStatus PMSetPageRange (
   PMPrintSettings printSettings,
   UInt32 minPage,
   UInt32 maxPage
);

Parameters
printSettings

The print settings object whose page range you want to set.

minPage

The minimum page number allowed. This value appears as the default in the From field of the Print dialog.

maxPage

The maximum page number allowed. This value appears as the default in the To field of the Print dialog. Pass the constant kPMPrintAllPages to allow the user to print the entire document. If the first page is set to 1, then passing kPMPrintAllPages as the maximum page number causes the All button to be selected.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

The function PMSetPageRange allows applications to set the minimum and maximum page numbers that can be printed for a document. If the user enters a value outside of this range in the Print dialog, the value is set to the closest allowed value. You can use the PMGetFirstPage and PMGetLastPage functions to obtain the values entered by the user in the Print dialog.)

If you call the function PMSetPageRange to set the maximum page to a value other than the constant kPMPrintAllPages, the function PMSetPageRange causes the page range in the Print dialog to be properly restricted to the specified range. If you call the function PMSetPageRange without also calling the functions PMSetFirstPage or PMSetLastPage, then the Print dialog shows the specified page range in the From and To fields but with the All button selected. If you call the function PMSetPageRange and then call PMSetFirstPage or PMSetLastPage using the same page range you specified for PMSetPageRange, then the Print dialog shows the From button selected.

In all cases, if your application sets a range with PMSetPageRange and subsequently calls PMSetFirstPage or PMSetLastPage with values outside of the specified range, Core Printing returns a result code of kPMValueOutOfRange. Conversely, if your application calls PMSetPageRange after calling PMSetFirstPage or PMSetLastPage (or after displaying the Print dialog), the page range specified by PMSetPageRange takes precedence, and the first and last page values are adjusted accordingly.

If you call this function after initiating a print job, the change is ignored for the current job.

Availability
See Also
Related Sample Code
Declared In
PMCore.h

PMSetPrintSettingsExtendedData

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

OSStatus PMSetPrintSettingsExtendedData (
   PMPrintSettings printSettings,
   OSType dataID,
   UInt32 size,
   void *extendedData
);

Parameters
printSettings

The print settings object in which to store your application-specific data.

dataID

A 4-character code that will be used to identify your data. The 4-character code must not contain any characters outside the standard ASCII 7-bit character range 0x20–0x7F. This is typically your application’s creator code.

size

The size, in bytes, of the data to be stored in the print settings object.

extendedData

A pointer to a buffer that contains the extended data you want to store.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You can retrieve the data you store with the function PMSetPrintSettingsExtendedData by calling the function PMGetPrintSettingsExtendedData.

You may find it easier to use the functions PMPrintSettingsSetValue and PMPrintSettingsGetValue to store and retrieve user-defined data in a print settings object. If you use these functions, make sure that the custom keys you define for your private data do not conflict with other print settings keys.

Availability
See Also
Declared In
PMCore.h

PMSetScale

Sets the scaling factor for the page and paper rectangles.

OSStatus PMSetScale (
   PMPageFormat pageFormat,
   double scale
);

Parameters
pageFormat

The page format object whose scaling factor you want to set.

scale

The desired scaling factor expressed as a percentage. For example, for 50 percent scaling, pass a value of 50.0; for no scaling, pass 100.0.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

You can call the function PMSetScale to change the scaling factor that appears when your application invokes the Page Setup dialog.

If you call PMSetScale after calling PMSessionPageSetupDialog, make sure you call PMSessionValidatePageFormat before you call PMSessionBeginCGDocument or PMSessionBeginDocument.

If you call this function after initiating a print job, the change is ignored for the current job.

Availability
See Also
Declared In
PMCore.h

PMWorkflowCopyItems

Obtains an array of the available PDF workflow items.

OSStatus PMWorkflowCopyItems (
   CFArrayRef *workflowItems
);

Parameters
workflowItems

A pointer to your CFArrayRef variable. On return, the variable refers to an Core Foundation array. Each element in the array is a dictionary that describes either a PDF workflow item or a folder containing a set of PDF workflow items. For a list of possible keys, see “PDF Workflow Dictionary Keys”. You are responsible for releasing the array.

Return Value

A result code. See “Core Printing Result Codes.”

Availability
Declared In
PMCore.h

PMWorkflowSubmitPDFWithOptions

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

OSStatus PMWorkflowSubmitPDFWithOptions (
   CFURLRef workflowItem,
   CFStringRef title,
   const char *options,
   CFURLRef pdfFile
);

Parameters
workflowItem

A file system URL pointing to the workflow item that will handle the PDF file. See PMWorkflowCopyItems. The following table describes the different types of workflow items for this function.

Workflow item

Description

Automator action

The action is executed for the PDF file. Available in Mac OS X v10.4 and later.

Folder alias

The PDF file is moved to the resolved folder.

Application or application alias

The application is sent an open event along with a reference to the PDF file.

Compiled AppleScript

The script is run with an open event along with a reference to the PDF file.

Executable tool

The tool is run with the following parameters: title, options, and pdfFile.

title

The user-displayable name of the PDF document.

options

A string of CUPS-style key-value pairs that may be passed to the PDF workflow item. This parameter can be NULL in which case an empty string of options is used.

pdfFile

A file system URL pointing to the PDF file to be processed by the workflow item.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

The printing system uses this function in conjunction with the function PMWorkflowCopyItems to implement the PDF workflow button in the Print dialog.

Availability
Declared In
PMCore.h

PMWorkflowSubmitPDFWithSettings

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

OSStatus PMWorkflowSubmitPDFWithSettings (
   CFURLRef workflowItem,
   PMPrintSettings settings,
   CFURLRef pdfFile
);

Parameters
workflowItem

A file system URL pointing to the workflow item that will handle the PDF file. See PMWorkflowCopyItems. The following table describes the different types of workflow items for this function.

Workflow item

Description

Automator action

The action is executed for the PDF file. Available in Mac OS X v10.4 and later.

Folder alias

The PDF file is moved to the resolved folder.

Application or application alias

The application is sent an open event along with a reference to the PDF file.

Compiled AppleScript

The script is run with an open event along with a reference to the PDF file.

Executable tool

The tool is run with the specified settings and PDF file. This function converts these parameters into a CUPS options string and passes the options string to the tool.

settings

The print settings to apply to the PDF document. These settings are passed to the workflow item as a CUPS options string.

pdfFile

A file system URL pointing to the PDF file to be processed by the workflow item.

Return Value

A result code. See “Core Printing Result Codes.”

Discussion

The printing system uses this function in conjunction with the function PMWorkflowCopyItems to implement the PDF workflow button in the Print dialog.

Special Considerations

In Mac OS X v10.4 and earlier, this function is not implemented and returns an error. You can use the function PMWorkflowSubmitPDFWithOptions together with the function PMPrintSettingsToOptions instead.

Availability
Declared In
PMCore.h

Callbacks

PMIdleProcPtr

Defines a pointer to an idle function. (Deprecated. There is no replacement; this callback function was included to facilitate porting legacy applications to Mac OS X, but it serves no useful purpose.)

typedef void (*PMIdleProcPtr) (void);

You would declare your idle function like this if you were to name it MyPrintIdleCallback:

void MyPrintIdleCallback (void);

Discussion

If you install an idle function using the function PMSessionSetIdleProc, the printing system calls your idle function periodically during your print loop. Your idle function can display application status while printing, but it should not duplicate information displayed by the printing system or the printer driver. If you don’t install an idle function, you get the standard dialog for the current driver in Mac OS 8 and 9.

Your idle function must check whether the user has pressed Command-period, in which case your application should stop its printing operation. If your status dialog contains a button to cancel the printing operation, your idle function should also check for clicks in the button and respond accordingly.

To provide a pointer to your idle function, you create a universal procedure pointer (UPP) of type PMIdleUPP, using the function NewPMIdleUPP. You can do so with code similar to the following: 

PMIdleUPP MyPrintIdleUPP;
MyPrintIdleUPP = NewPMIdleUPP (&MyPrintIdleCallback);

When your print job is completed, you should use the function DisposePMIdleUPP to dispose of the universal procedure pointer associated with your idle function. However, if you will use the same idle function in subsequent print jobs, you can reuse the same UPP, rather than dispose of it and later create a new UPP.

Special Considerations

Your idle function is not called in Mac OS X. It’s only called in Mac OS 8 and 9.

Availability
Declared In
PMCoreDeprecated.h

Data Types

PMDialog

An opaque type that represents a custom printing dialog.

typedef struct OpaquePMDialog* PMDialog;

Discussion

This data type is used by functions that are not recommended or deprecated.

Availability
Declared In
PMDefinitionsDeprecated.h

PMIdleUPP

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

typedef PMIdleProcPtr PMIdleUPP;

Discussion

This data type is used by functions that are not recommended or deprecated.

Availability
Declared In
PMCoreDeprecated.h

PMLanguageInfo

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

struct PMLanguageInfo {
   Str32 level;
   Str32 version;
   Str32 release;
};

Fields
level

Specifies the level of the imaging language used by the printer driver.

version

Specifies the version of the imaging language.

release

Specifies the release of the imaging language.

PMObject

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

typedef const void* PMObject;

Discussion

PMObject is the base type for opaque types such as PMPrintSession, PMPageFormat, PMPrintSettings, PMPrinter, PMPaper, PMPreset, and PMServer. PMObject is used in functions such as PMRetain and PMRelease that operate on any opaque type.

Availability
Declared In
PMDefinitions.h

PMPageFormat

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

typedef struct OpaquePMPageFormat* PMPageFormat;

Discussion

Your application uses page format objects to store information such as the paper size, orientation, and scale of pages in a printing session. To create a page format object, you use the function PMCreatePageFormat. A new page format object is empty and unusable until you call PMSessionDefaultPageFormat or PMCopyPageFormat to initialize the settings. You can also use the functions PMSetPageFormatExtendedData and PMGetPageFormatExtendedData to store and retrieve application-specific data in a page format object.

Availability
Declared In
PMDefinitions.h

PMPaper

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

typedef struct OpaquePMPaper* PMPaper;

Discussion

Your application uses paper objects to identify standard and custom types of printing paper.

Availability
Declared In
PMDefinitions.h

PMPaperMargins

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

typedef PMRect PMPaperMargins;

Discussion

Your application specifies paper margins when calling the function PMPaperCreateCustom to create a custom paper type. You can obtain a paper’s margins with the function PMPaperGetMargins.

Availability
Declared In
PMDefinitions.h

PMPreset

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

typedef struct OpaquePMPreset* PMPreset;

Discussion

Your application uses a preset object to identify a named preset in the Print dialog. You typically obtain an instance of this type using the function PMPrinterCopyPresets.

Availability
Declared In
PMDefinitions.h

PMPrinter

An opaque type that represents a printer.

typedef struct OpaquePMPrinter* PMPrinter;

Discussion

You typically obtain a printer object using the function PMSessionGetCurrentPrinter or PMServerCreatePrinterList.

Availability
Declared In
PMDefinitions.h

PMPrintSession

An opaque type that stores information about a print job.

typedef struct OpaquePMPrintSession* PMPrintSession;

Discussion

A printing session object contains information that’s needed by the page format and print settings objects, such as default page format and print settings values. For this reason, some printing functions can be called only after you have created a printing session object. For example, setting defaults for or validating page format and print settings objects can only be done after you have created a printing session object. Your application creates a printing session object using the function PMCreateSession.

You can use a printing session to implement multithreaded printing, and you can create multiple sessions within a single-threaded application. If your application does not use sheets, then your application can open only one dialog at a time. Each printing session can have its own dialog, and settings changed in one dialog are independent of settings in any other dialog.

Availability
Declared In
PMDefinitions.h

PMPrintSettings

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

typedef struct OpaquePMPrintSettings* PMPrintSettings;

Discussion

Your application uses print settings objects to store information such as the number of copies and the range of pages to print in a printing session. To create a print settings object, you use the function PMCreatePrintSettings. A new print settings object is empty and unusable until you call PMSessionDefaultPrintSettings or PMCopyPrintSettings to initialize the settings. You can also use the functions PMSetPrintSettingsExtendedData and PMGetPrintSettingsExtendedData to store and retrieve application-specific data in a print settings object.

Availability
Declared In
PMDefinitions.h

PMRect

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

struct PMRect {
   double top;
   double left;
   double bottom;
   double right;
};

Fields
top

The vertical coordinate for the upper-left point of the rectangle.

left

The horizontal coordinate for the upper-left point of the rectangle.

bottom

The vertical coordinate for the lower-right point of the rectangle.

right

The horizontal coordinate for the lower-right point of the rectangle.

PMResolution

A data structure that contains printing resolution information.

struct PMResolution {
   double hRes;
   double vRes;
};

Fields
hRes

The horizontal resolution in dots per inch (dpi).

vRes

The vertical resolution in dots per inch (dpi).

Discussion

The functions PMGetResolution and PMPrinterGetPrinterResolution use this structure to return printing resolution information. Your application can pass this information to the function PMSetResolution.

PMServer

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

typedef struct OpaquePMServer* PMServer;

Availability
Declared In
PMDefinitions.h

PMPrintContext

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

typedef struct OpaquePMPrintContext* PMPrintContext;

Discussion

This data type is used by functions that are not recommended or deprecated.

Availability
Declared In
PMDefinitionsDeprecated.h

PMColorMode

A type that specifies color modes to use for printing.

typedef UInt16 PMColorMode;

Discussion

This data type is used by functions that are not recommended or deprecated.

Availability
Declared In
PMDefinitionsDeprecated.h

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.

#define kPMNoData  NULL
#define kPMDontWantSize  NULL
#define kPMDontWantData  NULL
#define kPMDontWantBoolean  NULL
#define kPMNoPrintSettings  NULL
#define kPMNoPageFormat  NULL
#define kPMNoReference  NULL

Constants
kPMNoData

Specifies that your application does not need data returned for a particular parameter. For future compatibility, you are encouraged to use one of the following constants in cases where a specific type of data is not required.

kPMDontWantSize

Specifies that your application does not need the size information returned by the printing function.

kPMDontWantData

Specifies that your application does not need the data returned by the printing function.

kPMDontWantBoolean

Specifies that your application does not need a Boolean value returned by the printing function.

kPMNoPrintSettings

Specifies that your application does not need a PMPrintSettings object returned by the printing function.

kPMNoPageFormat

Specifies that your application does not need a PMPageFormat object returned by the printing function.

kPMNoReference

Specifies that your application does not need a reference returned by the printing function.

Data Representation Formats

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

enum PMDataFormat {
   kPMDataFormatXMLDefault = 0,
   kPMDataFormatXMLMinimal = 1,
   kPMDataFormatXMLCompressed = 2
};
typedef enum PMDataFormat PMDataFormat;

Constants
kPMDataFormatXMLDefault

Specifies a data format that is compatible with all Mac OS X versions. Data in this format can be used with the PMUnflattenXXX functions present in versions of Mac OS X prior to 10.5. This format is a pure XML representation of the data. However, this format is much larger than the more modern data formats described below.

Available in Mac OS X v10.5 and later.

Declared in PMDefinitions.h.

kPMDataFormatXMLMinimal

Specifies an uncompressed data format that is approximately 3-5 times smaller than kPMDataFormatXMLDefault. This data format is only compatible with Mac OS X v10.5 and later. This format is a good choice when you do not need to use the data in versions of Mac OS X prior to 10.5 and you need a pure XML representation of the data.

Available in Mac OS X v10.5 and later.

Declared in PMDefinitions.h.

kPMDataFormatXMLCompressed

Specifies a compressed data format that is approximately 20 times smaller than kPMDataFormatXMLDefault. This data format is only compatible with Mac OS X v10.5 and later. This format is a good choice when you do not need to use the data in versions of Mac OS X prior to 10.5 and the minimum data size is important. Note that this format is not a pure XML representation of the data.

Available in Mac OS X v10.5 and later.

Declared in PMDefinitions.h.

Destination Types

Constants that specify a destination for a print job.

typedef UInt16 PMDestinationType;
enum {
   kPMDestinationInvalid = 0,
   kPMDestinationPrinter = 1,
   kPMDestinationFile = 2,
   kPMDestinationFax = 3,
   kPMDestinationPreview = 4,
   kPMDestinationProcessPDF = 5
};

Constants
kPMDestinationInvalid

Specifies the destination is invalid.

Available in Mac OS X v10.1 and later.

Declared in PMDefinitions.h.

kPMDestinationPrinter

Specifies output to a printer.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMDestinationFile

Specifies output to a file.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMDestinationFax

Specifies output to a fax. This destination is currently not supported.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMDestinationPreview

Specifies output to print preview.

Available in Mac OS X v10.1 and later.

Declared in PMDefinitions.h.

kPMDestinationProcessPDF

Specifies output to a PDF workflow option.

Available in Mac OS X v10.4 and later.

Declared in PMDefinitions.h.

Document Format Strings

Constants that specify the document format for a print job.

#define kPMDocumentFormatDefault
   CFSTR("com.apple.documentformat.default")
#define kPMDocumentFormatPDF
   CFSTR("application/pdf")
#define kPMDocumentFormatPICT
   CFSTR("application/vnd.apple.printing-pict")
#define kPMDocumentFormatPICTPS
   CFSTR("application/vnd.apple.printing-pict-ps")
#define kPMDocumentFormatPostScript
   CFSTR("application/postscript")

Constants
kPMDocumentFormatDefault

Specifies the default format for the printing system. In Mac OS X, the default format is PDF.

kPMDocumentFormatPDF

Specifies PDF.

kPMDocumentFormatPICT

Specifies PICT format.

kPMDocumentFormatPICTPS

Specifies PICT format with embedded PostScript.

kPMDocumentFormatPostScript

Specifies PostScript format.

Duplex Modes

Constants that specify duplex mode settings.

typedef UInt32 PMDuplexMode;
enum {
   kPMDuplexNone = 0x0001,
   kPMDuplexNoTumble = 0x0002,
   kPMDuplexTumble = 0x0003,
   kPMSimplexTumble = 0x0004
};

Constants
kPMDuplexNone

Print on only one side of the paper.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMDuplexNoTumble

Print on both sides of the paper, with both sides oriented in the same direction (no tumbling.)

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMDuplexTumble

Print on both sides of the paper, with the output on the second side flipped relative to the first side (tumbling on.)

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMSimplexTumble

Print on only one side of the paper, but tumble the images while printing. This mode is not supported at this time.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

Graphics Context Types

Constants that specify the graphics context for a print job.

#define kPMGraphicsContextDefault
   CFSTR("com.apple.graphicscontext.default")
#define kPMGraphicsContextQuickdraw
   CFSTR("com.apple.graphicscontext.quickdraw")
#define kPMGraphicsContextCoreGraphics
   CFSTR("com.apple.graphicscontext.coregraphics")

Constants
kPMGraphicsContextDefault

Specifies the default graphics context for the application’s runtime environment.

kPMGraphicsContextQuickdraw

Specifies a QuickDraw graphics context.

kPMGraphicsContextCoreGraphics

Specifies a Quartz graphics context. The default coordinate system for a Quartz printing context is not the same as that used for a QuickDraw printing context. A Quartz printing context defines the coordinates of the lower-left corner of the paper as (0,0) whereas the origin for a QuickDraw is at the upper-right corner of the paper’s imageable area.

Page Orientation Constants

Constants that specify page orientation.

typedef UInt16 PMOrientation;
enum {
   kPMPortrait = 1,
   kPMLandscape = 2,
   kPMReversePortrait = 3,
   kPMReverseLandscape = 4
};

Constants
kPMPortrait

Specifies portrait (vertical) page orientation. Portrait orientation performs no alteration of the logical page.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMLandscape

Specifies landscape (horizontal) orientation. Landscape orientation performs a 90° counterclockwise rotation on the logical page image and sets the Quartz origin to the upper-left corner of the unrotated logical page with positive y-values increasing across and to the right of the unrotated page. This has the effect of rotating the logical page image 90° clockwise. In other words, the image appears on the unrotated page as if it were rotated 90° clockwise.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMReversePortrait

Specifies reverse portrait orientation. Reverse portrait orientation performs a 180° rotation on the logical page rectangle and sets the Quartz origin to the upper-right corner of the unrotated logical page with positive y-values increasing downwards. This has the effect of rotating the logical page image 180°. Reverse portrait orientation is supported in Mac OS X v10.5 and later.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMReverseLandscape

Specifies reverse landscape page orientation. Landscape orientation performs a 90° clockwise rotation on the logical page rectangle and sets the Quartz origin to the lower-right corner of the unrotated logical page, with the positive y-values increasing to across and to the left of the unrotated page. This has the effect of rotating the logical page image 90° counterclockwise. In other words, the image appears on the unrotated page as if it were rotated 90° counterclockwise.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

PDF Workflow Dictionary Keys

Constants that specify the keys in a PDF workflow dictionary.

#define kPDFWorkFlowItemURLKey CFSTR("itemURL")
#define kPDFWorkflowDisplayNameKey CFSTR("displayName")
#define kPDFWorkflowFolderURLKey CFSTR("folderURL")
#define kPDFWorkflowItemsKey CFSTR("items")

Constants
kPDFWorkFlowItemURLKey

The URL to the PDF workflow item.

Available in Mac OS X v10.3 and later.

Declared in PMDefinitions.h.

kPDFWorkflowDisplayNameKey

The user-displayable name for the PDF workflow item.

Available in Mac OS X v10.3 and later.

Declared in PMDefinitions.h.

kPDFWorkflowFolderURLKey

The URL to the folder containing PDF workflow items.

Available in Mac OS X v10.5 and later.

Declared in PMDefinitions.h.

kPDFWorkflowItemsKey

A Core Foundation array describing the PDF workflow items in the folder.

Available in Mac OS X v10.3 and later.

Declared in PMDefinitions.h.

PostScript Injection Dictionary Keys

Constants that specify keys for PostScript injection dictionary entries.

#define kPSInjectionSectionKey     CFSTR("section")
#define kPSInjectionSubSectionKey  CFSTR("subsection")
#define kPSInjectionPageKey        CFSTR("page")
#define kPSInjectionPlacementKey   CFSTR("place")
#define kPSInjectionPostScriptKey  CFSTR("psdata")

Constants
kPSInjectionSectionKey

Specifies a section.

kPSInjectionSubSectionKey

Specifies a subsection.

kPSInjectionPageKey

Specifies a page.

kPSInjectionPlacementKey

Specifies placement.

kPSInjectionPostScriptKey

Specifies PostScript data.

PostScript Page Injection Options

Constants that specify PostScript injection options.

enum {
   kPSPageInjectAllPages = -1,
   kPSInjectionMaxDictSize = 5
};

Constants
kPSPageInjectAllPages

Specifies to inject all pages in the print job with PostScript code.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPSInjectionMaxDictSize

Specifies the maximum size needed for a dictionary used for PostScript injection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

PostScript Injection Placement Options

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

typedef UInt16 PSInjectionPlacement;
enum {
   kPSInjectionBeforeSubsection = 1,
   kPSInjectionAfterSubsection = 2,
   kPSInjectionReplaceSubsection = 3
};

Constants
kPSInjectionBeforeSubsection

Specifies that your PostScript code be inserted before the standard PostScript code that is normally emitted for the subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPSInjectionAfterSubsection

Specifies that your PostScript code be inserted after the standard PostScript code that is normally emitted for the subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPSInjectionReplaceSubsection

Specifies that your PostScript code replace the standard PostScript code that is normally emitted for the subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

PostScript Injection Sections

Constants that specify keys for PostScript injection section values.

typedef SInt32 PSInjectionSection;
enum {
   kInjectionSectJob = 1,
   kInjectionSectCoverPage = 2
};

Constants
kInjectionSectJob

Specifies the job section. This is the default section if you do not specify a section key explicitly.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSectCoverPage

Specifies the cover page section. Currently unsupported.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

PostScript Injection Subsections

Constants that specify PostScript injection values for the subsection key.

typedef SInt32 PSInjectionSubsection;
enum {
   kInjectionSubPSAdobe = 1,
   kInjectionSubPSAdobeEPS = 2,
   kInjectionSubBoundingBox = 3,
   kInjectionSubEndComments = 4,
   kInjectionSubOrientation = 5,
   kInjectionSubPages = 6,
   kInjectionSubPageOrder = 7,
   kInjectionSubBeginProlog = 8,
   kInjectionSubEndProlog = 9,
   kInjectionSubBeginSetup = 10,
   kInjectionSubEndSetup = 11,
   kInjectionSubBeginDefaults = 12,
   kInjectionSubEndDefaults = 13,
   kInjectionSubDocFonts = 14,
   kInjectionSubDocNeededFonts = 15,
   kInjectionSubDocSuppliedFonts = 16,
   kInjectionSubDocNeededRes = 17,
   kInjectionSubDocSuppliedRes = 18,
   kInjectionSubDocCustomColors = 19,
   kInjectionSubDocProcessColors = 20,
   kInjectionSubPlateColor = 21,
   kInjectionSubPageTrailer = 22,
   kInjectionSubTrailer = 23,
   kInjectionSubEOF = 24,
   kInjectionSubBeginFont = 25,
   kInjectionSubEndFont = 26,
   kInjectionSubBeginResource = 27,
   kInjectionSubEndResource = 28,
   kInjectionSubPage = 29,
   kInjectionSubBeginPageSetup = 30,
   kInjectionSubEndPageSetup = 31
};

Constants
kInjectionSubPSAdobe

Specifies the “%!PS-Adobe” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubPSAdobeEPS

Specifies the “%!PS-Adobe-3.0 EPSF-3.0” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubBoundingBox

Specifies the “%BoundingBox” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubEndComments

Specifies the “%EndComments” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubOrientation

Specifies the “%Orientation” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubPages

Specifies the “%Pages” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubPageOrder

Specifies the “%PageOrder” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubBeginProlog

Specifies the “%BeginProlog” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubEndProlog

Specifies the “%EndProlog” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubBeginSetup

Specifies the “%BeginSetup” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubEndSetup

Specifies the “%EndSetup” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubBeginDefaults

Specifies the “%BeginDefaults” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubEndDefaults

Specifies the “%EndDefaults” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubDocFonts

Specifies the “%DocumentFonts” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubDocNeededFonts

Specifies the “%DocumentNeededFonts” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubDocSuppliedFonts

Specifies the “%DocumentSuppliedFonts” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubDocNeededRes

Specifies the “%DocumentNeededResources” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubDocSuppliedRes

Specifies the “%DocumentSuppliedResources” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubDocCustomColors

Specifies the “%DocumentCustomColors” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubDocProcessColors

Specifies the “%DocumentProcessColors” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubPlateColor

Specifies the “%PlateColor” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubPageTrailer

Specifies the “%PageTrailer” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubTrailer

Specifies the “%Trailer” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubEOF

Specifies the “%EOF” (end of file) subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubBeginFont

Specifies the “%BeginFont” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubEndFont

Specifies the “%EndFont” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubBeginResource

Specifies the “%BeginResource” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubEndResource

Specifies the “%EndResource” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubPage

Specifies the “%Page” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubBeginPageSetup

Specifies the “%BeginPageSetup” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kInjectionSubEndPageSetup

Specifies the “%EndPageSetup” subsection.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

PostScript Printer Description File Domains

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

typedef UInt16 PMPPDDomain;
enum {
   kAllPPDDomains = 1,
   kSystemPPDDomain = 2,
   kLocalPPDDomain = 3,
   kNetworkPPDDomain = 4,
   kUserPPDDomain = 5,
   kCUPSPPDDomain = 6
};

Constants
kAllPPDDomains

Specifies all available domains.

Available in Mac OS X v10.3 and later.

Declared in PMDefinitions.h.

kSystemPPDDomain

Specifies the system domain.

Available in Mac OS X v10.3 and later.

Declared in PMDefinitions.h.

kLocalPPDDomain

Specifies the local domain.

Available in Mac OS X v10.3 and later.

Declared in PMDefinitions.h.

kNetworkPPDDomain

Specifies the network domain.

Available in Mac OS X v10.3 and later.

Declared in PMDefinitions.h.

kUserPPDDomain

Specifies the user domain.

Available in Mac OS X v10.3 and later.

Declared in PMDefinitions.h.

kCUPSPPDDomain

Specifies the CUPS domain.

Available in Mac OS X v10.3 and later.

Declared in PMDefinitions.h.

Print All Pages Constant

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

enum {
   kPMPrintAllPages = -1
};

Constants
kPMPrintAllPages

Specifies that all pages of a document should be printed.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

Print Quality Modes

Constants that specify standard options for print quality.

typedef UInt32 PMQualityMode;
enum {
   kPMQualityLowest = 0,
   kPMQualityInkSaver = 1,
   kPMQualityDraft = 4,
   kPMQualityNormal = 8,
   kPMQualityPhoto = 11,
   kPMQualityBest = 13,
   kPMQualityHighest = 15
};

Constants
kPMQualityLowest

Specifies to use the lowest print quality available to the printer.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMQualityInkSaver

Specifies to use a mode that saves ink, even if it slows printing.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMQualityDraft

Specifies to print at the highest speed, with the amount of ink used as a secondary consideration.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMQualityNormal

Specifies a general usage mode that balances quality and speed.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMQualityPhoto

Specifies to optimize the quality of photos on the page, with speed not a concern.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMQualityBest

Specifies to get the best print quality for all objects and photos on a page.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

kPMQualityHighest

Specifies to use the highest print quality available to the printer.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

Print Queue States

Constants that specify the current state of a print queue.

typedef UInt16 PMPrinterState;
enum {
   kPMPrinterIdle = 3,
   kPMPrinterProcessing = 4,
   kPMPrinterStopped = 5
};

Constants
kPMPrinterIdle

Specifies the idle state.

Available in Mac OS X v10.2 and later.

Declared in PMDefinitions.h.

kPMPrinterProcessing

Specifies the processing state.

Available in Mac OS X v10.2 and later.

Declared in PMDefinitions.h.

kPMPrinterStopped

Specifies the stopped state.

Available in Mac OS X v10.2 and later.

Declared in PMDefinitions.h.

Printer Description Types

Constants that specify printer description types.

#define kPMPPDDescriptionType CFSTR("PMPPDDescriptionType")

Constants
kPMPPDDescriptionType

Specifies a PostScript printer description (PPD).

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

Tag Constants

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

typedef UInt32 PMTag;
enum {
   kPMCurrentValue = 'curr',
   kPMDefaultValue = 'dflt',
   kPMMinimumValue = 'minv',
   kPMMaximumValue = 'maxv',
   kPMSourceProfile = 'srcp',
   kPMMinRange = 'mnrg',
   kPMMaxRange = 'mxrg',
   kPMMinSquareResolution = 'mins',
   kPMMaxSquareResolution = 'maxs',
   kPMDefaultResolution = 'dftr'
};

Constants
kPMCurrentValue

Specifies the current setting or value.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMDefaultValue

Specifies the default setting or value.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMMinimumValue

Specifies the minimum setting or value.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMMaximumValue

Specifies the maximum setting or value.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMSourceProfile

Specifies a ColorSync source profile.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMMinRange

Specifies the minimum resolution supported by the printer.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMMaxRange

Specifies the maximum resolution supported by the printer.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMMinSquareResolution

Specifies the minimum resolution setting for which the horizontal and vertical resolutions are equal.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMMaxSquareResolution

Specifies the maximum resolution setting for which the horizontal and vertical resolutions are equal.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMDefaultResolution

Specifies the default resolution setting for the printer (typically 72 dots per inch).

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

User Cancellation Constant

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

enum {
   kPMCancel = 128
};

Constants
kPMCancel

Specifies that the user clicked the Cancel button in a Print or Page Setup dialog.

Available in Mac OS X v10.0 and later.

Declared in PMDefinitions.h.

Discussion

This constant is provided for compatibility with old applications and printer drivers that expect the iPrAbort error code to be returned when the user cancels a printing operation.

The default idle function checks for Command-period keyboard events during printing, and sets the error condition equal to kPMCancel if one occurs. Your application can check for this condition using the PMSessionError function, and should cancel the print job if kPMCancel is returned.

If you supply your own idle function (not needed in Mac OS 8, 9, or X), your function must check for Command-period keyboard events, and set the error condition using the function PMSessionSetError.

Color Modes

Constants that specify a color mode to use for printing.

typedef UInt16 PMColorMode;
enum {
   kPMBlackAndWhite = 1,
   kPMGray = 2,
   kPMColor = 3,
   kPMColorModeDuotone = 4,
   kPMColorModeSpecialColor = 5
};

Constants
kPMBlackAndWhite

Specifies black-and-white mode.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMGray

Specifies grayscale mode.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMColor

Specifies color mode.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMColorModeDuotone

Specifies two-channel color mode.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

kPMColorModeSpecialColor

Specifies to allow special colors such as metallic and light cyan.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in PMDefinitionsDeprecated.h.

Discussion

These constants are used by functions that are deprecated.

Result Codes

This table lists the result codes defined for Core Printing.

Result CodeValueDescription
kPMGeneralError -30870

An unspecified error occurred.

Available in Mac OS X v10.0 and later.

kPMOutOfScope -30871

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

Available in Mac OS X v10.0 and later.

kPMNoDefaultPrinter -30872

The user has not specified a default printer.

Available in Mac OS X v10.0 and later.

kPMNotImplemented -30873

The function is not implemented.

Available in Mac OS X v10.0 and later.

kPMNoSuchEntry -30874

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

Available in Mac OS X v10.0 and later.

kPMInvalidPrintSettings -30875

Your application passed an invalid print settings object.

Available in Mac OS X v10.0 and later.

kPMInvalidPageFormat -30876

Your application passed an invalid page format object.

Available in Mac OS X v10.0 and later.

kPMValueOutOfRange -30877

Your application passed an out-of-range value.

Available in Mac OS X v10.0 and later.

kPMLockIgnored -30878

The lock value was ignored.

Available in Mac OS X v10.0 and later.

kPMInvalidPrintSession -30879

Your application passed an invalid printing session object.

Available in Mac OS X v10.0 and later.

kPMInvalidPrinter -30880

Your application passed an invalid printer object.

Available in Mac OS X v10.0 and later.

kPMObjectInUse -30881

The specified object is in use.

Available in Mac OS X v10.0 and later.

kPMInvalidIndex-30882

An array index is invalid.

Available in Mac OS X v10.0 and later.

kPMStringConversionFailure-30883

An internal error occurred while converting a string.

Available in Mac OS X v10.0 and later.

kPMXMLParseError-30884

An error occurred while parsing XML data.

Available in Mac OS X v10.0 and later.

kPMInvalidJobTemplate-30885

An internal error occurred while creating a job template.

Available in Mac OS X v10.0 and later.

kPMInvalidPrinterInfo-30886

The printer information is invalid.

Available in Mac OS X v10.0 and later.

kPMInvalidConnection-30887

The printer connection type is invalid.

Available in Mac OS X v10.0 and later.

kPMInvalidKey-30888

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

Available in Mac OS X v10.0 and later.

kPMInvalidValue-30889

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

Available in Mac OS X v10.0 and later.

kPMInvalidAllocator-30890

The specified memory allocator is invalid.

Available in Mac OS X v10.0 and later.

kPMInvalidTicket-30891

The job ticket is invalid.

Available in Mac OS X v10.0 and later.

kPMInvalidItem-30892

The item being added to a ticket is invalid.

Available in Mac OS X v10.0 and later.

kPMInvalidType-30893

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

Available in Mac OS X v10.0 and later.

kPMInvalidReply-30894

A remote server or client sent an invalid reply.

Available in Mac OS X v10.0 and later.

kPMInvalidFileType-30895

The file type is invalid.

Available in Mac OS X v10.0 and later.

kPMInvalidObject-30896

The object is invalid.

Available in Mac OS X v10.0 and later.

kPMInvalidPaper-30897

Your application passed an invalid paper object.

Available in Mac OS X v10.2 and later.

kPMInvalidCalibrationTarget-30898

The dictionary specifying a printer calibration target is invalid.

Available in Mac OS X v10.3 and later.

kPMInvalidPreset-30899

Your application passed an invalid preset object.

Available in Mac OS X v10.3 and later.



Next Page > Hide TOC

© 2001, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-07-24)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.