Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

< Previous PageNext Page > Hide TOC

Deprecated Core Printing Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

DisposePMIdleUPP

Disposes of a universal procedure pointer (UPP) to an idle callback. (Deprecated in Mac OS X v10.4. There is no replacement; this function was included to facilitate porting legacy applications to Mac OS X, but it serves no useful purpose.)

void DisposePMIdleUPP (
   PMIdleUPP userUPP
);

Discussion

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

Availability
Declared In
PMCoreDeprecated.h

InvokePMIdleUPP

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

void InvokePMIdleUPP (
   PMIdleUPP userUPP
);

Discussion

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

Availability
Declared In
PMCoreDeprecated.h

NewPMIdleUPP

Creates a new universal procedure pointer (UPP) to an idle callback. (Deprecated in Mac OS X v10.4. There is no replacement; this function was included to facilitate porting legacy applications to Mac OS X, but it serves no useful purpose.)

PMIdleUPP NewPMIdleUPP (
   PMIdleProcPtr userRoutine
);

Discussion

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

Availability
Declared In
PMCoreDeprecated.h

PMBegin

Prepares Core Printing for use. (Deprecated in Mac OS X v10.4. Use PMCreateSession instead.)

OSStatus PMBegin ();

Return Value

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

Discussion

Do not nest calls to PMBegin.

Availability
Declared In
PMCoreDeprecated.h

PMConvertOldPrintRecord

Creates a new PMPageFormat object and a new PMPrintSettings object from a print record created by the classic Printing Manager. (Deprecated in Mac OS X v10.4. There is no replacement; during the transition from Mac OS 9 to Mac 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 Mac OS X.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMDefaultPageFormat

Assigns default parameter values to an existing PMPageFormat object, for the current printer. (Deprecated in Mac OS X v10.4. Use PMSessionDefaultPageFormat instead.)

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

Discussion

Valid after calling PMBegin and creating a page format object.

Availability
Declared In
PMCoreDeprecated.h

PMDefaultPrintSettings

Assigns default parameter values to a PMPrintSettings object. (Deprecated in Mac OS X v10.4. Use PMSessionDefaultPrintSettings instead.)

OSStatus PMDefaultPrintSettings (
   PMPrintSettings printSettings
);

Parameters
printSettings

A PMPrintSettings object. On return, the object contains default parameter values.

Return Value

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

Discussion

Valid after calling PMBegin and creating a print settings object.

Availability
Declared In
PMCoreDeprecated.h

PMDisableColorSync

Disables ColorSync color matching for the current page. (Deprecated in Mac OS X v10.4. There is no replacement; draw using Quartz 2D instead.)

OSStatus PMDisableColorSync ();

Return Value

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

Discussion

Valid between calls to PMBeginPage and PMEndPage.

Availability
Declared In
PMCoreDeprecated.h

PMDisposePageFormat

Releases memory previously allocated for a PMPageFormat object. (Deprecated in Mac OS X v10.4. Use PMRelease instead.)

OSStatus PMDisposePageFormat (
   PMPageFormat pageFormat
);

Parameters
pageFormat

On return, an invalidated PMPageFormat object.

Return Value

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

Discussion

Valid after calling PMBegin and creating a page format object.

Availability
Declared In
PMCoreDeprecated.h

PMDisposePrintSettings

Releases memory previously allocated for a PMPrintSettings object. (Deprecated in Mac OS X v10.4. Use PMRelease instead.)

OSStatus PMDisposePrintSettings (
   PMPrintSettings printSettings
);

Parameters
printSettings

On return, an invalidated PMPrintSettings reference.

Return Value

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

Discussion

Valid after calling PMBegin and creating a print settings object.

Availability
Declared In
PMCoreDeprecated.h

PMEnableColorSync

Enables ColorSync color matching for the current page. (Deprecated in Mac OS X v10.4. There is no replacement; draw using Quartz 2D instead.)

OSStatus PMEnableColorSync ();

Return Value

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

Discussion

Valid between calls to PMBeginPage and PMEndPage.

Availability
Declared In
PMCoreDeprecated.h

PMEnd

Closes Core Printing and releases its allocated memory. (Deprecated in Mac OS X v10.4. Use PMRelease to release a PMPrintSession object instead.)

OSStatus PMEnd (void);

Return Value

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

Availability
Declared In
PMCoreDeprecated.h

PMError

Obtains the result code from the last printing function called by your application. (Deprecated in Mac OS X v10.4. Use PMSessionError instead.)

OSStatus PMError ();

Return Value

A result code. The result code kPMCancel indicates the user canceled the current print job.

Discussion

Valid after calling PMBegin.

Availability
Declared In
PMCoreDeprecated.h

PMGeneral

Maintains compatibility with the PrGeneral function in the classic Printing Manager. (Deprecated in Mac OS X v10.4. Use PMPrinterGetCommInfo instead.)

OSStatus PMGeneral (
   Ptr pData
);

Parameters
pData

A pointer to a PrGeneral data structure.

Return Value

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

Discussion

Valid after calling PMBegin.

Availability
Declared In
PMCoreDeprecated.h

PMGetColorMode

Obtains the color mode for the print job. (Deprecated in Mac OS X v10.4. There is no replacement; this function was included to facilitate porting legacy applications to Mac OS X, but it serves no useful purpose.)

OSStatus PMGetColorMode (
   PMPrintSettings printSettings,
   PMColorMode *colorMode
);

Parameters
printSettings

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

colorMode

On return, a pointer to a value that represents the color mode setting. See “Color Modes” for a list of possible return values.

Return Value

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

Discussion

This function is not recommended. It doesn’t do anything in Mac OS X and in general is no longer appropriate for applications to call.

Availability
Declared In
PMCoreDeprecated.h

PMGetDriverCreator

Obtains the creator of the driver associated with the current printer. (Deprecated in Mac OS X v10.4. Use PMPrinterGetDriverCreator instead.)

OSStatus PMGetDriverCreator (
   OSType *creator
);

Parameters
creator

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

Return Value

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

Discussion

Valid after calling PMBegin.

Availability
Declared In
PMCoreDeprecated.h

PMGetDriverReleaseInfo

Obtains release information for the driver associated with the current printer. (Deprecated in Mac OS X v10.4. Use PMPrinterGetDriverReleaseInfo instead.)

OSStatus PMGetDriverReleaseInfo (
   VersRec *release
);

Parameters
release

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

Return Value

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

Discussion

Valid after calling PMBegin.

Availability
Declared In
PMCoreDeprecated.h

PMGetGrafPtr

Obtains the printing port from an opaque printing context. (Deprecated in Mac OS X v10.4. Use PMSessionGetCGGraphicsContext instead.)

OSStatus PMGetGrafPtr (
   PMPrintContext printContext,
   GrafPtr *grafPort
);

Parameters
printContext

A PMPrintContext object.

grafPort

On return, a pointer to a grafPort defining the current printing port.

Return Value

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

Discussion

Valid after calling PMBegin and creating a printing context.

Availability
Declared In
PMCoreDeprecated.h

PMGetIndexedPrinterResolution

Obtains a resolution setting based on an index into the range of settings supported by the current printer. (Deprecated in Mac OS X v10.4. Use PMPrinterGetIndexedPrinterResolution instead.)

OSStatus PMGetIndexedPrinterResolution (
   UInt32 index,
   PMResolution *res
);

Parameters
index

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

res

On return, the printer resolution setting.

Return Value

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

Discussion

Valid after calling PMBegin. You must first use the PMGetPrinterResolutionCount function to obtain the number of resolution settings supported by the current printer.

Availability
Declared In
PMCoreDeprecated.h

PMGetJobName

Obtains the name of the print job. (Deprecated in Mac OS X v10.4. Use PMPrintSettingsGetJobName instead.)

OSStatus PMGetJobName (
   PMPrintSettings printSettings,
   StringPtr name
);

Parameters
printSettings

A PMPrintSettings object.

name

On return, the name of the print job.

Return Value

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

Discussion

Valid after calling PMBegin and creating a print settings object. Before using this function you must call PMValidatePrintSettings to ensure that the print settings object is valid.

Availability
Declared In
PMCoreDeprecated.h

PMGetLanguageInfo

Obtains information about the current printer’s imaging language. (Deprecated in Mac OS X v10.4. Use PMPrinterGetLanguageInfo instead.)

OSStatus PMGetLanguageInfo (
   PMLanguageInfo *info
);

Parameters
info

On return, a pointer to a data structure containing the printer’s language level, version and release. The format of the returned data is based on the PostScript language.

Return Value

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

Discussion

Valid after calling PMBegin. PMGetLanguageInfo is useful for PostScript printers but may be irrelevant for other types of printers.

Availability
Declared In
PMCoreDeprecated.h

PMGetPhysicalPageSize

Obtains the size of the imageable area in points, unaffected by rotation, resolution, or scaling. (Deprecated in Mac OS X v10.4. Use PMGetUnadjustedPageRect or examine the paper returned by PMGetPageFormatPaper.)

OSStatus PMGetPhysicalPageSize (
   PMPageFormat pageFormat,
   PMRect *pageSize
);

Parameters
pageFormat

A PMPageFormat object previously created by your application.

pageSize

On return, a rectangle describing the physical page size where your application can draw.

Return Value

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

Availability
Declared In
PMCoreDeprecated.h

PMGetPhysicalPaperSize

Obtains the size of the paper in points, unaffected by rotation, resolution, or scaling. (Deprecated in Mac OS X v10.4. Use PMGetUnadjustedPaperRect or examine the paper returned by PMGetPageFormatPaper.)

OSStatus PMGetPhysicalPaperSize (
   PMPageFormat pageFormat,
   PMRect *paperSize
);

Parameters
pageFormat

A PMPageFormat object previously created by your application.

paperSize

On return, a rectangle describing the physical size of the paper. Units are in 1/72 inch. Thus a 8.5 x 11 sheet of paper returns for its individual components:

top - 0.0

left - 0.0

bottom - 792.0

right - 612.

Return Value

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

Availability
Declared In
PMCoreDeprecated.h

PMGetPrinterResolution

Obtains the resolution setting for the current printer according to the tag parameter. (Deprecated in Mac OS X v10.4. Use PMPrinterGetPrinterResolutionCount and PMPrinterGetIndexedPrinterResolution to examine the available printer resolutions.)

OSStatus PMGetPrinterResolution (
   PMTag tag,
   PMResolution *res
);

Parameters
tag

Specifies the kind of resolution information required.

res

The printer resolution setting.

Return Value

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

Discussion

Valid after calling PMBegin.

The following resolution tag constants are recognized:

kPMMinRange

The minimum resolution supported by the printer.

kPMMaxRange

The maximum resolution supported by the printer.

kPMMinSquareResolution

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

kPMMaxSquareResolution

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

kPMDefaultResolution

The default resolution setting for the printer (typically 72 dpi).

Availability
Declared In
PMCoreDeprecated.h

PMGetPrinterResolutionCount

Obtains the number of resolution settings supported by the current printer. (Deprecated in Mac OS X v10.4. Use PMPrinterGetPrinterResolutionCount instead.)

OSStatus PMGetPrinterResolutionCount (
   UInt32 *count
);

Parameters
count

On return, the number of supported printing resolutions.

Return Value

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

Discussion

Valid after calling PMBegin.

Availability
Declared In
PMCoreDeprecated.h

PMIsPostScriptDriver

Reports whether the current printer driver supports the PostScript language. (Deprecated in Mac OS X v10.4. Use PMPrinterIsPostScriptCapable or PMPrinterIsPostScriptPrinter instead.)

OSStatus PMIsPostScriptDriver (
   Boolean *isPostScript
);

Parameters
isPostScript

Returns true if the current printer driver supports PostScript.

Return Value

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

Discussion

Valid after calling PMBegin. In Mac OS X, PMIsPostScriptDriver always returns false.

Availability
Declared In
PMCoreDeprecated.h

PMMakeOldPrintRecord

Creates an old-style print record from a PMPageFormat and a PMPrintSettings object. (Deprecated in Mac OS X v10.4. There is no replacement; old-style print records are obsolete and serve no useful purpose in Mac OS X.)

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

Parameters
printSettings

A PMPrintSettings object.

pageFormat

A PMPageFormat object.

printRecordHandle

On return, a handle to a an old-style print record. Your application must dispose of this handle.

Return Value

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

Discussion

Valid after calling PMBegin and creating a page format and print settings object. Use PMMakeOldPrintRecord to create a 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-style print record, some settings may be lost in conversion.

Availability
Declared In
PMCoreDeprecated.h

PMNewPageFormat

Creates a new PMPageFormat object. (Deprecated in Mac OS X v10.4. Use PMCreatePageFormat instead.)

OSStatus PMNewPageFormat (
   PMPageFormat *pageFormat
);

Parameters
pageFormat

On return, an initialized PMPageFormat object.

Return Value

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

Discussion

Valid after calling PMBegin. The function PMNewPageFormat allocates memory for a new PMPageFormat object in your application’s memory space. The new page format object is empty until you set its values, or until you call PMDefaultPageFormat or PMValidatePageFormat.

Availability
Declared In
PMCoreDeprecated.h

PMNewPrintSettings

Creates a new PMPrintSettings object. (Deprecated in Mac OS X v10.4. Use PMCreatePrintSettings instead.)

OSStatus PMNewPrintSettings (
   PMPrintSettings *printSettings
);

Parameters
printSettings

On return, an initialized PMPrintSettings object.

Return Value

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

Discussion

Valid after calling PMBegin. The function PMNewPrintSettings allocates memory for a new PMPrintSettings object in your application’s memory space. The new print settings object is empty until you set its values, or until you call PMDefaultPrintSettings or PMValidatePrintSettings.

Availability
Declared In
PMCoreDeprecated.h

PMPostScriptBegin

Puts the current driver into PostScript mode, ready to accept PostScript data instead of QuickDraw data. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

OSStatus PMPostScriptBegin ();

Return Value

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

Discussion

Valid between calls to PMBeginPage and PMEndPage. Call PMIsPostScriptDriver before calling PMPostScriptBegin to ensure that the current driver supports PostScript data.

Availability
Declared In
PMCoreDeprecated.h

PMPostScriptData

Passes PostScript data, referenced by a pointer, to the current printer driver. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

OSStatus PMPostScriptData (
   Ptr psPtr,
   Size len
);

Parameters
psPtr

A pointer to PostScript data.

len

The number of bytes of PostScript data to pass to the current driver.

Return Value

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

Discussion

Valid between calls to PMPostScriptBegin and PMPostScriptEnd.

Availability
Declared In
PMCoreDeprecated.h

PMPostScriptEnd

Restores the current driver to QuickDraw mode, ready to accept QuickDraw data instead of PostScript data. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

OSStatus PMPostScriptEnd ();

Return Value

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

Discussion

Valid between calls to PMBeginPage and PMEndPage. Call PMPostScriptEnd to complete a PostScript session started with PMPostScriptBegin.

Availability
Declared In
PMCoreDeprecated.h

PMPostScriptFile

Passes PostScript data, contained in a file, to the current printer driver. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

OSStatus PMPostScriptFile (
   FSSpec *psFile
);

Parameters
psFile

A file specification.

Return Value

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

Discussion

Valid between calls to PMPostScriptBegin and PMPostScriptEnd.

Availability
Declared In
PMCoreDeprecated.h

PMPostScriptHandle

Passes PostScript data, referenced by a handle, to the current printer driver. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

OSStatus PMPostScriptHandle (
   Handle psHandle
);

Parameters
psHandle

A reference to PostScript data.

Return Value

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

Discussion

Valid between calls to PMPostScriptBegin and PMPostScriptEnd.

Availability
Declared In
PMCoreDeprecated.h

PMPrinterGetDescriptionURL

Obtains a reference to the specified printer’s description file. (Deprecated in Mac OS X v10.4. Use PMPrinterCopyDescriptionURL instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMPrinterGetDeviceURI

Obtains a copy of a printer's device URI. (Deprecated in Mac OS X v10.4. Use PMPrinterCopyDeviceURI instead.)

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

Availability
Declared In
PMCoreDeprecated.h

PMSessionConvertOldPrintRecord

Creates new page format and print settings objects from an old-style print record created for the classic Printing Manager. (Deprecated in Mac OS X v10.4. There is no replacement; during the transition from Mac OS 9 to Mac 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 Mac OS X.)

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

Availability
Declared In
PMCoreDeprecated.h

PMSessionGeneral

Maintains compatibility with the PrGeneral function in the classic Printing Manager. (Deprecated in Mac OS X v10.4. Use PMPrinterGetCommInfo instead.)

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

Availability
Declared In
PMCoreDeprecated.h

PMSessionGetDocumentFormatGeneration

Obtains the spool file formats that can be generated for the specified printing session. (Deprecated in Mac OS X v10.4. 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.)

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

Availability
See Also
Declared In
PMCoreDeprecated.h

PMSessionGetDocumentFormatSupported

Obtains the spool file formats that are accepted by the current printer driver. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

OSStatus PMSessionGetDocumentFormatSupported (
   PMPrintSession printSession,
   CFArrayRef *docFormats,
   UInt32 limit
);

Parameters
printSession

The current printing session.

docFormats

On return, an array of CFString values containing MIME types specifying the spool file formats supported by the current printer driver. See “Document Format Strings” for a description of possible return values.

limit

The maximum number of supported document formats to be returned.

Return Value

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

Discussion

Valid within the context of a printing session.

Spool file formats are represented by MIME types. In Mac OS X, printer modules may support a wide range of spool file formats. The first item in the list of supported spool file formats is the default for the current printer driver.

Availability
Declared In
PMCoreDeprecated.h

PMSessionIsDocumentFormatSupported

Reports whether the current printer driver supports a specified spool file format. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

OSStatus PMSessionIsDocumentFormatSupported (
   PMPrintSession printSession,
   CFStringRef docFormat,
   Boolean *supported
);

Parameters
printSession

The current printing session.

docFormat

A spool file format represented by a MIME type.

supported

Returns true if the spool file format is supported by the current printer driver.

Return Value

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

Discussion

Valid within the context of a printing session.

Availability
Declared In
PMCoreDeprecated.h

PMSessionMakeOldPrintRecord

Creates an old-style print record from page format and print settings objects. (Deprecated in Mac OS X v10.4. There is no replacement; old-style print records are obsolete and serve no useful purpose in Mac OS X.)

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

Availability
Declared In
PMCoreDeprecated.h

PMSessionPostScriptBegin

Puts the current printer driver into PostScript mode, ready to accept PostScript data instead of QuickDraw data. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSessionPostScriptData

Passes PostScript data, referenced by a pointer, to the current printer driver. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSessionPostScriptEnd

Restores the current driver to QuickDraw mode, ready to accept QuickDraw data instead of PostScript data. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSessionPostScriptFile

Passes the PostScript data, contained in a file, to the current printer driver. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSessionPostScriptHandle

Passes the PostScript data, referenced by a Memory Manager handle, to the current printer driver. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile, PMPrinterPrintWithProvider, or PMCGImageCreateWithEPSDataProvider instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSessionSetCurrentPrinter

Changes the current printer for a printing session to a printer specified by name. (Deprecated in Mac OS X v10.4. Use PMSessionSetCurrentPMPrinter instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSessionSetDocumentFormatGeneration

Requests a specified spool file format and supplies the graphics context type to use for drawing pages within the print loop. (Deprecated in Mac OS X v10.4. 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.)

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

Availability
See Also
Declared In
PMCoreDeprecated.h

PMSessionSetIdleProc

Installs an idle callback function in your print loop. (Deprecated in Mac OS X v10.4. There is no replacement; this function was included to facilitate porting legacy applications to Mac OS X, but it serves no useful purpose.)

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 Mac OS X. Instead, use the standard idle proc.

Availability
Declared In
PMCoreDeprecated.h

PMSessionSetPSInjectionData

Specifies a set of PostScript code injection points and the PostScript data to be injected. (Deprecated in Mac OS X v10.4. Use PMPrinterPrintWithFile or PMPrinterPrintWithProvider instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSetColorMode

Sets the desired color mode for the print job. (Deprecated in Mac OS X v10.4. There is no replacement; this function was included to facilitate porting legacy applications to Mac OS X, but it serves no useful purpose.)

OSStatus PMSetColorMode (
   PMPrintSettings printSettings,
   PMColorMode colorMode
);

Parameters
printSettings

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

colorMode

The desired color mode. See “Color Modes” for a list of possible values.

Return Value

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

Special Considerations

This function does nothing in Mac OS X.

Availability
Declared In
PMCoreDeprecated.h

PMSetError

Sets the value of the current result code. (Deprecated in Mac OS X v10.4. Use PMSessionSetError instead.)

OSStatus PMSetError (
   OSStatus printError
);

Parameters
printError

The result code you wish to set. This result code will be returned by the PMError function.

Return Value

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

Discussion

Valid after calling PMBegin.

Availability
Declared In
PMCoreDeprecated.h

PMSetIdleProc

Installs an idle callback function in your print loop. (Deprecated in Mac OS X v10.4. There is no replacement; this function was included to facilitate porting legacy applications to Mac OS X, but it serves no useful purpose.)

OSStatus PMSetIdleProc (
   PMIdleUPP idleProc
);

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

Discu