CGPDFDocument Reference

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

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

Retaining and Releasing PDF Documents

Getting the CFType ID for a PDF Document Object

Getting Information About Quartz PDF Documents

Managing Encryption

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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 and later.
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 iOS 2.0 and later.
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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.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 iOS 2.0 and later.
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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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:

Availability
  • Available in iOS 2.0 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 iOS 2.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 iOS 2.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 iOS 2.0 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 iOS 2.0 and later.
Declared In
CGPDFDocument.h