You are on page 1of 16

CGPDFDocument Reference

Graphics & Animation: 2D Drawing

2006-12-22

All rights reserved. EXPRESS OR IMPLIED. OR FITNESS FOR A PARTICULAR PURPOSE. or employee is authorized to make any modification. INCIDENTAL. THIS DOCUMENT IS PROVIDED “AS IS. Acrobat. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. 2006 Apple Computer. Pages. WITH RESPECT TO THIS DOCUMENT. AS A RESULT. electronic. . © 2003. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT. photocopying.Apple Inc.” AND YOU. Even though Apple has reviewed this document. ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. and you may also have other rights which vary from state to state. Inc. Apple is not responsible for typographical errors. registered in the United States and other countries. No part of this publication may be reproduced. and PostScript are trademarks or registered trademarks of Adobe Systems Incorporated in the U. No licenses. No Apple dealer.. SPECIAL. Adobe. This document is intended to assist application developers to develop applications only for Apple-labeled computers. or transmitted. with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. Apple Inc. EITHER EXPRESS OR IMPLIED. MERCHANTABILITY. ORAL OR WRITTEN. stored in a retrieval system. APPLE MAKES NO WARRANTY OR REPRESENTATION. agent. extension. without prior written permission of Apple Inc. Apple retains all intellectual property rights associated with the technology described in this document. even if advised of the possibility of such damages. 1 Infinite Loop Cupertino. INDIRECT. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages. ACCURACY. and Quartz are trademarks of Apple Inc.S. The Apple logo is a trademark of Apple Inc. in any form or by any means. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS. Simultaneously published in the United States and Canada. recording. or addition to this warranty. mechanical. CA 95014 408-996-1010 Apple. express or implied. the Apple logo. THE READER. so the above limitation or exclusion may not apply to you. Mac OS. Mac. OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT. are granted with respect to any of the technology described in this document.. and/or other countries. Every effort has been made to ensure that the information in this document is accurate. This warranty gives you specific legal rights. or otherwise. ITS QUALITY.

All Rights Reserved.Contents CGPDFDocument Reference 5 Overview 5 Functions by Task 5 Creating PDF Document Objects 5 Retaining and Releasing PDF Documents 5 Getting the CFType ID for a PDF Document Object 6 Getting Information About Quartz PDF Documents 6 Managing Encryption 6 Functions 6 CGPDFDocumentAllowsCopying 6 CGPDFDocumentAllowsPrinting 7 CGPDFDocumentCreateWithProvider 7 CGPDFDocumentCreateWithURL 8 CGPDFDocumentGetCatalog 8 CGPDFDocumentGetID 9 CGPDFDocumentGetInfo 9 CGPDFDocumentGetNumberOfPages 10 CGPDFDocumentGetPage 10 CGPDFDocumentGetTypeID 11 CGPDFDocumentGetVersion 11 CGPDFDocumentIsEncrypted 12 CGPDFDocumentIsUnlocked 12 CGPDFDocumentRelease 13 CGPDFDocumentRetain 13 CGPDFDocumentUnlockWithPassword 13 Data Types 14 CGPDFDocumentRef 14 Document Revision History 15 3 2006-12-22 | © 2003. Inc. . 2006 Apple Computer.

Inc. . 2006 Apple Computer.CONTENTS 4 2006-12-22 | © 2003. All Rights Reserved.

Retaining and Releasing PDF Documents CGPDFDocumentRelease (page 13) Decrements the retain count of a PDF document.h Overview The CGPDFDocumentRef opaque type encapsulates a document that contains PDF (Portable Document Format) drawing information. Overview 2006-12-22 | © 2003. All Rights Reserved. and that some operations may be restricted until a valid password is supplied—see the functions listed in “Managing Encryption” (page 6). Quartz can both display and generate files that are compliant with the PDF standard. PDF files can contain multiple pages of images and text. CGPDFDocumentRef is the basic type used to represent a PDF document. 5 . When imaging PDF files. 2006 Apple Computer.CGPDFDocument Reference Derived From: Framework: Companion guide Declared in CFType ApplicationServices/ApplicationServices. Inc. Functions by Task Creating PDF Document Objects CGPDFDocumentCreateWithProvider (page 7) Creates a Quartz PDF document using a data provider. CGPDFDocumentRetain (page 13) Increments the retain count of a Quartz PDF document. CGPDFDocumentCreateWithURL (page 8) Creates a Quartz PDF document using data specified by a URL. Quartz also supports decrypting encrypted documents. A PDF document object contains all the information relating to a PDF document. including its catalog and contents. PDF provides an efficient format for cross-platform exchange of documents with rich content.h Quartz 2D Programming Guide CGPDFDocument. Note that PDF documents may be encrypted.

Managing Encryption CGPDFDocumentAllowsCopying (page 6) Returns whether the specified PDF document allows copying. CGPDFDocumentIsEncrypted (page 12) Returns whether the specified PDF file is encrypted. . CGPDFDocumentGetID (page 9) Gets the file identifier for a PDF document. CGPDFDocumentIsUnlocked (page 12) Returns whether the specified PDF document is currently unlocked. All Rights Reserved. 6 Functions 2006-12-22 | © 2003. 2006 Apple Computer. CGPDFDocumentGetNumberOfPages (page 10) Returns the number of pages in a PDF document. Functions CGPDFDocumentAllowsCopying Returns whether the specified PDF document allows copying.CGPDFDocument Reference Getting the CFType ID for a PDF Document Object CGPDFDocumentGetTypeID (page 11) Returns the type identifier for Quartz PDF documents. Getting Information About Quartz PDF Documents CGPDFDocumentGetCatalog (page 8) Returns the document catalog of a Quartz PDF document. CGPDFDocumentGetPage (page 10) Returns a page from a Quartz PDF document. if a valid password is supplied. Inc. CGPDFDocumentGetInfo (page 9) Gets the information dictionary for a PDF document. CGPDFDocumentAllowsPrinting (page 7) Returns whether a PDF document allows printing. CGPDFDocumentUnlockWithPassword (page 13) Unlocks an encrypted PDF document. CGPDFDocumentGetVersion (page 11) Returns the major and minor version numbers of a Quartz PDF document.

Availability Declared In CGPDFDocument.h CGPDFDocumentAllowsPrinting Returns whether a PDF document allows printing. All Rights Reserved. Availability Declared In CGPDFDocument. If the value is false. If the value is false. Parameters document A PDF document. Return Value A Boolean that. bool CGPDFDocumentAllowsPrinting ( CGPDFDocumentRef document ).h CGPDFDocumentCreateWithProvider Creates a Quartz PDF document using a data provider. Discussion This function returns true if the specified PDF document allows copying. Discussion This function returns true if the specified PDF document allows printing. indicates that the document allows copying. It returns false if the document is encrypted and the current password doesn't grant permission to perform copying. 7 . the document does not allow copying. if true. It returns false if the document is encrypted and the current password doesn't grant permission to perform printing.CGPDFDocument Reference bool CGPDFDocumentAllowsCopying ( CGPDFDocumentRef document ). Parameters document A PDF document. indicates that the document allows printing. Return Value A Boolean that. Functions 2006-12-22 | © 2003. Inc. if true. 2006 Apple Computer. the document does not allow printing.

Availability Declared In CGPDFDocument. or NULL if a document could not be created. consider creating a separate document for each thread and operating on a block of pages per thread. or NULL if a document can not be created.h CGPDFDocumentGetCatalog Returns the document catalog of a Quartz PDF document.h CGPDFDocumentCreateWithURL Creates a Quartz PDF document using data specified by a URL. . If you want to use threads. Discussion Distributing individual pages of a PDF document to separate threads is not supported. Availability Related Sample Code QuartzDemo ZoomingPDFViewer Declared In CGPDFDocument. CGPDFDocumentRef CGPDFDocumentCreateWithURL ( CFURLRef url ). If you want to use threads. Parameters provider A data provider that supplies the PDF document data. 8 Functions 2006-12-22 | © 2003. consider creating a separate document for each thread and operating on a block of pages per thread. Return Value A new Quartz PDF document. All Rights Reserved. Discussion Distributing individual pages of a PDF document to separate threads is not supported. Parameters url The URL address at which the PDF document data is located. 2006 Apple Computer.CGPDFDocument Reference CGPDFDocumentRef CGPDFDocumentCreateWithProvider ( CGDataProviderRef provider ). Return Value A new Quartz PDF document. You are responsible for releasing the object using CGPDFDocumentRelease (page 13). Inc. You are responsible for releasing the object using CGPDFDocumentRelease (page 13).

Inc. see Quartz 2D Programming Guide. 2006 Apple Computer. Adobe Systems Incorporated. All Rights Reserved. CGPDFArrayRef CGPDFDocumentGetID ( CGPDFDocumentRef document ). the first of which is a permanent identifier that doesn’t change even when the file is updated. You can access the contents of a PDF document catalog by calling the function CGPDFDocumentGetCatalog. Discussion The entries in a PDF document catalog recursively describe the contents of the PDF document.3 (Second Edition). The second string changes each time the file is updated.h CGPDFDocumentGetInfo Gets the information dictionary for a PDF document. Parameters document A PDF document. see PDF Reference: Version 1. Availability Declared In CGPDFDocument. Functions 2006-12-22 | © 2003. Parameters document The document whose file identifier you want to obtain.CGPDFDocument Reference CGPDFDictionaryRef CGPDFDocumentGetCatalog ( CGPDFDocumentRef document ).h CGPDFDocumentGetID Gets the file identifier for a PDF document. For information on accessing PDF metadata. 9 . Discussion A PDF file identifier is defined in the PDF specification as an array of two strings. Return Value The document catalog of the specified document. For more information. Return Value Returns the file identifier for the document. Availability Declared In CGPDFDocument.

Parameters document A PDF document.CGPDFDocument Reference CGPDFDictionaryRef CGPDFDocumentGetInfo ( CGPDFDocumentRef document ). Availability Declared In CGPDFDocument. Inc. . pageNumber The number of the page requested. Return Value Return the PDF page corresponding to the specified page number. Parameters document The document whose dictionary you want to obtain. All Rights Reserved. Return Value The total number of pages in the PDF document. size_t CGPDFDocumentGetNumberOfPages ( CGPDFDocumentRef document ).h CGPDFDocumentGetPage Returns a page from a Quartz PDF document. 10 Functions 2006-12-22 | © 2003. Return Value The information dictionary for the document.h CGPDFDocumentGetNumberOfPages Returns the number of pages in a PDF document. 2006 Apple Computer. CGPDFPageRef CGPDFDocumentGetPage ( CGPDFDocumentRef document. Availability Declared In CGPDFDocument. size_t pageNumber ). Pages are numbered starting at 1. Parameters document The PDF document to examine. or NULL if no such page exists in the document.

minorVersion On return. Return Value The identifier for the opaque type CGPDFDocumentRef (page 14).h CGPDFDocumentGetVersion Returns the major and minor version numbers of a Quartz PDF document. CFTypeID CGPDFDocumentGetTypeID ( void ). Availability Declared In CGPDFDocument. int *minorVersion ). 11 .CGPDFDocument Reference Availability Related Sample Code QuartzDemo ZoomingPDFViewer Declared In CGPDFDocument. int *majorVersion. void CGPDFDocumentGetVersion ( CGPDFDocumentRef document. All Rights Reserved. contains the minor version number of the document. Parameters document A PDF document. Return Value On return. Availability Declared In CGPDFDocument.h CGPDFDocumentGetTypeID Returns the type identifier for Quartz PDF documents. the values of the majorVersion and minorVersion parameters are set to the major and minor version numbers of the document respectively. 2006 Apple Computer. Inc. contains the major version number of the document.h Functions 2006-12-22 | © 2003. majorVersion On return.

Parameters document A PDF document. If the value is false. Parameters document A PDF document. Availability Declared In CGPDFDocument. the document is locked. if true. Return Value A Boolean that. a password must be supplied before certain operations are enabled.CGPDFDocument Reference CGPDFDocumentIsEncrypted Returns whether the specified PDF file is encrypted. For more information. if true. indicates that the document is encrypted. If the value is false. indicates that the document is not locked. All Rights Reserved. the document is not encrypted. Return Value A Boolean that. The document is encrypted. Availability Declared In CGPDFDocument. bool CGPDFDocumentIsEncrypted ( CGPDFDocumentRef document ). see CGPDFDocumentUnlockWithPassword (page 13). and a valid password was previously specified using CGPDFDocumentUnlockWithPassword (page 13).h 12 Functions 2006-12-22 | © 2003. Discussion There are two possible reasons why a PDF document is unlocked: ■ ■ The document is not encrypted. 2006 Apple Computer. Inc. Discussion If the document is encrypted. bool CGPDFDocumentIsUnlocked ( CGPDFDocumentRef document ).h CGPDFDocumentIsUnlocked Returns whether the specified PDF document is currently unlocked. .

if a valid password is supplied. Availability Available in iOS 2. Related Sample Code QuartzDemo ZoomingPDFViewer Declared In CGPDFDocument. Functions 2006-12-22 | © 2003. void CGPDFDocumentRelease ( CGPDFDocumentRef document ).0 and later. except that it does not cause an error if the document parameter is NULL. Discussion This function is equivalent to CFRetain. Parameters document The PDF document to release. All Rights Reserved. Discussion This function is equivalent to CFRelease.h CGPDFDocumentUnlockWithPassword Unlocks an encrypted PDF document. Declared In CGPDFDocument.CGPDFDocument Reference CGPDFDocumentRelease Decrements the retain count of a PDF document.h CGPDFDocumentRetain Increments the retain count of a Quartz PDF document. except that it does not cause an error if the document parameter is NULL. Inc. Return Value The same document you passed in as the document parameter. Parameters document The PDF document to retain. 2006 Apple Computer.0 and later. CGPDFDocumentRef CGPDFDocumentRetain ( CGPDFDocumentRef document ). 13 . Availability Available in iOS 2.

typedef struct CGPDFDocument * CGPDFDocumentRef. Declared In CGPDFDocument.CGPDFDocument Reference bool CGPDFDocumentUnlockWithPassword ( CGPDFDocumentRef document. Discussion Given an encrypted PDF document and a password. based on the validity of the password. 2006 Apple Computer. Parameters document A PDF document. Different passwords enable different operations.0 and later. Availability Declared In CGPDFDocument. Availability Available in iOS 2. if true.h 14 Data Types 2006-12-22 | © 2003. const char *password ). Returns false if the document cannot be unlocked with the specified password. indicates that the document has been successfully unlocked. Return Value A Boolean that. If the value is false. the document has not been unlocked.h Data Types CGPDFDocumentRef An opaque type that represents a PDF (Portable Document Format) document. All Rights Reserved. password A pointer to a string that contains the password. Inc. . this function does the following: ■ ■ ■ Sets the lock state of the document. Unlocking a PDF document makes it possible to decrypt the document and perform other privileged operations. Returns true if the document is unlocked.

. An earlier version of this information appeared in Quartz 2D Reference. First version of this document.REVISION HISTORY Document Revision History This table describes the changes to CGPDFDocument Reference. Added the functions CGPDFDocumentGetInfo (page 9) and CGPDFDocumentGetID (page 9). All Rights Reserved. and cross references to conceptual documentation. additional information about deprecated functions. Updated for Mac OS X v10. 2004-08-31 Added introductory material. Date 2006-12-22 2005-04-29 Notes Added information about using threads. 2004-02-26 15 2006-12-22 | © 2003. 2006 Apple Computer.4. Inc.

. 2006 Apple Computer.REVISION HISTORY Document Revision History 16 2006-12-22 | © 2003. All Rights Reserved. Inc.