Mac Developer Library

Developer

ApplicationServices Framework Reference Core Printing Reference

Options
Deployment Target:

On This Page
Language:

Core Printing Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import ApplicationServices

Objective-C

@import ApplicationServices;

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

  • PMPrintSession for general information about a print job

  • PMPrintSettings for print job parameters

  • PMPageFormat for the page format of a printed document

  • PMPaper for information about a type of paper

  • PMPrinter for information about a printer

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

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

Functions

  • Releases a printing object by decrementing its reference count.

    Declaration

    Swift

    func PMRelease(_ object: PMObject) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMRetain

  • Retains a printing object by incrementing its reference count.

    Declaration

    Swift

    func PMRetain(_ object: PMObject) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMRelease

  • Creates a new page format object.

    Declaration

    Swift

    func PMCreatePageFormat(_ pageFormat: UnsafeMutablePointer<PMPageFormat>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Creates a page format object with a specified paper.

    Declaration

    Swift

    func PMCreatePageFormatWithPMPaper(_ pageFormat: UnsafeMutablePointer<PMPageFormat>, _ paper: PMPaper) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • Copies the settings from one page format object into another.

    Declaration

    Swift

    func PMCopyPageFormat(_ formatSrc: PMPageFormat, _ formatDest: PMPageFormat) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMSessionDefaultPageFormat(_ printSession: PMPrintSession, _ pageFormat: PMPageFormat) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMSessionValidatePageFormat(_ printSession: PMPrintSession, _ pageFormat: PMPageFormat, _ result: UnsafeMutablePointer<Boolean>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMSessionCreatePageFormatList(_ printSession: PMPrintSession, _ printer: PMPrinter, _ pageFormatList: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.1 and later.

  • Creates a data representation of a page format object.

    Declaration

    Swift

    func PMPageFormatCreateDataRepresentation(_ pageFormat: PMPageFormat, _ data: UnsafeMutablePointer<Unmanaged<CFData>?>, _ format: PMDataFormat) -> OSStatus

    Objective-C

    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 OS X versions)

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

    • kPMDataFormatXMLCompressed (approximately 20 times smaller; compatible with 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • Creates a page format object from a data representation.

    Declaration

    Swift

    func PMPageFormatCreateWithDataRepresentation(_ data: CFData!, _ pageFormat: UnsafeMutablePointer<PMPageFormat>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • PMFlattenPageFormat PMFlattenPageFormat Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    Use PMPageFormatCreateDataRepresentation instead.

    Declaration

    Objective-C

    OSStatus PMFlattenPageFormat ( PMPageFormat pageFormat, Handle *flatFormat );

    Parameters

    pageFormat

    The page format object to flatten.

    flatFormat

    A pointer to your Handle variable. On return, the variable refers to a Memory Manager handle that contains the flattened page format object. The handle is allocated by the function. You are responsible for disposing of the handle.

    Return Value

    A result code. See Core Printing Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • PMFlattenPageFormatToCFData PMFlattenPageFormatToCFData Available in OS X v10.4 through OS X v10.9

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

    Deprecation Statement

    Use PMPageFormatCreateDataRepresentation instead.

    Declaration

    Objective-C

    OSStatus PMFlattenPageFormatToCFData ( PMPageFormat pageFormat, CFDataRef *flatFormat );

    Parameters

    pageFormat

    The page format object to flatten.

    flatFormat

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

    Return Value

    A result code. See Core Printing Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.4 through OS X v10.9.

    Deprecated in OS X v10.5.

  • PMFlattenPageFormatToURL PMFlattenPageFormatToURL Available in OS X v10.4 through OS X v10.9

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

    Deprecation Statement

    Use PMPageFormatCreateDataRepresentation and write the resulting data to your destination.

    Declaration

    Objective-C

    OSStatus PMFlattenPageFormatToURL ( PMPageFormat pageFormat, CFURLRef flattenFileURL );

    Parameters

    pageFormat

    The page format object to flatten.

    flatFormat

    A Core Foundation URL specifying a file to contain a flattened representation of the specified page format object. If the file already exists, it is overwritten. Only file-based URLs are supported.

    Return Value

    A result code. See Core Printing Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.4 through OS X v10.9.

    Deprecated in OS X v10.5.

  • PMUnflattenPageFormat PMUnflattenPageFormat Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    Use PMPageFormatCreateWithDataRepresentation instead.

    Declaration

    Objective-C

    OSStatus PMUnflattenPageFormat ( Handle flatFormat, PMPageFormat *pageFormat );

    Parameters

    flatFormat

    A handle to a previously flattened page format object. You are responsible for disposing of the handle.

    pageFormat

    A pointer to your PMPageFormat variable. On return, the variable refers to a page format object that contains the data retrieved from the flattened page format data. You are responsible for releasing the page format object with the function PMRelease.

    Return Value

    A result code. See Core Printing Result Codes. The result code kPMInvalidParameter is returned if the flattened PMPageFormat object was created by an incompatible version of Core Printing.

    Discussion

    The PMUnflattenPageFormat function creates a new PMPageFormat object that contains the data from the flattened page format data. You should call the function PMSessionValidatePageFormat to make sure the page format object contains valid values.

    If the function returns the result code kPMInvalidParameter you need to create a new, default page format object. You should also notify the user that the flattened page format is not valid.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • PMUnflattenPageFormatWithCFData PMUnflattenPageFormatWithCFData Available in OS X v10.4 through OS X v10.9

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

    Deprecation Statement

    Use PMPageFormatCreateWithDataRepresentation instead.

    Declaration

    Objective-C

    OSStatus PMUnflattenPageFormatWithCFData ( CFDataRef flattenCFData, PMPageFormat *pageFormat );

    Parameters

    flattenCFData

    A Core Foundation data object that contains a flattened representation of a page format object.

    pageFormat

    A pointer to your PMPageFormat variable. On return, the variable refers to a page format object that is rebuilt from the specified Core Foundation 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.4 through OS X v10.9.

    Deprecated in OS X v10.5.

  • PMUnflattenPageFormatWithURL PMUnflattenPageFormatWithURL Available in OS X v10.4 through OS X v10.9

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

    Deprecation Statement

    Instead read the data into a CFData object and use PMPageFormatCreateWithDataRepresentation.

    Declaration

    Objective-C

    OSStatus PMUnflattenPageFormatWithURL ( CFURLRef flattenFileURL, PMPageFormat *pageFormat );

    Parameters

    flattenFileURL

    A Core Foundation URL that specifies a file containing a flattened representation of a page format object.

    pageFormat

    A pointer to your PMPageFormat variable. On return, the variable refers to a page format object that is rebuilt from the specified file. You are responsible for releasing the page format object with the function PMRelease.

    Return Value

    A result code. See Core Printing Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.4 through OS X v10.9.

    Deprecated in OS X v10.5.

  • Obtains extended page format data previously stored by your application.

    Declaration

    Swift

    func PMGetPageFormatExtendedData(_ pageFormat: PMPageFormat, _ dataID: OSType, _ size: UnsafeMutablePointer<UInt32>, _ extendedData: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMSetPageFormatExtendedData(_ pageFormat: PMPageFormat, _ dataID: OSType, _ size: UInt32, _ extendedData: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Obtains the paper associated with a page format object.

    Declaration

    Swift

    func PMGetPageFormatPaper(_ pageFormat: PMPageFormat, _ paper: UnsafeMutablePointer<PMPaper>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMPageFormatGetPrinterID(_ pageFormat: PMPageFormat, _ printerID: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • Obtains the current setting for page orientation.

    Declaration

    Swift

    func PMGetOrientation(_ pageFormat: PMPageFormat, _ orientation: UnsafeMutablePointer<PMOrientation>) -> OSStatus

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMSetOrientation

  • Sets the page orientation for printing.

    Declaration

    Swift

    func PMSetOrientation(_ pageFormat: PMPageFormat, _ orientation: PMOrientation, _ lock: Boolean) -> OSStatus

    Objective-C

    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 (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 OS X v10.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 OS X v10.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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMGetOrientation

  • PMGetResolution PMGetResolution Available in OS X v10.0 through OS X v10.9

    Obtains the current application’s drawing resolution.

    Deprecation Statement

    Draw using Quartz 2D and call CGContextScaleCTM instead.

    Declaration

    Objective-C

    OSStatus PMGetResolution ( PMPageFormat pageFormat, PMResolution *res );

    Parameters

    pageFormat

    The page format object whose drawing resolution you want to obtain.

    res

    A pointer to your PMResolution structure. On return, the structure contains the drawing resolution of the current application.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    This function obtains the drawing resolution specified in the page format, not the resolution of the current printer. You can use PMPrinterGetPrinterResolutionCount and PMPrinterGetIndexedPrinterResolution to examine the available printer resolutions.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • PMSetResolution PMSetResolution Available in OS X v10.0 through OS X v10.9

    Sets the application drawing resolution.

    Deprecation Statement

    Draw using Quartz 2D and call CGContextScaleCTM instead.

    Declaration

    Objective-C

    OSStatus PMSetResolution ( PMPageFormat pageFormat, const PMResolution *res );

    Parameters

    pageFormat

    The page format object whose drawing resolution you want to set.

    res

    A pointer to a structure of type PMResolution that specifies the desired drawing resolution for your application. You should specify the best resolution for your data. The printing system handles the mapping between the resolution you specify and the printer resolution.

    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.

    Special Considerations

    This function was needed in the past because QuickDraw uses integer coordinates and has no notion of scaling coordinate systems. For Quartz drawing, this function is obsolete. To change the resolution, draw with fractional coordinates or scale the coordinate system and draw with integer coordinates.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

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

    Declaration

    Swift

    func PMGetScale(_ pageFormat: PMPageFormat, _ scale: UnsafeMutablePointer<Double>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMSetScale

  • Sets the scaling factor for the page and paper rectangles.

    Declaration

    Swift

    func PMSetScale(_ pageFormat: PMPageFormat, _ scale: Double) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMGetScale

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

    Declaration

    Swift

    func PMGetAdjustedPageRect(_ pageFormat: PMPageFormat, _ pageRect: UnsafeMutablePointer<PMRect>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • PMSetAdjustedPageRect PMSetAdjustedPageRect Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    To set a particular paper size and margins, obtain or create a PMPaper object and call PMCreatePageFormatWithPMPaper.

    Declaration

    Objective-C

    OSStatus PMSetAdjustedPageRect ( PMPageFormat pageFormat, const PMRect *pageRect );

    Parameters

    pageFormat

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

    pageRect

    A pointer to your PMRect data structure that specifies the desired size of the page rectangle, in points. The top-left coordinates should be (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

    This function is not recommended. You should call this function only if your application provides desktop publishing and the Page Setup dialog does not provide sufficient control. Typically, such applications display their own specialized document format dialog.

    If you decide to use this function, you must call the function between the creation and release of a printing session. See the function PMCreateSession. You can use PMSetAdjustedPageRect to set a drawing rectangle without going through the Page Setup dialog or calling other page format accessor functions. This function allows an application to specify the dimensions of the imageable area into which it draws.

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

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

    Declaration

    Swift

    func PMGetAdjustedPaperRect(_ pageFormat: PMPageFormat, _ paperRect: UnsafeMutablePointer<PMRect>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMGetUnadjustedPageRect(_ pageFormat: PMPageFormat, _ pageRect: UnsafeMutablePointer<PMRect>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMGetUnadjustedPaperRect(_ pageFormat: PMPageFormat, _ paperRect: UnsafeMutablePointer<PMRect>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • PMSetUnadjustedPaperRect PMSetUnadjustedPaperRect Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    To set a particular paper size, obtain or create a PMPaper object and call PMCreatePageFormatWithPMPaper.

    Declaration

    Objective-C

    OSStatus PMSetUnadjustedPaperRect ( PMPageFormat pageFormat, const PMRect *paperRect );

    Parameters

    pageFormat

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

    paperRect

    A pointer to a structure of type PMRect that specifies the desired paper size, in points. The coordinates of the upper-left corner of the paper rectangle are specified relative to the page rectangle. 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. The result code kPMValueOutOfRange indicates that the printer driver does not support the requested page size.

    Discussion

    This function is not recommended. You should call this function only if your application provides desktop publishing and the Page Setup dialog does not provide sufficient control. Typically, such applications display their own specialized document format dialog.

    If you decide to use this function, you must call it between the creation and release of a printing session. After using the function PMSetUnadjustedPaperRect you should always call PMSessionValidatePageFormat then call PMGetUnadjustedPaperRect to verify that the paper size you set is recorded by the printer driver.

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Creates a new print settings object.

    Declaration

    Swift

    func PMCreatePrintSettings(_ printSettings: UnsafeMutablePointer<PMPrintSettings>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMSessionDefaultPrintSettings(_ printSession: PMPrintSession, _ printSettings: PMPrintSettings) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMSessionValidatePrintSettings(_ printSession: PMPrintSession, _ printSettings: PMPrintSettings, _ result: UnsafeMutablePointer<Boolean>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Creates a data representation of a print settings object.

    Declaration

    Swift

    func PMPrintSettingsCreateDataRepresentation(_ printSettings: PMPrintSettings, _ data: UnsafeMutablePointer<Unmanaged<CFData>?>, _ format: PMDataFormat) -> OSStatus

    Objective-C

    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 OS X versions)

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

    • kPMDataFormatXMLCompressed (approximately 20 times smaller; compatible with 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • Creates a print settings object from a data representation.

    Declaration

    Swift

    func PMPrintSettingsCreateWithDataRepresentation(_ data: CFData!, _ printSettings: UnsafeMutablePointer<PMPrintSettings>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • PMFlattenPrintSettings PMFlattenPrintSettings Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    Use PMPrintSettingsCreateDataRepresentation instead.

    Declaration

    Objective-C

    OSStatus PMFlattenPrintSettings ( PMPrintSettings printSettings, Handle *flatSettings );

    Parameters

    printSettings

    The print settings object to flatten.

    flatSettings

    A pointer to your Handle variable. On return, the variable refers to a Memory Manager handle that contains a flattened print settings object. The handle is allocated by the function. You are responsible for disposing of the handle.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    There are no scoping requirements as to when you may use this function.

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • PMFlattenPrintSettingsToCFData PMFlattenPrintSettingsToCFData Available in OS X v10.4 through OS X v10.9

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

    Deprecation Statement

    Use PMPrintSettingsCreateDataRepresentation instead.

    Declaration

    Objective-C

    OSStatus PMFlattenPrintSettingsToCFData ( PMPrintSettings printSettings, CFDataRef *flatSetting );

    Parameters

    printSettings

    The print settings object to flatten.

    flatSetting

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

    Return Value

    A result code. See Core Printing Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.4 through OS X v10.9.

    Deprecated in OS X v10.5.

  • PMFlattenPrintSettingsToURL PMFlattenPrintSettingsToURL Available in OS X v10.4 through OS X v10.9

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

    Deprecation Statement

    Instead use PMPrintSettingsCreateDataRepresentation and write the resulting data to your destination.

    Declaration

    Objective-C

    OSStatus PMFlattenPrintSettingsToURL ( PMPrintSettings printSettings, CFURLRef flattenFileURL );

    Parameters

    printSettings

    The print settings object to flatten.

    flattenFileURL

    A Core Foundation URL specifying a file to contain a flattened representation of the specified print settings object. If the file already exists, it is overwritten. Only file-based URLs are supported.

    Return Value

    A result code. See Core Printing Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.4 through OS X v10.9.

    Deprecated in OS X v10.5.

  • PMUnflattenPrintSettings PMUnflattenPrintSettings Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    Use PMPrintSettingsCreateWithDataRepresentation instead.

    Declaration

    Objective-C

    OSStatus PMUnflattenPrintSettings ( Handle flatSettings, PMPrintSettings *printSettings );

    Parameters

    flatSettings

    A handle to a flattened representation of a print settings object.

    printSettings

    A pointer to your PMPrintSettings variable. On return, the variable refers to a print settings object that contains the data retrieved from the flattened print settings. You are responsible for releasing the print settings object with the function PMRelease.

    Return Value

    A result code. See Core Printing Result Codes. The result code kPMInvalidParameter is returned if the flattened PMPrintSettings object was created by an incompatible version of Core Printing.

    Discussion

    The PMUnflattenPrintSettings function creates a new PMPrintSettings object containing the data from the flattened print settings. You should call the function PMSessionValidatePrintSettings, as some values in the print settings object may no longer be valid.

    If the function returns the result code kPMInvalidParameter you need to create a new, default print settings object. You should also notify the user that the print settings are not valid.

    There are no scoping requirements as to when you may use this function.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • PMUnflattenPrintSettingsWithCFData PMUnflattenPrintSettingsWithCFData Available in OS X v10.4 through OS X v10.9

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

    Deprecation Statement

    Use PMPrintSettingsCreateWithDataRepresentation instead.

    Declaration

    Objective-C

    OSStatus PMUnflattenPrintSettingsWithCFData ( CFDataRef flattenCFData, PMPrintSettings *printSettings );

    Parameters

    flattenCFData

    A flattened representation of a print settings object.

    printSettings

    A pointer to your PMPrintSettings variable. On return, the variable refers to a print settings object rebuilt from the specified Core Foundation 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.4 through OS X v10.9.

    Deprecated in OS X v10.5.

  • PMUnflattenPrintSettingsWithURL PMUnflattenPrintSettingsWithURL Available in OS X v10.4 through OS X v10.9

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

    Deprecation Statement

    Instead read the data into a CFData object and use PMPrintSettingsCreateWithDataRepresentation.

    Declaration

    Objective-C

    OSStatus PMUnflattenPrintSettingsWithURL ( CFURLRef flattenFileURL, PMPrintSettings *printSettings );

    Parameters

    flattenFileURL

    A file containing a flattened representation of a print settings object.

    printSettings

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

    Return Value

    A result code. See Core Printing Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.4 through OS X v10.9.

    Deprecated in OS X v10.5.

  • Copies the settings from one print settings object into another.

    Declaration

    Swift

    func PMCopyPrintSettings(_ settingSrc: PMPrintSettings, _ settingDest: PMPrintSettings) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Converts print settings into a CUPS options string.

    Declaration

    Swift

    func PMPrintSettingsToOptions(_ settings: PMPrintSettings, _ options: UnsafeMutablePointer<UnsafeMutablePointer<Int8>>) -> OSStatus

    Objective-C

    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 OS X v10.5 and later, Apple recommends that you use the PMPrintSettingsToOptionsWithPrinterAndPageFormat function instead.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMPrintSettingsToOptionsWithPrinterAndPageFormat(_ settings: PMPrintSettings, _ printer: PMPrinter, _ pageFormat: PMPageFormat, _ options: UnsafeMutablePointer<UnsafeMutablePointer<Int8>>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • PMGetPrintSettingsExtendedData PMGetPrintSettingsExtendedData Available in OS X v10.0 through OS X v10.9

    Obtains extended print settings data previously stored by your application.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.6.

  • PMSetPrintSettingsExtendedData PMSetPrintSettingsExtendedData Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.6.

  • Obtains the number of the first page to be printed.

    Declaration

    Swift

    func PMGetFirstPage(_ printSettings: PMPrintSettings, _ first: UnsafeMutablePointer<UInt32>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMSetFirstPage

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

    Declaration

    Swift

    func PMSetFirstPage(_ printSettings: PMPrintSettings, _ first: UInt32, _ lock: Boolean) -> OSStatus

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMGetFirstPage

  • Obtains the number of the last page to be printed.

    Declaration

    Swift

    func PMGetLastPage(_ printSettings: PMPrintSettings, _ last: UnsafeMutablePointer<UInt32>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMSetLastPage

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

    Declaration

    Swift

    func PMSetLastPage(_ printSettings: PMPrintSettings, _ last: UInt32, _ lock: Boolean) -> OSStatus

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMGetLastPage

  • Obtains the valid range of pages that can be printed.

    Declaration

    Swift

    func PMGetPageRange(_ printSettings: PMPrintSettings, _ minPage: UnsafeMutablePointer<UInt32>, _ maxPage: UnsafeMutablePointer<UInt32>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMSetPageRange

  • Sets the valid range of pages that can be printed.

    Declaration

    Swift

    func PMSetPageRange(_ printSettings: PMPrintSettings, _ minPage: UInt32, _ maxPage: UInt32) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMGetPageRange

  • Obtains the name of a print job.

    Declaration

    Swift

    func PMPrintSettingsGetJobName(_ printSettings: PMPrintSettings, _ name: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

  • Specifies the name of a print job.

    Declaration

    Swift

    func PMPrintSettingsSetJobName(_ printSettings: PMPrintSettings, _ name: CFString!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func PMGetCopies(_ printSettings: PMPrintSettings, _ copies: UnsafeMutablePointer<UInt32>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMSetCopies

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

    Declaration

    Swift

    func PMSetCopies(_ printSettings: PMPrintSettings, _ copies: UInt32, _ lock: Boolean) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

    See Also

    PMGetCopies

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

    Declaration

    Swift

    func PMGetCollate(_ printSettings: PMPrintSettings, _ collate: UnsafeMutablePointer<Boolean>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

    See Also

    PMSetCollate

  • Specifies whether the job collate option is selected.

    Declaration

    Swift

    func PMSetCollate(_ printSettings: PMPrintSettings, _ collate: Boolean) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

    See Also

    PMGetCollate

  • Obtains the selected duplex mode.

    Declaration

    Swift

    func PMGetDuplex(_ printSettings: PMPrintSettings, _ duplexSetting: UnsafeMutablePointer<PMDuplexMode>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

  • Sets the duplex mode.

    Declaration

    Swift

    func PMSetDuplex(_ printSettings: PMPrintSettings, _ duplexSetting: PMDuplexMode) -> OSStatus

    Objective-C

    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. This function allows you to specify whether the document should be printed single-sided, double-sided with short-edge binding, or double-sided with long-edge binding.

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

    See Also

    PMGetDuplex

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

    Declaration

    Swift

    func PMPrintSettingsGetValue(_ printSettings: PMPrintSettings, _ key: CFString!, _ value: UnsafeMutablePointer<Unmanaged<AnyObject>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func PMPrintSettingsSetValue(_ printSettings: PMPrintSettings, _ key: CFString!, _ value: AnyObject!, _ locked: Boolean) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func PMPrintSettingsCopyAsDictionary(_ printSettings: PMPrintSettings, _ settingsDictionary: UnsafeMutablePointer<Unmanaged<CFDictionary>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • Obtains the keys for items in a print settings object.

    Declaration

    Swift

    func PMPrintSettingsCopyKeys(_ printSettings: PMPrintSettings, _ settingsKeys: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • PMGetJobNameCFString PMGetJobNameCFString Available in OS X v10.0 through OS X v10.9

    Obtains the name of the print job.

    Deprecation Statement

    Use PMPrintSettingsGetJobName instead.

    Declaration

    Objective-C

    OSStatus PMGetJobNameCFString ( PMPrintSettings printSettings, CFStringRef *name );

    Parameters

    printSettings

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

    name

    A pointer to your CFStringRef variable. On return, the variable refers to a string that contains the name of the print job. Despite what its name implies, the function PMGetJobNameCFString has Create/Copy semantics which means your application must release the string returned to it.

    Return Value

    A result code. See Core Printing Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • PMSetJobNameCFString PMSetJobNameCFString Available in OS X v10.0 through OS X v10.9

    Specifies the name of a print job.

    Deprecation Statement

    Use PMPrintSettingsSetJobName instead.

    Declaration

    Objective-C

    OSStatus PMSetJobNameCFString ( 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. The result code kPMInvalidParameter is returned if you pass NULL or an empty string in the name parameter.

    Discussion

    You should call this function before you open the Print dialog.

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

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

    Declaration

    Swift

    func PMCreateSession(_ printSession: UnsafeMutablePointer<PMPrintSession>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMSessionGetDataFromSession(_ printSession: PMPrintSession, _ key: CFString!, _ data: UnsafeMutablePointer<Unmanaged<AnyObject>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMSessionSetDataInSession(_ printSession: PMPrintSession, _ key: CFString!, _ data: AnyObject!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Obtains the current printer associated with a printing session.

    Declaration

    Swift

    func PMSessionGetCurrentPrinter(_ printSession: PMPrintSession, _ currentPrinter: UnsafeMutablePointer<PMPrinter>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • PMSessionSetCurrentPrinter PMSessionSetCurrentPrinter Available in OS X v10.1 through OS X v10.9

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

    Deprecation Statement

    Use PMSessionSetCurrentPMPrinter instead.

    Declaration

    Objective-C

    OSStatus PMSessionSetCurrentPrinter ( PMPrintSession session, CFStringRef printerName );

    Parameters

    session

    The printing session whose printer you want to change.

    printerName

    The name of the printer you want to set as the current printer.

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.1 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Changes the current printer for a printing session.

    Declaration

    Swift

    func PMSessionSetCurrentPMPrinter(_ session: PMPrintSession, _ printer: PMPrinter) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Deprecation Statement

    If you’re drawing using Quartz 2D instead of QuickDraw, use PMSessionBeginCGDocument or PMSessionBeginCGDocumentNoDialog; for submitting PostScript data, use PMPrinterPrintWithFile or PMPrinterPrintWithProvider; to draw EPS data, use PMCGImageCreateWithEPSDataProvider.

    Declaration

    Objective-C

    OSStatus PMSessionGetDocumentFormatGeneration ( PMPrintSession printSession, CFArrayRef *docFormats );

    Parameters

    printSession

    The printing session whose spool file formats you want to obtain.

    docFormats

    A pointer to your CFArrayRef variable. On return, the variable refers to a Core Foundation array that contains the MIME types for the available spool file formats. Each element in the array is a Core Foundation string. Despite what its name implies, the function PMSessionGetDocumentFormatGeneration has Create/Copy semantics which means you are responsible for releasing the array.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    You must call the function PMSessionGetDocumentFormatGeneration between the creation and release of a printing session. See the function PMCreateSession. You should call PMSessionGetDocumentFormatGeneration only after the Print dialog is dismissed.

    The function PMSessionGetDocumentFormatGeneration determines the spool file formats that the specific print job supports. Spool file formats are represented by MIME types. The OS X print spooler supports PDF and PICT + PS. The default spool file format is PDF. PICT + PS is supported only for printing to a PostScript printer.

    Special Considerations

    The PICT + PS spool file format is not available on Intel-based systems.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

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

    Deprecation Statement

    If you’re drawing using Quartz 2D instead of QuickDraw, use PMSessionBeginCGDocument or PMSessionBeginCGDocumentNoDialog; for submitting PostScript data, use PMPrinterPrintWithFile or PMPrinterPrintWithProvider; to draw EPS data, use PMCGImageCreateWithEPSDataProvider.

    Declaration

    Objective-C

    OSStatus PMSessionSetDocumentFormatGeneration ( PMPrintSession printSession, CFStringRef docFormat, CFArrayRef graphicsContextTypes, CFTypeRef options );

    Parameters

    printSession

    The printing session whose spool file format and graphics context type you want to specify.

    docFormat

    A Core Foundation string that specifies the desired spool file format as a MIME type. See Document Format Strings for a description of the constants you can use to specify the document format.

    graphicsContexts

    A reference to a Core Foundation array of graphics contexts to use for drawing pages within the print loop. You can supply a QuickDraw graphics context (kPMGraphicsContextQuickDraw) or a Quartz 2D graphics context (kPMGraphicsContextCoreGraphics). An array of length 1 is the only length that is supported, regardless of graphics context type. See Graphics Context Types for a description of the constants you can use to specify a graphics context.

    options

    Reserved for future use.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    You only need to call the function PMSessionSetDocumentFormatGeneration if you want to specify a format other than the default format (PDF) or a graphics context other than the default context (QuickDraw). If you want to use the default format for the operating system and to draw with QuickDraw, then you do not need to call this function. If you want to generate PICT + PS to use as one of the supported formats, then call PMSessionSetDocumentFormatGeneration to set the graphics context to QuickDraw and the format to PICT + PS. Note that the PICT + PS format is not available on Intel-based systems.

    If you want to use a Quartz 2D graphics context to draw each page, you can call the following code to inform the printing system in all versions of OS X.

    • static OSStatus MyPMSessionBeginCGDocument (
    • PMPrintSession printSession,
    • PMPrintSettings printSettings,
    • PMPageFormat pageFormat)
    • {
    • OSStatus err = noErr;
    • // Use the simpler call if it is present.
    • if(&PMSessionBeginCGDocument != NULL) {
    • err = PMSessionBeginCGDocument (printSession, printSettings, pageFormat);
    • }
    • else {
    • CFStringRef s[1] = { kPMGraphicsContextCoreGraphics };
    • CFArrayRef graphicsContextsArray = CFArrayCreate (
    • kCFAllocatorDefault, (const void**)s, 1, &kCFTypeArrayCallBacks);
    • err = PMSessionSetDocumentFormatGeneration (
    • printSession, kPMDocumentFormatPDF, graphicsContextsArray, NULL);
    • CFRelease (graphicsContextsArray);
    • if(!err)
    • err = PMSessionBeginDocument (
    • printSession, printSettings, pageFormat);
    • }
    • return err;
    • }

    The previous code informs the printing system that you want a Quartz graphics context, but you get the actual context for your printing port only after you call the function PMSessionBeginPage and then call the following code.

    • static OSStatus MyPMSessionGetCGGraphicsContext (
    • PMPrintSession printSession,
    • CGContextRef *printingContextP)
    • {
    • OSStatus err = noErr;
    • // Use the simpler call if it is present.
    • if(&PMSessionGetCGGraphicsContext != NULL) {
    • err = PMSessionGetCGGraphicsContext (printSession, printingContextP);
    • }
    • else {
    • err = PMSessionGetGraphicsContext (
    • printSession, kPMGraphicsContextCoreGraphics,
    • (void**)printingContextP);
    • }
    • return err;
    • }

    The printing context you get is a Quartz context into which you can draw. Note that the default coordinate system for Quartz 2D is not the same as that used for QuickDraw. Quartz 2D defines the coordinates of the lower-left corner of the sheet as (0,0) whereas the origin for the QuickDraw port is the upper-left corner of the imageable area.

    You must call this function between the creation and release of a printing session. See the function PMCreateSession. You must call the function PMSessionSetDocumentFormatGeneration before you call PMSessionBeginDocument or PMSessionBeginDocumentNoDialog. Before requesting a spool file format using this function, you should call the function PMSessionGetDocumentFormatGeneration to get the list of supported formats.

    Special Considerations

    The PICT + PS spool file format is not available on Intel-based systems.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

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

    Declaration

    Swift

    func PMSessionGetCGGraphicsContext(_ printSession: PMPrintSession, _ context: UnsafeMutablePointer<Unmanaged<CGContext>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

  • PMSessionGetGraphicsContext PMSessionGetGraphicsContext Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    Use PMSessionGetCGGraphicsContext instead.

    Declaration

    Objective-C

    OSStatus PMSessionGetGraphicsContext ( PMPrintSession printSession, CFStringRef graphicsContextType, void **graphicsContext );

    Parameters

    printSession

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

    graphicsType

    The desired graphics context type. This parameter is currently ignored.

    graphicsContext

    On return, a reference to the current graphics context. The graphics context returned is the one last set by a call to the function PMSessionSetDocumentFormatGeneration or the default (QuickDraw) if there was no call to the function. You must typecast the context to an appropriate graphics type, either grafPtr or CGContextRef.

    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 must also call the function PMSessionGetGraphicsContext within the scope of the functions PMSessionBeginPage and PMSessionEndPage.

    In OS X v10.3 and earlier, you should call this function for each page you draw for a print job. After each call to the function PMSessionBeginPage your application should call PMSessionGetGraphicsContext to obtain the current graphics context. If that context is a QuickDraw context, then set the drawing port to this port by calling the QuickDraw SetPort function. See the discussion of the function PMSessionBeginPage for more information.

    Special Considerations

    In OS X v10.4 and later, Apple recommends using the function PMSessionGetCGGraphicsContext instead of this function. QuickDraw is deprecated and your application should be using Quartz 2D for its rendering.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

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

    Declaration

    Swift

    func PMSessionError(_ printSession: PMPrintSession) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMSessionSetError(_ printSession: PMPrintSession, _ printError: OSStatus) -> OSStatus

    Objective-C

    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 OS X, so this usage is not available.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • PMSessionGeneral PMSessionGeneral Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    Use PMPrinterGetCommInfo instead.

    Declaration

    Objective-C

    OSStatus PMSessionGeneral ( PMPrintSession printSession, Ptr pData );

    Parameters

    printSession

    The printing session whose data you want to obtain.

    pData

    A pointer to a PrGeneral data structure.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    The function PMSessionGeneral is valid for the printing session passed to the function. In OS X, the function PMSessionGeneral makes an attempt to get the requested data if the opcode is getPSInfoOp. Otherwise the result code kPMNotImplemented is returned.

    For more information about using the function PMSessionGeneral, see Supporting Printing in Your Carbon Application.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Obtains the localized name for a preset.

    Declaration

    Swift

    func PMPresetCopyName(_ preset: PMPreset, _ paperID: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMPresetCreatePrintSettings(_ preset: PMPreset, _ session: PMPrintSession, _ printSettings: UnsafeMutablePointer<PMPrintSettings>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • Obtains the attributes of a preset.

    Declaration

    Swift

    func PMPresetGetAttributes(_ preset: PMPreset, _ attributes: UnsafeMutablePointer<Unmanaged<CFDictionary>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • PMPaperCreate PMPaperCreate Available in OS X v10.3 through OS X v10.9

    Creates a paper object.

    Deprecation Statement

    Use PMPrinterGetPaperList to find the built-in papers available for a given printer or use PMPaperCreateCustom to create a custom paper.

    Declaration

    Objective-C

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

    Parameters

    printer

    A printer object for which the paper is appropriate.

    id

    A unique identifier for this paper.

    name

    The name to display to the user for this 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 paper object with the specified attributes. You are responsible for releasing the paper object with the function PMRelease. The variable is set to NULL if the object could not be created.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    This function creates a paper object appropriate for the specified printer. To obtain one of the available built-in paper sizes for a given printer, you should use the function PMPrinterGetPaperList.

    Special Considerations

    This function creates a paper object but does not mark it as a custom paper, so it appears to the printing system as if it were a built-in paper. This can be produce unpredictable results, so this function is deprecated.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.3 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Creates a custom paper object.

    Declaration

    Swift

    func PMPaperCreateCustom(_ printer: PMPrinter, _ id: CFString!, _ name: CFString!, _ width: Double, _ height: Double, _ margins: UnsafePointer<PMPaperMargins>, _ paperP: UnsafeMutablePointer<PMPaper>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func PMPaperIsCustom(_ paper: PMPaper) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • Obtains the identifier of a paper object.

    Declaration

    Swift

    func PMPaperGetID(_ paper: PMPaper, _ paperID: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • PMPaperGetName PMPaperGetName Available in OS X v10.3 through OS X v10.9

    Obtains the name for a given paper.

    Declaration

    Objective-C

    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 OS X v10.5 and later, instead of using this function, Apple recommends using the function PMPaperCreateLocalizedName.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.3 through OS X v10.9.

    Deprecated in OS X v10.7.

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

    Declaration

    Swift

    func PMPaperGetWidth(_ paper: PMPaper, _ paperWidth: UnsafeMutablePointer<Double>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMPaperGetHeight(_ paper: PMPaper, _ paperHeight: UnsafeMutablePointer<Double>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMPaperGetMargins(_ paper: PMPaper, _ paperMargins: UnsafeMutablePointer<PMPaperMargins>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • Obtains the localized name for a given paper.

    Declaration

    Swift

    func PMPaperCreateLocalizedName(_ paper: PMPaper, _ printer: PMPrinter, _ paperName: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    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 OS X v10.5 and later, Apple recommends using this function instead of PMPaperGetName.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func PMPaperGetPrinterID(_ paper: PMPaper, _ printerID: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • Obtains the PPD paper name for a given paper.

    Declaration

    Swift

    func PMPaperGetPPDPaperName(_ paper: PMPaper, _ paperName: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func PMSessionBeginCGDocumentNoDialog(_ printSession: PMPrintSession, _ printSettings: PMPrintSettings, _ pageFormat: PMPageFormat) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

  • PMSessionBeginDocumentNoDialog PMSessionBeginDocumentNoDialog Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    Use PMSessionBeginCGDocumentNoDialog instead.

    Declaration

    Objective-C

    OSStatus PMSessionBeginDocumentNoDialog ( 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

    The function PMSessionBeginDocumentNoDialog starts a print job and should be called within your application’s print loop. This function is similar to the function PMSessionBeginDocument 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. If you present a printing dialog before you call PMSessionBeginDocumentNoDialog, when calling this function you should use the same PMPrintSession object you used to present the dialog.

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

    This function must be called before its corresponding End function (PMSessionEndDocumentNoDialog). If the function PMSessionBeginDocumentNoDialog returns noErr, you must 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.

    Special Considerations

    In OS X v10.4 and later, Apple recommends using the function PMSessionBeginCGDocumentNoDialog instead of this function. QuickDraw is deprecated and your application should be using Quartz 2D for its rendering.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

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

    Declaration

    Swift

    func PMSessionEndDocumentNoDialog(_ printSession: PMPrintSession) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func PMSessionBeginPageNoDialog(_ printSession: PMPrintSession, _ pageFormat: PMPageFormat, _ pageFrame: UnsafePointer<PMRect>) -> OSStatus

    Objective-C

    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 OS X v10.5, the pageFormat parameter is ignored. In 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func PMSessionEndPageNoDialog(_ printSession: PMPrintSession) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • PMSessionSetIdleProc PMSessionSetIdleProc Available in OS X v10.0 through OS X v10.7

    Installs an idle callback function in your print loop.

    Deprecation Statement

    There is no replacement; this function was included to facilitate porting legacy applications to OS X, but it serves no useful purpose.

    Declaration

    Objective-C

    OSStatus PMSessionSetIdleProc ( PMPrintSession printSession, PMIdleUPP idleProc );

    Parameters

    printSession

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

    idleProc

    A universal procedure pointer to your idle function. Your idle function is defined by the callback PMIdleProcPtr.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    You do not need this function in OS X. Instead, use the standard idle proc.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.7.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

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

    Declaration

    Swift

    func PMSessionSetDestination(_ printSession: PMPrintSession, _ printSettings: PMPrintSettings, _ destType: PMDestinationType, _ destFormat: CFString!, _ destLocation: CFURL!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.1 and later.

  • Obtains the output destination for a print job.

    Declaration

    Swift

    func PMSessionGetDestinationType(_ printSession: PMPrintSession, _ printSettings: PMPrintSettings, _ destTypeP: UnsafeMutablePointer<PMDestinationType>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.1 and later.

  • Obtains the destination format for a print job.

    Declaration

    Swift

    func PMSessionCopyDestinationFormat(_ printSession: PMPrintSession, _ printSettings: PMPrintSettings, _ destFormatP: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.1 and later.

  • Obtains a destination location for a print job.

    Declaration

    Swift

    func PMSessionCopyDestinationLocation(_ printSession: PMPrintSession, _ printSettings: PMPrintSettings, _ destLocationP: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func PMSessionCopyOutputFormatList(_ printSession: PMPrintSession, _ destType: PMDestinationType, _ documentFormatP: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func PMServerLaunchPrinterBrowser(_ server: PMServer, _ options: CFDictionary!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • Creates a list of printers available to a print server.

    Declaration

    Swift

    func PMServerCreatePrinterList(_ server: PMServer, _ printerList: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func PMSessionCreatePrinterList(_ printSession: PMPrintSession, _ printerList: UnsafeMutablePointer<Unmanaged<CFArray>?>, _ currentIndex: UnsafeMutablePointer<CFIndex>, _ currentPrinter: UnsafeMutablePointer<PMPrinter>) -> OSStatus

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.1 and later.

  • Creates a printer object from a print queue identifier.

    Declaration

    Swift

    func PMPrinterCreateFromPrinterID(_ printerID: CFString!) -> PMPrinter

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

    See Also

    PMPrinterGetID

  • Creates a generic printer object.

    Declaration

    Swift

    func PMCreateGenericPrinter(_ printer: UnsafeMutablePointer<PMPrinter>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func PMPrinterCopyDescriptionURL(_ printer: PMPrinter, _ descriptionType: CFString!, _ fileURL: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

  • Obtains the device URI of a given printer.

    Declaration

    Swift

    func PMPrinterCopyDeviceURI(_ printer: PMPrinter, _ deviceURI: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func PMPrinterCopyHostName(_ printer: PMPrinter, _ hostNameP: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • Obtains a list of print settings presets for a printer.

    Declaration

    Swift

    func PMPrinterCopyPresets(_ printer: PMPrinter, _ presetList: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • Obtains information about the communication channel for a printer.

    Declaration

    Swift

    func PMPrinterGetCommInfo(_ printer: PMPrinter, _ supportsTransparentP: UnsafeMutablePointer<Boolean>, _ supportsEightBitP: UnsafeMutablePointer<Boolean>) -> OSStatus

    Objective-C

    OSStatus PMPrinterGetCommInfo ( PMPrinter printer, Boolean *supportsControlCharRangeP, 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • PMPrinterGetDescriptionURL PMPrinterGetDescriptionURL Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    Use PMPrinterCopyDescriptionURL instead.

    Declaration

    Objective-C

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

    Parameters

    printer

    The printer whose description file you want to obtain.

    descriptionType

    A Core Foundation string that specifies the type of description file for the selected printer. Currently, there is only one type defined—kPMPPDDescriptionType.

    fileURL

    A pointer to your CFURLRef variable. On return, the variable refers to a URL for the printer’s description file. In spite of the name, the function PMPrinterGetDescriptionURL has Create/Copy semantics which means the caller must release the returned URL if it is not NULL and the result code noErr is returned.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • PMPrinterGetDeviceURI PMPrinterGetDeviceURI Available in OS X v10.2 through OS X v10.9

    Obtains a copy of a printer's device URI.

    Deprecation Statement

    Use PMPrinterCopyDeviceURI instead.

    Declaration

    Objective-C

    OSStatus PMPrinterGetDeviceURI ( 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 URI for the location of the printer device. In spite of the name, this function has Create/Copy semantics which means the caller must release the returned URL if it is not NULL and the result code noErr is returned.

    Return Value

    A result code. See Core Printing Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

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

    Declaration

    Swift

    func PMPrinterGetDriverCreator(_ printer: PMPrinter, _ creator: UnsafeMutablePointer<OSType>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMPrinterGetDriverReleaseInfo(_ printer: PMPrinter, _ release: UnsafeMutablePointer<VersRec>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Returns the unique identifier of a printer.

    Declaration

    Swift

    func PMPrinterGetID(_ printer: PMPrinter) -> Unmanaged<CFString>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Obtains information about the imaging language for the specified printer.

    Declaration

    Swift

    func PMPrinterGetLanguageInfo(_ printer: PMPrinter, _ info: UnsafeMutablePointer<PMLanguageInfo>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Returns the location of a printer.

    Declaration

    Swift

    func PMPrinterGetLocation(_ printer: PMPrinter) -> Unmanaged<CFString>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Obtains the manufacturer and model name of the specified printer.

    Declaration

    Swift

    func PMPrinterGetMakeAndModelName(_ printer: PMPrinter, _ makeAndModel: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func PMPrinterGetMimeTypes(_ printer: PMPrinter, _ settings: PMPrintSettings, _ mimeTypes: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • Returns the human-readable name of a printer.

    Declaration

    Swift

    func PMPrinterGetName(_ printer: PMPrinter) -> Unmanaged<CFString>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func PMPrinterGetOutputResolution(_ printer: PMPrinter, _ printSettings: PMPrintSettings, _ resolutionP: UnsafeMutablePointer<PMResolution>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func PMPrinterSetOutputResolution(_ printer: PMPrinter, _ printSettings: PMPrintSettings, _ resolutionP: UnsafePointer<PMResolution>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • Obtains the list of papers available for a printer.

    Declaration

    Swift

    func PMPrinterGetPaperList(_ printer: PMPrinter, _ paperList: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • PMPrinterGetPrinterResolution PMPrinterGetPrinterResolution Available in OS X v10.0 through OS X v10.9

    Obtains a resolution setting for the specified printer.

    Deprecation Statement

    Use PMPrinterGetPrinterResolutionCount and PMPrinterGetIndexedPrinterResolution to examine the available printer resolutions.

    Declaration

    Objective-C

    OSStatus PMPrinterGetPrinterResolution ( PMPrinter printer, PMTag tag, PMResolution *res );

    Parameters

    printer

    The printer whose resolution you want to obtain.

    tag

    A tag that specifies the kind of resolution information you want to obtain (minimum, maximum, default, and so forth). See Tag Constants for a description of the constants you can pass in this parameter.

    res

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

    Return Value

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

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

    Declaration

    Swift

    func PMPrinterGetPrinterResolutionCount(_ printer: PMPrinter, _ count: UnsafeMutablePointer<UInt32>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMPrinterGetIndexedPrinterResolution(_ printer: PMPrinter, _ index: UInt32, _ res: UnsafeMutablePointer<PMResolution>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func PMPrinterGetState(_ printer: PMPrinter, _ state: UnsafeMutablePointer<PMPrinterState>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Sets the default printer for the current user.

    Declaration

    Swift

    func PMPrinterSetDefault(_ printer: PMPrinter) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func PMPrinterIsDefault(_ printer: PMPrinter) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func PMPrinterIsFavorite(_ printer: PMPrinter) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func PMPrinterIsPostScriptCapable(_ printer: PMPrinter) -> Boolean

    Objective-C

    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 OS X printing system can render PostScript content on non-PostScript printers.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Determines whether a printer is a PostScript printer.

    Declaration

    Swift

    func PMPrinterIsPostScriptPrinter(_ printer: PMPrinter, _ isPSPrinter: UnsafeMutablePointer<Boolean>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func PMPrinterIsRemote(_ printer: PMPrinter, _ isRemoteP: UnsafeMutablePointer<Boolean>) -> OSStatus

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMPrinterPrintWithFile(_ printer: PMPrinter, _ settings: PMPrintSettings, _ format: PMPageFormat, _ mimeType: CFString!, _ fileURL: CFURL!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMPrinterPrintWithProvider(_ printer: PMPrinter, _ settings: PMPrintSettings, _ format: PMPageFormat, _ mimeType: CFString!, _ provider: CGDataProvider!) -> OSStatus

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMCopyAvailablePPDs(_ domain: PMPPDDomain, _ ppds: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • Obtains a localized PostScript printer description (PPD) file.

    Declaration

    Swift

    func PMCopyLocalizedPPD(_ ppd: CFURL!, _ localizedPPD: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatus

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMCopyPPDData(_ ppd: CFURL!, _ data: UnsafeMutablePointer<Unmanaged<CFData>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMCGImageCreateWithEPSDataProvider(_ epsDataProvider: CGDataProvider!, _ epsPreview: CGImage!) -> Unmanaged<CGImage>!

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func PMPrinterWritePostScriptToURL(_ printer: PMPrinter, _ settings: PMPrintSettings, _ format: PMPageFormat, _ mimeType: CFString!, _ sourceFileURL: CFURL!, _ destinationFileURL: CFURL!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • PMSessionPostScriptBegin PMSessionPostScriptBegin Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    OSStatus PMSessionPostScriptBegin ( PMPrintSession printSession );

    Parameters

    printSession

    The current printing session.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    You must call the function PMSessionPostScriptBegin between the creation and release of a printing session. See the function PMCreateSession. You must also call the function within the scope of the functions PMSessionBeginPage and PMSessionEndPage.

    To ensure that the current printer driver supports PostScript data, call PMSessionGetDocumentFormatGeneration before you call the function PMSessionPostScriptBegin. Check the list of supported spool file formats. If PICT + PS is one of them, select that format by calling the function PMSessionSetDocumentFormatGeneration. The function PMSessionSetDocumentFormatGeneration must be called before you call PMSessionBeginDocument.

    The function PMSessionPostScriptBegin is not useful unless the current port is the printing port. The function returns true if the document format is not PICT + PS.

    Special Considerations

    The PICT + PS spool file format is not available on Intel-based systems.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • PMSessionPostScriptData PMSessionPostScriptData Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    OSStatus PMSessionPostScriptData ( PMPrintSession printSession, Ptr psPtr, Size len );

    Parameters

    printSession

    The current printing session.

    psPtr

    A pointer to the PostScript data you want to pass to the current printer driver.

    len

    The number of bytes of PostScript data.

    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. Typically you call this function with the scope of calls to the functions PMSessionPostScriptBegin and PMSessionPostScriptEnd.

    The function PMSessionPostScriptData is not useful unless the current port is the printing port and the document format is PICT + PS.

    Special Considerations

    The PICT + PS spool file format is not available on Intel-based systems.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • PMSessionPostScriptEnd PMSessionPostScriptEnd Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    OSStatus PMSessionPostScriptEnd ( PMPrintSession printSession );

    Parameters

    printSession

    The current 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. You must also call this function with the scope of calls to the functions PMSessionBeginPage and PMSessionEndPage.

    You call the function PMSessionPostScriptEnd to complete a PostScript block started with PMSessionPostScriptBegin. The function PMSessionPostScriptEnd is not useful unless the current port is the printing port and the document format is PICT + PS.

    Special Considerations

    The PICT + PS spool file format is not available on Intel-based systems.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • PMSessionPostScriptFile PMSessionPostScriptFile Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    OSStatus PMSessionPostScriptFile ( PMPrintSession printSession, FSSpec *psFile );

    Parameters

    printSession

    The current printing session.

    psFile

    A pointer to a variable that specifies a file location. The file should contain the PostScript data you want to pass to the current printer driver.

    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 typically call this function within the scope of calls to the function PMSessionPostScriptBegin and PMSessionPostScriptEnd.

    The function PMSessionPostScriptFile is not useful unless the current port is the printing port and the document format is PICT + PS.

    Special Considerations

    The PICT + PS spool file format is not available on Intel-based systems.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • PMSessionPostScriptHandle PMSessionPostScriptHandle Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    OSStatus PMSessionPostScriptHandle ( PMPrintSession printSession, Handle psHandle );

    Parameters

    printSession

    The current printing session.

    psHandle

    A handle to the PostScript data you want to pass to the current printer driver. You must make sure the handle is of the appropriate size for the data, otherwise you risk corrupting the spool file.

    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 must also call this function within the scope of calls to the function PMSessionPostScriptBegin and PMSessionPostScriptEnd.

    The function PMSessionPostScriptEnd is not useful unless the current port is the printing port and the document format is PICT + PS.

    Special Considerations

    The PICT + PS spool file format is not available on Intel-based systems.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • PMSessionSetPSInjectionData PMSessionSetPSInjectionData Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    Use PMPrinterPrintWithFile or PMPrinterPrintWithProvider instead.

    Declaration

    Objective-C

    OSStatus PMSessionSetPSInjectionData ( PMPrintSession printSession, PMPrintSettings printSettings, CFArrayRef injectionDictArray );

    Parameters

    printSession

    The current printing session.

    printSettings

    The print settings object in which to place the specified injection points.

    injectionDictArray

    A reference to a Core Foundation array that contains one or more Core Foundation dictionary (CFDictionary) entries. Each dictionary entry specifies PostScript injection data you want inserted at a specific point in the print stream. See PostScript Injection Dictionary Keys for a description of the constants you can use as keys for these dictionary entries.

    Return Value

    A result code. See Core Printing Result Codes. The result code kPMInvalidParameter is returned if the injectionDictArray object contains any invalid entries. The result code kPMInvalidPrintSession is returned if the document format has not been set to kPMDocumentFormatPICTPS for the specified printing session.

    Discussion

    You must call this function between the creation and release of a printing session. See the function PMCreateSession. Before calling PMSessionSetPSInjectionData, your application must set the document format of the printing session to kPMDocumentFormatPICTPS using the function PMSessionSetDocumentFormatGeneration.

    For applications that require extensive control over PostScript code generation, the function PMSessionSetPSInjectionData provides the ability to insert PostScript code into specified places in the print stream. It is intended for use by desktop publishing applications for which functions such as PMSessionPostScriptData do not provide sufficient control.

    You specify the injection points by creating an array of CFDictionary entries. Each dictionary consists of key-value pairs in which the key specifies where to inject the PostScript and the value specifies the PostScript data you want to inject. The function verifies that the injectionDictArray parameter is properly formed, and returns the kPMInvalidParameter result code if the array does not contain valid entries.

    If you call the function PMSessionSetPSInjectionData a second time for a given print settings object, the injection points you specified previously are replaced with the new injection points.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Obtains an array of the available PDF workflow items.

    Declaration

    Swift

    func PMWorkflowCopyItems(_ workflowItems: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMWorkflowSubmitPDFWithOptions(_ workflowItem: CFURL!, _ title: CFString!, _ options: UnsafePointer<Int8>, _ pdfFile: CFURL!) -> OSStatus

    Objective-C

    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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func PMWorkflowSubmitPDFWithSettings(_ workflowItem: CFURL!, _ settings: PMPrintSettings, _ pdfFile: CFURL!) -> OSStatus

    Objective-C

    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 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 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

  • PMSetProfile PMSetProfile Available in OS X v10.0 through OS X v10.9

    Embeds a color profile during printing.

    Deprecation Statement

    There is no replacement; draw using Quartz 2D instead.

    Declaration

    Objective-C

    OSStatus PMSetProfile ( PMPrintSettings printSettings, PMTag tag, const CMProfileLocation *profile );

    Parameters

    printSettings

    The print settings object in which to embed the color profile.

    tag

    A tag that describes the usage of the profile. Currently, the only tag value you can pass is the constant kPMSourceProfile. See Tag Constants for more information on this constant.

    profile

    A pointer to a structure of type CMProfileLocation that specifies the location of a ColorSync profile. The profile must be version 2 or later. If you pass a profile that is an earlier version, the function returns the result code kPMNotImplemented.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    You can use the function PMSetProfile to tag QuickDraw drawing with a custom ColorSync profile. The function PMSetProfile is useful only if the graphics context is QuickDraw and the current port is the printing port.

    You should call this function each time you want to change the profile used to draw page elements. The printing system resets the profile to the default at the beginning of each page. If you call the function PMSetProfile a second time, the old profile is ignored.

    Special Considerations

    This function is deprecated because QuickDraw is deprecated. When drawing with Quartz, the current stroke and fill color space and the color space associated with an image are used to characterize color. Quartz provides ways to use ColorSync profiles to create color spaces, so you can characterize color using ColorSync simply by drawing with Quartz.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • PMSessionEnableColorSync PMSessionEnableColorSync Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    There is no replacement; draw using Quartz 2D instead.

    Declaration

    Objective-C

    OSStatus PMSessionEnableColorSync ( PMPrintSession printSession );

    Parameters

    printSession

    The printing session whose page-specific ColorSync profile you want to enable.

    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 must call this function within the scope of calls to the functions PMSessionBeginPage and PMSessionEndPage.

    The function PMSessionEnableColorSync applies only to the current page. The function is useful only if the graphics context is QuickDraw and the current port is the printing port.

    Special Considerations

    This function is deprecated because QuickDraw is deprecated. When drawing with Quartz, the current stroke and fill color space and the color space associated with an image are used to characterize color. Quartz provides ways to use ColorSync profiles to create color spaces, so you can characterize color using ColorSync simply by drawing with Quartz.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • PMSessionDisableColorSync PMSessionDisableColorSync Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    There is no replacement; draw using Quartz 2D instead.

    Declaration

    Objective-C

    OSStatus PMSessionDisableColorSync ( PMPrintSession printSession );

    Parameters

    printSession

    The printing session whose page-specific ColorSync profile you want to disable.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    You must call the PMSessionDisableColorSync function between the creation and release of a printing session. See the function PMCreateSession. You must call this function within the scope of calls to the functions PMSessionBeginPage and PMSessionEndPage.

    The function PMSessionDisableColorSync applies only to the current page. The function is useful only if the graphics context is QuickDraw and the current port is the printing port.

    Special Considerations

    This function is deprecated because QuickDraw is deprecated. When drawing with Quartz, the current stroke and fill color space and the color space associated with an image are used to characterize color. Quartz provides ways to use ColorSync profiles to create color spaces, so you can characterize color using ColorSync simply by drawing with Quartz.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • PMSessionConvertOldPrintRecord PMSessionConvertOldPrintRecord Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    There is no replacement; during the transition from Mac OS 9 to OS X, this function facilitated the migration of print records saved in documents created in Mac OS 9, but the function no longer serves any useful purpose in OS X.

    Declaration

    Objective-C

    OSStatus PMSessionConvertOldPrintRecord ( PMPrintSession printSession, Handle printRecordHandle, PMPrintSettings *printSettings, PMPageFormat *pageFormat );

    Parameters

    printSession

    The current printing session.

    printRecordHandle

    A handle to an old-style print record created by the classic Printing Manager. You are responsible for disposing of the handle.

    printSettings

    On return, a print settings object that contains values converted from the print record. You are responsible for releasing the print settings object with the function PMRelease.

    pageFormat

    On return, a page format object that contains values converted from the print record. You are responsible for releasing the page format object with the function PMRelease.

    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 PMSessionConvertOldPrintRecord to create page format and print settings objects from old-style print records stored in documents created by pre-Carbon versions of your application. You should validate the page format and print settings objects returned to you by calling the functions PMSessionValidatePageFormat and PMSessionValidatePrintSettings. Note that perfect translation between the old and new style objects is not achievable.

    In OS X, the function assumes the print record to be converted is a LaserWriter 8 print record.

    Special Considerations

    If you need to convert a Mac OS 9 print record into data you can use in OS X, you should extract the page size data from the print record and use the function PMCreatePageFormatWithPMPaper to create a PMPageFormat object that corresponds to that data.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • PMSessionMakeOldPrintRecord PMSessionMakeOldPrintRecord Available in OS X v10.0 through OS X v10.9

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

    Deprecation Statement

    There is no replacement; old-style print records are obsolete and serve no useful purpose in OS X.

    Declaration

    Objective-C

    OSStatus PMSessionMakeOldPrintRecord ( PMPrintSession printSession, PMPrintSettings printSettings, PMPageFormat pageFormat, Handle *printRecordHandle );

    Parameters

    printSession

    The current printing session.

    printSettings

    A print settings object. To create a print settings object you can call the function PMCreatePrintSettings and then call the function PMSessionDefaultPrintSettings to initialize the print settings object to default values.

    pageFormat

    A page format object. To create a page format object you can call the function PMCreatePageFormat and then call the function PMSessionDefaultPageFormat to initialize the page format object to default values.

    printRecordHandle

    On return, a handle to an old-style print record. You are responsible for disposing of the handle.

    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 PMSessionMakeOldPrintRecord to create an old-style print record to store with your documents for compatibility with pre-Carbon versions of your application. Note that because the page format and print settings objects contain more information than the old print record, some settings may be lost in the conversion. That is, perfect translation between the old and new style objects is not achievable.

    In OS X, the function always creates a LaserWriter 8 compatible print record.

    Special Considerations

    The proper way to keep page format information for use in OS X is with a flattened PMPageFormat object. Typically applications don't keep print settings with a document but if that is appropriate for a given application, the proper way to do so is to use a flattened PMPrintSettings object.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • NewPMIdleUPP NewPMIdleUPP Available in OS X v10.0 through OS X v10.4

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

    Deprecation Statement

    There is no replacement; this function was included to facilitate porting legacy applications to OS X, but it serves no useful purpose.

    Declaration

    Objective-C

    PMIdleUPP NewPMIdleUPP ( PMIdleProcPtr userRoutine );

    Discussion

    You do not need this function in OS X. Instead, use the standard idle proc. See the PMIdleProcPtr callback function.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.4.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • InvokePMIdleUPP InvokePMIdleUPP Available in OS X v10.0 through OS X v10.4

    Calls an idle callback.

    Deprecation Statement

    There is no replacement; this function was included to facilitate porting legacy applications to OS X, but it serves no useful purpose.

    Declaration

    Objective-C

    void InvokePMIdleUPP ( PMIdleUPP userUPP );

    Discussion

    You do not need this function in OS X. Instead, use the standard idle proc. See the PMIdleProcPtr callback function.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.4.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • DisposePMIdleUPP DisposePMIdleUPP Available in OS X v10.0 through OS X v10.4

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

    Deprecation Statement

    There is no replacement; this function was included to facilitate porting legacy applications to OS X, but it serves no useful purpose.

    Declaration

    Objective-C

    void DisposePMIdleUPP ( PMIdleUPP userUPP );

    Discussion

    You do not need this function in OS X. Instead, use the standard idle proc. See the PMIdleProcPtr callback function.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.4.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Prepares Core Printing for use.

    Use PMCreateSession instead.

    Declaration

    Objective-C

    OSStatus PMBegin ();

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    Do not nest calls to PMBegin.

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

    There is no replacement; during the transition from Mac OS 9 to OS X, this function facilitated the migration of print records saved in documents created in Mac OS 9, but the function no longer serves any useful purpose in OS X.

    Declaration

    Objective-C

    OSStatus PMConvertOldPrintRecord ( Handle printRecordHandle, PMPrintSettings *printSettings, PMPageFormat *pageFormat );

    Parameters

    printRecordHandle

    A handle to a print record created by the classic Printing Manager.

    printSettings

    On return, a validated PMPrintSettings object.

    pageFormat

    On return, a validated PMPageFormat object.

    Return Value

    A result code. See Core Printing Result Codes.

    Discussion

    Valid after calling PMBegin.

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

    Use PMSessionDefaultPageFormat instead.

    Declaration

    Objective-C

    OSStatus PMDefaultPageFormat ( PMPageFormat pageFormat );

    Parameters

    pageFormat

    On return, a PMPageFormat object containing default parameter values.

    Return Value

    A result code. See Core Printing Result Codes.