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

< 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
Related Sample Code
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.”

Discussion

Valid after calling PMBegin. The printing system calls your idle function periodically during your print loop.

Special Considerations

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

Availability
Declared In
PMCoreDeprecated.h

PMSetJobName

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

OSStatus PMSetJobName (
   PMPrintSettings printSettings,
   StringPtr name
);

Parameters
printSettings

A PMPrintSettings object.

name

The name to assign to the print job. This string will be used to name the spool file.

Return Value

A result code. The result code kPMInvalidParameter is returned if you attempt to set the job name to an invalid file name or a null string.

Discussion

Valid after calling PMBegin and creating a print settings object.

Availability
Declared In
PMCoreDeprecated.h

PMSetPhysicalPaperSize

Requests a particular paper size, unaffected by rotation, resolution, or scaling. (Deprecated in Mac OS X v10.4. Use PMCreatePageFormatWithPMPaper instead.)

OSStatus PMSetPhysicalPaperSize (
   PMPageFormat pageFormat,
   const PMRect *paperSize
);

Parameters
pageFormat

The PMPageFormat which will hold the new physical paper size.

paperSize

The desired paper size expressed as a PMRect. The units are 1/72 inch. A PMRect is a rectangle whose individual components are doubles.

Return Value

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

Availability
Declared In
PMCoreDeprecated.h

PMValidatePageFormat

Obtains a valid PMPageFormat object. (Deprecated in Mac OS X v10.4. Use PMSessionValidatePageFormat instead.)

OSStatus PMValidatePageFormat (
   PMPageFormat pageFormat,
   Boolean *result
);

Parameters
pageFormat

A PMPageFormat object to be validated.

result

Returns true if any parameters were changed, false if no changes were required.

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

PMValidatePrintSettings

Obtains a valid PMPrintSettings object. (Deprecated in Mac OS X v10.4. Use PMSessionValidatePrintSettings instead.)

OSStatus PMValidatePrintSettings (
   PMPrintSettings printSettings,
   Boolean *result
);

Parameters
printSettings

The PMPrintSettings object to be validated.

result

On return, a value of true if any parameters were changed, or false if no changes were required.

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

Deprecated in Mac OS X v10.5

PMFlattenPageFormat

Flattens a page format object into a Memory Manager handle for storage in a user document. (Deprecated in Mac OS X v10.5. Use PMPageFormatCreateDataRepresentation instead.)

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

Availability
Related Sample Code
Declared In
PMCoreDeprecated.h

PMFlattenPageFormatToCFData

Flattens a page format object into a Core Foundation data object for storage in a user document. (Deprecated in Mac OS X v10.5. Use PMPageFormatCreateDataRepresentation instead.)

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

Availability
See Also
Declared In
PMCoreDeprecated.h

PMFlattenPageFormatToURL

Flattens a page format object into a file for storage in a user document. (Deprecated in Mac OS X v10.5. Use PMPageFormatCreateDataRepresentation and write the resulting data to your destination.)

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

Availability
See Also
Declared In
PMCoreDeprecated.h

PMFlattenPrintSettings

Flattens a print settings object into a Memory Manager handle for storage in a user document. (Deprecated in Mac OS X v10.5. Use PMPrintSettingsCreateDataRepresentation instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMFlattenPrintSettingsToCFData

Flattens a print settings object into a Core Foundation data object for storage in a user document. (Deprecated in Mac OS X v10.5. Use PMPrintSettingsCreateDataRepresentation instead.)

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

Availability
See Also
Declared In
PMCoreDeprecated.h

PMFlattenPrintSettingsToURL

Flattens a print settings object into a URL for storage in a user document. (Deprecated in Mac OS X v10.5. Instead use PMPrintSettingsCreateDataRepresentation and write the resulting data to your destination.)

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

Availability
See Also
Declared In
PMCoreDeprecated.h

PMGetDestination

Obtains the output destination of a print job. (Deprecated in Mac OS X v10.5. Use PMSessionGetDestinationType, PMSessionCopyDestinationFormat, or PMSessionCopyDestinationLocation instead.)

OSStatus PMGetDestination (
   PMPrintSettings printSettings,
   PMDestinationType *destType,
   CFURLRef *fileURL
);

Parameters
printSettings

The print settings object whose destination you want to obtain.

destType

A pointer to your PMDestinationType variable. On return, the variable indicates the destination for the print job. See “Destination Types.”

fileURL

A pointer to your CFURLRef variable. On return, the variable refers to a Core Foundation URL that contains the location of the print job destination.

Return Value

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

Discussion

For print jobs that are sent to disk, as opposed a printer, you can use this function to obtain the location of the destination file. Valid within a printing session after creating a print settings object.

Before using this function you must call PMSessionValidatePrintSettings or PMValidatePrintSettings to ensure that the print settings object is valid.

Special Considerations

This function does not take a print session parameter and therefore cannot indicate whether preview has been selected as the destination.

Availability
Declared In
PMCoreDeprecated.h

PMGetJobNameCFString

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

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

Availability
See Also
Declared In
PMCoreDeprecated.h

PMGetResolution

Obtains the current application’s drawing resolution. (Deprecated in Mac OS X v10.5. Draw using Quartz 2D and call CGContextScaleCTM instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMPaperCreate

Creates a paper object. (Deprecated in Mac OS X v10.5. Use PMPrinterGetPaperList to find the built-in papers available for a given printer or use PMPaperCreateCustom to create a custom paper.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMPrinterGetPrinterResolution

Obtains a resolution setting for the specified printer. (Deprecated in Mac OS X v10.5. Use PMPrinterGetPrinterResolutionCount and PMPrinterGetIndexedPrinterResolution to examine the available printer resolutions.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSessionBeginDocumentNoDialog

Begins a print job that, by default, draws into a QuickDraw graphics port, and suppresses the printing status dialog. (Deprecated in Mac OS X v10.5. Use PMSessionBeginCGDocumentNoDialog instead.)

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

Availability
Declared In
PMCoreDeprecated.h

PMSessionDisableColorSync

Disables use of a custom ColorSync profile previously enabled by the function PMSessionEnableColorSync. (Deprecated in Mac OS X v10.5. There is no replacement; draw using Quartz 2D instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSessionEnableColorSync

Enables use of a custom ColorSync profile previously set by the function PMSetProfile. (Deprecated in Mac OS X v10.5. There is no replacement; draw using Quartz 2D instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSessionGetGraphicsContext

Obtains the graphics context for the current page in a printing session. (Deprecated in Mac OS X v10.5. Use PMSessionGetCGGraphicsContext instead.)

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

Availability
Related Sample Code
Declared In
PMCoreDeprecated.h

PMSetAdjustedPageRect

Requests a particular page size, adjusted for the current rotation, resolution, or scaling settings. (Deprecated in Mac OS X v10.5. To set a particular paper size and margins, obtain or create a PMPaper object and call PMCreatePageFormatWithPMPaper.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSetJobNameCFString

Specifies the name of a print job. (Deprecated in Mac OS X v10.5. Use PMPrintSettingsSetJobName instead.)

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.

Availability
See Also
Related Sample Code
Declared In
PMCoreDeprecated.h

PMSetProfile

Embeds a color profile during printing. (Deprecated in Mac OS X v10.5. There is no replacement; draw using Quartz 2D instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSetResolution

Sets the application drawing resolution. (Deprecated in Mac OS X v10.5. Draw using Quartz 2D and call CGContextScaleCTM instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMSetUnadjustedPaperRect

Requests a particular paper size, unaffected by rotation, resolution, or scaling. (Deprecated in Mac OS X v10.5. To set a particular paper size, obtain or create a PMPaper object and call PMCreatePageFormatWithPMPaper.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMUnflattenPageFormat

Rebuilds a page format object from a Memory Manager handle that contains flattened page format data. (Deprecated in Mac OS X v10.5. Use PMPageFormatCreateWithDataRepresentation instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMUnflattenPageFormatWithCFData

Rebuilds a page format object from a Core Foundation data object that contains flattened page format data. (Deprecated in Mac OS X v10.5. Use PMPageFormatCreateWithDataRepresentation instead.)

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

Availability
See Also
Declared In
PMCoreDeprecated.h

PMUnflattenPageFormatWithURL

Rebuilds a page format object from a file system URL that contains flattened page format data. (Deprecated in Mac OS X v10.5. Instead read the data into a CFData object and use PMPageFormatCreateWithDataRepresentation.)

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

Availability
See Also
Declared In
PMCoreDeprecated.h

PMUnflattenPrintSettings

Rebuilds a print settings object from a Memory Manager handle that contains flattened print settings data. (Deprecated in Mac OS X v10.5. Use PMPrintSettingsCreateWithDataRepresentation instead.)

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.

Availability
Declared In
PMCoreDeprecated.h

PMUnflattenPrintSettingsWithCFData

Rebuilds a print settings object from a Core Foundation data object that contains flattened print settings data. (Deprecated in Mac OS X v10.5. Use PMPrintSettingsCreateWithDataRepresentation instead.)

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

Availability
See Also
Declared In
PMCoreDeprecated.h

PMUnflattenPrintSettingsWithURL

Rebuilds a print settings object from a file that contains flattened print settings data. (Deprecated in Mac OS X v10.5. Instead read the data into a CFData object and use PMPrintSettingsCreateWithDataRepresentation.)

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

Availability
See Also
Declared In
PMCoreDeprecated.h

< Previous PageNext Page > Hide TOC

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

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