CGPDFDictionary Reference

Derived from
None
Framework
ApplicationServices/ApplicationServices.h
Companion guide
Declared in
CGPDFDictionary.h

Overview

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 by Task

Applying a Function to All Entries

Getting Data from a Dictionary

Functions

CGPDFDictionaryApplyFunction

Applies a function to each entry in a dictionary.

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).

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

CGPDFDictionaryGetArray

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

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.

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

CGPDFDictionaryGetBoolean

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

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.

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

CGPDFDictionaryGetCount

Returns the number of entries in a PDF dictionary.

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.

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

CGPDFDictionaryGetDictionary

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

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.

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

CGPDFDictionaryGetInteger

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

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.

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

CGPDFDictionaryGetName

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.

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.

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

CGPDFDictionaryGetNumber

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

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.

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

CGPDFDictionaryGetObject

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

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.

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

CGPDFDictionaryGetStream

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

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.

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

CGPDFDictionaryGetString

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

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.

Availability
  • Available in OS X version 10.3 and later.
Declared In
CGPDFDictionary.h

Callbacks

CGPDFDictionaryApplierFunction

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

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

If you name your function MyFunction, you would declare it like this:

void MyFunction (
   const char *key,
   CGPDFObjectRef object,
   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.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGPDFDictionary.h

Data Types

CGPDFDictionaryRef

An opaque type that encapsulates a PDF dictionary.

typedef struct CGPDFDictionary *CGPDFDictionaryRef;
Availability
  • Available in OS X v10.3 and later.
Declared In
CGPDFDictionary.h