---

CGPDFDocument Reference

Overview

The CGPDFDocumentRef opaque type encapsulates a document that contains PDF (Portable Document Format) drawing information. PDF provides an efficient format for cross-platform exchange of documents with rich content. PDF files can contain multiple pages of images and text. A PDF document object contains all the information relating to a PDF document, including its catalog and contents.

Note that PDF documents may be encrypted, and that some operations may be restricted until a valid password is supplied—see the functions listed in “Managing Encryption.” Quartz also supports decrypting encrypted documents.

Quartz can both display and generate files that are compliant with the PDF standard. When imaging PDF files, CGPDFDocumentRef is the basic type used to represent a PDF document.

Functions by Task

Creating PDF Document Objects

• CGPDFDocumentCreateWithProvider
• CGPDFDocumentCreateWithURL

Retaining and Releasing PDF Documents

• CGPDFDocumentRelease
• CGPDFDocumentRetain

Getting the CFType ID for a PDF Document Object

• CGPDFDocumentGetTypeID

Getting Information About Quartz PDF Documents

• CGPDFDocumentGetCatalog
• CGPDFDocumentGetNumberOfPages
• CGPDFDocumentGetPage
• CGPDFDocumentGetVersion
• CGPDFDocumentGetInfo
• CGPDFDocumentGetID

Managing Encryption

• CGPDFDocumentAllowsCopying
• CGPDFDocumentAllowsPrinting
• CGPDFDocumentIsEncrypted
• CGPDFDocumentIsUnlocked
• CGPDFDocumentUnlockWithPassword

Getting Page Information

• CGPDFDocumentGetArtBox Deprecated in Mac OS X version 10.3 and later
• CGPDFDocumentGetBleedBox Deprecated in Mac OS X version 10.3 and later
• CGPDFDocumentGetCropBox Deprecated in Mac OS X version 10.3 and later
• CGPDFDocumentGetMediaBox Deprecated in Mac OS X version 10.3 and later
• CGPDFDocumentGetRotationAngle Deprecated in Mac OS X version 10.3 and later
• CGPDFDocumentGetTrimBox Deprecated in Mac OS X version 10.3 and later

Functions

CGPDFDocumentAllowsCopying

Returns whether the specified PDF document allows copying.

bool CGPDFDocumentAllowsCopying (
   CGPDFDocumentRef document
);

Parameters

document

A PDF document.

Return Value

A Boolean that, if true, indicates that the document allows copying. If the value is false, the document does not allow copying.

Discussion

This function returns true if the specified PDF document allows copying. It returns false if the document is encrypted and the current password doesn't grant permission to perform copying.

Availability

• Available in Mac OS X version 10.2 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentAllowsPrinting

Returns whether a PDF document allows printing.

bool CGPDFDocumentAllowsPrinting (
   CGPDFDocumentRef document
);

Parameters

document

A PDF document.

Return Value

A Boolean that, if true, indicates that the document allows printing. If the value is false, the document does not allow printing.

Discussion

This function returns true if the specified PDF document allows printing. It returns false if the document is encrypted and the current password doesn't grant permission to perform printing.

Availability

• Available in Mac OS X version 10.2 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentCreateWithProvider

Creates a Quartz PDF document using a data provider.

CGPDFDocumentRef CGPDFDocumentCreateWithProvider (
   CGDataProviderRef provider
);

Parameters

provider

A data provider that supplies the PDF document data.

Return Value

A new Quartz PDF document, or NULL if a document can not be created. You are responsible for releasing the object using CGPDFDocumentRelease.

Discussion

Distributing individual pages of a PDF document to separate threads is not supported. If you want to use threads, consider creating a separate document for each thread and operating on a block of pages per thread.

Availability

• Available in Mac OS X version 10.0 and later.

See Also

• CGContextDrawPDFDocument

Related Sample Code

• CarbonSketch

Declared In

CGPDFDocument.h

CGPDFDocumentCreateWithURL

Creates a Quartz PDF document using data specified by a URL.

CGPDFDocumentRef CGPDFDocumentCreateWithURL (
   CFURLRef url
);

Parameters

url

The URL address at which the PDF document data is located.

Return Value

A new Quartz PDF document, or NULL if a document could not be created. You are responsible for releasing the object using CGPDFDocumentRelease.

Discussion

Distributing individual pages of a PDF document to separate threads is not supported. If you want to use threads, consider creating a separate document for each thread and operating on a block of pages per thread.

Availability

• Available in Mac OS X version 10.0 and later.

See Also

• CGContextDrawPDFDocument

Declared In

CGPDFDocument.h

CGPDFDocumentGetCatalog

Returns the document catalog of a Quartz PDF document.

CGPDFDictionaryRef CGPDFDocumentGetCatalog (
   CGPDFDocumentRef document
);

Parameters

document

A PDF document.

Return Value

The document catalog of the specified document.

Discussion

The entries in a PDF document catalog recursively describe the contents of the PDF document. You can access the contents of a PDF document catalog by calling the function CGPDFDocumentGetCatalog. For information on accessing PDF metadata, see Quartz 2D Programming Guide.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentGetID

Gets the file identifier for a PDF document.

CGPDFArrayRef CGPDFDocumentGetID (
   CGPDFDocumentRef document
);

Parameters

document

The document whose file identifier you want to obtain.

Return Value

Returns the file identifier for the document.

Discussion

A PDF file identifier is defined in the PDF specification as an array of two strings, the first of which is a permanent identifier that doesn’t change even when the file is updated. The second string changes each time the file is updated. For more information, see PDF Reference: Version 1.3 (Second Edition), Adobe Systems Incorporated.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentGetInfo

Gets the information dictionary for a PDF document.

CGPDFDictionaryRef CGPDFDocumentGetInfo (
   CGPDFDocumentRef document
);

Parameters

document

The document whose dictionary you want to obtain.

Return Value

The information dictionary for the document.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentGetNumberOfPages

Returns the number of pages in a PDF document.

size_t CGPDFDocumentGetNumberOfPages (
   CGPDFDocumentRef document
);

Parameters

document

The PDF document to examine.

Return Value

The total number of pages in the PDF document.

Availability

• Available in Mac OS X version 10.0 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentGetPage

Returns a page from a Quartz PDF document.

CGPDFPageRef CGPDFDocumentGetPage (
   CGPDFDocumentRef document,
   size_t pageNumber
);

Parameters

document

A PDF document.

pageNumber

The number of the page requested.

Return Value

Return the PDF page corresponding to the specified page number, or NULL if no such page exists in the document. Pages are numbered starting at 1.

Availability

• Available in Mac OS X version 10.3 and later.

Related Sample Code

• CarbonSketch

Declared In

CGPDFDocument.h

CGPDFDocumentGetTypeID

Returns the type identifier for Quartz PDF documents.

CFTypeID CGPDFDocumentGetTypeID (
   void
);

Return Value

The identifier for the opaque type CGPDFDocumentRef.

Availability

• Available in Mac OS X version 10.2 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentGetVersion

Returns the major and minor version numbers of a Quartz PDF document.

void CGPDFDocumentGetVersion (
   CGPDFDocumentRef document,
   int *majorVersion,
   int *minorVersion
);

Parameters

document

A PDF document.

majorVersion

On return, contains the major version number of the document.

minorVersion

On return, contains the minor version number of the document.

Return Value

On return, the values of the majorVersion and minorVersion parameters are set to the major and minor version numbers of the document respectively.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentIsEncrypted

Returns whether the specified PDF file is encrypted.

bool CGPDFDocumentIsEncrypted (
   CGPDFDocumentRef document
);

Parameters

document

A PDF document.

Return Value

A Boolean that, if true, indicates that the document is encrypted. If the value is false, the document is not encrypted.

Discussion

If the document is encrypted, a password must be supplied before certain operations are enabled. For more information, see CGPDFDocumentUnlockWithPassword.

Availability

• Available in Mac OS X version 10.2 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentIsUnlocked

Returns whether the specified PDF document is currently unlocked.

bool CGPDFDocumentIsUnlocked (
   CGPDFDocumentRef document
);

Parameters

document

A PDF document.

Return Value

A Boolean that, if true, indicates that the document is not locked. If the value is false, the document is locked.

Discussion

There are two possible reasons why a PDF document is unlocked:

• The document is not encrypted.

• The document is encrypted, and a valid password was previously specified using CGPDFDocumentUnlockWithPassword.

Availability

• Available in Mac OS X version 10.2 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentRelease

Decrements the retain count of a PDF document.

void CGPDFDocumentRelease (
   CGPDFDocumentRef document
);

Parameters

document

The PDF document to release.

Discussion

This function is equivalent to CFRelease, except that it does not cause an error if the document parameter is NULL.

Availability

• Available in Mac OS X version 10.0 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentRetain

Increments the retain count of a Quartz PDF document.

CGPDFDocumentRef CGPDFDocumentRetain (
   CGPDFDocumentRef document
);

Parameters

document

The PDF document to retain.

Return Value

The same document you passed in as the document parameter.

Discussion

This function is equivalent to CFRetain, except that it does not cause an error if the document parameter is NULL.

Availability

• Available in Mac OS X version 10.0 and later.

Declared In

CGPDFDocument.h

CGPDFDocumentUnlockWithPassword

Unlocks an encrypted PDF document, if a valid password is supplied.

bool CGPDFDocumentUnlockWithPassword (
   CGPDFDocumentRef document,
   const char *password
);

Parameters

document

A PDF document.

password

A pointer to a string that contains the password.

Return Value

A Boolean that, if true, indicates that the document has been successfully unlocked. If the value is false, the document has not been unlocked.

Discussion

Given an encrypted PDF document and a password, this function does the following:

• Sets the lock state of the document, based on the validity of the password.

• Returns true if the document is unlocked.

• Returns false if the document cannot be unlocked with the specified password.

Unlocking a PDF document makes it possible to decrypt the document and perform other privileged operations. Different passwords enable different operations.

Availability

• Available in Mac OS X version 10.2 and later.

Declared In

CGPDFDocument.h

Data Types

CGPDFDocumentRef

An opaque type that represents a PDF (Portable Document Format) document.

typedef struct CGPDFDocument * CGPDFDocumentRef;

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CGPDFDocument.h

---