Mac Developer Library

Developer

ApplicationServices Framework Reference CGPDFDictionary Reference

Options
Deployment Target:

On This Page
Language:

CGPDFDictionary Reference

The CGPDFDictionaryRef opaque type encapsulates a PDF dictionary whose key-value pairs can specify any kind of PDF object, including another dictionary. Dictionary objects are the main building blocks of a PDF document. A key-value pair within a dictionary is called an entry. In a PDF dictionary, the key must be an array of characters. Within a given dictionary, the keys are unique—that is, no two keys in a single dictionary are equal (as determined by strcmp). The value associated with a key can be any kind of PDF object, including another dictionary. Dictionary objects are the main building blocks of a PDF document.

Many functions that retrieve values from a PDF dictionary take the form:

  • bool CGPDFDictionaryGet<DataType> (
  • CGPDFDictionaryRef dictionary,
  • const char *key,
  • <DataType>Ref *value
  • );

These functions test whether there is an object associated with the specified key. If there is an object associated with the specified key, they test its data type. If there is no associated object, or if there is but it is not of the expected type, the function returns false. If there is an object associated with the specified key and it is of the expected type, the function returns true and the object is passed back in the value parameter.

This opaque type is not derived from CFType and therefore there are no functions for retaining and releasing it. CGPDFDictionary objects exist only as constituent parts of a CGPDFDocument object, and they are managed by their container.

Functions

  • Applies a function to each entry in a dictionary.

    Declaration

    Swift

    func CGPDFDictionaryApplyFunction(_ dictionary: CGPDFDictionaryRef, _ function: CGPDFDictionaryApplierFunction, _ info: UnsafeMutablePointer<Void>)

    Objective-C

    void CGPDFDictionaryApplyFunction ( CGPDFDictionaryRef dict, CGPDFDictionaryApplierFunction function, void *info );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    function

    The function to apply to each entry in the dictionary.

    info

    A pointer to contextual information to pass to the function.

    Discussion

    This function enumerates all of the entries in the dictionary, calling the function once for each. The current key, its associated value, and the contextual information are passed to the function (see also CGPDFDictionaryApplierFunction).

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns whether there is a PDF array associated with a specified key in a PDF dictionary and, if so, retrieves that array.

    Declaration

    Swift

    func CGPDFDictionaryGetArray(_ dictionary: CGPDFDictionaryRef, _ key: UnsafePointer<Int8>, _ value: UnsafeMutablePointer<CGPDFArrayRef>) -> Bool

    Objective-C

    bool CGPDFDictionaryGetArray ( CGPDFDictionaryRef dict, const char *key, CGPDFArrayRef *value );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    key

    The key for the value to retrieve.

    value

    On input, an uninitialized pointer to a PDF array. If the value associated with the specified key is a PDF array, then on return contains that array; otherwise the value is unspecified.

    Return Value

    Returns true if there is a PDF array associated with the specified key; otherwise, false.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns whether there is a PDF Boolean value associated with a specified key in a PDF dictionary and, if so, retrieves the Boolean value.

    Declaration

    Swift

    func CGPDFDictionaryGetBoolean(_ dictionary: CGPDFDictionaryRef, _ key: UnsafePointer<Int8>, _ value: UnsafeMutablePointer<CGPDFBoolean>) -> Bool

    Objective-C

    bool CGPDFDictionaryGetBoolean ( CGPDFDictionaryRef dict, const char *key, CGPDFBoolean *value );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    key

    The key for the value to retrieve.

    value

    On input, a pointer to a PDF Boolean value. If the value associated with the specified key is a PDF Boolean value, then on return contains that value; otherwise the value is unspecified.

    Return Value

    Returns true if there is a PDF Boolean value associated with the specified key; otherwise, false.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns the number of entries in a PDF dictionary.

    Declaration

    Swift

    func CGPDFDictionaryGetCount(_ dictionary: CGPDFDictionaryRef) -> UInt

    Objective-C

    size_t CGPDFDictionaryGetCount ( CGPDFDictionaryRef dict );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    Return Value

    Returns the number of entries in the dictionary.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns whether there is another PDF dictionary associated with a specified key in a PDF dictionary and, if so, retrieves that dictionary.

    Declaration

    Swift

    func CGPDFDictionaryGetDictionary(_ dictionary: CGPDFDictionaryRef, _ key: UnsafePointer<Int8>, _ value: UnsafeMutablePointer<CGPDFDictionaryRef>) -> Bool

    Objective-C

    bool CGPDFDictionaryGetDictionary ( CGPDFDictionaryRef dict, const char *key, CGPDFDictionaryRef *value );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    key

    The key for the value to retrieve.

    value

    On input, a pointer to a PDF dictionary. If the value associated with the specified key is a PDF dictionary, then on return contains that dictionary; otherwise the value is unspecified.

    Return Value

    Returns true if there is a PDF dictionary associated with the specified key; otherwise, false.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns whether there is a PDF integer associated with a specified key in a PDF dictionary and, if so, retrieves that integer.

    Declaration

    Swift

    func CGPDFDictionaryGetInteger(_ dictionary: CGPDFDictionaryRef, _ key: UnsafePointer<Int8>, _ value: UnsafeMutablePointer<CGPDFInteger>) -> Bool

    Objective-C

    bool CGPDFDictionaryGetInteger ( CGPDFDictionaryRef dict, const char *key, CGPDFInteger *value );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    key

    The key for the value to retrieve.

    value

    On input, a pointer to a PDF integer. If the value associated with the specified key is a PDF integer, then on return contains that value; otherwise the value is unspecified.

    Return Value

    Returns true if there is a PDF integer associated with the specified key; otherwise, false.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns whether an object with a specified key in a PDF dictionary is a PDF name reference (represented as a constant C string) and, if so, retrieves that name.

    Declaration

    Swift

    func CGPDFDictionaryGetName(_ dictionary: CGPDFDictionaryRef, _ key: UnsafePointer<Int8>, _ value: UnsafeMutablePointer<UnsafePointer<Int8>>) -> Bool

    Objective-C

    bool CGPDFDictionaryGetName ( CGPDFDictionaryRef dict, const char *key, const char **value );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    key

    The key for the value to retrieve.

    value

    On input, a pointer to a PDF name reference, represented as a constant C string. If the value associated with the specified key is a reference to a PDF name, then on return, the variable points to the name; otherwise, the value is undefined.

    Return Value

    Returns true if there is a character array associated with the specified key; otherwise, false.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns whether there is a PDF number associated with a specified key in a PDF dictionary and, if so, retrieves that number.

    Declaration

    Swift

    func CGPDFDictionaryGetNumber(_ dictionary: CGPDFDictionaryRef, _ key: UnsafePointer<Int8>, _ value: UnsafeMutablePointer<CGPDFReal>) -> Bool

    Objective-C

    bool CGPDFDictionaryGetNumber ( CGPDFDictionaryRef dict, const char *key, CGPDFReal *value );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    key

    The key for the value to retrieve.

    value

    On input, a pointer to a PDF number. If the value associated with the specified key is a PDF number (real or integer), then on return contains that value; otherwise the value is unspecified.

    Return Value

    Returns true if there is a PDF number associated with the specified key; otherwise, false.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns whether there is a PDF object associated with a specified key in a PDF dictionary and, if so, retrieves that object.

    Declaration

    Swift

    func CGPDFDictionaryGetObject(_ dictionary: CGPDFDictionaryRef, _ key: UnsafePointer<Int8>, _ value: UnsafeMutablePointer<CGPDFObjectRef>) -> Bool

    Objective-C

    bool CGPDFDictionaryGetObject ( CGPDFDictionaryRef dict, const char *key, CGPDFObjectRef *value );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    key

    The key for the value to retrieve.

    value

    On input, a pointer to a PDF object. If the value associated with the specified key is a PDF object, then on return contains that object; otherwise the value is unspecified.

    Return Value

    Returns true if there is a PDF object associated with the specified key; otherwise, false.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns whether there is a PDF stream associated with a specified key in a PDF dictionary and, if so, retrieves that stream.

    Declaration

    Swift

    func CGPDFDictionaryGetStream(_ dictionary: CGPDFDictionaryRef, _ key: UnsafePointer<Int8>, _ value: UnsafeMutablePointer<CGPDFStreamRef>) -> Bool

    Objective-C

    bool CGPDFDictionaryGetStream ( CGPDFDictionaryRef dict, const char *key, CGPDFStreamRef *value );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    key

    The key for the value to be retrieved.

    value

    On input, a pointer to a PDF stream. If the value associated with the specified key is a PDF stream, then on return contains that stream; otherwise, the value is unspecified.

    Return Value

    Returns true if there is a PDF stream associated with the specified key; otherwise, false.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns whether there is a PDF string associated with a specified key in a PDF dictionary and, if so, retrieves that string.

    Declaration

    Swift

    func CGPDFDictionaryGetString(_ dictionary: CGPDFDictionaryRef, _ key: UnsafePointer<Int8>, _ value: UnsafeMutablePointer<CGPDFStringRef>) -> Bool

    Objective-C

    bool CGPDFDictionaryGetString ( CGPDFDictionaryRef dict, const char *key, CGPDFStringRef *value );

    Parameters

    dictionary

    A PDF dictionary. If this parameter is not a valid PDF dictionary, the behavior is undefined.

    key

    The key for the value to retrieve.

    value

    On input, a pointer to a PDF string. If the value associated with the specified key is a PDF string, then on return contains that string; otherwise the value is unspecified.

    Return Value

    Returns true if there is a PDF string associated with the specified key; otherwise, false.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

Callbacks

  • Performs custom processing on a key-value pair from a PDF dictionary, using optional contextual information.

    Declaration

    Swift

    typealias CGPDFDictionaryApplierFunction = CFunctionPointer<((UnsafePointer<Int8>, CGPDFObjectRef, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*CGPDFDictionaryApplierFunction) ( const char *key, CGPDFObjectRef value, void *info, );

    Parameters

    key

    The current key in the dictionary.

    object

    The value in the dictionary associated with the key.

    info

    The contextual information that your provided in the info parameter in CGPDFDictionaryApplyFunction.

    Discussion

    CGPDFDictionaryApplierFunction defines the callback for CGPDFDictionaryApplyFunction, that enumerates all of the entries in the dictionary, calling your custom applier function once for each entry. The current key, its associated value, and the contextual information are passed to your applier function using the key, value, and info parameters respectively.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

Data Types

  • An opaque type that encapsulates a PDF dictionary.

    Declaration

    Swift

    typealias CGPDFDictionaryRef = COpaquePointer

    Objective-C

    typedef struct CGPDFDictionary *CGPDFDictionaryRef;

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.