Mac Developer Library

Developer

ApplicationServices Framework Reference CGPDFDocument Reference

Options
Deployment Target:

On This Page
Language:

CGPDFDocument Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreGraphics

Objective-C

@import CoreGraphics;

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

  • Creates a Quartz PDF document using a data provider.

    Declaration

    Swift

    func CGPDFDocumentCreateWithProvider(_ provider: CGDataProvider!) -> CGPDFDocument!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.0 and later.

    See Also

    CGContextDrawPDFDocument

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

    Declaration

    Swift

    func CGPDFDocumentCreateWithURL(_ url: CFURL!) -> CGPDFDocument!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.0 and later.

    See Also

    CGContextDrawPDFDocument

  • Decrements the retain count of a PDF document.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.0 and later.

  • Increments the retain count of a Quartz PDF document.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.0 and later.

  • Returns the type identifier for Quartz PDF documents.

    Declaration

    Swift

    func CGPDFDocumentGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGPDFDocumentGetTypeID ( void );

    Return Value

    The identifier for the opaque type CGPDFDocumentRef.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.2 and later.

  • Returns the document catalog of a Quartz PDF document.

    Declaration

    Swift

    func CGPDFDocumentGetCatalog(_ document: CGPDFDocument!) -> CGPDFDictionaryRef

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns the number of pages in a PDF document.

    Declaration

    Swift

    func CGPDFDocumentGetNumberOfPages(_ document: CGPDFDocument!) -> Int

    Objective-C

    size_t CGPDFDocumentGetNumberOfPages ( CGPDFDocumentRef document );

    Parameters

    document

    The PDF document to examine.

    Return Value

    The total number of pages in the PDF document.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.0 and later.

  • Returns a page from a Quartz PDF document.

    Declaration

    Swift

    func CGPDFDocumentGetPage(_ document: CGPDFDocument!, _ pageNumber: Int) -> CGPDFPage!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

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

    Declaration

    Swift

    func CGPDFDocumentGetVersion(_ document: CGPDFDocument!, _ majorVersion: UnsafeMutablePointer<Int32>, _ minorVersion: UnsafeMutablePointer<Int32>)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Gets the information dictionary for a PDF document.

    Declaration

    Swift

    func CGPDFDocumentGetInfo(_ document: CGPDFDocument!) -> CGPDFDictionaryRef

    Objective-C

    CGPDFDictionaryRef CGPDFDocumentGetInfo ( CGPDFDocumentRef document );

    Parameters

    document

    The document whose dictionary you want to obtain.

    Return Value

    The information dictionary for the document.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Gets the file identifier for a PDF document.

    Declaration

    Swift

    func CGPDFDocumentGetID(_ document: CGPDFDocument!) -> CGPDFArrayRef

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns whether the specified PDF document allows copying.

    Declaration

    Swift

    func CGPDFDocumentAllowsCopying(_ document: CGPDFDocument!) -> Bool

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.2 and later.

  • Returns whether a PDF document allows printing.

    Declaration

    Swift

    func CGPDFDocumentAllowsPrinting(_ document: CGPDFDocument!) -> Bool

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.2 and later.

  • Returns whether the specified PDF file is encrypted.

    Declaration

    Swift

    func CGPDFDocumentIsEncrypted(_ document: CGPDFDocument!) -> Bool

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.2 and later.

  • Returns whether the specified PDF document is currently unlocked.

    Declaration

    Swift

    func CGPDFDocumentIsUnlocked(_ document: CGPDFDocument!) -> Bool

    Objective-C

    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:

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.2 and later.

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

    Declaration

    Swift

    func CGPDFDocumentUnlockWithPassword(_ document: CGPDFDocument!, _ password: UnsafePointer<Int8>) -> Bool

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.2 and later.

  • CGPDFDocumentGetArtBox CGPDFDocumentGetArtBox Deprecated in OS X version 10.3 and later

    Returns the art box of a page in a PDF document.

    Declaration

    Objective-C

    CGRect CGPDFDocumentGetArtBox ( CGPDFDocumentRef document, int page );

    Parameters

    document

    The PDF document to examine.

    page

    An integer that specifies the number of the page to examine.

    Return Value

    A rectangle that represents the art box for the specified page, expressed in default PDF user space units (points).

    Discussion

    The replacement function for this one is CGPDFPageGetBoxRect, which gets the rectangle associated with a type of box (art, media, crop, bleed trim) that represents a content region or page dimensions of a PDF page. For more information see CGPDFPage Reference.

    The art box defines the extent of the page’s meaningful content (including potential white space) as intended by the document creator. The default value is the page’s crop box.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.0 and later.

    Deprecated in OS X version 10.3 and later.

  • CGPDFDocumentGetBleedBox CGPDFDocumentGetBleedBox Deprecated in OS X version 10.3 and later

    Returns the bleed box of a page in a PDF document.

    Declaration

    Objective-C

    CGRect CGPDFDocumentGetBleedBox ( CGPDFDocumentRef document, int page );

    Parameters

    document

    The PDF document to examine.

    page

    An integer that specifies the number of the page to examine.

    Return Value

    A rectangle that represents the bleed box for the specified page, expressed in default PDF user space units (points).

    Discussion

    The replacement function for this one is CGPDFPageGetBoxRect, which gets the rectangle associated with a type of box (art, media, crop, bleed trim) that represents a content region or page dimensions of a PDF page. For more information see CGPDFPage Reference.

    The bleed box defines the bounds to which the contents of the page should be clipped when output in a production environment. The default value is the page’s crop box.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.0 and later.

    Deprecated in OS X version 10.3 and later.

  • CGPDFDocumentGetCropBox CGPDFDocumentGetCropBox Deprecated in OS X version 10.3 and later

    Returns the crop box of a page in a PDF document.

    Declaration

    Objective-C

    CGRect CGPDFDocumentGetCropBox ( CGPDFDocumentRef document, int page );

    Parameters

    document

    The PDF document to examine.

    page

    An integer that specifies the number of the page to examine.

    Return Value

    A rectangle that represents the crop box for the specified page, expressed in default PDF user space units (points).

    Discussion

    The replacement function for this one is CGPDFPageGetBoxRect, which gets the rectangle associated with a type of box (art, media, crop, bleed trim) that represents a content region or page dimensions of a PDF page. For more information see CGPDFPage Reference.

    The crop box defines the region to which the contents of the page are to be clipped (or cropped) when displayed or printed. Unlike the other boxes, the crop box has no defined meaning in terms of physical page geometry or intended use—it merely suggests where the page should be clipped.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.0 and later.

    Deprecated in OS X version 10.3 and later.

  • CGPDFDocumentGetMediaBox CGPDFDocumentGetMediaBox Deprecated in OS X version 10.3 and later

    Returns the media box of a page in a PDF document.

    Declaration

    Objective-C

    CGRect CGPDFDocumentGetMediaBox ( CGPDFDocumentRef document, int page );

    Parameters

    document

    The PDF document to examine.

    page

    An integer that specifies the number of the page to examine.

    Return Value

    A rectangle that represents the media box for the specified page, expressed in default PDF user space units (points).

    Discussion

    The replacement function for this one is CGPDFPageGetBoxRect, which gets the rectangle associated with a type of box (art, media, crop, bleed trim) that represents a content region or page dimensions of a PDF page. For more information see CGPDFPage Reference.

    The media box defines the location and size of the physical medium on which the page is intended to be displayed or printed. For example, if the page size is 8.5 by 11 inches, this function returns the coordinate pairs (0,0) and (612,792).

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.0 and later.

    Deprecated in OS X version 10.3 and later.

  • CGPDFDocumentGetRotationAngle CGPDFDocumentGetRotationAngle Deprecated in OS X version 10.3 and later

    Returns the rotation angle of a page in a PDF document.

    Declaration

    Objective-C

    int CGPDFDocumentGetRotationAngle ( CGPDFDocumentRef document, int page );

    Parameters

    document

    The PDF document to examine.

    page

    An integer that specifies the number of the page to examine.

    Return Value

    The rotation angle of the page, expressed in degrees. If the specified page does not exist, returns 0.

    Discussion

    The replacement function for this one is CGPDFPageGetRotationAngle. For more information see CGPDFPage Reference.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.0 and later.

    Deprecated in OS X version 10.3 and later.

  • CGPDFDocumentGetTrimBox CGPDFDocumentGetTrimBox Deprecated in OS X version 10.3 and later

    Returns the trim box of a page in a PDF document.

    Declaration

    Objective-C

    CGRect CGPDFDocumentGetTrimBox ( CGPDFDocumentRef document, int page );

    Parameters

    document

    The PDF document to examine.

    page

    A value specifying the number of the page to examine.

    Return Value

    Returns a rectangle that represents the trim box for the specified page, expressed in default PDF user space units (points).

    Discussion

    The replacement function for this one is CGPDFPageGetBoxRect, which gets the rectangle associated with a type of box (art, media, crop, bleed trim) that represents a content region or page dimensions of a PDF page. For more information see CGPDFPage Reference.

    The trim box defines the intended dimensions of the finished page after trimming. It may be smaller than the media box, to allow for production-related content such as printing instructions, cut marks, or color bars. The default value is the page’s crop box.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.0 and later.

    Deprecated in OS X version 10.3 and later.

Data Types

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

    Declaration

    Swift

    typealias CGPDFDocumentRef = CGPDFDocument

    Objective-C

    typedef struct CGPDFDocument * CGPDFDocumentRef;

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.