ADC Home > Reference Library > Reference > Graphics & Imaging > Quartz > CGPSConverter Reference >

Next Page > Hide TOC

CGPSConverter Reference

Derived from
Framework
ApplicationServices/ApplicationServices.h
Companion guide
Declared in
CGPSConverter.h

Overview

CGPSConverterRef is an opaque type used to convert PostScript data to PDF data. The PostScript data is supplied by a data provider and written into a data consumer. When you create a PostScript converter object, you can supply callback functions for Quartz to invoke at various stages of the conversion process,

Functions

CGPSConverterAbort

Tells a PostScript converter to abort a conversion at the next available opportunity.

bool CGPSConverterAbort (
   CGPSConverterRef converter
);

Parameters
converter

A PostScript converter.

Return Value

A Boolean value that indicates whether the converter is currently converting data (true if it is).

Availability
Declared In
CGPSConverter.h

CGPSConverterConvert

Uses a PostScript converter to convert PostScript data to PDF data.

bool CGPSConverterConvert (
   CGPSConverterRef converter,
   CGDataProviderRef provider,
   CGDataConsumerRef consumer,
   CFDictionaryRef options
);

Parameters
converter

A PostScript converter.

provider

A Quartz data provider that supplies PostScript data.

consumer

A Quartz data provider that will receive the resulting PDF data.

options

This parameter should be NULL; it is reserved for future expansion of the API.

Return Value

A Boolean value that indicates whether the PostScript conversion completed successfully (true if it did).

Discussion

The conversion is thread safe, however it is not possible to have more than one conversion job in process within a given address space or process. If a given thread is running a conversion and another thread starts a new conversion, the second conversion will block until the first conversion is complete.

Important: Although CGPSConverterConvert is thread safe (it uses locks to prevent more than one conversion at a time in the same process), it is not thread safe with respect to the Resource Manager. If your application uses the Resource Manager on a separate thread, you should either use locks to prevent CGPSConverterConvert from executing during your usage of the Resource Manager or you should perform your conversions using the Post Script converter in a separate process.

In general, you can avoid this issue by using nib files instead of Resource Manager resources.

Availability
Declared In
CGPSConverter.h

CGPSConverterCreate

Creates a new PostScript converter.

CGPSConverterRef CGPSConverterCreate (
   void *info,
   const CGPSConverterCallbacks *callbacks,
   CFDictionaryRef options
);

Parameters
info

A pointer to the data that will be passed to the callbacks.

callbacks

A pointer to a PostScript converter callbacks structure that specifies the callbacks to be used during a conversion process.

options

This parameter should be NULL; it is reserved for future expansion of the API.

Return Value

A new PostScript converter, or NULL if a converter could not be created. You are responsible for releasing this object.

Availability
Declared In
CGPSConverter.h

CGPSConverterGetTypeID

Returns the Core Foundation type identifier for PostScript converters.

CFTypeID CGPSConverterGetTypeID (
   void
);

Return Value

The Core Foundation identifier for the opaque type CGPSConverterRef.

Availability
Declared In
CGPSConverter.h

CGPSConverterIsConverting

Checks whether the converter is currently converting data.

bool CGPSConverterIsConverting (
   CGPSConverterRef converter
);

Parameters
converter

A PostScript converter.

Return Value

Returns true that indicates if the conversion is in progress.

Availability
Declared In
CGPSConverter.h

Callbacks by Task

Performing Custom Tasks at the Document Level

Performing Custom Tasks at the Page Level

Reporting Progress and Messages

Performing Custom Clean-up Tasks

Callbacks

CGPSConverterBeginDocumentCallback

Performs custom tasks at the beginning of a PostScript conversion process.

typedef void (*CGPSConverterBeginDocumentCallback)(void
*info);

If you name your function MyConverterBeginDocument, you would declare it like this:

size_t MyConverterBeginDocument (
   void *info
);

Parameters
info

A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGPSConverterCreate.

Availability
Declared In
CGPSConverter.h

CGPSConverterBeginPageCallback

Performs custom tasks at the beginning of each page in a PostScript conversion process.

typedef void (*CGPSConverterBeginPageCallback)(void
*info, size_t pageNumber, CFDictionaryRef pageInfo);

If you name your function MyConverterBeginDocument, you would declare it like this:

void MyConverterBeginPage (
   void *info,
   size_t pageNumber,
   CFDictionaryRef pageInfo
);

Parameters
info

A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGPSConverterCreate.

pageNumber

The current page number. Page numbers start at 1.

pageInfo

A dictionary that contains contextual information about the page. This parameter is reserved for future API expansion, and is currently unused.

Availability
Declared In
CGPSConverter.h

CGPSConverterEndDocumentCallback

Performs custom tasks at the end of a PostScript conversion process.

typedef void (*CGPSConverterEndDocumentCallback)(void
*info, bool success);

If you name your function MyConverterEndDocument, you would declare it like this:

void MyConverterEndDocument (
   void *info,
   bool success
);

Parameters
info

A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGPSConverterCreate.

success

A Boolean value that indicates whether the PostScript conversion completed successfully (true if it did).

Availability
Declared In
CGPSConverter.h

CGPSConverterEndPageCallback

Performs custom tasks at the end of each page of a PostScript conversion process.

typedef void (*CGPSConverterEndPageCallback)(void
*info, size_t pageNumber, CFDictionaryRef pageInfo);

If you name your function MyConverterEndPage, you would declare it like this:

void MyConverterEndPage (
   void *info,
   size_t *pageNumber,
   CFDictionaryRef pageInfo
);

Parameters
info

A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGPSConverterCreate.

pageNumber

The current page number. Page numbers start at 1.

pageInfo

A dictionary that contains contextual information about the page. This parameter is reserved for future API expansion, and is currently unused.

Availability
Declared In
CGPSConverter.h

CGPSConverterMessageCallback

Passes messages generated during a PostScript conversion process.

typedef void (*CGPSConverterMessageCallback)(void
*info, CFStringRef message);

If you name your function MyConverterMessage, you would declare it like this:

void MyConverterMessage (
   void *info,
   CFStringRef message
);

Parameters
info

A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGPSConverterCreate.

message

A string containing the message from the PostScript conversion process.

Discussion

There are several kinds of message that might be sent during a conversion process. The most likely are font substitution messages, and any messages that the PostScript code itself generates. Any PostScript messages written to stdout are routed through this callback—typically these are debugging or status messages and, although uncommon, can be useful in debugging. In addition, there may be error messages if the document is malformed.

Availability
Declared In
CGPSConverter.h

CGPSConverterProgressCallback

Reports progress periodically during a PostScript conversion process.

typedef void (*CGPSConverterProgressCallback)(void
*info);

If you name your function MyConverterProgress, you would declare it like this:

void MyConverterProgress (
   void *info
);

Parameters
info

A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGPSConverterCreate.

Availability
Declared In
CGPSConverter.h

CGPSConverterReleaseInfoCallback

Performs custom tasks when a PostScript converter is released.

typedef void (*CGPSConverterReleaseInfoCallback)(void
*info);

If you name your function MyConverterReleaseInfo, you would declare it like this:

void MyConverterReleaseInfo (
   void *info
);

Parameters
info

A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGPSConverterCreate.

Availability
Declared In
CGPSConverter.h

Data Types

CGPSConverterRef

An opaque data type used to convert PostScript data to PDF data.

typedef struct CGPSConverter *CGPSConverterRef;

Availability
Declared In
CGPSConverter.h

CGPSConverterCallbacks

A structure for holding the callbacks provided when you create a PostScript converter object.

struct CGPSConverterCallbacks {
   unsigned int version;
   CGPSConverterBeginDocumentCallback beginDocument;
   CGPSConverterEndDocumentCallback endDocument;
   CGPSConverterBeginPageCallback beginPage;
   CGPSConverterEndPageCallback endPage;
   CGPSConverterProgressCallback noteProgress;
   CGPSConverterMessageCallback noteMessage;
   CGPSConverterReleaseInfoCallback releaseInfo;
};
typedef struct CGPSConverterCallbacks CGPSConverterCallbacks;

Fields
version

The version number of the structure passed in as a parameter to the converter creation functions. The structure defined below is version 0.

beginDocument

The callback called at the beginning of the conversion of the PostScript document, or NULL.

endDocument

The callback called at the end of conversion of the PostScript document, or NULL.

beginPage

The callback called at the start of the conversion of each page in the PostScript document, or NULL.

endPage

The callback called at the end of the conversion of each page in the PostScript document, or NULL.

noteProgress

The callback called periodically during the conversion to indicate that conversion is proceeding, or NULL.

noteMessage

The callback called to pass any messages that might result during the conversion, or NULL.

releaseInfo

The callback called when the converter is deallocated, or NULL.

Availability
Declared In
CGPSConverter.h

Next Page > Hide TOC

© 2003, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-12-22)

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.