# PD Layer

> PD Layer: 47 components, 1090 items.

- Product: Adobe PDF Library 21
- Language: Adobe C++
- Version: APDFL21.0.0PlusP1e
- HTML page: https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer
- Version index: https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/llms.txt

## ASFileAttachment

### Functions (3)

#### ASFileAttachmentCreatePathName

```cpp
void ASFileAttachmentCreatePathName(PDDoc pdDoc, ASText pathText, ASFileSys *fileSys, ASPathName *pathName)
```

Header: `PDProcs.h:12669`

Creates an `ASPathName` corresponding to the specified file or folder in the collection.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document containing the specified file or folder.
- `pathText` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text-based representation of the path. The path consists of a file name or sequence of file names. A file name may not contain any of the characters `'\', '/', ':', '*', '?', '<', '>', '|'`, and may not contain `'.'` as the final character. When `'/'` appears in a path, it signifies that the preceding file name is a folder, and that the subsequent file name is a child of that folder. The root of a collection may be identified by passing `"/"`, `NULL`, or an empty string for `pathText`.
- `fileSys` ([`ASFileSys *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): A pointer that will be filled by the function. This parameter provides the caller with the `ASFileSys` to use in conjunction with the specified file or folder.
- `pathName` ([`ASPathName *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): A pointer that will be filled by the function. This parameter provides the caller with the `ASPathName` to use in conjunction with the specified file or folder.

**Returns:** `void`

#### ASFileAttachmentGetPDFileAttachment

```cpp
ASBool ASFileAttachmentGetPDFileAttachment(ASFileSys fileSys, ASPathName pathName, PDFileAttachment *attachment)
```

Header: `PDProcs.h:12680`

Produces a `PDFileAttachment` corresponding to the `ASFileSys` and `ASPathName`. It raises an exception if the `ASFileSys` is is not the embedded files file system, or if the `ASPathName` or `PDFileAttachment` parameters are `NULL`.

**Parameters**

- `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): The `ASFileSys` for file attachments.
- `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The `ASPathName` identifying the file attachment of interest.
- `attachment` ([`PDFileAttachment *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): A pointer that will be receive the file attachment.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the file attachment was found, `false` otherwise.

#### ASFileAttachmentGetPDFolder

```cpp
ASBool ASFileAttachmentGetPDFolder(ASFileSys fileSys, ASPathName pathName, PDFolder *folder)
```

Header: `PDProcs.h:12691`

Produces a `PDFolder` corresponding to the `ASFileSys` and `ASPathName`. It raises an exception if the `ASFileSys` is is not the embedded files file system, or if the `ASPathName` or `PDFolder` parameters are `NULL`.

**Parameters**

- `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): The `ASFileSys` for file attachments
- `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The `ASPathName` identifying the folder of interest.
- `folder` ([`PDFolder *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder))

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the folder was found, `false` otherwise.

## General

### Functions (18)

#### PDApplyFunction

```cpp
void PDApplyFunction(CosObj funcDict, const float inVals[], float outVals[])
```

Header: `PDProcs.h:7652`

Given a CosObj that represents a function, it applies the function to the supplied values. It raises an error if the CosObj is malformed. Deprecateduse PDApplyFunctionEx instead

**Parameters**

- `funcDict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The CosObj representing a function.
- `inVals` (`const float`): Input values.
- `outVals` (`float`): Output values.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the CosObj is not a function dictionary.

#### PDApplyFunctionEx

```cpp
void PDApplyFunctionEx(CosObj funcDict, const float inVals[], const ASArraySize nInput, float outVals[], const ASArraySize nOutput)
```

Header: `PDProcs.h:12709`

Given a CosObj that represents a function, it applies the function to the supplied values. It raises an error if the CosObj is malformed.

**Parameters**

- `funcDict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The CosObj representing a function.
- `inVals` (`const float`): Input values.
- `nInput` ([`const ASArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASArraySize)): Number of input values.
- `outVals` (`float`): Output values.
- `nOutput` ([`const ASArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASArraySize)): Number of output values.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the CosObj is not a function dictionary or the number of i/o do not match with that of the function.

#### PDDrawCosObjToWindow

```cpp
void PDDrawCosObjToWindow(CosObj cosObj, void *window, void *displayContext, ASBool isDPS, ASFixedMatrix *matrix, ASFixedRect *updateRect, CancelProc cancelProc, void *cancelProcClientData)
```

Header: `PDProcs.h:5502`

Draws the specified stream of PDF marking operators into the specified window. This method is used for platform-independent drawing of graphics and text. This method changes the Current Transformation Matrix (CTM) and zoom factor for the current page. This leaves the file "dirty," or stale. The version of the file on the disk no longer matches the more current version in system memory. See the description of Resource Dictionaries in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.8.3, on page 82. You can find this document on the web store of the International Standards Organization (ISO). See the description of the Content Stream Operators in Annex A of the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, Annex A.2, on page 643. You can find this document on the web store of the International Standards Organization (ISO). A pseudocode example of the stream object is: `<< /Length 1000 /Filter` `[...filters...] /Resources <<` `/ProcSet [ /PDF /Text ]` `/Font <</F5 6 0 R /F9 12 0 R>> >>` `>>` `stream` `...stream data...` `endstream` **Note:** Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

**Parameters**

- `cosObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The stream Cos object to draw into the window. This stream can be created using CosNewStream(). The stream's dictionary must contain a Resources key whose value is a dictionary specifying all the resources needed to draw the Cos object (including a ProcSet entry). Its structure and contents are the same as for the Resources dictionary for a Page object.
- `window` (`void *`): A pointer to a platform-dependent window object (`HWND` on Windows, `WindowPtr`). On Windows, to draw into an offscreen `DC`, pass `NULL` for `window`.
- `displayContext` (`void *`): A pointer to a platform-dependent display context structure (`hDC` on Windows).
- `isDPS` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Currently unused. Always set it to `false`.
- `matrix` (`ASFixedMatrix *`): A pointer to a matrix to concatenate onto the default page matrix. It is useful for scaling and for converting from page to window coordinates.
- `updateRect` (`ASFixedRect *`): A pointer to a rectangle, specified in user space coordinates. Any objects outside of `updateRect` will not be drawn. All objects are drawn if `updateRect` is `NULL`.
- `cancelProc` ([`CancelProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#CancelProc)): A procedure called periodically to check for the user's cancelling of the drawing operation. The default cancel proc can be obtained using AVAppGetCancelProc(). It may be `NULL`, in which case no cancel proc is used.
- `cancelProcClientData` (`void *`): A pointer to user-supplied data to pass to `cancelProc` each time it is called. It should be `NULL` if `cancelProc` is `NULL`.

**Returns:** `void`

**See also:** [`CosNewStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewStream), [`PDPageDrawContentsToWindow`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageDrawContentsToWindow), [`PDPageDrawContentsToWindowEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageDrawContentsToWindowEx)

#### PDDrawCosObjWithParams

```cpp
void PDDrawCosObjWithParams(CosObj cosObj, PDDrawParams params)
```

Header: `PDProcs.h:10537`

Provides control over the rendering of contents, including both those parameters you would pass to PDDrawCosObjWithParams(), and an optional-content context that determines which contents are visible. **Note:** Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

**Parameters**

- `cosObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object to draw.
- `params` (`PDDrawParams`): The parameters with which to draw the object, including the optional-content context to use for content visibility.

**Returns:** `void`

**Exceptions**

- `pdPErrUnableToCreateRasterPort`

**See also:** [`PDDrawCosObjToWindow`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDrawCosObjToWindow), [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

#### PDFormEnumPaintProc

```cpp
void PDFormEnumPaintProc(PDXObject obj, PDGraphicEnumMonitor mon, void *clientData)
```

Header: `PDProcs.h:3994`

(Obsolete, provided only for backwards compatibility) Enumerates a form's drawing operations.

**Parameters**

- `obj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The form whose drawing operations are enumerated.
- `mon` ([`PDGraphicEnumMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGraphicEnumMonitor)): A structure containing user-supplied callbacks that are called for each drawing operator on a page. Enumeration ends if any procedure returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `mon` each time it is called.

**Returns:** `void`

**See also:** [`PDFormEnumResources`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumResources), [`PDFormEnumPaintProcWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumPaintProcWithParams)

#### PDFormEnumPaintProcWithParams

```cpp
void PDFormEnumPaintProcWithParams(PDXObject obj, PDGraphicEnumParams params)
```

Header: `PDProcs.h:10557`

Enumerates a form's drawing operations for those contents that are visible in a given optional-content context. The parameters include both the monitor and data you would pass to PDFormEnumPaintProc(), and an optional-content context that determines which contents are visible.

**Parameters**

- `obj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The form whose drawing operations are enumerated.
- `params` (`PDGraphicEnumParams`): The parameters, including the optional-content context to use for content visibility.

**Returns:** `void`

**Exceptions**

- `pdPErrUnableToCreateRasterPort`

**See also:** [`PDFormEnumPaintProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumPaintProc), [`PDCharProcEnumWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharProcEnumWithParams)

#### PDFormEnumResources

```cpp
void PDFormEnumResources(PDXObject obj, PDResourceEnumMonitor mon, void *clientData)
```

Header: `PDProcs.h:3977`

(Obsolete, provided only for backwards compatibility) Enumerates the resources used by a form.

**Parameters**

- `obj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The form whose resources are enumerated.
- `mon` ([`PDResourceEnumMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDResourceEnumMonitor)): A structure containing user-supplied callbacks that are called for each of the form's resources. Enumeration ends if any procedure returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `mon` each time it is called.

**Returns:** `void`

**See also:** [`PDFormEnumPaintProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumPaintProc)

#### PDFormGetBBox

```cpp
void PDFormGetBBox(PDXObject obj, ASFixedRect *bboxP)
```

Header: `PDProcs.h:3938`

(Obsolete, provided only for backwards compatibility) Gets a form's bounding box.

**Parameters**

- `obj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The form whose bounding box is obtained.
- `bboxP` (`ASFixedRect *`): (Filled by the method) A pointer to a rectangle containing the form's bounding box, specified in user space coordinates.

**Returns:** `void`

#### PDFormGetFormType

```cpp
ASInt32 PDFormGetFormType(PDXObject obj)
```

Header: `PDProcs.h:3927`

(Obsolete, provided only for backwards compatibility) Gets the value of a form's FormType attribute.

**Parameters**

- `obj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The form whose type is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The form type (the value of the PDF FormType key). This value is `1` for PDF 1.0, 1.1, and 1.2.

#### PDFormGetMatrix

```cpp
void PDFormGetMatrix(PDXObject obj, ASFixedMatrix *matrixP)
```

Header: `PDProcs.h:3951`

(Obsolete, provided only for backwards compatibility) Gets the specified form's transformation matrix.

**Parameters**

- `obj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The form whose transformation matrix is obtained.
- `matrixP` (`ASFixedMatrix *`): (Filled by the method) A pointer to a matrix containing the form's transformation matrix, which specifies the transformation from form space to user space. See Section 4.9 in the *PDF Reference*.

**Returns:** `void`

#### PDFormGetXUIDCosObj

```cpp
CosObj PDFormGetXUIDCosObj(PDXObject obj)
```

Header: `PDProcs.h:3962`

(Obsolete, provided only for backwards compatibility) Gets the array Cos object corresponding to a form's XUID. An XUID is an array of numbers that uniquely identify the form in order to allow it to be cached.

**Parameters**

- `obj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The form whose XUID is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The array Cos object for the form's XUID.

#### PDImageColorSpaceGetIndexLookup

```cpp
void PDImageColorSpaceGetIndexLookup(PDXObject xobj, ASUns8 *data, ASInt32 dataLen)
```

Header: `PDProcs.h:3917`

(Obsolete, provided only for backwards compatibility) Gets the lookup table for an indexed color space. The table will contain the number of entries specified by the index size, and there will be 1 byte for each color component for each entry. The number of color components depends on the color space: Color Number of components gray 1 RGB 3 CMYK 4 Lab 3 For additional information on indexed color space, see the Special Color Spaces section in the ISO 32000-1:2008, Document Management- Portable Document Format-Part 1: PDF 1.7, section 8.6.6, page 155. You can find this document on the web store of the International Standards Organization (ISO). There is also some useful discussion in the *PostScript Language Reference Manual* under indexed color spaces. [https://www.adobe.com/jp/print/postscript/pdfs/PLRM.pdf](https://www.adobe.com/jp/print/postscript/pdfs/PLRM.pdf)

**Parameters**

- `xobj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The image whose lookup table is obtained.
- `data` ([`ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): (Filled by the method) An array for the returned color space information.
- `dataLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length of data in bytes.

**Returns:** `void`

**See also:** [`PDInlineImageColorSpaceGetIndexLookup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDInlineImageColorSpaceGetIndexLookup)

#### PDImageGetAttrs

```cpp
void PDImageGetAttrs(PDXObject obj, PDImageAttrsP attrsP, ASInt32 attrsLen)
```

Header: `PDProcs.h:3881`

(Obsolete, provided only for backwards compatibility. Use PDEImageGetAttrs and/or Cos-level calls instead.) Gets the attributes of an image (for example, Type, Subtype, Name, Width, Height, BitsPerComponent, ColorSpace, Decode, Interpolate, or ImageMask).

**Parameters**

- `obj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The image whose attributes are obtained.
- `attrsP` (`PDImageAttrsP`): (Filled by the method) A pointer to a `PDImageAttrs` structure containing the image attributes.
- `attrsLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): It must be `sizeof(PDImageAttrs)`.

**Returns:** `void`

**See also:** [`PDInlineImageGetAttrs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDInlineImageGetAttrs)

#### PDImageSelAdjustMatrix

```cpp
void PDImageSelAdjustMatrix(void *callData, ASFixedMatrix newUserMatrix)
```

Header: `PDProcs.h:7636`

This method is obsolete and is provided only for backwards compatibility. The method allows an image selector client to change the region of the page occupied by an image. It must only be used by image selector clients that return data for only the visible part of an image, to set the region of the page that the sub-image occupies. It must not be used otherwise. This method only has an effect while displaying on the screen. It does nothing when printing. The matrix set by this call remains in effect only for the current image. The Acrobat viewer automatically replaces it after the image has been drawn.

**Parameters**

- `callData` (`void *`): The value passed to the image selector
  as a parameter to PDImageSelectAlternate().
- `newUserMatrix` (`ASFixedMatrix`): The matrix that will replace the
  `imageToUserMatri` (see PDImageSelGetGeoAttr()). The
  `imageToDevMatrix` is automatically calculated from `newUserMatrix`.

**Returns:** `void`

**See also:** `PDImageSelGetGeoAttr (obsolete)`, `PDImageSelGetDeviceAttr (obsolete)`, `PDImageSelectAlternate (obsolete)`

#### PDImageSelGetDeviceAttr

```cpp
void PDImageSelGetDeviceAttr(void *callData, PDColorSpace *colorSpaceP, ASUns32 *bitsPerPixelP, ASAtom *deviceTypeP)
```

Header: `PDProcs.h:7608`

This method is obsolete and provided only for backwards compatibility. The method gets device-related attributes for a particular image XObject. It must only be used from within an image selector client, since it returns information that is only valid in that context. This method can be used by an image selector client to obtain additional information to help the selector determine which alternate image to choose. If an image is displayed on two devices simultaneously (for example, if the window containing the image is split across two monitors in a multi-monitor system), the values returned for `colorSpaceP` and `bitsPerPixelP` are each the maximum for the devices on which the image is currently displayed. For example, if the image is currently split across the following devices: 8-bit gray scale monitor 4-bit RGB color monitor `colorSpaceP` would be `DeviceRGB`, because that is the *highest* color space on which the image is currently displayed. `bitsPerPixelP` would be `8`, because that is the highest bit depth on which the image is currently displayed.

**Parameters**

- `callData` (`void *`): (Filled by the method) The value passed
  to the image selector as a parameter to PDImageSelectAlternate().
- `colorSpaceP` ([`PDColorSpace *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDColorSpace)): (Filled by the method) The destination
  device's color space. It will be one of the following:

  ValueDescription
  PDDeviceGrayGrayscale device
  PDDeviceRGBRGB device
  PDDeviceCMYKCMYK device

  If the device has some other color space or
  its color space cannot be determined, PDDeviceRGB is returned.
- `bitsPerPixelP` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): (Filled by the method) The number of
  bits used for each pixel. For example, a device with 8 bits
  red, 8 bits green, and 8 bits blue would have a `bitsPerPixel`
  of `24`. If `bitsPerPixelP` has a value of `0` (instead of
  the more standard `1`, `8`, or `24`), the number of bits per pixel on the output device could not be determined.

  Value
  Description

  `Display`
  A display device such as a monitor

  `PostScript`
  A PostScript printer or PostScript file

  `nonPostScriptPrinter`
  A non-PostScript printer
- `deviceTypeP` ([`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): (Filled by the method) The output device type. It will be one of the following:

**Returns:** `void`

**See also:** `PDImageSelAdjustMatrix (obsolete)`, `PDImageSelGetDeviceAttr (obsolete)`, `PDImageSelectAlternate (obsolete)`

#### PDImageSelGetGeoAttr

```cpp
void PDImageSelGetGeoAttr(void *callData, ASFixedRect *updateBBoxP, ASFixedMatrix *imageToDefaultMatrixP, ASFixedMatrix *imageToDevMatrixP)
```

Header: `PDProcs.h:7541`

This method is obsolete and provided only for backwards compatibility. The method requests geometry-related attributes of an image XObject. This method can be used by an image selector client to obtain additional information to help the selector determine which alternate image to choose. • `imageToDefaultMatrixP->a` is equal to the image horizontal size in 1/72 of an inch units. • `imageToDefaultMatrixP->b = 0` • `imageToDefaultMatrixP->c = 0` • `imageToDefaultMatrixP->d` is equal to the image vertical size in 1/72 of an inch units. • `imageToDefaultMatrixP->h` is equal to the left edge of image. • `imageToDefaultMatrixP->v` is equal to the bottom edge of the image. In other words, this matrix provides the image's height, width, and position on the page, all in units of points (compare to `imageToDefaultMatrixP`). The intersection of the rectangle obtained by transforming a 1x1 unit rectangle (the image) through `imageToDeviceMatrixP` and the `updateBBoxP` rectangle is the region of the image that is actually drawn. This is the region of the image for which data is required.

**Parameters**

- `callData` (`void *`): (Filled by the method) The value passed to the image selector as a parameter to PDImageSelectAlternate().
- `updateBBoxP` (`ASFixedRect *`): (Filled by the method) The rectangle bounding the region of the page to update. This is the intersection of the visible portion of the page, any update regions, and any clipping paths that have been explicitly set in the PDF file. Its coordinates are specified in default user space.
- `imageToDefaultMatrixP` (`ASFixedMatrix *`): (Filled by the method) A matrix specifying the transformation from image space (the space in which all images are 1x1 units) to default user space (the space with 72 units per inch). It contains sufficient information for the image selector plug-in to determine the image's size and location on the page. For a *normal page and image* (an *upright* image on a non-rotated page), the following is true:
- `imageToDevMatrixP` (`ASFixedMatrix *`): (Filled by the method) A matrix specifying the transformation from image space (the space in which all images are 1x1 unit) to device space (the space in which one unit is one pixel). This matrix provides the image's height, width, and position on the page, all in pixels (compare to `imageToDefaultMatrixP`).

**Returns:** `void`

**See also:** `PDImageSelAdjustMatrix (obsolete)`, `PDImageSelGetDeviceAttr (obsolete)`, `PDImageSelectAlternate (obsolete)`

#### PDImageSelectAlternate

```cpp
CosObj PDImageSelectAlternate(CosObj image, ASBool print, ASUns32 tickLimit, ASBool *cacheImageP, void *callData)
```

Header: `PDProcs.h:7487`

This method is obsolete and never called in Acrobat 8. (Obsolete, provided only for backwards compatibility) Selects which Alternate image to use. This method can do one of three things: • Return an existing Alternate. • Create and return an image XObject. • Indicate that this XObject should be skipped. This method is called each time the Acrobat viewer draws an XObject image, regardless of whether the image XObject has an Alternates key. You can replace this method with your own version, using HFTReplaceEntry(). • If `tickLimit` is zero, the image selector must not return control to the Acrobat viewer until the selector can provide the alternate image to use. • If `tickLimit` is nonzero, the image selector does not have to provide the image XObject within `tickLimit`, but it must raise the fileErrBytesNotReady exception if it cannot. This returns control to the Acrobat viewer and informs it that the data is not ready. The Acrobat viewer then calls the image selector periodically until the image selector returns the selected image XObject.

**Parameters**

- `image` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object for this image XObject's base image. Under some circumstances, PDImageSelectAlternate() can be called with an XObject type other than an image; for example, a form. Because of this, your code must check the XObject's subtype (you can use CosDictGet() to read the value of the XObject's Subtype key). If the subtype is not Image, your code must not modify the XObject, but simply return the CosObj that was passed to you.
- `print` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): `true` if printing, `false` if displaying.
- `tickLimit` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The amount of time, in ticks, before the image selector must return control to the Acrobat viewer. This parameter is not relevant for image selectors that simply choose an existing alternate or create a new image XObject using Cos methods, but it is relevant for image selectors that create a new image XObject by calculating or reading data from a network or a slow device.
- `cacheImageP` ([`ASBool *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, the image data returned to the Acrobat viewer is cached for future use. If `false`, it is not. Pass `true` if you expect your image data to remain valid for at least several calls to your client. Pass `false` if you expect your image data to change on the next call to your client. If you create and return a Cos stream object with an external file system and the stream's data will not always be the same, you must set `cacheImageP` to `false`. If you fail to do this, the Acrobat viewer may use cached image data when it should not.
- `callData` (`void *`): An opaque pointer containing data that must be passed in other image selector calls.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The image XObject to use. Returning a `NULL` Cos object (obtained using CosNewNull) tells the Acrobat viewer to skip this XObject entirely.

**Exceptions**

- `fileErrBytesNotReady`

**See also:** `PDImageSelGetGeoAttr (obsolete)`, `PDImageSelGetDeviceAttr (obsolete)`, `PDImageSelAdjustMatrix (obsolete)`

#### PDSetHostEncoding

```cpp
void PDSetHostEncoding(ASHostEncoding encoding, char *parseTable)
```

Header: `PDProcs.h:10880`

For internal use only.

**Parameters**

- `encoding` ([`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding))
- `parseTable` (`char *`)

**Returns:** `void`

### Typedefs (22)

#### PDCharOffset

```cpp
typedef ASUns16 PDCharOffset
```

Header: `PDExpT.h:106`

#### PDColorSpace

```cpp
typedef ASEnum8 PDColorSpace
```

Header: `PDExpT.h:924`

#### PDCount

```cpp
typedef ASInt32 PDCount
```

Header: `PDExpT.h:111`

A numeric count value for use in `PDImageAttrs`.

#### PDEndStyle

```cpp
typedef ASEnum8 PDEndStyle
```

Header: `PDExpT.h:5880`

#### PDFindFlags

```cpp
typedef ASEnum8 PDFindFlags
```

Header: `PDExpT.h:2218`

#### PDHorizAlign

```cpp
typedef ASEnum8 PDHorizAlign
```

Header: `PDExpT.h:6570`

#### PDImageScalar

```cpp
typedef ASInt32 PDImageScalar
```

Header: `PDExpT.h:92`

A signed measurement of an image offset, for use in `PDImageAttrs`.

#### PDJoinStyle

```cpp
typedef ASEnum8 PDJoinStyle
```

Header: `PDExpT.h:5871`

#### PDOperation

```cpp
typedef ASEnum8 PDOperation
```

Header: `PDExpT.h:1020`

#### PDPlacementTypes

```cpp
typedef ASEnum8 PDPlacementTypes
```

Header: `PDExpT.h:5883`

#### PDSaveFlags2

```cpp
typedef ASFlagBits PDSaveFlags2
```

Header: `PDExpT.h:1652`

This enumeration defines the flags used in the `saveFlags2` bitfield of the PDDocSaveParams structure passed to PDDocSaveWithParams(). These flags are an extension to those defined by the PDSaveFlags enumeration, which are stored in the `saveFlags` bitfield of the PDDocSaveParams structure.

**See also:** [`PDDocSaveWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSaveWithParams), [`PDDocInsertPages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocInsertPages), [`PDDocSaveParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSaveParams), [`PDSaveFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDSaveFlags)

#### PDSmallFlagBits

```cpp
typedef ASUns16 PDSmallFlagBits
```

Header: `PDExpT.h:67`

A flag value for use in PDDocInsertPagesParams().

**See also:** [`PDDocInsertPages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocInsertPages)

#### PDVertAlign

```cpp
typedef ASEnum8 PDVertAlign
```

Header: `PDExpT.h:6574`

#### PDWatermarkDrawOption

```cpp
typedef ASEnum8 PDWatermarkDrawOption
```

Header: `PDExpT.h:6642`

#### PDiFontMetric

```cpp
typedef ASInt16 PDiFontMetric
```

Header: `PDExpT.h:87`

A font metric value (which is never negative), for use in `PDFontMetrics`.

#### StdPassword

```cpp
typedef char StdPassword[MAX_PWCHARS+1][MAX_PWCHARS+1]
```

Header: `PDExpT.h:4314`

#### PDFindTranslateStringProc

```cpp
typedef ASBool(*) PDFindTranslateStringProc(char *string, ASInt32 stringLength, PDWord pdWord, void *clientData)(char *string, ASInt32 stringLength, PDWord pdWord, void *clientData)
```

Header: `PDExpT.h:3417`

PDFindTranslateStringProc() is passed to PDFindText().

#### PDLaunchActionProc

```cpp
typedef ASBool(*) PDLaunchActionProc(void *fileSpecHandlerObj, PDDoc pdDoc, PDAction pdAction)(void *fileSpecHandlerObj, PDDoc pdDoc, PDAction pdAction)
```

Header: `PDExpT.h:1177`

(Optional) A callback for PDFileSpecHandler. It launches a specified file. It is called when the Acrobat viewer encounters a Launch (GoTo File) action. If this callback is `NULL`, no launch action is performed.

#### PDResourceEnumColorSpaceProc

```cpp
typedef ASBool(*) PDResourceEnumColorSpaceProc(char *name, CosObj colorSpace, void *clientData)(char *name, CosObj colorSpace, void *clientData)
```

Header: `PDExpT.h:2734`

A callback for PDResourceEnumMonitor. It is called for color space resources.

**See also:** [`PDFormEnumResources`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumResources)

#### PDResourceEnumFontProc

```cpp
typedef ASBool(*) PDResourceEnumFontProc(PDFont font, char *name, void *clientData)(PDFont font, char *name, void *clientData)
```

Header: `PDExpT.h:2694`

A callback for PDResourceEnumMonitor. It is a procedure called for font resources.

**See also:** [`PDFormEnumResources`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumResources)

#### PDResourceEnumProcSetProc

```cpp
typedef ASBool(*) PDResourceEnumProcSetProc(char *name, void *clientData)(char *name, void *clientData)
```

Header: `PDExpT.h:2720`

A callback for PDResourceEnumMonitor. It is a procedure called for ProcSet resources.

**See also:** [`PDFormEnumResources`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumResources)

#### PDResourceEnumXObjectProc

```cpp
typedef ASBool(*) PDResourceEnumXObjectProc(PDXObject xObject, char *name, void *clientData)(PDXObject xObject, char *name, void *clientData)
```

Header: `PDExpT.h:2707`

A callback for PDResourceEnumMonitor. It is a procedure called for XObject resources.

**See also:** [`PDFormEnumResources`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumResources)

### Structures (5)

#### PDConstColorValue

```cpp
typedef const struct _t_PDColorValueRec* PDConstColorValue
```

Header: `PDExpT.h:958`

#### PDContent

```cpp
typedef struct _t_PDContent* PDContent
```

Header: `PDBasicExpT.h:114`

A pointer to a PDContent `struct`.

#### PDFind

```cpp
typedef struct _t_PDFind* PDFind
```

Header: `PDExpT.h:2191`

#### PDResourceEnumMonitor

```cpp
typedef struct _t_PDResourceEnumMonitor* PDResourceEnumMonitor
```

Header: `PDExpT.h:2745`

A data structure containing callbacks used when enumerating the resources of a form with PDFormEnumResources() or PDPageEnumResources(). **Note:** PDPageEnumResources is provided only for backwards compatibility. You should use the PDFEdit API to enumerate page resources.

**See also:** [`PDFormEnumResources`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumResources)

#### PDTrapPreset

```cpp
typedef  struct PDTrapPresetRec * PDTrapPreset
```

Header: `PDExpT.h:5904`

### Enums (15)

#### GCHTextType

Header: `PDExpT.h:4402`

**Values**

- `kGCHTTipText = 1`
- `kGCHTMiniText = 2`
- `kGCHTLargeText = 3`

#### HSEmitFonts

Header: `PDExpT.h:5909`

**Values**

- `kHSEmitFontNoFonts = 0`: Embed no fonts.
- `kHSEmitFontEmbeddedFonts = 1`: Emit all embedded fonts.
- `kHSEmitFontAllFonts = 2`: Emit all fonts.

#### InkTypes

Header: `PDExpT.h:5944`

Ink types.

**Values**

- `kNormal = 0`
- `kTransparent = 1`
- `kOpaqueInk = 2`
- `kOpaqueIgnore = 3`

#### PDCharSets

Header: `PDExpT.h:2329`

An enumerated data type that identifies the character set of a Type 1, Multiple Master Type 1, or TrueType font.

**Values**

- `PDUnknownCharSet = 0`: The font does not use Adobe standard encoding.
- `PDStandardRomanCharSet = 1`: The font uses Adobe standard encoding. This is determined by the `"Uses Adobe Standard Encoding"` bit in the font descriptor.
- `PDAdobeExpertCharSet = 2`: Currently unused.
- `PDLastCharSet = 3`

#### PDColorSpaces

Header: `PDExpT.h:913`

An enumerated data type that specifies the color space in which a color value is specified (for example, RGB or grayscale).

**Values**

- `PDDeviceGray = 0`: Grayscale. It requires one value entry to specify the color.
- `PDDeviceRGB = 1`: Red-Green-Blue color specification. It requires three value entries to specify the color.
- `PDDeviceCMYK = 2`: Cyan-Magenta-Yellow-Black color specification. It requires four value entries to specify the color.

#### PDEContentAddPageFlags

Header: `PDExpT.h:6828`

**Values**

- `kAnnotAll = 0x0001`: Copy all annotations; do not consult annotation type list
- `kDoNotMergeFonts = 0x0004`: Do not merge duplicate fonts on merge: may result in larger files when saved, but can show performance benefits when inserting a page that uses a large number of fonts.

#### PDEndStyles

Header: `PDExpT.h:5872`

**Values**

- `kPDEndMiter = 0`
- `kPDEndOverlap = 1`

#### PDFindFlagTypes

Header: `PDExpT.h:2194`

Passed to PDFindText().

**Values**

- `PDFindWholeWords = 0x0001`: Find whole words only.
- `PDFindCaseSens = 0x0002`: Perform a case-sensitive search.
- `PDFindReverse = 0x0004`: Perform a reverse order search.
- `PDFindAllOnPage = 0x0008`: Return a PDTextSelect with all found words on the page.
- `PDFindIgnoreFH = 0x0100`: Do not perform a match of full-width/half-width Kana characters.
- `PDFindIgnoreDiacritics = 0x0200`: Ignore diacritics.
- `PDFindReset = 0x0800`: Reset to the beginning of the document.

#### PDHorizAlignments

Header: `PDExpT.h:6569`

**Values**

- `kPDHorizLeft = 0`
- `kPDHorizCenter = 1`
- `kPDHorizRight = 2`

#### PDInsertFlags

Header: `PDExpT.h:2138`

Used by PDDocInsertPages().

**Values**

- `PDInsertBookmarks = 0x0001`: Insert bookmarks as well as pages.
- `PDInsertAll = 0x1000`: Insert all Catalog and Info dictionary values as well as pages.
- `PDInsertThreads = 0x0002`: Insert articles as well.
- `PDDoNotInsertOutputIntent = 0x0004`: Do not merge output Intents
- `PDInsertDoNotMergeFonts = 0x0008`: Do not merge duplicate fonts when merging documents. This may result in larger files when saved, but can show performance benefits when inserting a page that uses a large number of fonts.
- `PDInsertDoNotResolveInvalidStructureParentReferences = 0x0010`: This is not necessary in most cases but it can show performance benefits for a document with a complicated Structure Tree.
- `PDInsertDoNotRemovePageInheritance = 0x0020`: This can slow down the performance when document has a very large page tree
- `PDInsertNamedDestinations = 0x0040`: Copy named destinations to maintain link annotations

**See also:** `PDDOcInsertPages`

#### PDJoinStyles

Header: `PDExpT.h:5860`

**Values**

- `kPDJoinMiter = 0`
- `kPDJoinRound = 1`
- `kPDJoinBevel = 2`

#### PDLayoutModes

Header: `PDExpT.h:2038`

A structure that defines the layout of a document. The layout can be set as the viewer's `avpPageViewLayoutMode` preference (set by AVAppSetPreference()) or in a view of a document by the `pageViewLayoutMode` field in AVDocViewDef (set by AVDocGetViewDef()).

**Values**

- `PDLayoutDontCare = 0`: (Default) Use the user preference when opening the file, as specified in the `avpPageViewLayoutMode` preference, set by AVAppSetPreference().
- `PDLayoutSinglePage = 1`: Use single-page mode.
- `PDLayoutOneColumn = 2`: Use one-column continuous mode.
- `PDLayoutTwoColumnLeft = 3`: Use two-column continuous mode with the first page on the left.
- `PDLayoutTwoColumnRight = 4`: Use two-column continuous mode with the first page on the right.
- `PDLayoutTwoPageLeft = 5`
- `PDLayoutTwoPageRight = 6`

**See also:** `AVDocGetViewDef`, `AVPageViewGetLayoutMode`, `AVPageViewSetLayoutMode`

#### PDVertAlignments

Header: `PDExpT.h:6573`

**Values**

- `kPDVertTop = 0`
- `kPDVertCenter = 1`
- `kPDVertBottom = 2`

#### PlateSeparationOptions

Header: `PDExpT.h:5918`

**Values**

- `kEmitPlate = 0`
- `kDontEmitPlate = 1`
- `kConvertToProcess = 2`: Represents an ink used on a page.
- `kConvertToAltSpace = 3`: Can be used while doing color convert only. This is a matching flag for kColorConvToAltSpace flag in PDColorConvertActionType kConvertToProcess matches kColorConvConvert in PDColorConvertActionType kEmitPlate & kDontEmitPlate matches kColorConvPreserve in PDColorConvertActionType

#### marksStyles

Header: `PDExpT.h:5955`

**Values**

- `kPDDefaultMarkType = 0`: No flags means InDesign style printer marks.
- `kPDInDesignJ1MarkType = 1`
- `kPDInDesignJ2MarkType = 2`
- `kPDIllustratorMarkType = 3`
- `kPDIllustratorJ = 4`
- `kPDQuarkXPress = 5`

### Definitions (5)

#### MAX_PWCHARS

Header: `PDExpT.h:4312`

Value: `255`

#### kPDEmitEasternTileMarks

Header: `PDExpT.h:6296`

Value: `0x0002`

Tile marks.

#### kPDEmitNoMarks

Header: `PDExpT.h:6286`

Value: `0`

Nothing.

#### kPDEmitSlug

Header: `PDExpT.h:6301`

Value: `0x0004`

Emit information about the document, name, page number, and so on.

#### kPDEmitWesternTileMarks

Header: `PDExpT.h:6291`

Value: `0x0001`

Tile marks.

## Metadata

### Functions (4)

#### PDDocGetInfo

```cpp
ASInt32 PDDocGetInfo(PDDoc doc, const char *infoKey, char *buffer, ASInt32 bufSize)
```

Header: `PDProcs.h:2322`

Gets the value of a key in a document's Info dictionary, or the value of this same key in the XMP metadata, whichever is later. However, it is preferable to use PDDocGetXAPMetadataProperty(), because it also allows accessing XMP properties that are not duplicated in the Info dictionary. See the description of the Document Information Dictionary in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 14.3.3, page 549. You can find this document on the web store of the International Standards Organization (ISO). All values in the Info dictionary should be strings; other data types such as numbers and booleans should not be used as values in the Info dictionary. Users may define their own Info dictionary entries. In this case, it is strongly recommended that the key have the developer's prefix assigned by the Adobe Solutions Network.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose Info dictionary key is obtained.
- `infoKey` (`const char *`): The name of the Info dictionary key whose
  value is obtained.
- `buffer` (`char *`): (Filled by the method) The buffer containing
  the value associated with `infoKey`. If `buffer` is `NULL`,
  the method will just return the number of bytes required.

  **Note:** This text is stored in either PDFDocEncoding or in Unicode. If it is stored in Unicode, a valid Byte Order Mark must be present.
- `bufSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The maximum number of bytes that can be written into `buffer`.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

If `buffer` is `NULL`, it returns the number of bytes in the specified key's value. If `buffer` is not `NULL`, it returns the number of bytes copied into `buffer`, excluding the terminating `NULL`. You must pass at least the `length + 1` as the buffer size since the routine adds a `'\0'` terminator to the data, even though the data is not a C string (it can contain embedded `'\0'` values).

**See also:** `PDDocGetXAPMetadataProperty`, [`PDDocSetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetInfo)

#### PDDocGetInfoASText

```cpp
void PDDocGetInfoASText(PDDoc doc, const ASText key, ASText value)
```

Header: `PDProcs.h:11514`

Gets the value of a key in a document's Info dictionary, or the value of this same key in the XMP metadata, whichever is latest as an ASText object.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose Info dictionary key is obtained.
- `key` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The name of the Info dictionary key whose value is obtained.
- `value` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The text object containing the value associated with `key`. The client must pass a valid ASText object value. The routine does not allocate it.

**Returns:** `void`

**See also:** [`PDDocGetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetInfo), `PDDocGetXAPMetadataProperty`, `PDDocSetInfoASText`, [`PDDocSetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetInfo)

#### PDDocSetInfo

```cpp
void PDDocSetInfo(PDDoc doc, const char *infoKey, const char *buffer, ASInt32 nBytes)
```

Header: `PDProcs.h:2358`

Sets the value of a key in a document's Info dictionary. However, it is preferable to use PDDocSetXAPMetadataProperty(), because it also allows accessing XMP properties that are not duplicated in the Info dictionary. See the description of the Document Information Dictionary in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 14.3.3, page 549. You can find this document on the web store of the International Standards Organization (ISO). All values in the Info dictionary should be strings; other data types such as numbers and Boolean values should not be used as values in the Info dictionary. If an Info dictionary key is specified that is not currently in the Info dictionary, it is added to the dictionary. Users may define their own Info dictionary entries. In this case, it is strongly recommended that the key have the developer's prefix assigned by the Adobe Developers Association. @note This text is stored in either PDFDocEncoding or in Unicode. If it is stored in Unicode, a valid Byte Order Mark must be present.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose Info dictionary key is set.
- `infoKey` (`const char *`): The name of the Info dictionary key whose value is set.
- `buffer` (`const char *`): The buffer containing the value to associate with `infoKey`.
- `nBytes` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of bytes in `buffer`.

**Returns:** `void`

**See also:** [`PDDocGetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetInfo), `PDDocSetXAPMetadataProperty`

#### PDDocSetInfoAsASText

```cpp
void PDDocSetInfoAsASText(PDDoc doc, const ASText infoKey, const ASText value)
```

Header: `PDProcs.h:11531`

Sets the value of a key in a document's Info dictionary.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose Info dictionary key is set.
- `infoKey` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The name of the Info dictionary key whose value is set.
- `value` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the value to associate with `infoKey`.

**Returns:** `void`

**See also:** [`PDDocSetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetInfo), [`PDDocGetInfoASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetInfoASText), [`PDDocGetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetInfo), `PDDocSetXAPMetadataProperty`

## PDAction

### Functions (16)

#### PDActionCanCopy

```cpp
ASBool PDActionCanCopy(PDAction action)
```

Header: `PDProcs.h:8718`

Tests whether the data from an action object can be copied to a clipboard for pasting. If the action is part of an action chain, the method tests all actions in the chain, and returns `true` only if all actions in the chain can be copied.

**Parameters**

- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): The action to test.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the action object or all actions in the action chain can be copied, `false` otherwise.

**See also:** [`PDActionCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCanPaste), [`PDActionCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCopy), [`PDActionPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionPaste), [`PDActionDestroyClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionDestroyClipboardData)

#### PDActionCanPaste

```cpp
ASBool PDActionCanPaste(PDDoc dest, PDActionClipboardData data)
```

Header: `PDProcs.h:8750`

Tests whether data from an action object that has been copied to a clipboard can be pasted into a destination document. It tests, for example, whether pasting is allowed by document permissions.

**Parameters**

- `dest` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The destination document.
- `data` ([`PDActionClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionClipboardData)): The action data to test.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

**See also:** [`PDActionCanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCanCopy), [`PDActionCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCopy), [`PDActionPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionPaste), [`PDActionDestroyClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionDestroyClipboardData)

#### PDActionCopy

```cpp
PDActionClipboardData PDActionCopy(PDAction action)
```

Header: `PDProcs.h:8733`

Copies action object data to a clipboard structure, from which it can be pasted. When the PDActionClipboardData is no longer required, it must be explicitly freed using PDActionDestroyClipboardData().

**Parameters**

- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): The action to copy.

**Returns:** [`PDActionClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionClipboardData)

The action clipboard data object.

**See also:** [`PDActionCanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCanCopy), [`PDActionCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCanPaste), [`PDActionPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionPaste), [`PDActionDestroyClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionDestroyClipboardData)

#### PDActionDestroy

```cpp
void PDActionDestroy(PDAction action)
```

Header: `PDProcs.h:122`

Destroys an action object.

**Parameters**

- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): IN/OUT The action to destroy.

**Returns:** `void`

**See also:** [`PDActionNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNew), [`PDActionNewFromDest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNewFromDest), [`PDActionNewFromFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNewFromFileSpec), [`PDActionFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionFromCosObj)

#### PDActionDestroyClipboardData

```cpp
void PDActionDestroyClipboardData(PDActionClipboardData data)
```

Header: `PDProcs.h:8788`

Destroys data that has been copied from an action object into a clipboard. Use this method when the clipboard data is no longer needed.

**Parameters**

- `data` ([`PDActionClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionClipboardData)): The clipboard action data to destroy.

**Returns:** `void`

**See also:** [`PDActionCanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCanCopy), [`PDActionCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCanPaste), [`PDActionCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCopy), [`PDActionPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionPaste)

#### PDActionEqual

```cpp
ASBool PDActionEqual(PDAction action, PDAction action2)
```

Header: `PDProcs.h:162`

Compares two actions for equality. Two actions are equal only if their Cos objects are equal (see CosObjEqual()).

**Parameters**

- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): The first actions to be compared.
- `action2` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): The second action to be compared.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the actions are equal, `false` otherwise.

**See also:** [`CosObjEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEqual)

#### PDActionFromCosObj

```cpp
PDAction PDActionFromCosObj(CosObj obj)
```

Header: `PDProcs.h:222`

Converts a dictionary Cos object to an action and verifies that the action is valid. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary Cos object whose action is obtained.

**Returns:** [`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)

The PDAction corresponding to `obj`.

**Exceptions**

- `pdErrBadAction`: is raised if the action is invalid as determined by PDActionIsValid().

**See also:** [`PDActionGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionGetCosObj), [`PDActionNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNew), [`PDActionNewFromDest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNewFromDest), [`PDActionNewFromFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNewFromFileSpec)

#### PDActionGetCosObj

```cpp
CosObj PDActionGetCosObj(PDAction action)
```

Header: `PDProcs.h:205`

Gets the Cos object corresponding to an action. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): IN/OUT The action whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The dictionary Cos object for the action. The contents of the dictionary can be enumerated using CosObjEnum().

**See also:** [`PDActionFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionFromCosObj)

#### PDActionGetDest

```cpp
PDViewDestination PDActionGetDest(PDAction action)
```

Header: `PDProcs.h:192`

Gets an action's destination view. This only works for actions that contain a view destination; that is, actions whose subtype is GoTo. For named destinations, this method may return a Cos string object or a Cos name object. See the description of the Named Destinations in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.3.2, page 365. You can find this document on the web store of the International Standards Organization (ISO). **Note:** Since this method may not return a PDViewDestination, use the PDViewDestResolve() method on the returned value to obtain a PDViewDestination.

**Parameters**

- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): The action whose destination is obtained.

**Returns:** [`PDViewDestination`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestination)

The action's destination, which may be a PDViewDestination, or for named destinations, a Cos string object or a Cos name object. Use the PDViewDestResolve() method on this returned value to obtain a PDViewDestination.

**See also:** [`PDActionGetFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionGetFileSpec), [`PDViewDestResolve`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestResolve)

#### PDActionGetFileSpec

```cpp
PDFileSpec PDActionGetFileSpec(PDAction action)
```

Header: `PDProcs.h:241`

Gets a file specification from an action. Not all types of actions have file specifications; this method only works for actions that contain a file specification. See the description of Actions in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.6, page 414. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): The action whose file specification is obtained.

**Returns:** [`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)

The action's file specification.

**See also:** [`PDActionGetDest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionGetDest)

#### PDActionGetSubtype

```cpp
ASAtom PDActionGetSubtype(PDAction action)
```

Header: `PDProcs.h:149`

Gets an action's subtype.

**Parameters**

- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): IN/OUT The action whose subtype is obtained.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

The ASAtom corresponding to the action's subtype. The ASAtom can be converted to a string using ASAtomGetString().

#### PDActionIsValid

```cpp
ASBool PDActionIsValid(PDAction action)
```

Header: `PDProcs.h:140`

Tests whether an action is valid. This method can be used in the following cases: • To determine whether a PDAction returned from a method is really an action. For example, calling PDLinkAnnotGetAction() returns an invalid action if no action is associated with the link annotation. • To ensure that an action has not been deleted.

**Parameters**

- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): The action whose validity is determined.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the action is valid, `false` otherwise.

**See also:** [`PDActionEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionEqual)

#### PDActionNew

```cpp
PDAction PDActionNew(PDDoc doc, ASAtom type)
```

Header: `PDProcs.h:67`

Creates a new action object.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the action is created.
- `type` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom corresponding to the action's subtype. The ASAtom can be obtained from a string using ASAtomFromString().

**Returns:** [`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)

The newly created PDAction.

**See also:** [`PDActionNewFromDest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNewFromDest), [`PDActionNewFromFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNewFromFileSpec), [`PDActionFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionFromCosObj), [`PDActionDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionDestroy)

#### PDActionNewFromDest

```cpp
PDAction PDActionNewFromDest(PDDoc doc, PDViewDestination dest, PDDoc destDoc)
```

Header: `PDProcs.h:94`

Creates a new action that takes the user to the specified destination view. This method can only be used for destinations in the same document as the source document. Cross-document links must be built up from the Cos level, populating the Action dictionary for the GotoR action. See the description of the GoToR Action in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.6.4, page 417. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the action is created and used.
- `dest` ([`PDViewDestination`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestination)): The destination view.
- `destDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The destination document. `destDoc` must be the same as `doc`.

**Returns:** [`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)

The newly created action.

**See also:** [`PDActionNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNew), [`PDActionNewFromFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNewFromFileSpec), [`PDActionFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionFromCosObj), [`PDActionDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionDestroy)

#### PDActionNewFromFileSpec

```cpp
PDAction PDActionNewFromFileSpec(PDDoc containingDoc, ASAtom type, PDFileSpec fileSpec)
```

Header: `PDProcs.h:111`

Creates an action of the specified type from a file specification.

**Parameters**

- `containingDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the action is created and used.
- `type` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The type of action to create.
- `fileSpec` ([`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)): The file specification that is made part of an action.

**Returns:** [`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)

The newly created PDAction.

**See also:** [`PDActionNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNew), [`PDActionNewFromDest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNewFromDest), [`PDActionFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionFromCosObj), [`PDActionDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionDestroy)

#### PDActionPaste

```cpp
PDAction PDActionPaste(PDDoc dest, PDActionClipboardData data)
```

Header: `PDProcs.h:8775`

Creates a new PDAction in the destination document, using clipboard data generated by PDActionCopy(). If the original PDAction was an action chain, the entire action chain is recreated. The returned PDAction is the first item in the chain. When the data is no longer needed, use PDActionDestroyClipboardData() to free the structure.

**Parameters**

- `dest` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The destination document for the paste operation.
- `data` ([`PDActionClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionClipboardData)): The clipboard structure holding the copied action data.

**Returns:** [`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)

A newly created action object (or the first such object in the action chain) associated with the specified document, containing the same data as the copied action.

**See also:** [`PDActionCanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCanCopy), [`PDActionCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCanPaste), [`PDActionCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCopy), [`PDActionDestroyClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionDestroyClipboardData)

### Typedefs (1)

#### PDAction

```cpp
typedef OPAQUE_64_BITS PDAction
```

Header: `PDExpT.h:133`

Actions are what happens when a user clicks on a link or bookmark. In addition, the Acrobat viewer allows a document to have an action that is executed automatically when the document is opened. Applications can also support actions in custom annotation types they add.

**See also:** [`PDActionNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNew), [`PDActionNewFromDest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNewFromDest), [`PDActionNewFromFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionNewFromFileSpec), [`PDLinkAnnotGetAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnotGetAction), [`PDBookmarkGetAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetAction), [`PDDocGetOpenAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOpenAction), [`PDActionDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionDestroy)

### Structures (1)

#### PDActionClipboardData

```cpp
typedef struct _t_PDActionClipboardData* PDActionClipboardData
```

Header: `PDExpT.h:136`

## PDActionHandler

### Functions (1)

#### PDRegisterActionHandler

```cpp
void PDRegisterActionHandler(PDActionHandler handler)
```

Header: `PDProcs.h:8701`

Registers a handler for PDAction operations.

**Parameters**

- `handler` ([`PDActionHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandler)): A pointer to a structure containing the action handler's callbacks. This structure must not be freed after this call, but must be retained.

**Returns:** `void`

### Typedefs (8)

#### PDActionHandlerData

```cpp
typedef void* PDActionHandlerData
```

Header: `PDExpT.h:146`

Used to store PDAction data for copy and paste operations.

**See also:** [`PDActionHandlerCanPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCanPasteProc), [`PDActionHandlerCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCopyProc), [`PDActionHandlerDestroyDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerDestroyDataProc), [`PDActionHandlerPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerPasteProc)

#### PDActionHandlerCanCopyProc

```cpp
typedef ASBool(*) PDActionHandlerCanCopyProc(PDActionHandler pdah, PDAction action)(PDActionHandler pdah, PDAction action)
```

Header: `PDExpT.h:176`

(Optional) A callback for PDActionHandler. It returns `true` if the copy operation is expected to succeed. It tests, for example, whether copying is allowed by document permissions. **Note:** The handler is not expected to test other actions (if any) in the action chain.

**See also:** [`PDActionHandlerCanPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCanPasteProc), [`PDActionHandlerCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCopyProc), [`PDActionHandlerDestroyDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerDestroyDataProc), [`PDActionHandlerPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerPasteProc), [`PDActionCanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCanCopy), [`PDRegisterActionHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterActionHandler)

#### PDActionHandlerCanPasteProc

```cpp
typedef ASBool(*) PDActionHandlerCanPasteProc(PDActionHandler pdah, PDDoc dest, PDActionHandlerData data)(PDActionHandler pdah, PDDoc dest, PDActionHandlerData data)
```

Header: `PDExpT.h:215`

(Optional) A callback for PDActionHandler. It returns `true` if the paste operation is expected to succeed. It tests, for example, whether pasting is allowed by document permissions. **Note:** The handler is not expect to test other actions (if any) in the action chain.

**See also:** [`PDActionHandlerCanCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCanCopyProc), [`PDActionHandlerCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCopyProc), [`PDActionHandlerDestroyDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerDestroyDataProc), [`PDActionHandlerPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerPasteProc), [`PDActionCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCanPaste), [`PDRegisterActionHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterActionHandler)

#### PDActionHandlerCopyProc

```cpp
typedef PDActionHandlerData(*) PDActionHandlerCopyProc(PDActionHandler pdah, PDAction action)(PDActionHandler pdah, PDAction action)
```

Header: `PDExpT.h:195`

(Optional) A callback for PDActionHandler. It copies data from an action object to a new data structure, from which it can be pasted to a new document. The PDActionHandlerData does not store any information related to a Next action. Rebuilding the action chain is the responsibility of the caller and can be ignored by the PDActionHandler.

**See also:** [`PDActionHandlerCanCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCanCopyProc), [`PDActionHandlerCanPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCanPasteProc), [`PDActionHandlerDestroyDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerDestroyDataProc), [`PDActionHandlerPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerPasteProc), [`PDActionCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionCopy), [`PDRegisterActionHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterActionHandler)

#### PDActionHandlerDestroyDataProc

```cpp
typedef void(*) PDActionHandlerDestroyDataProc(PDActionHandler pdah, PDActionHandlerData data)(PDActionHandler pdah, PDActionHandlerData data)
```

Header: `PDExpT.h:251`

A callback for PDActionHandler. It destroys data copied into an action clipboard data structure after it has been successfully pasted to a new document.

**See also:** [`PDActionHandlerCanCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCanCopyProc), [`PDActionHandlerCanPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCanPasteProc), [`PDActionHandlerCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCopyProc), [`PDActionHandlerPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerPasteProc), [`PDActionPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionPaste), [`PDRegisterActionHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterActionHandler)

#### PDActionHandlerDestroyProc

```cpp
typedef void(*) PDActionHandlerDestroyProc(PDActionHandler pdah)(PDActionHandler pdah)
```

Header: `PDExpT.h:261`

(Optional) A callback for PDActionHandler. It destroys the action handler structure when the application no longer requires it. The handler should destroy any dynamic memory stored in the `userData` field.

**See also:** [`PDRegisterActionHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterActionHandler)

#### PDActionHandlerGetTypeProc

```cpp
typedef ASAtom(*) PDActionHandlerGetTypeProc(PDActionHandler pdah)(PDActionHandler pdah)
```

Header: `PDExpT.h:157`

A callback for PDActionHandler. It returns an ASAtom indicating the action type for which the handler is responsible. Types are defined by the client when registering the action handler.

**See also:** [`PDRegisterActionHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterActionHandler)

#### PDActionHandlerPasteProc

```cpp
typedef PDAction(*) PDActionHandlerPasteProc(PDActionHandler pdah, PDDoc dest, PDActionHandlerData data)(PDActionHandler pdah, PDDoc dest, PDActionHandlerData data)
```

Header: `PDExpT.h:235`

(Optional) A callback for PDActionHandler. It creates a new PDAction in the destination document using data that was placed in a PDActionClipboardA data structure using the PDActionCopy() function, and returns the new action object.

**See also:** [`PDActionHandlerCanCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCanCopyProc), [`PDActionHandlerCanPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCanPasteProc), [`PDActionHandlerCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerCopyProc), [`PDActionHandlerDestroyDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionHandlerDestroyDataProc), [`PDActionPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionPaste), [`PDRegisterActionHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterActionHandler)

### Structures (1)

#### PDActionHandler

```cpp
typedef struct _t_PDActionHandler* PDActionHandler
```

Header: `PDExpT.h:135`

## PDAnnot

### Functions (28)

#### PDAnnotCanCopy

```cpp
ASBool PDAnnotCanCopy(PDPage sourcePage, PDAnnot annot)
```

Header: `PDProcs.h:10900`

Tests whether the data from an annotation on a given page can be copied to a clipboard for pasting. This depends on whether there is a PDAnnotHandler with copy and paste support for the annotation, and whether copying is allowed by document permissions.

**Parameters**

- `sourcePage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page containing the annotation to test. It can be `NULL` (as when copying annotations while spawning a hidden template).
- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation to test.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the annotation object can be copied, `false` otherwise.

**See also:** [`PDAnnotCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanPaste), [`PDAnnotCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCopy), [`PDAnnotDestroyClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotDestroyClipboardData), [`PDAnnotPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotPaste)

#### PDAnnotCanPaste

```cpp
ASBool PDAnnotCanPaste(PDPage destPage, const ASFixedPoint *center, PDAnnotClipboardData data)
```

Header: `PDProcs.h:10938`

Tests whether data from an annotation that has been copied to a clipboard can be pasted to a location on a page. Pasting can be disallowed by document permissions, or because the annotation cannot be accurately reproduced in the destination document.

**Parameters**

- `destPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to which the annotation would be pasted.
- `center` (`const ASFixedPoint *`): The location for the center of the annotation on the destination page, or a `NULL` pointer to center the annotation on the destination page.
- `data` ([`PDAnnotClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotClipboardData)): The copied annotation data to test.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the annotation data can be pasted, `false` otherwise.

**See also:** [`PDAnnotCanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanCopy), [`PDAnnotCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCopy), [`PDAnnotDestroyClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotDestroyClipboardData), [`PDAnnotPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotPaste)

#### PDAnnotCopy

```cpp
PDAnnotClipboardData PDAnnotCopy(PDPage sourcePage, PDAnnot annot)
```

Header: `PDProcs.h:10916`

Copies action object data to a clipboard structure, from which it can be pasted.

**Parameters**

- `sourcePage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page containing the annotation to copy. It can be `NULL` (as when copying annotations while spawning a hidden template).
- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation to copy.

**Returns:** [`PDAnnotClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotClipboardData)

The annotation clipboard data object.

**See also:** [`PDAnnotCanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanCopy), [`PDAnnotCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanPaste), [`PDAnnotDestroyClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotDestroyClipboardData), [`PDAnnotPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotPaste)

#### PDAnnotDestroyClipboardData

```cpp
void PDAnnotDestroyClipboardData(PDAnnotClipboardData data)
```

Header: `PDProcs.h:10973`

Destroys data that has been copied from an annotation object into a clipboard. Use this method after successfully pasting the data to a new document.

**Parameters**

- `data` ([`PDAnnotClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotClipboardData)): The clipboard annotation data to destroy.

**Returns:** `void`

**See also:** [`PDAnnotCanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanCopy), [`PDAnnotCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanPaste), [`PDAnnotCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCopy), [`PDAnnotPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotPaste)

#### PDAnnotEqual

```cpp
ASBool PDAnnotEqual(PDAnnot anAnnot, PDAnnot annot2)
```

Header: `PDProcs.h:393`

Tests whether two annotations are identical.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The first annotation to compare.
- `annot2` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The second annotation to compare.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the annotations are equal, `false` otherwise. Two annotations are equal only if their Cos objects are equal (see CosObjEqual()).

**Exceptions**

- `pdErrBadAnnotation`

**See also:** [`CosObjEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEqual)

#### PDAnnotFromCosObj

```cpp
PDAnnot PDAnnotFromCosObj(CosObj obj)
```

Header: `PDProcs.h:566`

Converts a dictionary Cos object to an annotation. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary Cos object whose annotation is obtained.

**Returns:** [`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)

The PDAnnot corresponding to the Cos object.

**Exceptions**

- `pdErrBadAnnotation`: is raised if the annotation is invalid, as determined by PDAnnotIsValid().

**See also:** [`PDAnnotGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetCosObj)

#### PDAnnotGetColor

```cpp
ASBool PDAnnotGetColor(PDAnnot anAnnot, PDColorValue color)
```

Header: `PDProcs.h:423`

Gets a note or link annotation's color. If the annotation does not specify an explicit color, a default color is returned. Text annotations return *default yellow*; all others return black. Only RGB color specifications are currently supported. Annotation Use Closed text note The icon background color. Open, un-selected text note The bounding rectangle color. Open, selected text note The color of the annotation's title bar. Link annotation The link border color.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The note or link annotation whose color is obtained.
- `color` (`PDColorValue`): (Filled by the method) The annotation's color, which is used as follows:

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the annotation specifies an explicit color, `false` if a default color was used.

**See also:** [`PDAnnotSetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetColor), [`PDAnnotGetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetDate), [`PDAnnotGetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetFlags), [`PDAnnotGetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetRect), [`PDAnnotGetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetTitle)

#### PDAnnotGetCosObj

```cpp
CosObj PDAnnotGetCosObj(PDAnnot annot)
```

Header: `PDProcs.h:552`

Gets the Cos object corresponding to an annotation. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The annotation whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The dictionary Cos object for the annotation. The contents of the dictionary can be enumerated using CosObjEnum(). It returns a `NULL` Cos object if the annotation is not valid, as determined by PDAnnotIsValid().

**See also:** [`PDAnnotFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotFromCosObj)

#### PDAnnotGetDate

```cpp
ASBool PDAnnotGetDate(PDAnnot anAnnot, ASTimeRecP date)
```

Header: `PDProcs.h:522`

Gets an annotation's date.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation whose date is obtained.
- `date` (`ASTimeRecP`): (Filled by the method) The annotation's time and date.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the annotation contains a date key and the value of that key can be successfully parsed as a date string, `false` otherwise.

**Exceptions**

- `pdErrBadAnnotation`: is raised if the annotation is not valid or if the value of the annotation's M (ModDate) key is not a string.
- `genErrBadParm`: is raised if `date` is `NULL`.

**See also:** [`PDAnnotSetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetDate), [`PDAnnotGetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetColor), [`PDAnnotGetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetFlags), [`PDAnnotGetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetRect), [`PDAnnotGetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetTitle)

#### PDAnnotGetFlags

```cpp
ASUns32 PDAnnotGetFlags(PDAnnot anAnnot)
```

Header: `PDProcs.h:718`

Gets an annotation's flags.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The annotation whose flags are obtained.

**Returns:** [`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)

The flags, or `0` if the annotation does not have a flags key.

**See also:** [`PDAnnotSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetFlags), [`PDAnnotGetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetColor), [`PDAnnotGetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetDate), [`PDAnnotGetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetRect), [`PDAnnotGetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetTitle)

#### PDAnnotGetOCMD

```cpp
PDOCMD PDAnnotGetOCMD(PDAnnot annot)
```

Header: `PDProcs.h:9352`

Gets an optional-content membership dictionary (OCMD) object associated with the annotation.

**Parameters**

- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation from which the dictionary is obtained.

**Returns:** [`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)

The dictionary object, or `NULL` if the annotation does not contain a dictionary.

**See also:** [`PDAnnotSetOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetOCMD), [`PDAnnotRemoveOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotRemoveOCMD), [`PDEElementGetOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDEElementGetOCMD), [`PDOCMDFindOrCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDFindOrCreate)

#### PDAnnotGetRect

```cpp
void PDAnnotGetRect(PDAnnot anAnnot, ASFixedRect *boxP)
```

Header: `PDProcs.h:361`

Gets the size and location of an annotation on its page.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The annotation whose location and size are set.
- `boxP` (`ASFixedRect *`): IN/OUT (Filled by the method) A pointer to a rectangle that specifies the annotation's bounding rectangle, specified in user space coordinates.

**Returns:** `void`

**Exceptions**

- `pdErrBadAnnotation`

**See also:** [`PDAnnotSetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetRect), [`PDAnnotGetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetColor), [`PDAnnotGetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetDate), [`PDAnnotGetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetFlags), [`PDAnnotGetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetTitle)

#### PDAnnotGetSubtype

```cpp
ASAtom PDAnnotGetSubtype(PDAnnot anAnnot)
```

Header: `PDProcs.h:343`

Gets an annotation's subtype.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation whose subtype is obtained.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

The ASAtom for the annotation's subtype. This can be converted to a string using ASAtomGetString(). The storage pointed to by the return value is owned by the Acrobat viewer and should be assumed to be valid only until the next call into any client API method; it should be immediately copied by the client if the client wants to reference it later.

**Exceptions**

- `pdErrBadAnnotation`

#### PDAnnotGetTitle

```cpp
ASInt32 PDAnnotGetTitle(PDAnnot anAnnot, char *buffer, ASInt32 bufSize)
```

Header: `PDProcs.h:479`

Gets an annotation's label text. @since

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The annotation whose label is obtained.
- `buffer` (`char *`): IN/OUT (Filled by the method) The string into which
  the annotation's label string is copied. If the string is non-`NULL`,
  up to `bufsSize` bytes are copied into the buffer.`bufSize` bytes
  of the annotation label string are copied into the string
  and an ASCII `NULL` character is appended. The caller is expected
  to have allocated `bufSize + 1` bytes to allow for the `NULL`.
  If `buffer` is `NULL`, it copies nothing.`NULL`, it returns the number of bytes copied, not
  counting the trailing `NULL`. If the string is `NULL`, it returns the
  number of bytes that would be copied if the string were not `NULL`.

  **Note:** This text is stored in either PDFDocEncoding or in Unicode. If it is stored in Unicode, a valid Byte Order Mark must be present.
- `bufSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

**Exceptions**

- `pdErrBadAnnotation`

**See also:** [`PDAnnotSetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetTitle), [`PDAnnotGetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetColor), [`PDAnnotGetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetDate), [`PDAnnotGetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetRect), [`PDAnnotGetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetFlags)

#### PDAnnotGetTitleASText

```cpp
void PDAnnotGetTitleASText(PDAnnot anAnnot, ASText title)
```

Header: `PDProcs.h:11445`

Gets an annotation's label text as an ASText object.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation whose label is obtained.
- `title` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The text object containing the annotation's label string. The client must pass a valid ASText object title. The routine does not allocate it.

**Returns:** `void`

**Exceptions**

- `pdErrBadAnnotation`

**See also:** [`PDAnnotGetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetTitle), [`PDAnnotSetTitleASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetTitleASText), [`PDAnnotSetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetTitle), [`PDAnnotGetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetColor), [`PDAnnotGetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetDate), [`PDAnnotGetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetRect), [`PDAnnotGetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetFlags)

#### PDAnnotIsCurrentlyVisible

```cpp
ASBool PDAnnotIsCurrentlyVisible(PDAnnot annot, PDOCContext ocContext)
```

Header: `PDProcs.h:9418`

Tests whether an annotation with an OC entry is visible in a given optional-content context, considering the current `ON-OFF` states of the optional-content groups in the optional-content dictionary (OCMD) and the dictionary's visibility policy.

**Parameters**

- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation to test.
- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The optional-content context in which the visibility is tested.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the annotation is visible in the given context or if the annotation has no OC entry, `false` if it is hidden.

**See also:** [`PDAnnotGetOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetOCMD)

#### PDAnnotIsValid

```cpp
ASBool PDAnnotIsValid(PDAnnot anAnnot)
```

Header: `PDProcs.h:326`

Tests whether an annotation is valid. This is intended only to ensure that the annotation has not been deleted, not to ensure that all necessary information is present and valid.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation whose validity is tested.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if `anAnnot` is a valid annotation object, `false` otherwise. An annotation is valid if it is a Cos dictionary object and has a Rect key.

**See also:** [`PDAnnotEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotEqual)

#### PDAnnotNotifyDidChange

```cpp
void PDAnnotNotifyDidChange(PDAnnot annot, ASAtom key, ASInt32 err)
```

Header: `PDProcs.h:274`

Broadcasts a PDAnnotDidChange() notification. Clients must call this method after making any change to a custom annotation.

**Parameters**

- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation that has changed.
- `key` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom corresponding to the name of the key in the annotation's Cos dictionary that is changing.
- `err` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): An error code to pass to any method registered to receive the PDAnnotDidChange() notification. Pass zero if the annotation was changed successfully. Pass a nonzero value if an error occurred while changing the annotation. @notify PDAnnotDidChange

**Returns:** `void`

**See also:** [`PDAnnotNotifyWillChange`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotNotifyWillChange), `AVAppRegisterNotification`

#### PDAnnotNotifyWillChange

```cpp
void PDAnnotNotifyWillChange(PDAnnot annot, ASAtom key)
```

Header: `PDProcs.h:255`

Broadcasts a PDAnnotWillChange() notification. Clients must call this method before making any change to a custom annotation.

**Parameters**

- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation that has changed.
- `key` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom corresponding to the name of the key in the annotation's Cos dictionary that is changing. @notify PDAnnotWillChange

**Returns:** `void`

**See also:** [`PDAnnotNotifyDidChange`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotNotifyDidChange), `AVAppRegisterNotification`

#### PDAnnotPaste

```cpp
PDAnnot PDAnnotPaste(PDPage destPage, const ASFixedPoint *center, PDAnnotClipboardData data)
```

Header: `PDProcs.h:10960`

Pastes copied annotation data from a clipboard structure to a new annotation object in a specified document. After successfully pasting the data, use PDAnnotDestroyClipboardData() to free the associated memory.

**Parameters**

- `destPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to which the annotation is pasted.
- `center` (`const ASFixedPoint *`): The location for the center of the annotation on the destination page, or a `NULL` pointer to center the annotation on the destination page.
- `data` ([`PDAnnotClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotClipboardData)): The copied annotation data to paste.

**Returns:** [`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)

A newly created annotation object associated with the specified document, containing the same data as the copied annotation.

**See also:** [`PDAnnotCanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanCopy), [`PDAnnotCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanPaste), [`PDAnnotCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCopy), [`PDAnnotDestroyClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotDestroyClipboardData)

#### PDAnnotRemoveOCMD

```cpp
void PDAnnotRemoveOCMD(PDAnnot annot)
```

Header: `PDProcs.h:9363`

Dissociates any optional-content membership dictionary (OCMD) object from the annotation.

**Parameters**

- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation for which to remove the dictionary.

**Returns:** `void`

**See also:** [`PDAnnotGetOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetOCMD), [`PDAnnotSetOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetOCMD), [`PDOCMDFindOrCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDFindOrCreate)

#### PDAnnotSetColor

```cpp
void PDAnnotSetColor(PDAnnot anAnnot, const PDColorValue color)
```

Header: `PDProcs.h:449`

Sets a note or link annotation's color. Only RGB color specifications are currently supported. Annotation Use Closed text note The icon background color. Open, un-selected text note The bounding rectangle color. Open, selected text note The color of the annotation's title bar. Link annotation The link border color. @notify PDAnnotWillChange @notify PDAnnotDidChange

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The note or link annotation whose color is set.
- `color` (`const PDColorValue`): IN/OUT The annotation's color, which is used as follows:

**Returns:** `void`

**See also:** [`PDAnnotGetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetColor), [`PDAnnotSetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetDate), [`PDAnnotSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetFlags), [`PDAnnotSetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetRect), [`PDAnnotSetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetTitle)

#### PDAnnotSetDate

```cpp
void PDAnnotSetDate(PDAnnot anAnnot, const ASTimeRecP date)
```

Header: `PDProcs.h:537`

Sets an annotation's date.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The annotation whose date is set.
- `date` (`const ASTimeRecP`): IN/OUT The annotation's time and date. @notify PDAnnotWillChange @notify PDAnnotDidChange

**Returns:** `void`

**See also:** [`PDAnnotGetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetDate), [`PDAnnotSetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetColor), [`PDAnnotSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetFlags), [`PDAnnotSetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetRect), [`PDAnnotSetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetTitle)

#### PDAnnotSetFlags

```cpp
void PDAnnotSetFlags(PDAnnot anAnnot, ASUns32 flags)
```

Header: `PDProcs.h:733`

Sets an annotation's flags.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The annotation whose flags are set.
- `flags` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): IN/OUT An `OR` of the PDAnnot Flags values. @notify PDAnnotWillChange @notify PDAnnotDidChange

**Returns:** `void`

**See also:** [`PDAnnotGetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetFlags), [`PDAnnotSetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetColor), [`PDAnnotSetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetDate), [`PDAnnotSetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetRect), [`PDAnnotSetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetTitle)

#### PDAnnotSetOCMD

```cpp
void PDAnnotSetOCMD(PDAnnot annot, PDOCMD pdocmd)
```

Header: `PDProcs.h:9337`

Associates an optional-content membership dictionary (OCMD) object with the annotation, making it optionally visible according to the OCMD's visibility policy. If the annotation already has a dictionary, the method replaces it.

**Parameters**

- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation for which to set the dictionary.
- `pdocmd` ([`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)): The new dictionary.

**Returns:** `void`

**See also:** [`PDAnnotGetOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetOCMD), [`PDOCMDFindOrCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDFindOrCreate), [`PDAnnotRemoveOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotRemoveOCMD)

#### PDAnnotSetRect

```cpp
void PDAnnotSetRect(PDAnnot anAnnot, const ASFixedRect *newBox)
```

Header: `PDProcs.h:380`

Sets the size and location of an annotation on its page.

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The annotation whose location and size are set.
- `newBox` (`const ASFixedRect *`): IN/OUT A pointer to a rectangle that specifies the annotation's bounding rectangle, specified in user space coordinates. @notify PDAnnotWillChange @notify PDAnnotDidChange

**Returns:** `void`

**See also:** [`PDAnnotGetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetRect), [`PDAnnotSetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetColor), [`PDAnnotSetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetDate), [`PDAnnotSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetFlags), [`PDAnnotSetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetTitle)

#### PDAnnotSetTitle

```cpp
void PDAnnotSetTitle(PDAnnot anAnnot, const char *str, ASInt32 nBytes)
```

Header: `PDProcs.h:501`

Sets an annotation's label text. @notify PDAnnotWillChange @notify PDAnnotDidChange **Note:** This text is stored in either PDFDocEncoding or in Unicode. If it is stored in Unicode, a valid Byte Order Mark must be present. @since

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The annotation whose label is set.
- `str` (`const char *`): IN/OUT The string containing the label to set.
- `nBytes` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The length of the label. The first `nBytes` bytes of
  `str` are used as the label.

**Returns:** `void`

**See also:** [`PDAnnotGetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetTitle), [`PDAnnotSetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetColor), [`PDAnnotSetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetDate), [`PDAnnotSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetFlags), [`PDAnnotSetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetRect)

#### PDAnnotSetTitleASText

```cpp
void PDAnnotSetTitleASText(PDAnnot anAnnot, const ASText title)
```

Header: `PDProcs.h:11464`

Sets an annotation's label text. @notify PDAnnotWillChange @notify PDAnnotDidChange

**Parameters**

- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation whose label is set.
- `title` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the label to set.

**Returns:** `void`

**See also:** [`PDAnnotSetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetTitle), [`PDAnnotGetTitleASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetTitleASText), [`PDAnnotGetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetTitle), [`PDAnnotSetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetColor), [`PDAnnotSetDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetDate), [`PDAnnotSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetFlags), [`PDAnnotSetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotSetRect)

### Typedefs (3)

#### PDAnnot

```cpp
typedef OPAQUE_64_BITS PDAnnot
```

Header: `PDExpT.h:323`

An annotation on a page in a PDF file. Acrobat viewers have two built-in annotation types: PDTextAnnot and PDLinkAnnot. Physical attributes of the annotation can be set and queried. Plug-ins add movie and Widget (form field) annotations. Developers can define new annotation subtypes by creating new annotation handlers.

**See also:** `AVPageViewIsAnnotAtPoint`, [`PDAnnotFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotFromCosObj), [`PDPageAddNewAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddNewAnnot), [`PDPageCreateAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageCreateAnnot), [`PDPageGetAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetAnnot), [`PDPageRemoveAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveAnnot)

#### PDAnnotPrintOp

```cpp
typedef ASEnum16 PDAnnotPrintOp
```

Header: `PDExpT.h:564`

#### PDAnnotWillPrintProc

```cpp
typedef ASBool(*) PDAnnotWillPrintProc(PDAnnotHandler pdanh, PDAnnot annot)(PDAnnotHandler pdanh, PDAnnot annot)
```

Header: `PDExpT.h:661`

A callback for PDAnnotHandler. This method is called to determine whether an annotation is printed.

**See also:** [`PDDocWillExportAnnotProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocWillExportAnnotProc), [`PDDocWillImportAnnotProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocWillImportAnnotProc), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

### Structures (1)

#### PDAnnotClipboardData

```cpp
typedef struct _t_PDAnnotClipboardData* PDAnnotClipboardData
```

Header: `PDExpT.h:545`

Used to store PDAnnot data for copy and paste operations.

**See also:** [`PDAnnotCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanPaste), [`PDAnnotCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCopy), [`PDAnnotDestroyClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotDestroyClipboardData), [`PDAnnotPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotPaste)

### Enums (1)

#### PDAnnotPrintOps

Header: `PDExpT.h:556`

PDAnnotPrintOp is passed to the PDAnnotHandlerGetPrintAppearanceProc() callback to specify the type of print operation being performed.

**Values**

- `kPDAnnotPrintStandard = 1`: A standard print operation.
- `kPDAnnotPrintVariableData = 2`: The user selected Form Fields Only.

**See also:** [`PDAnnotHandlerGetPrintAppearanceProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerGetPrintAppearanceProc)

### Definitions (20)

#### CastToPDAnnot

Header: `PDExpT.h:431`

Value: `*(PDAnnot *)&(a)`

Casts a link annotation or a text annotation to a generic annotation.

**See also:** [`CastToPDLinkAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#CastToPDLinkAnnot), [`CastToPDTextAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#CastToPDTextAnnot)

#### PDAnnotIgnorePerms

Header: `PDExpT.h:469`

Value: `0x0008`

Allows modifying this annotation type in a write-protected document.

#### PDAnnotInfoInit

Header: `PDExpT.h:517`

Value: `do { \&#10; ASmemset(x, 0, sizeof(PDAnnotInfoRec)); \&#10; x->size = sizeof(PDAnnotInfoRec); \&#10; x->fxLayer = fixedTwo; \&#10;} while (0)`

#### PDAnnotMaxDashes

Header: `PDExpT.h:1026`

Value: `10`

#### PDAnnotOperationAll

Header: `PDExpT.h:479`

Value: `0xFFFF`

All operations are allowed.

#### PDAnnotOperationFilter

Header: `PDExpT.h:459`

Value: `0x0002`

It is okay to filter annotations.

#### PDAnnotOperationFlatten

Header: `PDExpT.h:474`

Value: `0x0010`

When creating a flattened page include this annot

#### PDAnnotOperationManager

Header: `PDExpT.h:464`

Value: `0x0004`

It is okay to manage annotations.

#### PDAnnotOperationSummarize

Header: `PDExpT.h:454`

Value: `0x0001`

It is okay to summarize annotations.

#### pdAnnotHidden

Header: `PDExpT.h:376`

Value: `0x02`

The annotation is not visible and does not print.

#### pdAnnotInvisible

Header: `PDExpT.h:371`

Value: `0x01`

If there is no annotation handler, the annotation is invisible.

#### pdAnnotLock

Header: `PDExpT.h:407`

Value: `0x80`

The annotation does not move or resize with the view. Currently only form fields respect this flag. If the annotation is locked, the user cannot delete, move or change its associated form field's properties.

#### pdAnnotLockContents

Header: `PDExpT.h:417`

Value: `0x200`

If the annotation is content-locked, the user can not change its content key.

#### pdAnnotNoRotate

Header: `PDExpT.h:391`

Value: `0x10`

The annotation does not rotate with the page.

#### pdAnnotNoView

Header: `PDExpT.h:396`

Value: `0x20`

The annotation does not view but can print.

#### pdAnnotNoZoom

Header: `PDExpT.h:386`

Value: `0x08`

The annotation does not zoom with the view.

#### pdAnnotPrint

Header: `PDExpT.h:381`

Value: `0x04`

The annotation prints.

#### pdAnnotReadOnly

Header: `PDExpT.h:401`

Value: `0x40`

The annotation does not interact with the user.

#### pdAnnotSequenceAdjust

Header: `PDExpT.h:422`

Value: `0x80000000`

A place holder used only at runtime. Do not set this bit in PDF/FDF files.

#### pdAnnotToggleNoView

Header: `PDExpT.h:412`

Value: `0x100`

A mouse-over or selection causes the `noView` bit to toggle.

## PDAnnotHandler

### Functions (2)

#### PDGetAnnotHandlerByName

```cpp
PDAnnotHandler PDGetAnnotHandlerByName(ASAtom name)
```

Header: `PDProcs.h:6905`

Gets the annotation handler that handles the specified annotation type.

**Parameters**

- `name` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): IN/OUT The name of the requested annotation handler. The character string for the name can be converted to an ASAtom using ASAtomFromString().

**Returns:** [`PDAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandler)

The annotation handler that services annotations of type `name`. It returns the default annotation handler if no handler services the specified annotation type.

**See also:** [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler), `AVAppRegisterAnnotHandler`

#### PDRegisterAnnotHandler

```cpp
void PDRegisterAnnotHandler(PDAnnotHandler handler)
```

Header: `PDProcs.h:6889`

Registers a handler for an annotation subtype, replacing any previous handler that had been registered for that subtype. The annotation handler is not registered if its PDAnnotHandlerGetTypeProc() returns `NULL`. To effectively use a PDAnnotHandler, the AVAnnotHandler associated with this annotation must have its AVAnnotHandlerGetInfoProc() and AVAnnotHandlerDeleteInfoProc() callbacks defined. PDF Library applications can use this method to register their annotation handlers. Link and Watermark annotations have default handlers. For other annotation types, the applications should register their own handlers.

**Parameters**

- `handler` ([`PDAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandler)): IN/OUT A pointer to a structure containing the annotation handler's callbacks. This structure must not be freed after this call, but must be retained.

**Returns:** `void`

**See also:** [`PDGetAnnotHandlerByName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetAnnotHandlerByName), `AVAppGetAnnotHandlerByName`

### Typedefs (13)

#### PDAnnotHandlerClipboardData

```cpp
typedef void* PDAnnotHandlerClipboardData
```

Header: `PDExpT.h:548`

Opaque data used by PDAnnotHandlers.

#### PDAnnotHandlerCanCopyProc

```cpp
typedef ASBool(*) PDAnnotHandlerCanCopyProc(PDAnnotHandler pdanh, PDPage sourcePage, PDAnnot pdan)(PDAnnotHandler pdanh, PDPage sourcePage, PDAnnot pdan)
```

Header: `PDExpT.h:701`

(Optional) A callback for PDAnnotHandler. It returns `true` if the copy operation is expected to succeed. It tests, for example, whether copying is allowed by document permissions.

**See also:** [`PDAnnotHandlerCanPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCanPasteProc), [`PDAnnotHandlerCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCopyProc), [`PDAnnotHandlerPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerPasteProc), [`PDAnnotHandlerDestroyDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerDestroyDataProc), [`PDAnnotCanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanCopy), `PDRegisterAnnotHandlerCanCopy`

#### PDAnnotHandlerCanPasteProc

```cpp
typedef ASBool(*) PDAnnotHandlerCanPasteProc(PDAnnotHandler pdanh, PDPage destPage, const ASFixedPoint *center, PDAnnotHandlerClipboardData data)(PDAnnotHandler pdanh, PDPage destPage, const ASFixedPoint *center, PDAnnotHandlerClipboardData data)
```

Header: `PDExpT.h:750`

(Optional) A callback for PDAnnotHandler. It returns `true` if the paste operation is expected to succeed. It tests whether data from an annotation that has been copied to a clipboard can be pasted to a location on a page. Pasting can be disallowed by document permissions, or because the annotation cannot be accurately reproduced in the destination document.

**See also:** [`PDAnnotHandlerCanCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCanCopyProc), [`PDAnnotHandlerCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCopyProc), [`PDAnnotHandlerPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerPasteProc), [`PDAnnotHandlerDestroyDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerDestroyDataProc), [`PDAnnotCanPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCanPaste), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDAnnotHandlerCopyProc

```cpp
typedef PDAnnotHandlerClipboardData(*) PDAnnotHandlerCopyProc(PDAnnotHandler pdanh, PDPage sourcePage, PDAnnot pdan)(PDAnnotHandler pdanh, PDPage sourcePage, PDAnnot pdan)
```

Header: `PDExpT.h:722`

(Optional) A callback for PDAnnotHandler. It copies data from the annotation object to a new clipboard structure, and returns the clipboard structure.

**See also:** [`PDAnnotHandlerCanCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCanCopyProc), [`PDAnnotHandlerCanPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCanPasteProc), [`PDAnnotHandlerCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCopyProc), [`PDAnnotHandlerDestroyDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerDestroyDataProc), [`PDAnnotHandlerPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerPasteProc), [`PDAnnotCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCopy), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDAnnotHandlerDeleteAnnotInfoProc

```cpp
typedef void(*) PDAnnotHandlerDeleteAnnotInfoProc(PDAnnotHandler pdanh, PDAnnotInfo info)(PDAnnotHandler pdanh, PDAnnotInfo info)
```

Header: `PDExpT.h:597`

(Optional) A callback for PDAnnotHandler. It deletes information associated with an annotation. It frees all the memory associated with the annotation information.

**See also:** `AVAnnotHandlerDeleteInfoProc`, [`PDAnnotHandlerGetAnnotInfoProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerGetAnnotInfoProc), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDAnnotHandlerDestroyDataProc

```cpp
typedef void(*) PDAnnotHandlerDestroyDataProc(PDAnnotHandler pdanh, PDAnnotHandlerClipboardData data)(PDAnnotHandler pdanh, PDAnnotHandlerClipboardData data)
```

Header: `PDExpT.h:794`

(Optional) A callback for PDAnnotHandler. It destroys data from an annotation that has been copied to a clipboard. This callback may be executed regardless of how many times (if any) the annotation was pasted.

**See also:** [`PDAnnotHandlerCanCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCanCopyProc), [`PDAnnotHandlerCanPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCanPasteProc), [`PDAnnotHandlerCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCopyProc), [`PDAnnotHandlerPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerPasteProc), [`PDAnnotDestroyClipboardData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotDestroyClipboardData), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDAnnotHandlerDestroyProc

```cpp
typedef void(*) PDAnnotHandlerDestroyProc(PDAnnotHandler pdanh)(PDAnnotHandler pdanh)
```

Header: `PDExpT.h:805`

(Optional) A callback for PDAnnotHandler. It destroys the annotation handler structure when the application no longer requires it. The handler should destroy any dynamic memory stored in the `userData` field.

**See also:** [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDAnnotHandlerGetAnnotInfoFlagsProc

```cpp
typedef ASFlagBits(*) PDAnnotHandlerGetAnnotInfoFlagsProc(PDAnnotHandler pdanh, PDAnnot pdan)(PDAnnotHandler pdanh, PDAnnot pdan)
```

Header: `PDExpT.h:685`

A callback for PDAnnotHandler. It gets the annotation handler information flags, which indicate the operations allowed with annotations of this type. The value is an OR of the following flags: Operation Description `PDAnnotOperationSummarize` It is okay to summarize annotations. `PDAnnotOperationFilter` It is okay to filter annotations. `PDAnnotOperationManager` It is okay to manage annotations. `PDAnnotIgnorePerms` Allow modifying this annotation type in a write-protected document. `PDAnnotOperationAll` All operations are allowed.

**See also:** [`PDAnnotHandlerGetAnnotInfoProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerGetAnnotInfoProc), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDAnnotHandlerGetAnnotInfoProc

```cpp
typedef PDAnnotInfo(*) PDAnnotHandlerGetAnnotInfoProc(PDAnnotHandler pdanh, PDAnnot pdan, PDPage pdpage)(PDAnnotHandler pdanh, PDAnnot pdan, PDPage pdpage)
```

Header: `PDExpT.h:582`

A callback for PDAnnotHandler. It gets the annotation information for an annotation.

**See also:** `AVAnnotHandlerGetInfoProc`, [`PDAnnotHandlerDeleteAnnotInfoProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerDeleteAnnotInfoProc), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDAnnotHandlerGetHeelPointProc

```cpp
typedef void(*) PDAnnotHandlerGetHeelPointProc(PDAnnotHandler pdanh, PDAnnot pdan, ASFixedPoint *point)(PDAnnotHandler pdanh, PDAnnot pdan, ASFixedPoint *point)
```

Header: `PDExpT.h:818`

A callback for PDAnnotHandler. It gets the heel point (the focus or starting point) for the annotation. For a rectangular annotation, this is usually the top left corner.

**See also:** [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDAnnotHandlerGetPrintAppearanceProc

```cpp
typedef CosObj(*) PDAnnotHandlerGetPrintAppearanceProc(PDAnnotHandler pdanh, PDAnnot pdan, ASFixedRect *frAnnot, PDAnnotPrintOp op)(PDAnnotHandler pdanh, PDAnnot pdan, ASFixedRect *frAnnot, PDAnnotPrintOp op)
```

Header: `PDExpT.h:840`

A callback for PDAnnotHandler. It is called by the host application to obtain a print appearance (a Form XObject). If this callback is not implemented, the default appearance (if any) is used.

**See also:** [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDAnnotHandlerGetTypeProc

```cpp
typedef ASAtom(*) PDAnnotHandlerGetTypeProc(PDAnnotHandler pdanh)(PDAnnotHandler pdanh)
```

Header: `PDExpT.h:611`

A callback for PDAnnotHandler. It gets an ASAtom indicating the annotation type for which the handler is responsible. This corresponds to the annotation's Subtype key in the PDF file.

**See also:** [`PDAnnotHandlerGetAnnotInfoProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerGetAnnotInfoProc), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDAnnotHandlerPasteProc

```cpp
typedef PDAnnot(*) PDAnnotHandlerPasteProc(PDAnnotHandler pdanh, PDPage destPage, const ASFixedPoint *center, PDAnnotHandlerClipboardData data)(PDAnnotHandler pdanh, PDPage destPage, const ASFixedPoint *center, PDAnnotHandlerClipboardData data)
```

Header: `PDExpT.h:775`

(Optional) A callback for PDAnnotHandler. It creates a new annotation on the specified page using clipboard data generated by PDAnnotCopy().

**See also:** [`PDAnnotHandlerCanCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCanCopyProc), [`PDAnnotHandlerCanPasteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCanPasteProc), [`PDAnnotHandlerCopyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerCopyProc), [`PDAnnotHandlerDestroyDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerDestroyDataProc), [`PDAnnotCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotCopy), [`PDAnnotPaste`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotPaste), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

### Structures (1)

#### PDAnnotHandler

```cpp
typedef struct _t_PDAnnotHandler* PDAnnotHandler
```

Header: `PDExpT.h:535`

A data structure containing callbacks that implement an annotation manager. The callbacks implement the annotation manager functions (for example, view, delete, or export the annotations of a document as a list, sorted by type, author, or date). To fully use a PDAnnotHandler, the AVAnnotHandler associated with this annotation must have its AVAnnotHandlerGetInfoProc() and AVAnnotHandlerDeleteInfoProc() callbacks defined.

**See also:** [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

## PDBead

### Functions (15)

#### PDBeadAcquirePage

```cpp
PDPage PDBeadAcquirePage(PDBead bead, PDDoc pdDoc)
```

Header: `PDProcs.h:4263`

Acquires the page on which a bead is located.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead whose page is acquired.
- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document in which bead is located.

**Returns:** [`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)

The page on which the bead resides. The acquired page must be freed using PDPageRelease() when it is no longer needed.

**See also:** [`PDPageRelease`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRelease)

#### PDBeadDestroy

```cpp
void PDBeadDestroy(PDBead bead)
```

Header: `PDProcs.h:4208`

Destroys a bead.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead to destroy.

**Returns:** `void`

**Exceptions**

- `pdErrBadBead`

**See also:** [`PDBeadNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadNew), [`PDBeadFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadFromCosObj)

#### PDBeadEqual

```cpp
ASBool PDBeadEqual(PDBead bead, PDBead bead2)
```

Header: `PDProcs.h:4348`

Tests two beads for equality. This method is useful to detect the end of a thread since the last bead in a thread points to the first.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): The first bead to compare.
- `bead2` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): The second bead to compare.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the two beads are identical, `false` otherwise. Two beads are equal only if their Cos objects are equal (see CosObjEqual()).

**See also:** [`CosObjEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEqual)

#### PDBeadFromCosObj

```cpp
PDBead PDBeadFromCosObj(CosObj obj)
```

Header: `PDProcs.h:4375`

Gets the PDBead corresponding to a Cos object, after checking the bead's validity. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary Cos object whose bead is obtained.

**Returns:** [`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)

The PDBead object for the bead.

**Exceptions**

- `pdErrBadBead`: is raised if the bead is not valid, as determined by PDBeadIsValid().

**See also:** [`PDBeadGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetCosObj)

#### PDBeadGetCosObj

```cpp
CosObj PDBeadGetCosObj(PDBead bead)
```

Header: `PDProcs.h:4362`

Gets the Cos object corresponding to a bead. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The dictionary Cos object for the bead. The contents of the dictionary can be enumerated using CosObjEnum(). It returns a `NULL` Cos object if `PDBeadIsValid(bead)` returns `false`.

**See also:** [`PDBeadFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadFromCosObj)

#### PDBeadGetIndex

```cpp
ASInt32 PDBeadGetIndex(PDBead bead)
```

Header: `PDProcs.h:4334`

Gets the index of a bead in its thread.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead whose index is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The index of the bead in its thread. The first bead in a thread has an index of zero.

#### PDBeadGetNext

```cpp
PDBead PDBeadGetNext(PDBead bead)
```

Header: `PDProcs.h:4223`

Gets the next bead in a thread.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead for which the next bead is obtained.

**Returns:** [`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)

The next bead, or a `NULL` Cos object (cast to a PDBead using PDBeadFromCosObj()). On the last bead, PDBeadGetNext() returns the first bead.

**See also:** [`PDBeadGetPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetPrev), [`PDThreadGetFirstBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadGetFirstBead), [`PDBeadEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadEqual)

#### PDBeadGetPrev

```cpp
PDBead PDBeadGetPrev(PDBead bead)
```

Header: `PDProcs.h:4238`

Gets the previous bead in a thread.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead for which the previous bead is obtained.

**Returns:** [`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)

The previous bead, or a `NULL` Cos object (cast to a PDBead using PDBeadFromCosObj()) if this is the first bead in the thread.

**See also:** [`PDBeadGetNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetNext), [`PDThreadGetFirstBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadGetFirstBead), [`PDBeadEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadEqual)

#### PDBeadGetRect

```cpp
void PDBeadGetRect(PDBead bead, ASFixedRectP rectP)
```

Header: `PDProcs.h:4286`

Gets a bead's bounding rectangle.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead whose bounding rectangle is obtained.
- `rectP` (`ASFixedRectP`): IN/OUT (Filled by the method) A pointer to a `ASFixedRect` specifying the bead's bounding rectangle, specified in user space coordinates.

**Returns:** `void`

#### PDBeadGetThread

```cpp
PDThread PDBeadGetThread(PDBead bead)
```

Header: `PDProcs.h:4324`

Gets the thread containing the specified bead.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead whose thread is obtained.

**Returns:** [`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)

The bead's thread, or a `NULL` Cos object if the bead does not belong to a thread.

**See also:** [`PDBeadGetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetRect), [`PDBeadGetIndex`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetIndex), [`PDBeadGetNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetNext), [`PDBeadGetPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetPrev)

#### PDBeadInsert

```cpp
void PDBeadInsert(PDBead bead, PDBead newNext)
```

Header: `PDProcs.h:4250`

Inserts a bead after the specified bead.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead after which newNext will be inserted.
- `newNext` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead to insert.

**Returns:** `void`

**See also:** [`PDBeadNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadNew), [`PDThreadSetFirstBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadSetFirstBead)

#### PDBeadIsValid

```cpp
ASBool PDBeadIsValid(PDBead bead)
```

Header: `PDProcs.h:4310`

Tests a bead's validity. This is intended only to ensure that the bead has not been deleted, not to ensure that all necessary information is present and valid.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): The bead whose validity is tested.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the bead is valid, `false` otherwise.

**See also:** [`PDBeadEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadEqual)

#### PDBeadNew

```cpp
PDBead PDBeadNew(PDPage page, const ASFixedRectP destRect)
```

Header: `PDProcs.h:4197`

Creates a new bead on the specified page. The newly created bead is not linked to a thread or another bead. Use PDThreadSetFirstBead() to make the bead the first bead in a thread. Use PDBeadInsert() to link it to another bead.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page on which the bead is created.
- `destRect` (`const ASFixedRectP`): A pointer to a `ASFixedRect` specifying the bead's bounding rectangle, specified in user space coordinates.

**Returns:** [`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)

The newly created bead.

**See also:** [`PDThreadSetFirstBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadSetFirstBead), [`PDBeadInsert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadInsert), [`PDBeadFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadFromCosObj), [`PDBeadDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadDestroy)

#### PDBeadSetPage

```cpp
void PDBeadSetPage(PDBead bead, PDPage newPage)
```

Header: `PDProcs.h:4274`

Sets the page for a bead.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead whose page is set.
- `newPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page on which bead is located.

**Returns:** `void`

**Exceptions**

- `pdErrBadBead`

**See also:** [`PDBeadSetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadSetRect)

#### PDBeadSetRect

```cpp
void PDBeadSetRect(PDBead bead, const ASFixedRectP newDestRect)
```

Header: `PDProcs.h:4299`

Sets a bead's bounding rectangle.

**Parameters**

- `bead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead whose bounding rectangle is set.
- `newDestRect` (`const ASFixedRectP`): IN/OUT A pointer to a `ASFixedRect` specifying the bead's bounding rectangle, specified in user space coordinates.

**Returns:** `void`

**See also:** [`PDBeadGetRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetRect), [`PDBeadSetPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadSetPage)

### Typedefs (1)

#### PDBead

```cpp
typedef OPAQUE_64_BITS PDBead
```

Header: `PDExpT.h:3244`

A single rectangle in an article thread. (Article threads are known simply as articles in the Acrobat viewer's user interface). A bead remains valid as long as a thread is *current* and *active*.

**See also:** `AVPageViewGetActiveBead`, `AVPageViewIsBeadAtPoint`, [`PDBeadNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadNew), [`PDBeadGetNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetNext), [`PDBeadGetPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetPrev), [`PDThreadGetFirstBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadGetFirstBead), [`PDBeadDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadDestroy)

## PDBookmark

### Functions (38)

#### PDBookmarkAddChild

```cpp
void PDBookmarkAddChild(PDBookmark parent, PDBookmark aBookmark)
```

Header: `PDProcs.h:905`

Adds `aBookmark` as the last child of `parent`, adjusting the tree containing `parent` appropriately. If `parent` previously had no children, it is open after the child is added.

**Parameters**

- `parent` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The parent of the bookmark being added.
- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark that will become the last child of `aBookmark`. `aBookmark` must have been previously unlinked. @notify PDBookmarkDidChangePosition

**Returns:** `void`

**See also:** [`PDBookmarkAddNewSibling`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSibling), [`PDBookmarkAddNewChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChild), [`PDBookmarkAddSubtree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddSubtree), [`PDBookmarkAddPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddPrev), [`PDBookmarkAddNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNext), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkAddNewChild

```cpp
PDBookmark PDBookmarkAddNewChild(PDBookmark aBookmark, const char *initialText)
```

Header: `PDProcs.h:773`

Adds a new bookmark to the tree containing `aBookmark`, as the new last child of `aBookmark`. If `aBookmark` previously had no children, it will be open after the child is added.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark to which a new last child is added.
- `initialText` (`const char *`): The new bookmark's title.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

The newly created bookmark. @notify PDBookmarkDidChangePosition @notify PDBookmarkWasCreated

**See also:** [`PDBookmarkAddNewSibling`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSibling), [`PDBookmarkAddSubtree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddSubtree), [`PDBookmarkAddPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddPrev), [`PDBookmarkAddNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNext), [`PDBookmarkAddChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddChild), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkAddNewChildASText

```cpp
PDBookmark PDBookmarkAddNewChildASText(PDBookmark aBookmark, const ASText initialText)
```

Header: `PDProcs.h:11616`

Adds a new bookmark to the tree containing `aBookmark`, as the new last child of aBookmark. If `aBookmark` previously had no children, it will be open after the child is added. @notify PDBookmarkDidChangePosition @notify PDBookmarkWasCreated

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark to which a new last child is added.
- `initialText` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the new bookmark's title.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

The newly created bookmark.

**See also:** [`PDBookmarkAddNewChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChild), [`PDBookmarkAddNewSiblingASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSiblingASText), [`PDBookmarkAddNewSibling`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSibling), [`PDBookmarkAddSubtreeASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddSubtreeASText), [`PDBookmarkAddSubtree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddSubtree), [`PDBookmarkAddPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddPrev), [`PDBookmarkAddNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNext), [`PDBookmarkAddChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddChild), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkAddNewSibling

```cpp
PDBookmark PDBookmarkAddNewSibling(PDBookmark aBookmark, char *initialText)
```

Header: `PDProcs.h:752`

Adds a new bookmark to the tree containing `aBookmark`, as the new right sibling.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark that will be the left sibling of the new bookmark.
- `initialText` (`char *`): The new bookmark's title.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

The newly created bookmark. @notify PDBookmarkDidChangePosition @notify PDBookmarkWasCreated

**See also:** [`PDBookmarkAddChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddChild), [`PDBookmarkAddNewChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChild), [`PDBookmarkAddNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNext), [`PDBookmarkAddPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddPrev), [`PDBookmarkAddSubtree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddSubtree), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkAddNewSiblingASText

```cpp
PDBookmark PDBookmarkAddNewSiblingASText(PDBookmark aBookmark, const ASText initialText)
```

Header: `PDProcs.h:11590`

Adds a new bookmark to the tree containing `aBookmark`, as the new right sibling. @notify PDBookmarkDidChangePosition @notify PDBookmarkWasCreated

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark that will be the left sibling of the new bookmark.
- `initialText` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the new bookmark's title.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

The newly created bookmark.

**See also:** [`PDBookmarkAddNewSibling`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSibling), [`PDBookmarkAddChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddChild), [`PDBookmarkAddNewChildASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChildASText), [`PDBookmarkAddNewChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChild), [`PDBookmarkAddNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNext), [`PDBookmarkAddPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddPrev), [`PDBookmarkAddSubtreeASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddSubtreeASText), [`PDBookmarkAddSubtree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddSubtree), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkAddNext

```cpp
void PDBookmarkAddNext(PDBookmark aBookmark, PDBookmark newNext)
```

Header: `PDProcs.h:885`

Adds `newNext` as the new right sibling to `aBookmark`. @notify PDBookmarkDidChangePosition

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark that will receive a new right sibling.
- `newNext` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark to become the new right sibling of `aBookmark`. `newNext` must have been previously unlinked.

**Returns:** `void`

**See also:** [`PDBookmarkAddNewSibling`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSibling), [`PDBookmarkAddChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddChild), [`PDBookmarkAddSubtree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddSubtree), [`PDBookmarkAddPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddPrev), [`PDBookmarkAddNewChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChild), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkAddPrev

```cpp
void PDBookmarkAddPrev(PDBookmark aBookmark, PDBookmark newPrev)
```

Header: `PDProcs.h:867`

Adds `newPrev` as the new left sibling to `aBookmark`, adjusting the tree containing `aBookmark` appropriately.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark that will receive a new left sibling `newPrev`.
- `newPrev` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark to become the new left sibling of `aBookmark`. `newPrev` must have been previously unlinked. @notify PDBookmarkDidChangePosition

**Returns:** `void`

**See also:** [`PDBookmarkAddNewSibling`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSibling), [`PDBookmarkAddNewChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChild), [`PDBookmarkAddSubtree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddSubtree), [`PDBookmarkAddNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNext), [`PDBookmarkAddChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddChild), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkAddSubtree

```cpp
void PDBookmarkAddSubtree(PDBookmark aBookmark, PDBookmark source, char *sourceTitle)
```

Header: `PDProcs.h:797`

Adds a copy of the bookmark subtree source to `aBookmark`, as a new last child of `aBookmark`. This new item will have the text value `sourceTitle`, will be open, and will have no destination attribute. `source` must have been previously unlinked. If `aBookmark` previously had no children, it will be open after the subtree is added.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark to which the subtree source will be added as a new last child.
- `source` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark subtree to add.
- `sourceTitle` (`char *`): IN/OUT The new bookmark's title. @notify PDBookmarkWillChange @notify PDBookmarkDidChange @notify PDBookmarkDidChangePosition

**Returns:** `void`

**See also:** [`PDBookmarkAddNewSibling`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSibling), [`PDBookmarkAddNewChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChild), [`PDBookmarkAddPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddPrev), [`PDBookmarkAddNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNext), [`PDBookmarkAddChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddChild), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkAddSubtreeASText

```cpp
void PDBookmarkAddSubtreeASText(PDBookmark aBookmark, PDBookmark source, const ASText sourceTitle)
```

Header: `PDProcs.h:11645`

Adds a copy of the bookmark subtree source to `aBookmark`, as a new last child of `aBookmark`. This new item will have the text value `sourceTitle`, will be open, and will have no destination attribute. `source` must have been previously unlinked. If `aBookmark` previously had no children, it will be open after the subtree is added. @notify PDBookmarkWillChange @notify PDBookmarkDidChange @notify PDBookmarkDidChangePosition

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark to which the subtree source
  will be added as a new last child.
- `source` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark subtree to add.
- `sourceTitle` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the new bookmark's title.

**Returns:** `void`

**See also:** [`PDBookmarkAddSubtree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddSubtree), [`PDBookmarkAddNewSiblingASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSiblingASText), [`PDBookmarkAddNewSibling`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSibling), [`PDBookmarkAddNewChildASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChildASText), [`PDBookmarkAddNewChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChild), [`PDBookmarkAddPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddPrev), [`PDBookmarkAddNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNext), [`PDBookmarkAddChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddChild), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkDestroy

```cpp
void PDBookmarkDestroy(PDBookmark aBookmark)
```

Header: `PDProcs.h:812`

Removes a bookmark subtree from the bookmark tree containing it. @notify PDBookmarkWillDestroy @notify PDBookmarkDidDestroy

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The root bookmark of the subtree to remove.

**Returns:** `void`

**See also:** [`PDBookmarkAddNewChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChild), [`PDBookmarkAddNewSibling`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSibling), [`PDBookmarkFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkFromCosObj), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkEqual

```cpp
ASBool PDBookmarkEqual(PDBookmark aBookmark, PDBookmark bookmark2)
```

Header: `PDProcs.h:1128`

Tests whether two bookmarks are equal. Two bookmarks are equal only if their Cos objects are equal (see CosObjEqual()).

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The first bookmark to compare.
- `bookmark2` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The second bookmark to compare.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the bookmarks are equal, `false` otherwise.

**See also:** [`CosObjEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEqual)

#### PDBookmarkFromCosObj

```cpp
PDBookmark PDBookmarkFromCosObj(CosObj obj)
```

Header: `PDProcs.h:1157`

Converts a Cos dictionary object to a bookmark and checks the validity of the bookmark. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary Cos object whose bookmark is obtained.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

The bookmark corresponding to the Cos object.

**Exceptions**

- `pdErrBadBookmark`: is raised if the bookmark is not valid as determined by PDBookmarkIsValid().

**See also:** [`PDBookmarkGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetCosObj)

#### PDBookmarkGetAction

```cpp
PDAction PDBookmarkGetAction(PDBookmark aBookmark)
```

Header: `PDProcs.h:1104`

Gets a bookmark's action. After you obtain the action, you can execute it with AVDocPerformAction().

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark whose action is obtained.

**Returns:** [`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)

The bookmark's action.

**See also:** `AVDocPerformAction`, [`PDBookmarkSetAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkSetAction), [`PDLinkAnnotGetAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnotGetAction)

#### PDBookmarkGetByTitle

```cpp
PDBookmark PDBookmarkGetByTitle(PDBookmark aBookmark, const char *aname, ASInt32 nameLen, ASInt32 maxdepth)
```

Header: `PDProcs.h:838`

Gets the first bookmark whose title is `aName`. Value Description `0` Only look at `aBookmark`, not at any of its children. `1` Check `aBookmark` and its children, but not any grandchildren or great grandchildren, and so on. `-1` Check the entire subtree. **Note:** This text is stored in either PDFDocEncoding or in Unicode. If it is stored in Unicode, a valid Byte Order Mark must be present.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The root of the bookmark subtree to search.
- `aname` (`const char *`): IN/OUT The text value to search for. Character codes in `aName` are interpreted using the `PDFDocEncoding`.
- `nameLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The length of `aName`.
- `maxdepth` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The number of subtree levels to search, not counting the root level:

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

The bookmark with the specified title, or a `NULL` Cos object if there is no such bookmark.

#### PDBookmarkGetByTitleASText

```cpp
PDBookmark PDBookmarkGetByTitleASText(PDBookmark aBookmark, const ASText title, ASInt32 maxDepth)
```

Header: `PDProcs.h:11668`

Gets the first bookmark whose title is set in passed the ASText object.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The root of the bookmark subtree to search.
- `title` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the title value to search for.
- `maxDepth` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of subtree levels to search,
  not counting the root level.

  ValueDescription
  `0`Only look at `aBookmark`, not at any of its children.
  `1`Check `aBookmark` and its children, but not any grandchildren or great grandchildren, and so on.
  `-1`Check the entire subtree.`NULL` Cos object
  if there is no such bookmark.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

**See also:** [`PDBookmarkGetByTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetByTitle)

#### PDBookmarkGetColor

```cpp
ASBool PDBookmarkGetColor(PDBookmark bm, PDColorValue pdcvOut)
```

Header: `PDProcs.h:8064`

Retrieves the color of the specified bookmark. An exception is thrown if the bookmark is invalid or the existing color is malformed in the PDF file.

**Parameters**

- `bm` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark in question.
- `pdcvOut` (`PDColorValue`): (Filled by the method) The color of the bookmark in PDColorValue format.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the color was specified, `false` otherwise (the default color is returned in `pdcvOut`).

**See also:** [`PDBookmarkSetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkSetColor)

#### PDBookmarkGetCosObj

```cpp
CosObj PDBookmarkGetCosObj(PDBookmark aBookmark)
```

Header: `PDProcs.h:1142`

Gets the Cos object for a bookmark. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The dictionary Cos object for the bookmark. The contents of the dictionary can be enumerated using CosObjEnum().

**See also:** [`PDBookmarkFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkFromCosObj), [`CosObjEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEnum)

#### PDBookmarkGetCount

```cpp
ASInt32 PDBookmarkGetCount(PDBookmark aBookmark)
```

Header: `PDProcs.h:849`

Gets the number of open bookmarks in a subtree.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The root bookmark of a subtree to count.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of open bookmarks in the subtree (not including `aBookmark`).

**See also:** [`PDBookmarkGetIndent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetIndent), [`PDBookmarkHasChildren`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkHasChildren)

#### PDBookmarkGetFirstChild

```cpp
PDBookmark PDBookmarkGetFirstChild(PDBookmark aBookmark)
```

Header: `PDProcs.h:955`

Gets a bookmark's first child.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark whose first child is obtained.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

**See also:** [`PDBookmarkGetParent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetParent), [`PDBookmarkGetLastChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetLastChild), [`PDBookmarkHasChildren`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkHasChildren), [`PDBookmarkGetNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetNext), [`PDBookmarkGetPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetPrev)

#### PDBookmarkGetFlags

```cpp
ASInt32 PDBookmarkGetFlags(PDBookmark bm)
```

Header: `PDProcs.h:8090`

Retrieves the flags of the specified bookmark. An exception is thrown if the bookmark is invalid or the existing style is malformed in the PDF file.

**Parameters**

- `bm` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose flags are obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The bookmark's flags. Bit 1 (the least significant bit) indicates an italic font; bit 2 indicates a bold font.

**See also:** [`PDBookmarkSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkSetFlags)

#### PDBookmarkGetIndent

```cpp
ASInt32 PDBookmarkGetIndent(PDBookmark aBookmark)
```

Header: `PDProcs.h:1009`

Returns the indentation level of a bookmark in its containing tree.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark whose indentation level is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The indentation level of `aBookmark` in its containing tree. The root and its direct children have an indentation level of zero.

#### PDBookmarkGetLastChild

```cpp
PDBookmark PDBookmarkGetLastChild(PDBookmark aBookmark)
```

Header: `PDProcs.h:969`

Gets a bookmark's last child.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark whose last child is obtained.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

**See also:** [`PDBookmarkGetParent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetParent), [`PDBookmarkGetFirstChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetFirstChild), [`PDBookmarkGetNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetNext), [`PDBookmarkGetPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetPrev)

#### PDBookmarkGetNext

```cpp
PDBookmark PDBookmarkGetNext(PDBookmark aBookmark)
```

Header: `PDProcs.h:983`

Gets a bookmark's next (right) sibling.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose right sibling is obtained.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

**See also:** [`PDBookmarkGetParent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetParent), [`PDBookmarkGetFirstChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetFirstChild), [`PDBookmarkGetLastChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetLastChild), [`PDBookmarkGetPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetPrev)

#### PDBookmarkGetParent

```cpp
PDBookmark PDBookmarkGetParent(PDBookmark aBookmark)
```

Header: `PDProcs.h:940`

Gets a bookmark's parent bookmark.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose parent is obtained.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

**See also:** [`PDBookmarkGetFirstChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetFirstChild), [`PDBookmarkGetLastChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetLastChild), [`PDBookmarkGetNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetNext), [`PDBookmarkGetPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetPrev)

#### PDBookmarkGetPrev

```cpp
PDBookmark PDBookmarkGetPrev(PDBookmark aBookmark)
```

Header: `PDProcs.h:998`

Returns a bookmark's previous (left) sibling.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark whose left sibling is obtained.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

Previous (left) sibling of `aBookmark`, or a `NULL` Cos object if `aBookmark` has no previous sibling (it is its parent's first child).

**See also:** [`PDBookmarkGetParent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetParent), [`PDBookmarkGetFirstChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetFirstChild), [`PDBookmarkGetLastChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetLastChild), [`PDBookmarkGetNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetNext)

#### PDBookmarkGetTitle

```cpp
ASInt32 PDBookmarkGetTitle(PDBookmark aBookmark, char *buffer, ASInt32 bufSize)
```

Header: `PDProcs.h:1036`

Gets a bookmark's title. @since

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose title is obtained.
- `buffer` (`char *`): (Filled by the method) The buffer into which
  the title will be written. If `buffer` is non-`NULL`, its length
  is assumed to be `bufSize + 1`, because a `NULL` byte is appended
  to the title. The returned text remains valid only until the
  next PDModel method call. The text may be converted to a
  platform's native encoding using PDXlateToHost() or PDXlateToHostEx().
- `bufSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The size of the buffer.`buffer`, not counting the
  trailing `NULL` byte. If `buffer` is `NULL`, the number of
  bytes in the bookmark is returned.

  **Note:** This text is stored in either PDFDocEncoding or in Unicode. If it is stored in Unicode, a valid Byte Order Mark must be present.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

**See also:** [`PDBookmarkSetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkSetTitle), [`PDXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHost), [`PDXlateToHostEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHostEx)

#### PDBookmarkGetTitleASText

```cpp
void PDBookmarkGetTitleASText(PDBookmark aBookmark, ASText title)
```

Header: `PDProcs.h:11548`

Gets a bookmark's title as an ASText object.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose title is obtained.
- `title` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The text object containing the title. The client must pass a valid ASText object title. The routine does not allocate it.

**Returns:** `void`

**See also:** [`PDBookmarkGetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetTitle), [`PDBookmarkSetTitleASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkSetTitleASText), [`PDBookmarkSetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkSetTitle), [`PDXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHost), [`PDXlateToHostEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHostEx)

#### PDBookmarkHasChildren

```cpp
ASBool PDBookmarkHasChildren(PDBookmark aBookmark)
```

Header: `PDProcs.h:1068`

Tests whether a bookmark has children.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark to test.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if `aBookmark` has any children, `false` otherwise.

#### PDBookmarkIsOpen

```cpp
ASBool PDBookmarkIsOpen(PDBookmark aBookmark)
```

Header: `PDProcs.h:1078`

Tests whether a bookmark is open. An open bookmark shows all its children.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark to test.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the bookmark is open, `false` otherwise.

**See also:** [`PDBookmarkSetOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkSetOpen)

#### PDBookmarkIsValid

```cpp
ASBool PDBookmarkIsValid(PDBookmark aBookmark)
```

Header: `PDProcs.h:927`

Tests whether a bookmark is valid. This is intended only to ensure that the bookmark has not been deleted, not to ensure that all necessary information is present and valid.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose validity is tested.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the bookmark is valid, `false` otherwise.

**See also:** [`PDBookmarkEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkEqual)

#### PDBookmarkRemoveAction

```cpp
void PDBookmarkRemoveAction(PDBookmark aBookmark)
```

Header: `PDProcs.h:7928`

Removes a bookmark's action.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose action is removed.

**Returns:** `void`

**Exceptions**

- `pdErrBadAction`: @notify PDBookmarkDidChange @notify PDBookmarkWillChange

#### PDBookmarkSetAction

```cpp
void PDBookmarkSetAction(PDBookmark aBookmark, PDAction action)
```

Header: `PDProcs.h:1115`

Sets a bookmark's action.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark whose action is set.
- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): IN/OUT The bookmark's action. @notify PDBookmarkWillChange @notify PDBookmarkDidChange

**Returns:** `void`

**See also:** [`PDBookmarkGetAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetAction)

#### PDBookmarkSetColor

```cpp
void PDBookmarkSetColor(PDBookmark bm, PDColorValue pdcvIn)
```

Header: `PDProcs.h:8077`

Sets the color of the specified bookmark. @notify PDBookmarkWillChange with C as the key. @notify PDBookmarkDidChange with C as the key.

**Parameters**

- `bm` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose color is set.
- `pdcvIn` (`PDColorValue`): The new color. It must be in `DeviceRGB`.

**Returns:** `void`

**Exceptions**

- `If`: color is `NULL` or not in `DeviceRGB`, the bookmark is
  invalid or the existing bookmark color is malformed.

**See also:** [`PDBookmarkGetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetColor)

#### PDBookmarkSetFlags

```cpp
void PDBookmarkSetFlags(PDBookmark bm, ASInt32 nFlags)
```

Header: `PDProcs.h:8105`

Sets the flags of the specified bookmark. An exception is thrown if the bookmark is invalid or the existing style is malformed in the PDF file.

**Parameters**

- `bm` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose flags are set.
- `nFlags` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The new bookmark flags. Bit 1 (the least significant bit) indicates an italic font; bit 2 indicates a bold font. @notify PDBookmarkWillChange with F as the key. @notify PDBookmarkDidChange with F as the key

**Returns:** `void`

**See also:** [`PDBookmarkGetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetFlags)

#### PDBookmarkSetOpen

```cpp
void PDBookmarkSetOpen(PDBookmark aBookmark, ASBool isOpen)
```

Header: `PDProcs.h:1091`

Opens or closes a bookmark. An open bookmark shows its children, while a closed bookmark does not.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark to open or close.
- `isOpen` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): IN/OUT `true` if the bookmark is opened, `false` if the bookmark is closed. @notify PDBookmarkWillChange @notify PDBookmarkDidChange

**Returns:** `void`

**See also:** [`PDBookmarkIsOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkIsOpen)

#### PDBookmarkSetTitle

```cpp
void PDBookmarkSetTitle(PDBookmark aBookmark, const char *str, ASInt32 nBytes)
```

Header: `PDProcs.h:1059`

Sets a bookmark's title. @notify PDBookmarkWillChange @notify PDBookmarkDidChange @note This text is stored in either PDFDocEncoding or in Unicode. If it is stored in Unicode, a valid Byte Order Mark must be present. @since

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose title is set.
- `str` (`const char *`): A read-only string containing the bookmark's
  new title. The text must be encoded using `PDFDocEncoding`.
  Strings encoded using a platform's native encoding can be
  converted to `PDFDocEncoding` using PDXlateToPDFDocEnc() or
  PDXlateToPDFDocEncEx().`str` to copy.
- `nBytes` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))

**Returns:** `void`

**Exceptions**

- `pdErrBookmarksError`: is raised if there is an error setting
  the title.

**See also:** [`PDBookmarkGetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetTitle)

#### PDBookmarkSetTitleASText

```cpp
void PDBookmarkSetTitleASText(PDBookmark aBookmark, const ASText title)
```

Header: `PDProcs.h:11566`

Sets a bookmark's title. @notify PDBookmarkWillChange @notify PDBookmarkDidChange

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): The bookmark whose title is set.
- `title` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the bookmark's
  new title.

**Returns:** `void`

**Exceptions**

- `pdErrBookmarksError`: is raised if there is an error setting
  the title.

**See also:** [`PDBookmarkSetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkSetTitle), [`PDBookmarkGetTitleASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetTitleASText), [`PDBookmarkGetTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetTitle)

#### PDBookmarkUnlink

```cpp
void PDBookmarkUnlink(PDBookmark aBookmark)
```

Header: `PDProcs.h:914`

Unlinks a bookmark from the bookmark tree that contains it, and adjusts the tree appropriately.

**Parameters**

- `aBookmark` ([`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)): IN/OUT The bookmark to unlink.

**Returns:** `void`

**See also:** [`PDBookmarkDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkDestroy)

### Typedefs (2)

#### PDBookmark

```cpp
typedef OPAQUE_64_BITS PDBookmark
```

Header: `PDExpT.h:1088`

A bookmark on a page in a PDF file. Each bookmark has a title that appears on screen, and an action that specifies what happens when a user clicks on the bookmark. Bookmarks can either be created interactively by the user through the Acrobat viewer's user interface or programmatically generated. The typical action for a user-created bookmark is to move to another location in the current document, although any action (see PDAction) can be specified.

**See also:** [`PDDocGetBookmarkRoot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetBookmarkRoot), [`PDBookmarkAddNewSibling`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewSibling), [`PDBookmarkAddNewChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkAddNewChild), [`PDBookmarkFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkFromCosObj), [`PDBookmarkGetByTitle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetByTitle), [`PDBookmarkGetParent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetParent), [`PDBookmarkGetFirstChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetFirstChild), [`PDBookmarkGetLastChild`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetLastChild), [`PDBookmarkGetNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetNext), [`PDBookmarkGetPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkGetPrev), [`PDBookmarkDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkDestroy), [`PDBookmarkUnlink`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmarkUnlink)

#### PDBookmarkFlags

```cpp
typedef ASEnum8 PDBookmarkFlags
```

Header: `PDExpT.h:1100`

## PDCharProc

### Functions (2)

#### PDCharProcEnum

```cpp
void PDCharProcEnum(PDCharProc obj, PDGraphicEnumMonitor mon, void *clientData)
```

Header: `PDProcs.h:4037`

Enumerates the graphic description of a single character procedure for a Type 3 font. To enumerate all the character procedures in a Type 3 font (but not their graphic descriptions), use PDFontEnumCharProcs().

**Parameters**

- `obj` ([`PDCharProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharProc)): The character procedure whose graphic description is enumerated.
- `mon` ([`PDGraphicEnumMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGraphicEnumMonitor)): A pointer to a structure containing user-supplied callbacks that are called for each drawing operator on a page. Enumeration halts if any procedure returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to each monitor routine that is called.

**Returns:** `void`

**See also:** [`PDCharProcEnumWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharProcEnumWithParams), [`PDFontEnumCharProcs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontEnumCharProcs), [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts), [`PDDocEnumLoadedFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumLoadedFonts)

#### PDCharProcGetCosObj

```cpp
CosObj PDCharProcGetCosObj(PDCharProc obj)
```

Header: `PDProcs.h:4051`

Get the stream Cos object associated with the PDCharProc. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `obj` ([`PDCharProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharProc)): IN/OUT The character procedure whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The character procedure's stream Cos object.

**See also:** [`PDFontEnumCharProcs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontEnumCharProcs), [`PDCharProcEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharProcEnum)

## PDCollection

### Functions (16)

#### PDCollectionCreateFolder

```cpp
PDFolder PDCollectionCreateFolder(PDCollection collection, ASConstText path)
```

Header: `PDProcs.h:12432`

Creates a new folder. `/ \ : ? * " < > |`

and may not end with a `.` (period). @iverbatim Please note that a folder name cannot consist entirely of spaces. To specify the root folder itself, assign a value of `"/"`.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection that will be associated with the new folder.
- `path` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The path and name of the folder. The path syntax for folders takes the form `[parent/]folder`, where the mandatory `parent/` section may be repeated as necessary to provide a complete path to the new folder. The path is always interpreted as being relative to the root level of the folder hierarchy. Paths that specify simply a new folder name are located in the root folder. The character set for folder names is limited. Folders may not contain any of the characters in the set

**Returns:** [`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)

The new folder object.

#### PDCollectionGetFolder

```cpp
PDFolder PDCollectionGetFolder(PDCollection collection, ASConstText path)
```

Header: `PDProcs.h:12450`

Gets an existing folder.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection associated with the folder to be obtained.
- `path` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The path to the folder. To specify the root folder itself, assign a value of `"/"`. The path syntax for folders takes the form `[parent/]folder`, where the mandatory `parent/` section may be repeated as necessary to provide a complete path to the new folder.

**Returns:** [`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)

The specified folder. If the folder does not exist, the returned folder is invalid.

#### PDCollectionGetInitialStyle

```cpp
ASBool PDCollectionGetInitialStyle(PDCollection collection, ASCab style)
```

Header: `PDProcs.h:12463`

Gets the initial style dictionary for the collection.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection object.
- `style` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): Dictionary to set

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

true if the dictionary is present, if false the passed cabinet is unchanged

#### PDCollectionGetSortOrder

```cpp
ASArraySize PDCollectionGetSortOrder(PDCollection collection, PDCollectionSchemaSortPairRec *pairs, ASArraySize arrayLen)
```

Header: `PDProcs.h:12343`

Gets the contents of the collection sort dictionary.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection object.
- `pairs` (`PDCollectionSchemaSortPairRec *`): The array of pairs. It may be `NULL`.
- `arrayLen` ([`ASArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASArraySize)): The length of the pairs array.

**Returns:** [`ASArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASArraySize)

If `pairs` is `NULL`, the number of items in the collection sort dictionary is returned; otherwise, the number of items stored in the `pairs` array is returned.

#### PDCollectionGetViewData

```cpp
void PDCollectionGetViewData(PDCollection collection, PDCollectionViewDataRec *data)
```

Header: `PDProcs.h:12356`

Gets the view data for the collection.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection object.
- `data` (`PDCollectionViewDataRec *`): The collection view data.

**Returns:** `void`

#### PDCollectionIsValid

```cpp
ASBool PDCollectionIsValid(PDCollection collection)
```

Header: `PDProcs.h:12316`

Determines if a collection is valid.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the collection is valid, `false` otherwise.

#### PDCollectionRemoveFolder

```cpp
void PDCollectionRemoveFolder(PDCollection collection, ASConstText path)
```

Header: `PDProcs.h:12440`

Removes a folder and its descendant folders and associated file attachments.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection associated with the folder that will be removed.
- `path` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The path to the folder.

**Returns:** `void`

`0` if the folder hierarchy was successfully removed; otherwise an error code identifying the failure condition is returned.

#### PDCollectionRemoveInitialStyle

```cpp
void PDCollectionRemoveInitialStyle(PDCollection collection)
```

Header: `PDProcs.h:12468`

Removes the initial style dictionary from a collect, if present

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection object.

**Returns:** `void`

#### PDCollectionSchemaDestroy

```cpp
void PDCollectionSchemaDestroy(PDCollectionSchema schema)
```

Header: `PDProcs.h:12374`

Destroys a `PDCollectionSchema` object.

**Parameters**

- `schema` ([`PDCollectionSchema`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollectionSchema))

**Returns:** `void`

The collection object.

#### PDCollectionSchemaGetField

```cpp
ASBool PDCollectionSchemaGetField(PDCollectionSchema schema, PDCollectionFieldRec *field)
```

Header: `PDProcs.h:12392`

Gets a field by name or position. The caller must set `field.size` to `sizeof(PDCollectionFieldRec)`. To look up a field by name, set `field.fieldName` to the appropriate name. To look up a field by position, set `field.fieldName` to `ASAtomNull`, and set `field.index` to the position. The caller owns (and must destroy) `field.fieldText` if it is not `NULL`.

**Parameters**

- `schema` ([`PDCollectionSchema`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollectionSchema)): The collection schema object.
- `field` (`PDCollectionFieldRec *`): The field to be obtained.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field was found, `false` otherwise.

#### PDCollectionSchemaGetLength

```cpp
ASArraySize PDCollectionSchemaGetLength(PDCollectionSchema schema)
```

Header: `PDProcs.h:12380`

Gets the number of fields in the schema.

**Parameters**

- `schema` ([`PDCollectionSchema`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollectionSchema))

**Returns:** [`ASArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASArraySize)

The number of fields in the schema.

#### PDCollectionSchemaRemoveField

```cpp
void PDCollectionSchemaRemoveField(PDCollectionSchema schema, ASAtom fieldName)
```

Header: `PDProcs.h:12410`

Removes a field from the collection schema.

**Parameters**

- `schema` ([`PDCollectionSchema`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollectionSchema)): The collection schema.
- `fieldName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The name of the field to remove from the collection schema.

**Returns:** `void`

#### PDCollectionSchemaSetField

```cpp
void PDCollectionSchemaSetField(PDCollectionSchema schema, const PDCollectionFieldRec *field)
```

Header: `PDProcs.h:12404`

Sets a field with new values. The target field is identified by the `field.fieldName` member. If the target field exists, it is overwritten; otherwise a new field is added. The caller must set `field.size` to `sizeof(PDCollectionFieldRec)`. Specifying a new value for `field.index` will affect other field values as necessary to maintain the correct overall ordering. See `PDCollectionSchema` for information about ordering.

**Parameters**

- `schema` ([`PDCollectionSchema`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollectionSchema)): The collection schema object.
- `field` (`const PDCollectionFieldRec *`): The field to add or modify in the collection schema.

**Returns:** `void`

**See also:** [`PDCollectionSchema`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollectionSchema)

#### PDCollectionSetInitialStyle

```cpp
void PDCollectionSetInitialStyle(PDCollection collection, ASConstCab style)
```

Header: `PDProcs.h:12456`

Sets the initial style dictionary for the collection.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection object.
- `style` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): Dictionary to fill

**Returns:** `void`

#### PDCollectionSetSortOrder

```cpp
void PDCollectionSetSortOrder(PDCollection collection, const PDCollectionSchemaSortPairRec *pairs, ASArraySize arrayLen)
```

Header: `PDProcs.h:12350`

Set the contents of the collection sort dictionary.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection object.
- `pairs` (`const PDCollectionSchemaSortPairRec *`): The array of pairs. If it is `NULL`, the collection sort dictionary is removed.
- `arrayLen` ([`ASArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASArraySize)): The length of the `pairs` array.

**Returns:** `void`

#### PDCollectionSetViewData

```cpp
void PDCollectionSetViewData(PDCollection collection, const PDCollectionViewDataRec *data)
```

Header: `PDProcs.h:12362`

Set the view data for the collection.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection object.
- `data` (`const PDCollectionViewDataRec *`): The collection view data.

**Returns:** `void`

### Typedefs (4)

#### PDCollection

```cpp
typedef OPAQUE_64_BITS PDCollection
```

Header: `PDExpT.h:7023`

A `PDCollection` represents a collection dictionary in a PDF file. Collection view types and split types are unusual. A straight mapping of the View key and the Split key would result in the key/value of `/View/H` being part of the view type enumeration, but that would result in ambiguity when setting View to H and Split to N (`/View/H` maps to "preview" in Acrobat 8, but `/Split/N` is documented to map to "no split, show navigator" in Acrobat 9. Because of this, and the fact that `/View/H` is really interpreted as a kind of split rather than a style of navigator, Preview was moved to the split type enumeration in the API. This interacts with the underlying file as follows: when a `/View/H` value is read it is mapped to "Tile" and "Preview" for the navigator style and split position. When the Tile/Preview combination is written out, it is recorded back to `/View/H` for consistency with Acrobat 8.

**See also:** [`PDDocGetPDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPDCollection), [`PDDocCreatePDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreatePDCollection), [`PDDocDeleteCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocDeleteCollection)

#### PDCollectionSplitType

```cpp
typedef ASUns16 PDCollectionSplitType
```

Header: `PDExpT.h:7058`

#### PDCollectionViewType

```cpp
typedef ASUns16 PDCollectionViewType
```

Header: `PDExpT.h:7043`

#### PDNavigator

```cpp
typedef OPAQUE_64_BITS PDNavigator
```

Header: `PDExpT.h:7032`

Opaque object representing a collection navigator dictionary.

### Enums (2)

#### PDCollectionSplitTypes

Header: `PDExpT.h:7046`

Collection split types.

**Values**

- `kCollectionSplitDefault = 0x2000`: Default split based on view.
- `kCollectionSplitHorizontal = 8193`: Split vertical.
- `kCollectionSplitVertical = 8194`: Split horizontal.
- `kCollectionSplitNone = 8195`: No split; show the navigator.
- `kCollectionSplitPreview = 8196`: No split; show the preview.

#### PDCollectionViewTypes

Header: `PDExpT.h:7035`

Collection view types.

**Values**

- `kCollectionViewTile = 0x1000`: Tile navigator.
- `kCollectionViewDetails = 4097`: Details navigator.
- `kCollectionViewCustom = 4098`: Custom navigator.

## PDCollectionSchema

### Functions (1)

#### PDCollectionSchemaAcquire

```cpp
PDCollectionSchema PDCollectionSchemaAcquire(PDCollection collection)
```

Header: `PDProcs.h:12368`

Acquires the `PDCollectionSchema` object for a collection.

**Parameters**

- `collection` ([`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)): The collection object.

**Returns:** [`PDCollectionSchema`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollectionSchema)

The collection object.

### Structures (1)

#### PDCollectionSchema

```cpp
typedef struct CPDCollectionSchema* PDCollectionSchema
```

Header: `PDExpT.h:7088`

An opaque pointer to a collection schema object. A `PDCollectionSchema` is ordered with the following considerations. The `PDCollectionSchema` has characteristics of both a collection of named fields and an array. Field names are guaranteed to be unique. Indexing is guaranteed to be 0-based, in ascending order, with no gaps. When repositioning a field by changing its index, the schema will be re-indexed as necessary to conform to this convention. If a field is assigned an out-of-bound index, the index is adjusted to be in bounds rather than raising an error.

## PDCrypt

### Functions (3)

#### PDCryptAuthorizeFilterAccess

```cpp
ASBool PDCryptAuthorizeFilterAccess(PDDoc doc, ASAtom handlerName, ASAtom filterName, ASBool bEncrypt)
```

Header: `PDProcs.h:10841`

Gets authorization to encrypt or decrypt an embedded file, where that file's cryptographic filter is not the one used to open the document in which the file is embedded.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document containing the embedded file whose filter access is requested.
- `handlerName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The security handler containing the Authorize() callback procedure to run.
- `filterName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom corresponding to the name of the security filter used by the embedded file.
- `bEncrypt` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): When `true`, the access is required for an encryption operation. When `false`, it is a decryption operation.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the authorization succeeds, `false` otherwise.

**Exceptions**

- `pdErrNoCryptHandler`: is raised if there is no security handler registered for the document.

**See also:** [`PDDocSetNewCryptFilterData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptFilterData), [`PDDocSetNewCryptFilterMethod`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptFilterMethod), [`PDDocSetNewDefaultFilters`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewDefaultFilters)

#### PDRegisterCryptHandler

```cpp
void PDRegisterCryptHandler(PDCryptHandler handler, const char *pdfName, const char *userName)
```

Header: `PDProcs.h:2594`

Registers a new security handler with the Acrobat viewer.

**Parameters**

- `handler` ([`PDCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptHandler)): A pointer to a structure that contains the security handler's callback functions. This structure must not be freed after calling PDRegisterCryptHandler().
- `pdfName` (`const char *`): The name of the security handler as it will appear in the PDF file. This name is also used by PDDocSetNewCryptHandler(). Storage for this name can be freed after PDRegisterCryptHandler() has been called.
- `userName` (`const char *`): The name of the security handler as it will be shown in menus. This name can be localized into different languages. Storage for this name can be freed after PDRegisterCryptHandler() has been called.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the security handler's size field is incorrect.
- `ErrSysPDSEdit`: is raised if either `pdfName` or `userName` are already in use by a registered security handler.
- `genErrNoMemory`: is raised is memory is exhausted. Other exceptions may be raised as well.

**See also:** [`PDDocGetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewCryptHandler), [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest), [`PDDocSetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandler), [`PDDocSetNewCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandlerEx), [`PDRegisterCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandlerEx)

#### PDRegisterCryptHandlerEx

```cpp
void PDRegisterCryptHandlerEx(PDCryptHandler handler, const char *pdfName, const char *userName, void *clientData)
```

Header: `PDProcs.h:6103`

Registers a new security handler with the Acrobat viewer. It is the same as PDRegisterCryptHandler() except that it accepts a client data parameter.

**Parameters**

- `handler` ([`PDCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptHandler)): A pointer to a structure that contains the security handler's callback functions. This structure must not be freed after calling PDRegisterCryptHandlerEx().
- `pdfName` (`const char *`): The name of the security handler as it will appear in the PDF file. This name is also used by PDDocSetNewCryptHandler(). Storage for this name can be freed after PDRegisterCryptHandlerEx() has been called.
- `userName` (`const char *`): The name of the security handler as it will be shown in menus. This name can be localized to different languages. Storage for this name can be freed after PDRegisterCryptHandlerEx() has been called.
- `clientData` (`void *`): A pointer to user-supplied data to store with the handler.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the security handler's size field is incorrect.
- `ErrSysPDSEdit`: is raised if either pdfName or userName are already in use by a registered security handler.
- `genErrNoMemory`: is raised is memory is exhausted.

**See also:** [`PDDocSetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandler), [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest), [`PDRegisterCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandler)

### Typedefs (34)

#### PDCryptAuthorizeExProc

```cpp
typedef PDPermReqStatus(*) PDCryptAuthorizeExProc(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void *authData)(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void *authData)
```

Header: `PDExpT.h:4783`

Replaces PDCryptAuthorizeProc. PDPerms are obsolete, but Acrobat still supports old security handlers. It is called whenever Acrobat needs to get authorization data and/or check permissions for operations.

**See also:** [`PDCryptAuthorizeProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptAuthorizeProc), [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest)

#### PDCryptAuthorizeProc

```cpp
typedef PDPerms(*) PDCryptAuthorizeProc(PDDoc pdDoc, void *authData, PDPerms permWanted)(PDDoc pdDoc, void *authData, PDPerms permWanted)
```

Header: `PDExpT.h:4461`

A callback for PDCryptHandler. It is called by PDDocAuthorize() when a user tries to set security for an encrypted document and by a PDAuthProc() when a user tries to open a file. It must decide, based on the contents of the authorization data structure, whether the user is permitted to open the file, and what permissions the user has for this file. The authorization data structure is available for making this decision. Alternate implementations may not require authorization data and may, for example, make authorization decisions based on data contained in the security data structure (use PDCryptNewSecurityDataProc()). This callback must not obtain the authorization data (for example, by displaying a user interface into which a user can type a password). Obtaining authorization data is handled by the security handler's PDCryptGetAuthDataProc(), which must be called before this callback. Instead, PDCryptAuthorizeProc() must work with whatever authorization data is passed to it. It is legitimate for this callback to be called with `NULL` authorization data; the Acrobat viewer's built-in `authProc` does this in order to support authorization methods that do not require authorization data. When this callback is invoked to determine whether a user is permitted to open a file, `permWanted` is set to `pdPermOpen`. In this case, the file's contents are not yet decrypted (since this callback is being asked to permit decryption), and some calls must be avoided. For example, a call that causes a page to be parsed results in an error, since the encrypted contents are parsed. In general, it is safe to obtain information about the presence or absence of things, or the number of things, and to examine any part of a document at the Cos level.

**Parameters**

- `pdDoc`: The document for which authorized permissions
  are being requested.
- `authData`: Authorization data. Its format is security
  handler-specific; each handler can select its own authorization
  data format.
- `permWanted`: The permissions being requested. It is
  either `pdPermOpen` (if the file is being opened) or `pdPermSecure`
  (if a request is being made to change the document's security
  settings).`authData`. For opening,
  the permissions returned usually should be `pdPermOpen` and
  some or all of `pdPermPrint`, `pdPermEdit`, and
  `pdPermCopy`. For setting security, permissions returned should be `pdPermAll`. However, if authorization fails, `0` should be returned.

**See also:** [`PDCryptAuthorizeExProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptAuthorizeExProc), [`PDCryptAuthorizeFilterAccess`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptAuthorizeFilterAccess), [`PDDocAuthorize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAuthorize), [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenEx)

#### PDCryptBatchAuthorizeProc

```cpp
typedef PDPermReqStatus(*) PDCryptBatchAuthorizeProc(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void *authData)(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void *authData)
```

Header: `PDExpT.h:5011`

A callback for PDCryptBatchHandler. It is called when a PDF file is opened. It is first called with `NULL` `authData` for the case without a user password. It is called again with authorization data provided for the security handler that matches the one used in the PDF file. **Note:** This function is called a batch operation and therefore should not display any user interface. During a batch operation, a file will first be opened with the `pdPermSecure` bit set. It will then be opened with the `pdPermOpen` bit set.

#### PDCryptBatchFreeAuthDataProc

```cpp
typedef void(*) PDCryptBatchFreeAuthDataProc(void *authData)(void *authData)
```

Header: `PDExpT.h:5023`

A callback for PDCryptBatchHandler. If provided, it must be used to free `authData` acquired via BatchGetAuthData() or BatchNewAuthData(). If no BatchFreeAuthData() function is provided, a default one will be used which calls ASfree() on the `authData` if it is non-`NULL`.

#### PDCryptBatchNewAuthDataProc

```cpp
typedef void *(*) PDCryptBatchNewAuthDataProc(void)(void)
```

Header: `PDExpT.h:4989`

A callback for PDCryptBatchHandler. It is different from the regular PDCryptHandler `NewAuthData` function. It creates and returns a `void*` which is the authorization data for the batch security handler. This data should be used to batch both open files and secure files. Therefore, make sure to provide password information for both the `pdPermOpen` and `pdPermSecure` cases. This data will be passed to the PDCryptBatchAuthorizeProc() callback and eventually to PDCryptBatchFreeAuthDataProc() to free the data. This authorization data is collected before any files are opened in the batch sequence. It is permitted to display a user interface at this point since the batch operation has not started yet. The data applies to all files, and therefore could represent one or more passwords which can be enumerated in the `BatchAuthorize` function which receives the batch authorization data.

#### PDCryptBatchParamDescProc

```cpp
typedef void(*) PDCryptBatchParamDescProc(const ASCab settings, ASCab paramDesc)(const ASCab settings, ASCab paramDesc)
```

Header: `PDExpT.h:4970`

A callback for PDCryptBatchHandler. The developer should provide information about the current batch settings for the security handler. Batch settings are provided as a read-only ASCab that is passed to the function. A writable ASCab is also provided, which should be used to store parameter information about the security handler. The description information should be stored starting in the `paramDesc` ASCab using ASText objects starting with key `" 1"`. **Example key=" 1", value="Title: API Reference" (ASText object)**

#### PDCryptBatchPostSequenceProc

```cpp
typedef void(*) PDCryptBatchPostSequenceProc(ASCab settings)(ASCab settings)
```

Header: `PDExpT.h:5051`

A callback for PDCryptBatchHandler. This function is called at the end of a batch sequence after all files have been processed. Any memory that was allocated in the BatchPreSequence() call should be cleaned up in this callback.

#### PDCryptBatchPreSequenceProc

```cpp
typedef ASBool(*) PDCryptBatchPreSequenceProc(ASCab settings)(ASCab settings)
```

Header: `PDExpT.h:5042`

A callback for PDCryptBatchHandler. This function is called at the beginning of a batch sequence before any files have been opened. This allows a security handler to be called back with the ASCab of settings that were filled out by the BatchShowDialog() function, or by an ASCab that was read in from disk. Pointers of security information are not serialized to disk, and therefore a security information structure may need to be regenerated based on other security information in the ASCab. It is permitted for the BatchPreSequence() callback to put up a user interface asking the user for more information since the batch sequence has not started yet. If this function returns `false`, the viewer will assume that the command cannot be executed and will cancel the sequence.

#### PDCryptBatchShowDialogProc

```cpp
typedef ASBool(*) PDCryptBatchShowDialogProc(ASCab settings)(ASCab settings)
```

Header: `PDExpT.h:4955`

A callback for PDCryptBatchHandler. This callback puts up a dialog box that allows a user to enter data that will be used to batch secure a series of files. The data is stored in an ASCab which is part of a batch sequence file. The actual security data, including password(s), should be stored as a pointer in the ASCab so that password information is not serialized to disk. Pointers are not serialized from ASCab objects, but ASText objects, ASInt32 objects, and ASBool objects are serialized.

#### PDCryptBatchUpdateSecurityDataProc

```cpp
typedef ASBool(*) PDCryptBatchUpdateSecurityDataProc(PDDoc pdDoc, ASCab settings, ASAtom *cryptHandler, void **secDataP)(PDDoc pdDoc, ASCab settings, ASAtom *cryptHandler, void **secDataP)
```

Header: `PDExpT.h:5069`

A callback for PDCryptBatchHandler. This function should update the crypt handler's security data without bringing up a dialog. This data is provided by a PDCryptBatchShowDialogProc(). The current security data can be obtained by calling PDDocGetNewSecurityData(). **Note:** This function is called a batch operation and therefore should not display any user interface.

#### PDCryptCanParseEncryptDictProc

```cpp
typedef ASBool(*) PDCryptCanParseEncryptDictProc(PDDoc pdDoc, CosObj encryptDict)(PDDoc pdDoc, CosObj encryptDict)
```

Header: `PDExpT.h:4870`

(Optional) This call is used to provide PDCrypt handler interoperability. When an encrypted document is being opened and the security handler specified in the encryption dictionary is not present, this callback is used to determine if one of the registered security handlers can be used to open the document.

#### PDCryptDisplaySecurityDataProc

```cpp
typedef ASBool(*) PDCryptDisplaySecurityDataProc(PDDoc pdDoc, ASAtom cryptHandler)(PDDoc pdDoc, ASAtom cryptHandler)
```

Header: `PDExpT.h:4850`

Called when the security handler should bring up a document (security) information dialog box with the current settings. It also should return `true` when the user wants to change the settings. If this callback is not supplied, the default information dialog is displayed with PDPerms bits information (an Acrobat 4.x-equivalent dialog).

#### PDCryptEncryptDocMetadata

```cpp
typedef ASBool(*) PDCryptEncryptDocMetadata(PDDoc pdDoc)(PDDoc pdDoc)
```

Header: `PDExpT.h:4914`

(Optional) A callback for PDCryptHandler. It determines whether a document's metadata will be encrypted. If this call is not implemented, the metadata is always encrypted. Note that documents with plain text metadata can be opened only by Acrobat versions 6.0 and later.

#### PDCryptFillEncryptDictProc

```cpp
typedef void(*) PDCryptFillEncryptDictProc(PDDoc pdDoc, CosObj encryptDict)(PDDoc pdDoc, CosObj encryptDict)
```

Header: `PDExpT.h:4673`

A callback for PDCryptHandler. It is called when an encrypted document is saved. It fills the document's Encryption dictionary with whatever information the security handler wants to store in the document. Normally this callback is called after PDCryptUpdateSecurityDataProc(). The security data structure can be obtained with a call to PDDocGetNewSecurityData(), and `encryptDict` is filled based on this data. The sequencing of events that the viewer performs during creation of the encryptDict is as follows: • The viewer creates the `encryptDict`. • The viewer adds the Filter attribute to the dictionary. • The viewer calls this PDCryptFillEncryptDictProc() to allow the security handler to add its own attributes to the dictionary. • The viewer calls the PDCryptNewCryptDataExProc() (the PDCryptNewCryptDataProc() if unsuccessful) to get the algorithm version, key, and key length. • The viewer checks if the V attribute has been added to the dictionary and, if not, it sets V to the algorithm version. • The viewer sets the Length attribute if V is `2` or greater. • The viewer adds the encryptDict to the document.

**See also:** [`PDDocSave`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSave)

#### PDCryptFilterAuthorizeProc

```cpp
typedef ASBool(*) PDCryptFilterAuthorizeProc(CosDoc dP, ASAtom filterName, CosObj encryptDict, ASBool bEncrypt, ASBool bUIAllowed)(CosDoc dP, ASAtom filterName, CosObj encryptDict, ASBool bEncrypt, ASBool bUIAllowed)
```

Header: `PDExpT.h:5129`

(Optional) A callback for PDCryptFilterHandler. Acrobat's security mechanism calls this method to determine whether the user should have access to this filter.

**See also:** [`PDCryptFilterGetDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFilterGetDataProc), [`PDCryptFilterStreamProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFilterStreamProc), [`PDCryptFilterStringProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFilterStringProc), [`PDCryptAuthorizeFilterAccess`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptAuthorizeFilterAccess), [`PDDocSetNewCryptFilterMethod`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptFilterMethod), [`PDDocSetNewDefaultFilters`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewDefaultFilters)

#### PDCryptFilterGetDataProc

```cpp
typedef ASInt32(*) PDCryptFilterGetDataProc(CosDoc dP, ASAtom filterName, char **key, ASBool bNewKey, ASBool bUIAllowed)(CosDoc dP, ASAtom filterName, char **key, ASBool bNewKey, ASBool bUIAllowed)
```

Header: `PDExpT.h:5152`

(Optional) A callback for PDCryptFilterHandler. Acrobat's security mechanism calls this method to retrieve the encryption/decryption key for this filter. It is called only when the filter's encryption method is V2.

**See also:** [`PDCryptFilterAuthorizeProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFilterAuthorizeProc), [`PDCryptFilterStreamProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFilterStreamProc), [`PDCryptFilterStringProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFilterStringProc), [`PDDocSetNewCryptFilterData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptFilterData), [`PDDocSetNewCryptFilterMethod`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptFilterMethod), [`PDDocSetNewDefaultFilters`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewDefaultFilters)

#### PDCryptFilterStreamProc

```cpp
typedef void(*) PDCryptFilterStreamProc(CosDoc dP, ASAtom filterName, ASCryptStm stm, ASBool handOff, CosObj params, ASInt32 stmLength)(CosDoc dP, ASAtom filterName, ASCryptStm stm, ASBool handOff, CosObj params, ASInt32 stmLength)
```

Header: `PDExpT.h:5104`

(Optional) A callback for PDCryptFilterHandler. Callbacks that conform to this prototype are called to encrypt or decrypt streams from a document. The first call to a procedure of this type must fill out an `ASCryptStmRec` structure with pointers to callback routines for various types of stream access; see `ASCryptStmProcs()`.

**See also:** [`PDCryptFilterAuthorizeProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFilterAuthorizeProc), [`PDCryptFilterGetDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFilterGetDataProc), [`PDCryptFilterStringProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFilterStringProc), [`PDDocSetNewCryptFilterData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptFilterData), [`PDDocSetNewCryptFilterMethod`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptFilterMethod), [`PDDocSetNewDefaultFilters`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewDefaultFilters)

#### PDCryptFreeAuthDataProc

```cpp
typedef void(*) PDCryptFreeAuthDataProc(PDDoc pdDoc, void *authData)(PDDoc pdDoc, void *authData)
```

Header: `PDExpT.h:4724`

(Optional) A callback for PDCryptHandler. It is used to free authorization data acquired via PDCryptNewAuthDataProc(). If this callback is omitted, the viewer defaults to freeing the data using ASfree().

**See also:** [`PDCryptNewAuthDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptNewAuthDataProc), [`PDDocGetNewSecurityInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewSecurityInfo)

#### PDCryptFreeCryptDataProc

```cpp
typedef void(*) PDCryptFreeCryptDataProc(PDDoc pdDoc, char *cryptData)(PDDoc pdDoc, char *cryptData)
```

Header: `PDExpT.h:4738`

(Optional) A callback for PDCryptHandler. It is used to free authorization data acquired via PDCryptNewCryptDataProc(). If this callback is omitted, the viewer defaults to freeing the data using ASfree().

**See also:** [`PDCryptNewCryptDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptNewCryptDataProc), [`PDDocGetNewSecurityInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewSecurityInfo)

#### PDCryptFreeSecurityDataProc

```cpp
typedef void(*) PDCryptFreeSecurityDataProc(PDDoc pdDoc, void *secData)(PDDoc pdDoc, void *secData)
```

Header: `PDExpT.h:4710`

(Optional) A callback for PDCryptHandler. It is used to free security data acquired via PDCryptNewSecurityDataProc(). If this callback is omitted, the viewer defaults to freeing the data using ASfree().

**See also:** [`PDCryptNewSecurityDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptNewSecurityDataProc), [`PDDocGetNewSecurityInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewSecurityInfo)

#### PDCryptGetAuthDataExProc

```cpp
typedef ASBool(*) PDCryptGetAuthDataExProc(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void **authDataP)(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void **authDataP)
```

Header: `PDExpT.h:4806`

Replaces PDCryptGetAuthDataProc(). It is called whenever Acrobat needs to get authorization data and/or check permissions for operations. PDPerms are obsolete. Acrobat provides permission controls, but Acrobat still supports old security handlers.

**See also:** [`PDCryptGetAuthDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptGetAuthDataProc)

#### PDCryptGetAuthDataProc

```cpp
typedef ASBool(*) PDCryptGetAuthDataProc(PDDoc pdDoc, PDPerms permWanted, void **authDataP)(PDDoc pdDoc, PDPerms permWanted, void **authDataP)
```

Header: `PDExpT.h:4515`

A callback for PDCryptHandler. This callback is called from a PDAuthProc when a file is opened after PDCryptNewSecurityDataProc() is called. The callback must determine the user's authorization properties for the document by obtaining authorization data, such as a user interface log in or password entry. It populates an authorization data structure with this data. This callback may call the security handler's PDCryptNewAuthDataProc() to allocate the authorization data structure. The use of an authorization data structure is optional (an implementation may wish to contain authorization data within the security data structure). The authorization data structure is subsequently used by the security handler's PDCryptAuthorizeProc() to determine whether the user is authorized to open the file. A security handler can specify the standard password dialog box by using AVCryptGetPassword(). In this case, `authData` is a `char*`.

**See also:** [`PDCryptGetAuthDataExProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptGetAuthDataExProc), [`PDCryptNewAuthDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptNewAuthDataProc), [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenEx)

#### PDCryptGetDocPermsProc

```cpp
typedef void(*) PDCryptGetDocPermsProc(PDDoc pdDoc, ASBool perms[PDPermReqObjLast][PDPermReqOprLast], ASInt16 *version)(PDDoc pdDoc, ASBool perms[PDPermReqObjLast][PDPermReqOprLast], ASInt16 *version)
```

Header: `PDExpT.h:4899`

A callback for PDCryptHandler. This function should extract and return information about the document permissions to display for the user: whether the user can print, edit, copy text and graphics, edit notes and do form fill in and signing. The permissions returned are logically AND-ed with the document permissions returned by any other permissions handlers, and displayed to the user. All crypt handlers should implement this call so that consolidated permissions can be displayed. To display your own crypt handler's permissions, implement PDCryptDisplaySecurityDataProc(). If this callback is absent, Acrobat assumes that all the operations on the document are allowed.

**See also:** [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest)

#### PDCryptGetInfoTextProc

```cpp
typedef ASText(*) PDCryptGetInfoTextProc(PDDoc pdDoc, GCHTextType textType)(PDDoc pdDoc, GCHTextType textType)
```

Header: `PDExpT.h:4934`

(Optional) A callback for PDCryptHandler. It provides information for display about document security settings. Value Description `kGCHTTipText` Text used for a security tool tip. It should be short. Its default is `"This document is secured."` `kGCHTMiniText` Text used for a security hover. It should be medium length. Its default is `"This document has been encrypted and may use..."` `kGCHTLargeText` Text use for Toast on Windows. It can have a longer length. There is no default.

#### PDCryptGetSecurityInfoProc

```cpp
typedef void(*) PDCryptGetSecurityInfoProc(PDDoc pdDoc, ASUns32 *secInfo)(PDDoc pdDoc, ASUns32 *secInfo)
```

Header: `PDExpT.h:4696`

(Optional) A callback for PDCryptHandler. It is called by PDDocGetNewSecurityInfo(). It extracts the security information from the security data structure, and returns the security information. This function is also used after a Save As... to reset the permissions according to the current document. A default set of permissions is used if this callback is absent: `pdInfoCanPrint|pdInfoCanEdit|pdInfoCanCopy|pdInfoCanEditNotes` See PDPerms.

**See also:** [`PDDocGetNewSecurityInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewSecurityInfo)

#### PDCryptNewAuthDataProc

```cpp
typedef void *(*) PDCryptNewAuthDataProc(PDDoc pdDoc)(PDDoc pdDoc)
```

Header: `PDExpT.h:4478`

(Optional) A callback for PDCryptHandler. It creates a new empty authorization data structure. This structure is subsequently filled by PDCryptGetAuthDataProc(), then passed to PDCryptAuthorizeProc() and eventually to ASfree(). This callback is not called by the Acrobat viewer, but a security handler may use it if it wishes. The Acrobat viewer's standard security handler does not use this method.

**See also:** [`PDCryptFreeAuthDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFreeAuthDataProc), [`PDCryptGetAuthDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptGetAuthDataProc)

#### PDCryptNewCryptDataExProc

```cpp
typedef void(*) PDCryptNewCryptDataExProc(PDDoc pdDoc, char **cryptData, ASInt32 *cryptDataLen, ASInt32 *cryptVersion)(PDDoc pdDoc, char **cryptData, ASInt32 *cryptDataLen, ASInt32 *cryptVersion)
```

Header: `PDExpT.h:4761`

A callback for PDCryptHandler. It sets up the key to be passed to initialize the RC4 cipher for encryption and decryption of a PDF file. It is called when an encrypted document is opened or saved. The key is truncated when the length is greater than the viewer currently supports. Data is freed by PDCryptFreeCryptDataProc() if provided. Otherwise, ASfree() is used.

**Parameters**

- `pdDoc`: IN/OUT The document for which the key is set.
- `cryptData`: IN/OUT (Filled by the callback) The key. `cryptData`
  must be allocated by ASmalloc() because the Acrobat viewer
  will free it using ASfree().
- `cryptDataLen`: IN/OUT (Filled by the callback) The number
  of bytes in `cryptData`. It cannot be greater than `5` bytes.
- `cryptVersion`: IN/OUT The Cos crypt version, which is the version
  of the algorithm that is used to encrypt and decrypt document
  data. `cryptVersion` equal to `0` is treated as
  `cryptVersion` equal to `1` to maintain backward compatibility.

**See also:** [`PDCryptFreeCryptDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFreeCryptDataProc)

#### PDCryptNewCryptDataProc

```cpp
typedef void(*) PDCryptNewCryptDataProc(PDDoc pdDoc, char **cryptData, ASInt32 *cryptDataLen)(PDDoc pdDoc, char **cryptData, ASInt32 *cryptDataLen)
```

Header: `PDExpT.h:4635`

A callback for PDCryptHandler. It sets up the key to be passed to initialize the RC4 cipher for encryption and decryption of a PDF file. It is called when an encrypted document is opened or saved.

**See also:** [`PDCryptNewAuthDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptNewAuthDataProc)

#### PDCryptNewSecurityDataFromOriginalDocProc

```cpp
typedef ASBool(*) PDCryptNewSecurityDataFromOriginalDocProc(PDDoc pdDoc, CosObj encryptDict, PDDoc alreadyOpenedDoc, CosObj openedEncryptDict, void **authDataP)(PDDoc pdDoc, CosObj encryptDict, PDDoc alreadyOpenedDoc, CosObj openedEncryptDict, void **authDataP)
```

Header: `PDExpT.h:4834`

Called when the application needs to open a rolled back portion of the original document. A *rolled back* document is the original portion of the document when it is digitally signed. This functionality is used for document modification detection. A rolled back document still requires authorization data which should be identical to the original document's. However, the `authDataP` structure is unique to each security handler; therefore, it cannot be duplicated by the application. This callback is intended for opening a rolled back document silently by asking the security handler to provide authorization data for it. The security handler should be able to duplicate the security data associated with the original document and supply for the rolled back document. The callee is expected to authorize subsequent callbacks, including Crypt Filters. If this callback is not provided, the security handler is asked for authorization data via a normal call such as PDCryptGetAuthDataExProc(). The side effect might include the security handler's prompting for a password for the rolled back document.

#### PDCryptNewSecurityDataProc

```cpp
typedef void *(*) PDCryptNewSecurityDataProc(PDDoc pdDoc, CosObj encryptDict)(PDDoc pdDoc, CosObj encryptDict)
```

Header: `PDExpT.h:4558`

(Optional) A callback for PDCryptHandler. It creates and populates a new structure that contains whatever security-related information the security handler requires (for example, permissions, whether the file has owner and/or user passwords, owner and/or user passwords, or other data used internally by the security handler). If `encryptDict` is not `NULL`, the structure should be populated based on the `encryptDict` parameter's contents. This method is intended only to initialize the security data structure. This callback is called under two circumstances: • When a document is opened, it is called with encryptDict set to the document's Encryption dictionary. The handler should then populate the new security data structure with data that is obtained from the Encryption dictionary. • When the user chooses a new encryption method, it is called without an encryptDict. The handler should return a security data structure with default values. If a security handler does not have this callback, the document's `newSecurityData` field is set to `NULL`. If a file is to be saved, then PDCryptUpdateSecurityDataProc() is subsequently called to allow user interface modification of the contents. Security data is freed using PDCryptFreeSecurityDataProc(). If PDCryptFreeSecurityDataProc() is not defined, ASfree() is used.

**See also:** [`PDCryptFreeSecurityDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFreeSecurityDataProc)

#### PDCryptReservedProc

```cpp
typedef void *(*) PDCryptReservedProc(void)(void)
```

Header: `PDExpT.h:4856`

(Optional) A callback for PDCryptHandler. It is used by the Acrobat WebBuy proprietary method of passing crypt data.

#### PDCryptReservedProc2

```cpp
typedef void *(*) PDCryptReservedProc2(PDDoc pdDoc, ASCab settings)(PDDoc pdDoc, ASCab settings)
```

Header: `PDExpT.h:4939`

(Optional) Used by Acrobat for Automated Permission Testing.

#### PDCryptUpdateSecurityDataProc

```cpp
typedef ASBool(*) PDCryptUpdateSecurityDataProc(PDDoc pdDoc, ASAtom *cryptHandler, void **secDataP)(PDDoc pdDoc, ASAtom *cryptHandler, void **secDataP)
```

Header: `PDExpT.h:4619`

A callback for PDCryptHandler. It updates the security data structure that was created by PDCryptNewSecurityDataProc(). This structure can be obtained by calling PDDocGetNewSecurityData(). The security data structure of the previously saved file can be obtained with a call to PDDocGetSecurityData(). The security data structure should be updated to reflect the encryption parameters that will be used when saving the file (this information is usually obtained via dialogs). The encryption parameters are transferred to the Encrypt dictionary by a subsequent callback to PDCryptFillEncryptDictProc(). The security data should be allocated by ASmalloc() or a related function. Security data is freed using PDCryptFreeSecurityDataProc(). If PDCryptFreeSecurityDataProc() is not defined, ASfree() is used. The callback can also update the security handler itself. For example, the standard encryption handler switches to no encryption if no passwords or permissions are set in the security dialog box. Return ASAtomNull in `cryptHandler` if no encryption is used in the saved file.

**See also:** [`PDCryptValidateSecurityDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptValidateSecurityDataProc), [`PDDocGetSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetSecurityData)

#### PDCryptValidateSecurityDataProc

```cpp
typedef void(*) PDCryptValidateSecurityDataProc(PDDoc pdDoc, void *secData)(PDDoc pdDoc, void *secData)
```

Header: `PDExpT.h:4582`

(Optional) A callback for PDCryptHandler. It validates the security data structure, which specifies the user's permissions. This callback may modify the security data structure (for example, because the user is not authorized to change the security as they requested). A client may have called PDDocNewSecurityData() to obtain a new security data structure, then modified it, and then called PDDocSetNewSecurityData() to change the document security. This callback should be called before actually setting the document's security data. This callback is not called automatically by the Acrobat viewer. It must be called, if desired, by the security handler's PDCryptUpdateSecurityDataProc().

**See also:** [`PDCryptUpdateSecurityDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptUpdateSecurityDataProc), [`PDDocNewSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocNewSecurityData), [`PDDocSetNewSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewSecurityData)

### Structures (3)

#### PDCryptBatchHandler

```cpp
typedef struct _t_PDCryptBatchHandler* PDCryptBatchHandler
```

Header: `PDExpT.h:5288`

#### PDCryptFilterHandler

```cpp
typedef struct _t_PDCryptFilterHandler* PDCryptFilterHandler
```

Header: `PDExpT.h:5192`

#### PDCryptHandler

```cpp
typedef struct _t_PDCryptHandler* PDCryptHandler
```

Header: `PDExpT.h:5519`

### Definitions (1)

#### PDCryptFilterStringProc

Header: `PDExpT.h:5155`

Value: `CosCryptStringProc`

## PDDoc

### Functions (121)

#### PDDocAcquire

```cpp
void PDDocAcquire(PDDoc doc)
```

Header: `PDProcs.h:1394`

Increments a document's reference count. The document will not be closed until the reference count is zero, or the application terminates.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose reference count is incremented.

**Returns:** `void`

**See also:** [`PDDocRelease`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRelease)

#### PDDocAcquirePage

```cpp
PDPage PDDocAcquirePage(PDDoc doc, ASInt32 pageNum)
```

Header: `PDProcs.h:1565`

Gets a PDPage from a document. It increments the page's reference count. After you are done using the page, release it using PDPageRelease(). If PDPageRelease() is not called, it could block the document containing the page from being closed. To avoid such problems, use the `CSmartPDPage` class, as it ensures that the page is released as it goes out of scope.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document containing the page to acquire.
- `pageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number of the page to acquire. The first page is `0`.

**Returns:** [`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)

The acquired page.

**Exceptions**

- `genErrBadParm`

**See also:** `CSmartPDPage`, [`PDPageRelease`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRelease)

#### PDDocAddJobID

```cpp
void PDDocAddJobID(PDDoc doc, ASInt32 jobId)
```

Header: `PDProcs.h:12839`

Adds a print job identifier, or JobId, from the print job to the PDDoc's list of associated jobIds.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose jobId is being set.
- `jobId` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The job Id being added to the document's list of job ids.

**Returns:** `void`

#### PDDocAddThread

```cpp
void PDDocAddThread(PDDoc doc, ASInt32 addAfterIndex, PDThread thread)
```

Header: `PDProcs.h:1865`

Adds an article thread to a document after the specified thread index.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document in which the thread is added. It must match the document used in the call to PDThreadNew() that created the thread.
- `addAfterIndex` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The index of the thread after which `thread` is added.
- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): IN/OUT The thread to add. @notify PDDocDidAddThread

**Returns:** `void`

**See also:** [`PDThreadNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadNew), [`PDThreadFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadFromCosObj), [`PDDocRemoveThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemoveThread)

#### PDDocAddWatermarkFromPDPage

```cpp
void PDDocAddWatermarkFromPDPage(PDDoc pdDoc, PDPage pdPage, PDDocAddWatermarkParamsRec *pParams)
```

Header: `PDProcs.h:11313`

Adds a PDPage as a watermark to a page range in the given document.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document onto which the watermark will be added.
- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to be added as a watermark.
- `pParams` (`PDDocAddWatermarkParamsRec *`): Structure specifying how the watermark should be added to the document.

**Returns:** `void`

#### PDDocAddWatermarkFromText

```cpp
void PDDocAddWatermarkFromText(PDDoc pdDoc, PDDocWatermarkTextParamsRec *pTextParams, PDDocAddWatermarkParamsRec *pParams)
```

Header: `PDProcs.h:11321`

Adds a text-based watermark to a page range in the given document.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document onto which the watermark will be added.
- `pTextParams` (`PDDocWatermarkTextParamsRec *`): Structure describing the text-based watermark to be added.
- `pParams` (`PDDocAddWatermarkParamsRec *`): Structure specifying how the watermark should be added to the document.

**Returns:** `void`

#### PDDocApplyRedactions

```cpp
ASBool PDDocApplyRedactions(PDDoc pdDoc, PDApplyRedactionParams applyParams)
```

Header: `PDProcs.h:11937`

Applies a set of redaction marks to the document, permanently removing the affected document content and the marks themselves.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document to which the redaction marks should be applied.
- `applyParams` (`PDApplyRedactionParams`): IN/OUT A pointer to a `PDApplyRedactionParams` specifying which redaction marks to apply and what parameters to use when applying them. If `NULL`, then all redaction marks present in the document will be applied.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the document's content was changed, `false` otherwise.

**Exceptions**

- `pdErrBadAnnotation`: is raised if any specified redaction marks are invalid

**See also:** [`PDDocCreateRedaction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateRedaction), [`PDRedactionGetProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRedactionGetProps), [`PDRedactionSetProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRedactionSetProps)

#### PDDocAuthorize

```cpp
PDPerms PDDocAuthorize(PDDoc pdDoc, PDPerms permsWanted, void *authData)
```

Header: `PDProcs.h:2433`

Deprecated in Acrobat 7.0. Use PDDocPermRequest() instead. Adds permissions to the specified document, if permitted. It calls the PDCryptAuthorizeProc() callback of the document's security handler to determine which of the specified permissions will actually be granted. After calling this method, the document's permissions will be the `OR` of the previous permissions and the permissions granted by the PDCryptAuthorizeProc() callback. Use PDDocPermRequest() to determine if a document's permissions allow a particular operation for a particular object.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document for which new permissions are
  requested.
- `permsWanted` ([`PDPerms`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPerms)): The new permissions being requested.
  It must be an `OR` of the PDPerms values.
- `authData` (`void *`): A pointer to data to pass to the PDCryptAuthorizeProc()
  callback of the document's security handler. For the Acrobat
  viewer's built-in security handler, `authData` is a `char*`
  containing the password.`OR` of the previous value of the document's permissions
  field, and the permissions granted by the PDCryptAuthorizeProc()
  callback of the document's security handler. The result
  will be an `OR` of the PDPerms values.

**Returns:** [`PDPerms`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPerms)

**Exceptions**

- `pdErrNeedCryptHandler`: is raised if no security handler is associated
  with `pdDoc`. It also raises whatever exceptions are raised by the security
  handler's PDCryptAuthorizeProc() callback.

**See also:** [`PDDocGetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewCryptHandler), `PDDocGetPermissions (obsolete)`, [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest), [`PDDocSetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandler), [`PDDocSetNewCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandlerEx), [`PDRegisterCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandler), [`PDRegisterCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandlerEx)

#### PDDocClearErrors

```cpp
void PDDocClearErrors(PDDoc doc)
```

Header: `PDProcs.h:12732`

Clears all the non-fatal errors encountered since the document was opened, or `PDDocClearErrors` was called.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the non-fatal errors have occurred.

**Returns:** `void`

#### PDDocClearFlags

```cpp
void PDDocClearFlags(PDDoc doc, ASInt32 flags)
```

Header: `PDProcs.h:5435`

Clears flags associated with a document. This method is most frequently used to mark a modified document as clean (by clearing the PDDocNeedsSave flag) to avoid bringing up the Save dialog box when the file is closed.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose flags are cleared.
- `flags` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The flags to clear. It must be an `OR` of the PDDocFlags values.

**Returns:** `void`

**See also:** [`PDDocSave`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSave), [`PDDocClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClose), [`PDDocGetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetFlags), [`PDDocSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetFlags)

#### PDDocClose

```cpp
void PDDocClose(PDDoc doc)
```

Header: `PDProcs.h:1383`

Closes a document and releases its resources. If `doc` is `NULL`, it does nothing. Changes are not saved. You must use PDDocSave() to save any modifications before calling PDDocClose(). If the document has been modified but you wish to mark it as clean, use PDDocClearFlags().

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document to close.

**Returns:** `void`

**Exceptions**

- `pdErrUnableToCloseDueToRefs`: is raised if there are any outstanding references to objects in the document, and the document will still be valid (its resources will not be released).
- `genErrBadUnlock`: is raised if the document's open count is less than one.

**See also:** [`PDDocSave`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSave), [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreate), [`PDDocClearFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClearFlags), [`PDDocSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetFlags)

#### PDDocCopyToFile

```cpp
void PDDocCopyToFile(PDDoc pdDoc, PDDocCopyParams params)
```

Header: `PDProcs.h:7821`

This method copies bytes from a document's ASFile to a specified location. This also happens if the saveChanges field is set to "false." If saveChanges is set to "true," and the user has opened the file in Adobe Acrobat, a full save is completed for the file. That way, if the version of the document in system memory is more current than the original version on the disk drive (the original version of the file is stale, or 'dirty'), the save process assembles all of the recent changes to the document and applies them to the final saved copy. The resulting file is linearized, or optimized for display in a web browser. If the file already exists, it is overwritten.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document to copy.
- `params` (`PDDocCopyParams`): A structure that defines how the PDF file is copied.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if an invalid argument is passed in params.
- `pdErrAlreadyOpen`: is raised if the target and source files are the same.
- `fileErrDiskFull`: is raised if there is no space for the copy.
- `pdErrCancelSave`: is raised if the save was canceled (`cancelProc` in `params` returned `true`).
- `pdErrUnableToRead`: is raised if a read error occurred on the source.
- `pdErrUnableToWrite`: is raised if a write error occurred on the destination.

#### PDDocCreate

```cpp
PDDoc PDDocCreate(void)
```

Header: `PDProcs.h:1283`

Creates a new document. The only Cos object in the document will be a Catalog. See the description of Document Structure in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.7, page 70. You can find this document on the web store of the International Standards Organization (ISO). After the document is created, at least one page must be added using PDDocCreatePage() or PDDocInsertPages() before the Acrobat viewer can display or save the document. When you are done with the document, you must call PDDocClose() to release the resources used by the PDDoc; do not call PDDocRelease().

**Parameters**

- (unnamed) (`void`)

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

The newly created document.

**See also:** [`PDDocClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClose), [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocSave`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSave), [`PDDocCreatePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreatePage), [`PDDocInsertPages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocInsertPages)

#### PDDocCreateNameTree

```cpp
PDNameTree PDDocCreateNameTree(PDDoc thePDDoc, ASAtom theTree)
```

Header: `PDProcs.h:7081`

Retrieves the name tree inside the Names dictionary with the specified key name, or creates it if it does not exist.

**Parameters**

- `thePDDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the name tree is created.
- `theTree` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The name of the name tree to create. A string can be converted to an ASAtom using ASAtomFromString().

**Returns:** [`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)

The newly created PDNameTree for the PDDoc. It returns a `NULL` PDNameTree if `pdDoc` has no root dictionary. The return value should be tested with PDNameTreeIsValid().

**See also:** [`PDNameTreeIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeIsValid), [`PDDocGetNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNameTree), [`PDDocRemoveNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemoveNameTree)

#### PDDocCreatePDCollection

```cpp
PDCollection PDDocCreatePDCollection(PDDoc pdDoc)
```

Header: `PDProcs.h:12329`

Creates a collection in a document. It replaces any existing collection.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document that will host the new collection.

**Returns:** [`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)

The new collection object.

#### PDDocCreatePage

```cpp
PDPage PDDocCreatePage(PDDoc doc, ASInt32 afterPageNum, ASFixedRect mediaBox)
```

Header: `PDProcs.h:1590`

Creates and acquires a new page. The page is inserted into the document at the specified location. Call PDPageRelease() when you are done using the page.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the page is created.
- `afterPageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number after which the new page is inserted. The first page is `0`. Use PDBeforeFirstPage() (see `PDExpT.h`) to insert the new page at the beginning of a document.
- `mediaBox` (`ASFixedRect`): A rectangle specifying the page's media box, specified in user space coordinates.

**Returns:** [`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)

The newly created page. @notify PDDocWillInsertPages @notify PDDocDidInsertPages @notify PDDocDidChangePages @notify PDDocDidChangeThumbs

**See also:** [`PDPageRelease`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRelease), [`PDDocDeletePages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocDeletePages), [`PDDocInsertPages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocInsertPages), [`PDDocReplacePages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocReplacePages)

#### PDDocCreateRedaction

```cpp
PDAnnot PDDocCreateRedaction(PDDoc pdDoc, PDRedactParams redactionProps)
```

Header: `PDProcs.h:11952`

Creates a redaction mark on a given page. The resulting annotation will be added to the page, but the affected content will not be removed until `PDDocApplyRedactions` is called with this mark.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document for which the new redaction mark should be created.
- `redactionProps` (`PDRedactParams`): IN A set of properties to be used for the new redaction mark.

**Returns:** [`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)

The new annotation representing the redaction mark.

**Exceptions**

- `genErrBadParm`: is raised if `redactionProps` is `NULL` or if contains an invalid page number or an empty list of quads.

**See also:** [`PDDocApplyRedactions`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocApplyRedactions), [`PDRedactionGetProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRedactionGetProps), [`PDRedactionSetProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRedactionSetProps)

#### PDDocCreateTextSelect

```cpp
PDTextSelect PDDocCreateTextSelect(PDDoc doc, ASInt32 pageNum, ASFixedRect *boundingRect)
```

Header: `PDProcs.h:2277`

Creates a text selection that includes all words totally or partially enclosed by a rectangle. The text selection can then be set as the current selection using AVDocSetSelection(). **Note:** When this method is used to create a text selection on a rotated page, you must pass in a rotated `boundingRect`.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which a text selection is created.
- `pageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number on which the text selection is created.
- `boundingRect` (`ASFixedRect *`): A pointer to a rectangle specifying the text selection's bounding rectangle, specified in user space coordinates.

**Returns:** [`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)

The newly created text selection.

**See also:** [`PDTextSelectDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectDestroy), `AVDocSetSelection`, [`PDTextSelectEnumQuads`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumQuads), [`PDTextSelectEnumText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumText), [`PDWordCreateTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordCreateTextSelect)

#### PDDocCreateTextSelectUCS

```cpp
PDTextSelect PDDocCreateTextSelectUCS(PDDoc doc, ASInt32 pageNum, ASFixedRect *fxBoundingRectP)
```

Header: `PDProcs.h:12898`

Creates a text selection that includes all words totally or partially enclosed by a rectangle. The text selection can then be set as the current selection using AVDocSetSelection(). **Note:** When this method is used to create a text selection on a rotated page, you must pass in a rotated `boundingRect`.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which a text selection is created.
- `pageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number on which the text selection is created.
- `fxBoundingRectP` (`ASFixedRect *`)

**Returns:** [`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)

The newly created text selection.

**See also:** [`PDTextSelectDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectDestroy), `AVDocSetSelection`, [`PDTextSelectEnumQuads`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumQuads), [`PDTextSelectEnumText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumText), [`PDWordCreateTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordCreateTextSelect)

#### PDDocCreateThumbs

```cpp
void PDDocCreateThumbs(PDDoc doc, ASInt32 firstPage, ASInt32 lastPage, PDThumbCreationServer server, void *serverClientData, ASAtom colorSpace, ASInt32 bitsPerComponent, ASInt32 hiVal, char *lookupTable, ProgressMonitor progMon, void *progMonClientData, CancelProc cancelProc, void *cancelProcClientData)
```

Header: `PDProcs.h:2005`

Creates thumbnail images for the specified range of pages. Thumbnail images are only created for pages that have none. Use as large a page range as possible, because the color space object is shared by all the thumbnails created by a single invocation of this method. This means that if you call this method separately for each page, there will be duplicate color space objects. See the description of Color Spaces in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 8.6, page 139. You can find this document on the web store of the International Standards Organization (ISO). See *Developing Plug-ins and Applications* for additional important information about creating thumbnails. • `sizeof(ASUns8)` • `3`, where the `3` arises because an RGB color space has three color components. @notify PDDocDidChangeThumbs

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document for which thumbnail images are created.
- `firstPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The page number of the first page for which thumbnails are created. The first page is `0`.
- `lastPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The page number of the last page for which thumbnails are created. The constant PDLastPage (see `PDExpT.h`) can also be used.
- `server` ([`PDThumbCreationServer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThumbCreationServer)): IN/OUT A server (set of callback procedures) that provides the sampled image used as the thumbnail image. Pass `NULL` to use the default server.
- `serverClientData` (`void *`): IN/OUT User-supplied data to pass to the thumbnail creation server.
- `colorSpace` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): IN/OUT The color space in which the thumbnail data is represented. It must be `DeviceRGB`. Thumbnails may be created in either a direct or an indexed color space; however, it is strongly recommended that you use indexed color spaces over direct color spaces. Using direct color spaces with this version of Acrobat may cause bad looking thumbnails. To specify a direct color space, pass `0` for `hiVal` and `NULL` for `lookupTable`. To specify an indexed color space, pass the appropriate values in `hiVal` and `lookupTable`. Direct color spaces on Windows are supported in Acrobat.
- `bitsPerComponent` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The number of bits per color component in the thumbnail image's data. `8` is the only valid value.
- `hiVal` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT Used only for indexed color space; pass `0` for direct color spaces, as described in `colorSpace`. `hiVal` specifies the highest valid index in `lookupTable`. Because indices start at `0`, the number of entries in `lookupTable` is `hiVal + 1`. `hiVal` must be `0` for device color spaces.
- `lookupTable` (`char *`): IN/OUT Used only for indexed color space; pass `NULL` for direct color spaces, as described in `colorSpace`. `lookupTable` is a table that maps data values to colors. It is used only for indexed color spaces. It must be `NULL` for device color spaces. For an indexed color space, the size of the lookup table must be `(hiVal + 1)`:
- `progMon` ([`ProgressMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ProgressMonitor)): IN/OUT A monitor to call to display thumbnail creation progress. Use AVAppGetDocProgressMonitor() to obtain the standard progress monitor to pass for this parameter. `NULL` may be passed, in which case no progress monitor is used.
- `progMonClientData` (`void *`): IN/OUT A user-supplied data to pass to `progMon` each time it is called. It should be `NULL` if `progMon` is `NULL`.
- `cancelProc` ([`CancelProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#CancelProc)): IN/OUT A procedure to call frequently to allow the user to cancel thumbnail creation. Use AVAppGetCancelProc() to obtain the default cancel proc for this parameter. It may be `NULL`, in which case no cancel proc is used.
- `cancelProcClientData` (`void *`): IN/OUT A user-supplied data to pass to `cancelProc` each time it is called. It should be `NULL` if `cancelProc` is `NULL`.

**Returns:** `void`

**See also:** [`PDDocDeleteThumbs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocDeleteThumbs)

#### PDDocCreateWordFinder

```cpp
PDWordFinder PDDocCreateWordFinder(PDDoc doc, ASUns16 *outEncInfo, char **outEncVec, char **ligatureTbl, ASInt16 algVersion, ASUns16 rdFlags, void *clientData)
```

Header: `PDProcs.h:2199`

Creates a word finder that is used to extract text in the host encoding from a PDF file. The word finder may either be used by PDWordFinderEnumWords() (which enumerates words one-by-one) or by PDWordFinderAcquireWordList() (which fills a table with all the words on a page). After you are done using the WordFinder, you must release it with PDWordFinderDestroy(). A default ligature table is used, containing the following ligatures: • fi • ff • fl • ffi • ffl • ch • cl • ct • ll • ss • fs • st • oe • OE The glyph name is substituted for the ligature. This method also works for non-Roman (CJK or Chinese-Japanese-Korean) viewers. In this case, words are extracted to the host encoding. Developers desiring Unicode output must use PDDocCreateWordFinderUCS(), which does the extraction for Roman or non-Roman text. The type of PDWordFinder determines the encoding of the string returned by PDWordGetString(). For instance, if PDDocCreateWordFinderUCS() is used to create the word finder, PDWordGetString() returns only Unicode. For CJK viewers, words are stored internally using CID encoding. See the description of Composite Fonts and CID fonts in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7, page 267. You can find this document on the web store of the International Standards Organization (ISO). For detailed information on CIDFonts, see: Technical Note #5092, CID-Keyed Font Technology Overview [https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5092.CID_Overview.pdf](https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5092.CID_Overview.pdf) Technical Note #5014, Adobe CMap and CIDFont Files Specification [https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf](https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf) [https://www.adobe.com/jp/print/postscript/pdfs/PLRM.pdf](https://www.adobe.com/jp/print/postscript/pdfs/PLRM.pdf) If `outEncVec` is `NULL`, the platform's default encoding vector is used. For non-UNIX Roman systems, it is `WinAnsiEncoding` on Windows and `MacRomanEncoding` on Mac OS. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`. For descriptions of `WinAnsiEncoding` and `MacRomanEncoding`, and `PDFDocEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). Use this parameter with `outEncInfo`. See `outEncInfo` for more information.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document on which the word finder is used.
- `outEncInfo` ([`ASUns16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)): An array of 256 flags, specifying the type of character at each position in the encoding. Each flag is an `OR` of the Character Type Codes. If `outEncInfo` is `NULL`, the platform's default encoding info is used. Use `outEncInfo` and `outEncVec` together; for every `outEncInfo` use a corresponding `outEncVec` to specify the character at that position in the encoding. Regardless of the characters specified in `outEncInfo` as word separators, a default set of word separators is used (see Glyph Names of Word Separators). There is no way to change the list of characters that are considered to be word separators.
- `outEncVec` (`char **`): Array of 256 `NULL`-terminated strings that are the glyph names in encoding order. See the discussion of character names in the *PostScript Language Reference Manual*.
- `ligatureTbl` (`char **`): A `NULL`-terminated array of `NULL`-terminated
  strings. Each string is the glyph name of a ligature in
  the font. When a word contains a ligature, the glyph name
  of the ligature is substituted for the ligature (for example,
  `ff` is substituted for the ff ligature). This table must
  be terminated with `NULL`. If `ligatureTbl` is `NULL`, a default
  ligature table is used, containing the following ligatures:

  fi
  ff
  fl
  ffi
  ffl
  ch
  cl
  ct
  ll
  ss
  fs
  st
  oe
  OE
- `algVersion` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): The version of the word-finding algorithm
  to use (see PDExpT.h), as follows (pass `0` if your client
  does not care):

  Version

  Description

  `WF_LATEST_VERSION`

  To obtain the latest available version.

  `WF_VERSION_2`

  Version used for Acrobat 3.x, 4.x.

  `WF_VERSION_3`

  Available in Acrobat 5.0 without accessibility enabled. Includes some improved word-piecing algorithms.

  `WF_VERSION_4`

  For Acrobat 5.0 with accessibility enabled. Includes advanced word-ordering algorithms in addition to improved word-piecing algorithms.

  **Note:** The word finder also extracts text from Form XObjects that are executed in the page contents. See the description of Form XObjects in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 8.10, page 217.

  You can find this document on the web store of the International Standards Organization (ISO).

  GlyphNames CharacterTypeCodes WordFinderSortOrderFlags
- `rdFlags` ([`ASUns16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)): Word-finding options that determine the tables filled when using PDWordFinderAcquireWordList(). It must be an `OR` of one or more of the WordFinder Sort Order Flags. In Acrobat 5.0 this parameter is ignored and you should pass in `NULL`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to the newly created word finder.

**Returns:** [`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)

The newly created word finder.

**See also:** [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords), [`PDWordFinderAcquireWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireWordList), [`PDWordFinderDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderDestroy), [`PDWordFilterWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFilterWord)

#### PDDocCreateWordFinderEx

```cpp
PDWordFinder PDDocCreateWordFinderEx(PDDoc doc, ASInt16 algVersion, ASBool outUnicode, PDWordFinderConfig wbConfig)
```

Header: `PDProcs.h:8412`

This is a version 6.0 replacement for PDDocCreateWordFinder() and PDDocCreateWordFinderUCS() that adds configurable word-breaking behavior. This method creates a word finder that is used to extract text from a PDF file, according to the given configuration. The word finder can be used to enumerate words one-by-one or to fill a table with all the words on a page. You can choose to find only words that are visible in a given context. You can use version 6.0 methods such as PDWordGetCharOffsetEx() to extract character information from words if you create the word finder with WF_VERSION_3 or later. After you are done using the WordFinder, you must release it with PDWordFinderDestroy(). Annotation Use WF_LATEST_VERSION To obtain latest available version. WF_VERSION_2 Version used for Acrobat 3.x, 4.x. WF_VERSION_3 Available in Acrobat 5.0 and 6.0 without Tagged PDF support. WF_VERSION_4 For Acrobat 5.0 and 6.0 with Tagged PDF support. **Note:** The word finder also extracts text from Form XObjects that are executed in the page contents. See the description of Form XObjects in the ISO 32000-1:2008, Document Management- Portable Document Format-Part 1: PDF 1.7, section 8.10, page 217. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document on which the word finder is used.
- `algVersion` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): The version of the word-finding algorithm to use (see `PDExpT.h`), as follows (pass `0` if your client does not care):
- `outUnicode` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Whether to return Unicode. When `true`, the word finder encodes the extracted text in Unicode format. Otherwise, the word finder extracts the text in the host encoding.
- `wbConfig` (`PDWordFinderConfig`): A pointer to a configuration record for the new word finder that customizes the way the extraction is performed. The configuration is only used if the algorithm version is WF_VERSION_3 or higher. When it is `NULL`, the default configuration is used.

**Returns:** [`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)

The newly created word finder object.

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords), [`PDWordFinderAcquireWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireWordList), [`PDWordFinderDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderDestroy), [`PDWordFilterWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFilterWord), [`PDWordGetCharOffsetEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharOffsetEx)

#### PDDocCreateWordFinderUCS

```cpp
PDWordFinder PDDocCreateWordFinderUCS(PDDoc doc, ASInt16 algVersion, ASUns16 rdFlags, void *clientData)
```

Header: `PDProcs.h:6621`

Creates a word finder that is used to extract text in Unicode format from a PDF file. The word finder may either be used by PDWordFinderEnumWords() (which enumerates words one-by-one) or by PDWordFinderAcquireWordList() (which fills a table with all the words on a page). After you are done using the WordFinder, you must release it with PDWordFinderDestroy(). PDDocCreateWordFinder() also works for non-Roman character set viewers. For PDDocCreateWordFinder(), words are extracted to the host encoding. Users desiring Unicode output should use PDDocCreateWordFinderUCS(). The type of PDWordFinder determines the encoding of the string returned by PDWordGetString(). If PDDocCreateWordFinderUCS() is used to create the word finder, PDWordGetString() returns only Unicode. Note that there is no way to detect Unicode strings returned by PDWordGetString(), since there is no UCS header (FEFF) added to each string returned. In CJK viewers, words are stored internally using CID encoding. See the description of Composite Fonts and CIDFonts in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7, page 267. You can find this document on the web store of the International Standards Organization (ISO). For detailed information on CIDFonts, see: Technical Note #5092, CID-Keyed Font Technology Overview [https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5092.CID_Overview.pdf](https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5092.CID_Overview.pdf) Technical Note #5014, Adobe CMap and CIDFont Files Specification [https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf](https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf) **Note:** The word finder also extracts text from Form XObjects that are executed in the page contents. See the description of Form XObjects in the ISO 32000-1:2008, Document Management- Portable Document Format-Part 1: PDF 1.7, section 8.10, page 217. You can find this document on the web store of the International Standards Organization (ISO). **Note:** PDDocCreateWordFinderUCS() is useful for converting non-Roman text (CJK or Chinese-Japanese-Korean) to Unicode. This method also converts Roman text to Unicode in any document. WordFinderSortOrderFlags

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document on which the word finder is used.
- `algVersion` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): The version of the word-finding algorithm to use. If it is WF_LATEST_VERSION (see `PDExpT.h`), the most recent version is used. Set to `0` to ignore the version.
- `rdFlags` ([`ASUns16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)): Word-finding options that determine the tables filled when using PDWordFinderAcquireWordList(). It must be an `OR` of one or more of the WordFinder Sort Order Flags.
- `clientData` (`void *`): A pointer to user-supplied data to pass to the newly created word finder.

**Returns:** [`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)

The newly created word finder.

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords), [`PDWordFinderAcquireWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireWordList), [`PDWordFinderDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderDestroy), [`PDWordFilterWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFilterWord)

#### PDDocDeleteCollection

```cpp
void PDDocDeleteCollection(PDDoc pdDoc)
```

Header: `PDProcs.h:12334`

Removes a collection dictionary from a document.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose collection dictionary is to be removed.

**Returns:** `void`

#### PDDocDeletePages

```cpp
void PDDocDeletePages(PDDoc doc, ASInt32 firstPage, ASInt32 lastPage, ProgressMonitor progMon, void *progMonClientData)
```

Header: `PDProcs.h:1615`

Deletes the specified pages.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document from which pages are deleted.
- `firstPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number of the first page to delete. The first page is `0`.
- `lastPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number of the last page to delete.
- `progMon` ([`ProgressMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ProgressMonitor)): A progress monitor. Use AVAppGetDocProgressMonitor() to obtain the default progress monitor. `NULL` may be passed, in which case no progress monitor is used.
- `progMonClientData` (`void *`): A pointer to user-supplied data passed to `progMon` each time it is called. It should be `NULL` if progMon is `NULL`. @notify PDDocWillChangePages @notify PDDocWillDeletePages @notify PDDocDidDeletePages @notify PDDocDidChangePages

**Returns:** `void`

**See also:** [`PDDocInsertPages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocInsertPages), [`PDDocReplacePages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocReplacePages), [`PDDocMovePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocMovePage)

#### PDDocDeleteThumbs

```cpp
void PDDocDeleteThumbs(PDDoc doc, ASInt32 firstPage, ASInt32 lastPage, ProgressMonitor progMon, void *progMonClientData)
```

Header: `PDProcs.h:2028`

Deletes thumbnail images for a range of pages in a document.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document from which thumbnail images are deleted.
- `firstPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The page number of the first page in `doc` whose thumbnail image is deleted. The first page is `0`.
- `lastPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The page number of the last page in `doc` whose thumbnail image is deleted.
- `progMon` ([`ProgressMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ProgressMonitor)): IN/OUT A monitor to call to display thumbnail deletion progress. Use AVAppGetDocProgressMonitor() to obtain the standard progress monitor to pass for this parameter. `NULL` may be passed, in which case no progress monitor is used.
- `progMonClientData` (`void *`): IN/OUT A pointer to user-supplied data to pass to `progMon`. It should be `NULL` if `progMon` is `NULL`. @notify PDDocDidChangeThumbs

**Returns:** `void`

**See also:** [`PDDocCreateThumbs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateThumbs)

#### PDDocEnumFonts

```cpp
void PDDocEnumFonts(PDDoc doc, ASInt32 firstPage, ASInt32 lastPage, PDFontEnumProc eproc, void *clientData, ProgressMonitor progMon, void *progMonClientData)
```

Header: `PDProcs.h:1907`

Enumerates all the fonts in the specified page range. This may take a considerable amount of time for a large page range.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose fonts are enumerated.
- `firstPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number of the first page for which fonts are enumerated. The first page is `0`.
- `lastPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number of the last page for which fonts are enumerated.
- `eproc` ([`PDFontEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontEnumProc)): A user-supplied callback to call for each font. Enumeration terminates if `eproc` returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `eproc` each time it is called.
- `progMon` ([`ProgressMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ProgressMonitor)): A progress monitor. Use AVAppGetDocProgressMonitor() to obtain the standard progress monitor. `NULL` may be passed, in which case no progress monitor is used.
- `progMonClientData` (`void *`): A pointer to user-supplied data to pass to `progMon` each time it is called. It should be `NULL` if `progMon` is `NULL`.

**Returns:** `void`

**See also:** [`PDDocEnumLoadedFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumLoadedFonts), [`PDFontEnumCharProcs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontEnumCharProcs)

#### PDDocEnumLoadedFonts

```cpp
void PDDocEnumLoadedFonts(PDDoc doc, PDFontEnumProc proc, void *clientData)
```

Header: `PDProcs.h:1926`

Enumerates all the fonts that have been encountered so far. A font is loaded when a page that uses it is processed. This typically happens when a page is drawn or its thumbnail image is created.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose loaded fonts are enumerated.
- `proc` ([`PDFontEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontEnumProc)): IN/OUT A user-supplied callback to call for each loaded font. Enumeration terminates if `proc` returns `false`.
- `clientData` (`void *`): IN/OUT A pointer to user-supplied data to pass to `proc` each time it is called.

**Returns:** `void`

**See also:** [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts), [`PDFontEnumCharProcs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontEnumCharProcs)

#### PDDocEnumOCConfigs

```cpp
void PDDocEnumOCConfigs(PDDoc pdDoc, PDOCConfigEnumProc enumProc, void *clientData)
```

Header: `PDProcs.h:10305`

Enumerates the optional-content configurations for the document, calling the supplied procedure for each one. These include the configuration for the D configuration dictionary and those for all entries in the Configs array dictionary.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose configurations are enumerated.
- `enumProc` ([`PDOCConfigEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigEnumProc)): A user-supplied callback to call for each configuration. Enumeration terminates if `enumProc` returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `proc` each time it is called.

**Returns:** `void`

**See also:** [`PDDocGetOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCConfig), [`PDDocEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCGs)

#### PDDocEnumOCGs

```cpp
void PDDocEnumOCGs(PDDoc pdDoc, PDOCGEnumProc enumProc, void *clientData)
```

Header: `PDProcs.h:9195`

Enumerates the optional-content groups for the document, calling the supplied procedure for each one. Enumeration continues until all groups have been enumerated, or until `enumProc` returns `false`. Each group is reported once, even if it is referenced multiple times in a page, or on multiple pages.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose groups are enumerated.
- `enumProc` ([`PDOCGEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGEnumProc)): A user-supplied callback to call for each group. Enumeration terminates if `enumProc` returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `enumProc` each time it is called.

**Returns:** `void`

**See also:** [`PDDocGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCGs), [`PDDocEnumOCConfigs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCConfigs), [`PDPageEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumOCGs)

#### PDDocEnumResources

```cpp
void PDDocEnumResources(PDDoc pdDoc, ASInt32 startPage, ASInt32 endPage, ASAtom resourceType, CosObjEnumProc enumProc, void *clientData)
```

Header: `PDProcs.h:6783`

Enumerates the specified type of page resources, for a specified range of pages. This method enumerates resources in each page's Resources dictionary (ColorSpace resources, Fonts, ExtGState objects, or others). In addition, it looks inside in-line images and page contents to enumerate ColorSpace resources that are not in the Resources dictionary, such as DeviceGray, DeviceRGB, and DeviceCMYK. You can find this document on the web store of the International Standards Organization (ISO). Pass ASAtomNull to enumerate all resource types.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose resources are enumerated.
- `startPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The first page whose resources are enumerated. The first page in a document is `0`.
- `endPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The last page whose resources are enumerated.
- `resourceType` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): IN/OUT Resource type to enumerate. It must be one of the valid PDF resource types, such as Font, ColorSpace, XObject, Pattern, and so on. See the description of PDF resource types under "Resource Dictionaries" in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.8.3, page 83.
- `enumProc` ([`CosObjEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEnumProc)): IN/OUT A user-supplied callback to call once for each resource of the specified type. The resource is presented as a CosObj, and it is the first parameter of `enumProc` (the second parameter is unused).
- `clientData` (`void *`): IN/OUT User-supplied data to pass to `enumProc` each time it is called.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`
- `pdErrOpNotPermitted`

**See also:** [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts), [`PDEEnumElements`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDEEnumElements), [`PDELogDump`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDELogDump), [`PDEObjectDump`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDEObjectDump)

#### PDDocExportNotes

```cpp
CosDoc PDDocExportNotes(PDDoc doc, ASFileSys unused1, ASPathName unused2, void *unused3, void *unused4, PDDocWillExportAnnotCallback exportFilter, ASInt32 *numNotesP)
```

Header: `PDProcs.h:6840`

Creates a document containing empty pages plus text annotations (notes) from `sourceDoc`. It does not create a new document if `sourceDoc` contains no notes.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document from which notes are exported.
- `unused1` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): Currently unused.
- `unused2` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): Currently unused.
- `unused3` (`void *`): Currently unused.
- `unused4` (`void *`): Currently unused.
- `exportFilter` ([`PDDocWillExportAnnotCallback`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocWillExportAnnotCallback)): A user-supplied routine that selects which notes to export.
- `numNotesP` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): If non-`NULL`, the number of notes exported.

**Returns:** [`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)

The CosDoc of the document created to hold the exported notes. @notify PDDocWillExportAnnots @notify PDDocDidExportAnnots

**See also:** [`PDDocImportCosDocNotes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocImportCosDocNotes), [`PDDocImportNotes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocImportNotes), [`PDDocExportSomeNotes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocExportSomeNotes)

#### PDDocExportSomeNotes

```cpp
CosDoc PDDocExportSomeNotes(PDDoc doc, ASFileSys unused1, ASPathName unused2, void *unused3, void *unused4, PDDocWillExportAnnotCallback exportFilter, PDAnnotArray pdanArray, ASInt32 *numNotesP)
```

Header: `PDProcs.h:8136`

Like PDDocExportNotes(), but the caller provides the list of annotations to export. This is useful in scenarios when it may be inappropriate to use PDDocExportNotes() and look for annotations on every page. This is an especially important consideration when in a browser. **Note:** Make sure to explicitly include popups.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document from which notes are exported.
- `unused1` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): Currently unused.
- `unused2` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): Currently unused.
- `unused3` (`void *`): Currently unused.
- `unused4` (`void *`): Currently unused.
- `exportFilter` ([`PDDocWillExportAnnotCallback`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocWillExportAnnotCallback)): A user-supplied routine that selects which notes to export.
- `pdanArray` (`PDAnnotArray`): An array of `PDAnnotArrayRec` objects; the number of items in the arrray is the number of pages in `doc`.
- `numNotesP` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): (Filled by the method) If non-`NULL`, the number of notes exported.

**Returns:** [`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)

The CosDoc of the document created to hold the exported notes. @notify PDDocWillExportAnnots @notify PDDocDidExportAnnots

**See also:** `PDDocGetXAPMetadata`, [`PDDocImportNotes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocImportNotes), [`PDDocExportNotes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocExportNotes)

#### PDDocFindPageNumForLabel

```cpp
ASInt32 PDDocFindPageNumForLabel(PDDoc pdDoc, const char *labelStr, ASInt32 labelLen)
```

Header: `PDProcs.h:7387`

Superseded by PDDocFindPageNumForLabelEx() in Acrobat 6.0. Finds the first page in the document with a specified label.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document to search for the page named in `labelStr`.
- `labelStr` (`const char *`): The label of the page to find.
- `labelLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length of `labelStr`.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The page number of the first page with the specified label, or `-1` if no such page exists.

**See also:** [`PDDocGetLabelForPageNum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetLabelForPageNum), [`PDDocGetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageLabel), [`PDDocRemovePageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemovePageLabel), [`PDDocSetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetPageLabel), [`PDPageLabelNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelNew)

#### PDDocFindPageNumForLabelEx

```cpp
ASInt32 PDDocFindPageNumForLabelEx(PDDoc pdDoc, ASConstText labelText)
```

Header: `PDProcs.h:11099`

Supersedes PDDocFindPageNumForLabel in Acrobat 6.0. Finds the first page in the document with a specified label.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document to search for the page named in `labelStr`.
- `labelText` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The label of the page to find.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The page number of the first page with the specified label, or `-1` if no such page exists.

**See also:** [`PDDocGetLabelForPageNumEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetLabelForPageNumEx), [`PDDocGetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageLabel), [`PDDocRemovePageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemovePageLabel), [`PDDocSetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetPageLabel), [`PDPageLabelNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelNew)

#### PDDocFlattenOC

```cpp
ASBool PDDocFlattenOC(PDDoc pdDoc, PDOCContext context)
```

Header: `PDProcs.h:10491`

Replaces the contents of every page in the document with a version that has no optional content, containing only what was visible on the page when the call was made, and removes all other optional-content information.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document to be modified.
- `context` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The optional-content context in which content is checked for visibility.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the operation is successful, `false` otherwise.

**See also:** [`PDPageFlattenOC`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageFlattenOC), [`PDEContentFlattenOC`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDEContentFlattenOC)

#### PDDocFromCosDoc

```cpp
PDDoc PDDocFromCosDoc(CosDoc cosDoc)
```

Header: `PDProcs.h:6743`

Gets the PDDoc associated with a CosDoc.

**Parameters**

- `cosDoc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The Cos-level document object for which a PDDoc is obtained. This object represents the PDF.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

The PDDoc associated with cosDoc.

**Exceptions**

- `genErrBadParm`: is raised if the CosDoc is not valid.
- `pdErrNoPDDocForCosDoc`: is raised if there is no PDDoc associated with this CosDoc.

**See also:** `AVDocGetPDDoc`, [`PDPageGetDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetDoc), [`PDDocGetCosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetCosDoc)

#### PDDocGetAdobePDFVersion

```cpp
AdobePDFVersion PDDocGetAdobePDFVersion(PDDoc doc)
```

Header: `PDProcs.h:12805`

PDDocGetAdobePDFVersion() returns the current version of the document in the AdobePDFVersion define in CosExp.T

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose version is obtained.

**Returns:** [`AdobePDFVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#AdobePDFVersion)

current version of document.

#### PDDocGetBookmarkRoot

```cpp
PDBookmark PDDocGetBookmarkRoot(PDDoc pdDoc)
```

Header: `PDProcs.h:1535`

Gets the root of the document's bookmark tree. The return value is valid even if the document's bookmark tree is empty (meaning that there is no Outlines key in the underlying PDF file).

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT Document whose root bookmark is obtained.

**Returns:** [`PDBookmark`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBookmark)

The document's root bookmark.

#### PDDocGetCosDoc

```cpp
CosDoc PDDocGetCosDoc(PDDoc doc)
```

Header: `PDProcs.h:1467`

Gets a document's Cos-level document object.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose CosDoc is obtained.

**Returns:** [`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)

The document's CosDoc.

**See also:** [`CosObjGetDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetDoc)

#### PDDocGetCryptHandler

```cpp
ASAtom PDDocGetCryptHandler(PDDoc doc)
```

Header: `PDProcs.h:11360`

Gets the specified document's current security handler (that is, the security handler that was used to open the document).

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose new security handler is obtained.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

The ASAtom corresponding to the name of the document's security handler. It returns ASAtomNull if the document does not have a current security handler.

**See also:** [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest), [`PDDocGetSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetSecurityData), [`PDDocSetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandler), [`PDDocSetNewCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandlerEx), [`PDRegisterCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandler), [`PDRegisterCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandlerEx)

#### PDDocGetCryptHandlerClientData

```cpp
void * PDDocGetCryptHandlerClientData(PDDoc pdDoc)
```

Header: `PDProcs.h:6117`

Gets the client data for the encryption handler associated with the PDDoc. This is the client data provided as a parameter in PDRegisterCryptHandlerEx().

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose encryption handler client data is obtained.

**Returns:** `void *`

Client data for the encryption handler associated with the PDDoc. It returns `NULL` if there is no encryption handler or no client data was provided.

**See also:** [`PDRegisterCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandlerEx)

#### PDDocGetCryptRevision

```cpp
ASInt32 PDDocGetCryptRevision(PDDoc pdDoc)
```

Header: `PDProcs.h:12725`

Sets the `cryptRevision` param based on the Security handler of the document. This is either retrieved directly from the Security handler or read from the encrypt dict.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The Crypt Revision retreived from the Security handler or encrypt dict or 0 if not found or not encrypted

#### PDDocGetCryptVersion

```cpp
ASInt32 PDDocGetCryptVersion(PDDoc pdDoc)
```

Header: `PDProcs.h:12717`

Sets the `cryptVersion` param based on the Security handler of the document. This is either retrieved directly from the Security handler or read from the encrypt dict.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The Crypt Version retreived from the Security handler or encrypt dict or 0 if not found or not encrypted

#### PDDocGetFile

```cpp
ASFile PDDocGetFile(PDDoc doc)
```

Header: `PDProcs.h:1475`

Gets the file object for a document.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose ASFile is obtained.

**Returns:** [`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)

The document's ASFile.

#### PDDocGetFlags

```cpp
ASInt32 PDDocGetFlags(PDDoc doc)
```

Header: `PDProcs.h:1418`

Gets information about the document's file and its state.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose flags are obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

Flags field, containing an `OR` of the PDDocFlags values.

**See also:** [`PDDocSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetFlags), [`PDDocClearFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClearFlags)

#### PDDocGetFullScreen

```cpp
ASBool PDDocGetFullScreen(PDDoc pdDoc)
```

Header: `PDProcs.h:6129`

Tests whether the document will open in full-screen mode. This provides an alternative to calling PDDocGetPageMode() to test for PDFullScreen.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document to test.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the PDDoc is in full-screen mode, `false` otherwise.

**See also:** [`PDDocSetFullScreen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetFullScreen)

#### PDDocGetID

```cpp
ASInt32 PDDocGetID(PDDoc doc, ASInt32 nElemNum, ASUns8 *buffer, ASInt32 bufferSize)
```

Header: `PDProcs.h:1501`

Gets an element of a document's file identifier. See the description of File Identifiers in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 14.4, page 551. You can find this document on the web store of the International Standards Organization (ISO). Value Description `0` The permanent ID. `1` The permanent ID.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose file ID is obtained.
- `nElemNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The element number to get from the document's file ID. It must be one of the following:
- `buffer` ([`ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): (Filled by the method) If `buffer` is non-`NULL`, then up to `bufferSize` bytes of the ID will be written to the buffer.
- `bufferSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length of `buffer` in bytes.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of bytes in the ID element.

#### PDDocGetLabelForPageNum

```cpp
ASInt32 PDDocGetLabelForPageNum(PDDoc pdDoc, ASInt32 pageNum, char *buffer, ASInt32 bufferLen)
```

Header: `PDProcs.h:7367`

Superseded by PDDocGetLabelForPageNumEx() in Acrobat 6.0. Retrieves the label string associated with the given page number. The page number is returned in host encoding and is truncated to the length of the buffer.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document containing the page for which a label is requested.
- `pageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of the page whose label is requested.
- `buffer` (`char *`): If a label exists for `pageNum`, it will be placed in this buffer.
- `bufferLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length of the label (`NULL`-terminated).

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The length of the resulting label. If no such page number exists, the resulting string will be the ASCII representation of `pageNum + 1`.

**See also:** [`PDDocGetLabelForPageNumEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetLabelForPageNumEx), [`PDDocFindPageNumForLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocFindPageNumForLabel), [`PDDocGetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageLabel), [`PDDocRemovePageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemovePageLabel), [`PDDocSetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetPageLabel), [`PDPageLabelNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelNew)

#### PDDocGetLabelForPageNumEx

```cpp
void PDDocGetLabelForPageNumEx(PDDoc pdDoc, ASInt32 pageNum, ASText text)
```

Header: `PDProcs.h:11080`

Supersedes PDDocGetLabelForPageNum() in Acrobat 6.0. Retrieves the label string associated with the given page number. The page number is returned in host encoding as a ASText object.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document containing the page for which a label is requested.
- `pageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of the page whose label is requested.
- `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): If a label exists for `pageNum`, it is returned in this object.

**Returns:** `void`

**See also:** [`PDDocFindPageNumForLabelEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocFindPageNumForLabelEx), [`PDDocGetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageLabel), [`PDDocRemovePageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemovePageLabel), [`PDDocSetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetPageLabel), [`PDPageLabelNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelNew)

#### PDDocGetLayoutMode

```cpp
PDLayoutMode PDDocGetLayoutMode(PDDoc doc)
```

Header: `PDProcs.h:11341`

Gets the value of the PageLayout key in the Catalog dictionary.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN The document whose layout mode is obtained.

**Returns:** [`PDLayoutMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLayoutMode)

Layout mode value from the PDF Catalog dictionary.

**See also:** [`PDDocSetLayoutMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetLayoutMode)

#### PDDocGetNameTree

```cpp
PDNameTree PDDocGetNameTree(PDDoc thePDDoc, ASAtom theTree)
```

Header: `PDProcs.h:7063`

Retrieves a name tree, with the key name specified in `theTree`, from the Names dictionary of `thePDDoc`.

**Parameters**

- `thePDDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document containing the name tree desired.
- `theTree` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): IN/OUT The name of the tree requested. This can be created by passing a string to the ASAtomFromString() method.

**Returns:** [`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)

The PDNameTree requested.

**See also:** [`PDNameTreeIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeIsValid), [`PDDocCreateNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateNameTree), [`PDDocRemoveNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemoveNameTree)

#### PDDocGetNewCryptHandler

```cpp
ASAtom PDDocGetNewCryptHandler(PDDoc doc)
```

Header: `PDProcs.h:2529`

Gets the specified document's new security handler (that is, the security handler that will be used after the document is saved). If the document does not have a new security handler, it returns the document's current security handler.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose new security handler is obtained.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

The ASAtom corresponding to the `pdfName` of the document's new security handler. It returns ASAtomNull if the document does not have a new security handler.

**See also:** [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest), [`PDDocSetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandler), [`PDDocSetNewCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandlerEx), [`PDRegisterCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandler), [`PDRegisterCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandlerEx)

#### PDDocGetNewSecurityData

```cpp
void * PDDocGetNewSecurityData(PDDoc doc)
```

Header: `PDProcs.h:2394`

Gets the security data structure for the specified document's new security handler. Use PDDocGetSecurityData() to get the security data structure for the document's current security handler.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose new security data structure is obtained.

**Returns:** `void *`

The security data structure for the document's new security handler.

**See also:** [`PDDocGetSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetSecurityData), [`PDDocNewSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocNewSecurityData), [`PDDocGetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewCryptHandler), [`PDDocSetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandler), [`PDDocSetNewSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewSecurityData), [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest)

#### PDDocGetNewSecurityInfo

```cpp
void PDDocGetNewSecurityInfo(PDDoc pdDoc, ASUns32 *secInfo)
```

Header: `PDProcs.h:2550`

Gets the security information from the specified document's new security handler. It calls the PDCryptGetSecurityInfoProc() callback of the document's new security handler. No permissions are required to call this method. It raises only those exceptions raised by the new security handler's PDCryptGetSecurityInfoProc() callback.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose new security information is obtained.
- `secInfo` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): IN/OUT (Filled by the method) The document's new security information. The value must be an `OR` of the Security Info Flags. It is set to `pdInfoCanPrint | pdInfoCanEdit | pdInfoCanCopy | pdInfoCanEditNotes` (see PDPerms) if the document's new security handler does not have a PDCryptGetSecurityInfoProc() callback.

**Returns:** `void`

**See also:** [`PDRegisterCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandler)

#### PDDocGetNthError

```cpp
ASInt32 PDDocGetNthError(PDDoc doc, ASInt32 errNumber, ASInt32 *errorP, char *buffer, ASInt32 bufSize)
```

Header: `PDProcs.h:12007`

Returns the error code and format argument string for the Nth non-fatal error encountered since the document was opened, or `PDDocClearErrors` was called.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the error has occurred.
- `errNumber` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): This is the index of the non-fatal error to be returned, PDDocGetNumErrors() returns how many errors there are.
- `errorP` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The error code. Use `ASGetErrorString()` to get the error message associated with it (which may contain a format specifier).
- `buffer` (`char *`): If there is a format argument string associated with this error, it's copied to this buffer. The buffer must be non-`NULL` and `NULL`-terminated.
- `bufSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The maximum number of bytes that will be written to the buffer.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

If there is a format argument string associated with this error, the length of it is returned. If a problem occurs looking up the error number, the return value is zero.

#### PDDocGetNumErrors

```cpp
ASInt32 PDDocGetNumErrors(PDDoc doc)
```

Header: `PDProcs.h:11992`

Return the number of non-fatal errors encountered since the document was opened, or `PDDocClearErrors` was called.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the non-fatal errors have occurred.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

#### PDDocGetNumOCGs

```cpp
ASUns32 PDDocGetNumOCGs(PDDoc pdDoc)
```

Header: `PDProcs.h:10337`

Returns the number of optional-content groups associated with a document, which is the number of unique entries in the document's OCProperties OCGs array.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose groups are counted.

**Returns:** [`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)

The number of OCGs for the document.

**See also:** [`PDDocHasOC`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocHasOC), [`PDDocGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCGs), [`PDDocReplaceOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocReplaceOCG), [`PDDocEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCGs), [`PDDocGetOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCConfig), [`PDDocGetOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCContext)

#### PDDocGetNumPages

```cpp
ASInt32 PDDocGetNumPages(PDDoc doc)
```

Header: `PDProcs.h:1546`

Gets the number of pages in a document.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document for which the number of pages is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of pages in the document. Remember to subtract `1` from this value if you are going to pass it to a PD- level method that takes a zero-based page number.

#### PDDocGetNumThreads

```cpp
ASInt32 PDDocGetNumThreads(PDDoc doc)
```

Header: `PDProcs.h:1824`

Gets the number of article threads in a document.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose article thread count is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of article threads in the document.

#### PDDocGetOCConfig

```cpp
PDOCConfig PDDocGetOCConfig(PDDoc pdDoc)
```

Header: `PDProcs.h:10023`

Gets the built-in default optional-content configuration for the document from the OCProperties D entry.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose configuration is obtained.

**Returns:** [`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)

The document's current optional-content configuration.

**See also:** [`PDDocGetOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCContext), [`PDDocGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCGs), [`PDDocEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCGs), [`PDDocEnumOCConfigs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCConfigs), [`PDOCConfigGetPDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetPDDoc)

#### PDDocGetOCContext

```cpp
PDOCContext PDDocGetOCContext(PDDoc pdDoc)
```

Header: `PDProcs.h:9495`

Gets the built-in default optional-content context for the document. This context is used by all content drawing and enumeration calls that do not take an optional-content context parameter, or for which no context is specified.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose context is obtained.

**Returns:** [`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)

The document's current optional-content context.

**See also:** [`PDDocGetOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCConfig), [`PDDocGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCGs), [`PDOCContextGetPDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetPDDoc)

#### PDDocGetOCGs

```cpp
PDOCG * PDDocGetOCGs(PDDoc pdDoc)
```

Header: `PDProcs.h:10357`

Gets the optional-content groups for the document. The order of the groups is not guaranteed to be the creation order, and is not the same as the display order (see PDOCConfigGetOCGOrder()).

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose OCGs are obtained.

**Returns:** [`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)

A `NULL`-terminated array of PDOCG objects. The client is responsible for freeing the array using ASfree().

**See also:** [`PDDocHasOC`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocHasOC), [`PDDocReplaceOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocReplaceOCG), [`PDDocEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCGs), [`PDDocGetNumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNumOCGs), [`PDDocGetOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCConfig), [`PDDocGetOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCContext), [`PDOCGGetPDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetPDDoc), [`PDOCMDGetPDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDGetPDDoc)

#### PDDocGetOpenAction

```cpp
PDAction PDDocGetOpenAction(PDDoc doc)
```

Header: `PDProcs.h:1244`

Gets the value of the OpenAction key in the Catalog dictionary, which is the action performed when the document is opened. After you obtain the action, you can execute it with AVDocPerformAction().

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose open action is obtained.

**Returns:** [`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)

The document's open action. It is invalid if there is no OpenAction key in the Catalog dictionary (this can be tested with PDActionIsValid()).

**See also:** `AVDocPerformAction`, [`PDDocSetOpenAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetOpenAction)

#### PDDocGetPDCollection

```cpp
PDCollection PDDocGetPDCollection(PDDoc pdDoc)
```

Header: `PDProcs.h:12323`

Gets the collection object in a document.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document.

**Returns:** [`PDCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCollection)

The collection. If the document does not have a collection, the returned collection is invalid.

#### PDDocGetPageLabel

```cpp
PDPageLabel PDDocGetPageLabel(PDDoc pdDoc, ASInt32 pageNum, ASInt32 *firstPage, ASInt32 *lastPage)
```

Header: `PDProcs.h:7230`

Returns the label that is in effect for the given page.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document for which a page label is desired.
- `pageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number of the page for which a label is requested.
- `firstPage` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): (Filled by the method) If non-`NULL`, it is the number of the first page that the page label is attached to.
- `lastPage` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): (Filled by the method) If non-`NULL`, it is the number of the last page that the page label is attached to. Setting `lastPage` to non-`NULL` forces the implementation to perform another traverse of the page label tree, with some slight performance impact.

**Returns:** [`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)

The label that is in effect for the given page. If there is no label object in effect, this method returns an invalid page label object, and `firstPage` and `lastPage` will be set to `-1`.

**See also:** [`PDDocFindPageNumForLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocFindPageNumForLabel), [`PDDocGetLabelForPageNum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetLabelForPageNum), [`PDDocRemovePageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemovePageLabel), [`PDDocSetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetPageLabel), [`PDPageLabelNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelNew)

#### PDDocGetPageMode

```cpp
PDPageMode PDDocGetPageMode(PDDoc doc)
```

Header: `PDProcs.h:1447`

Gets the value of the PageMode key in the Catalog dictionary. **Note:** PDDocGetFullScreen should be used when the page mode is set to full screen.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose page mode is obtained.

**Returns:** [`PDPageMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageMode)

Page mode value from PDF Catalog dictionary.

**See also:** [`PDDocSetPageMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetPageMode), `AVDocSetViewMode`

#### PDDocGetPageObjByNum

```cpp
CosObj PDDocGetPageObjByNum(PDDoc pdd, ASInt32 nPage)
```

Header: `PDProcs.h:7980`

Returns the page Cos object corresponding to the given page number.

**Parameters**

- `pdd` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The PDDoc containing the given page.
- `nPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

A Cos object representing the page, or an object of type CosNull if the page does not exist.

**Exceptions**

- `genErrBadParm`
- `pdErrBadPageObj`

#### PDDocGetPermissions

```cpp
PDPerms PDDocGetPermissions(PDDoc doc)
```

Header: `PDProcs.h:2566`

Deprecated in Acrobat 5.0. Use PDDocPermRequest() instead. Gets the permissions for the specified document. You can set permissions with PDDocAuthorize().

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose permissions are obtained.

**Returns:** [`PDPerms`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPerms)

A bit field indicating the document's permissions. It is an `OR` of the PDPerms values.

**See also:** [`PDDocAuthorize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAuthorize), [`PDDocGetSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetSecurityData), [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest)

#### PDDocGetSecurityData

```cpp
void * PDDocGetSecurityData(PDDoc doc)
```

Header: `PDProcs.h:2375`

Superseded in Acrobat 5.0 by PDDocPermRequest. Gets the security data structure for the specified document's current security handler. Use PDDocGetNewSecurityData() to get the data structure for the document's new security handler.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose security data structure is obtained.

**Returns:** `void *`

A pointer to the document's current security data structure.

**See also:** [`PDDocGetNewSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewSecurityData), [`PDDocGetCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetCryptHandler)

#### PDDocGetThread

```cpp
PDThread PDDocGetThread(PDDoc doc, ASInt32 index)
```

Header: `PDProcs.h:1838`

Gets an article thread having the specified index.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document containing the article thread.
- `index` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The index of the article thread to obtain.

**Returns:** [`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)

The specified article thread.

**See also:** [`PDDocAddThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAddThread), [`PDDocRemoveThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemoveThread), [`PDThreadIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadIsValid)

#### PDDocGetThreadIndex

```cpp
ASInt32 PDDocGetThreadIndex(PDDoc doc, PDThread thread)
```

Header: `PDProcs.h:1848`

Gets the index of the specified article thread.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document containing the thread.
- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): IN/OUT The thread whose index is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The index of thread in doc. It returns `-1` if `thread` is not in `doc`.

#### PDDocGetTrapped

```cpp
ASAtom PDDocGetTrapped(PDDoc pdDoc)
```

Header: `PDProcs.h:11039`

Gets the value of the Trapped key in the Info dictionary.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose Trapped key value is obtained.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

The value of the Trapped key in the Info dictionary if the entry exists and is a name, or ASAtomNull if the entry does not exist or is not a name.

**See also:** [`PDDocSetTrapped`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetTrapped)

#### PDDocGetVersion

```cpp
void PDDocGetVersion(PDDoc doc, ASInt16 *majorP, ASInt16 *minorP)
```

Header: `PDProcs.h:1523`

Gets the major and minor PDF document versions. This is the PDF version of the document, which is specified in the header of a PDF file in the string `"%PDF-xx. yy"` where `xx` is the major version and `yy` is the minor version. For example, version 1.2 has the string `"%PDF<code>-1`.2"</code>. See the description of PDF Version Numbers in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section I.2, page 727. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose version is obtained.
- `majorP` ([`ASInt16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): IN/OUT (Filled by the method) The major version number.
- `minorP` ([`ASInt16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): IN/OUT (Filled by the method) The minor version number.

**Returns:** `void`

#### PDDocGetVersionEx

```cpp
void PDDocGetVersionEx(PDDoc doc, ASUns32 *majorP, ASUns32 *minorP, CosObj *adbeExtensionBaseP, ASUns32 *adbeExtensionLevelP)
```

Header: `PDProcs.h:12039`

Returns the Adobe version of the PDF format to which the PDF file conforms. For PDF versions 1.0 through 1.7, this method will return a major version of 1, a minor version in the range of 0 through 7, and an `adbeExtensionLevel` of 0. For Acrobat 9, this method will return a major version of 1 and a minor version of 8. For Acrobat 10, this method will return a major version of 1 and a minor version of 9. Starting with Acrobat 9, Adobe extensions to the PDF format will be identified via the Adobe Extensions Dictionary for the ISO 32000 standard in the catalog; in this case, the major and minor versions will be returned, and the Adobe extension level will be returned via the last argument. When the Extensions Dictionary is added to a PDF document, it allows PDF features provided in Adobe Acrobat after PDF version 1.7 to be used with that document. The version of the PDF file is drawn from the Extensions Dictionary instead of from the file header. See https://www.adobe.com/devnet/pdf/pdf_reference.html

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose version is obtained.
- `majorP` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): IN/OUT (Filled by the method) The major version number.
- `minorP` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): IN/OUT (Filled by the method) The minor version number.
- `adbeExtensionBaseP` ([`CosObj *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT (Filled in by the method) The value of the BaseVersion
  entry in the ADBE dictionary. If there is no Extensions dictionary or no ADBE
  sub-dictionary, the value returned will be a null CosObj.
- `adbeExtensionLevelP` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): IN/OUT (Filled in by the method) The values of the ExtensionLevel entry in the ADBE dictionary. If there is no Extensions dictionary or no ADBE sub-dictionary, the value returned will be zero.

**Returns:** `void`

#### PDDocGetWordFinder

```cpp
PDWordFinder PDDocGetWordFinder(PDDoc docP, ASInt16 WXEVersion)
```

Header: `PDProcs.h:2046`

Gets the word finder associated with a document. It is not necessary to destroy the word finder returned by this method.

**Parameters**

- `docP` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose word finder is obtained.
- `WXEVersion` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): The version of the word finder to get.

**Returns:** [`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)

The document's word finder. It returns `NULL` if the document does not have a word finder or its version does not match the version requested.

**Exceptions**

- `genErrBadParm`: is thrown if an invalid version number is passed.

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS)

#### PDDocHasISOExtensions

```cpp
ASBool PDDocHasISOExtensions(PDDoc doc)
```

Header: `PDProcs.h:12058`

Returns true if the document contains the Adobe Extensions Dictionary for specifying the inclusion of features beyond the ISO 32000 specification. Starting with Acrobat 9, Adobe extensions to the PDF format will be identified via this Extensions Dictionary in the catalog. When the Extensions Dictionary is added to a PDF document, it allows PDF features provided in Adobe Acrobat after PDF version 1.7 to be used with that document. The version of the PDF file is drawn from the Extensions Dictionary instead of from the file header. See https://www.adobe.com/devnet/pdf/pdf_reference.html @since

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document tested for ISO extensions.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

#### PDDocHasOC

```cpp
ASBool PDDocHasOC(PDDoc pdDoc)
```

Header: `PDProcs.h:10321`

Determines whether the optional content feature is associated with the document. The document is considered to have optional content if there is an OCProperties dictionary in the document's catalog, and that dictionary has one or more entries in the OCGs array.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose OC status is obtained.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the document has optional content, `false` otherwise.

**See also:** [`PDDocGetOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCConfig), [`PDDocGetOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCContext), [`PDDocGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCGs)

#### PDDocImportCosDocNotes

```cpp
ASInt32 PDDocImportCosDocNotes(PDDoc doc, CosDoc src, const char *noteTitle, ASInt32 noteTitleLen, PDColorValue color, void *progMon, void *monClientData, PDDocWillImportAnnotCallback importFilter)
```

Header: `PDProcs.h:6815`

Adds text annotations from `sourceDoc` to `doc`. It raises an exception if the given object has the wrong Cos type. It also raises exceptions if storage is exhausted or file access fails.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document that will receive the imported annotations.
- `src` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document from which the annotations will be imported.
- `noteTitle` (`const char *`): Not currently used.
- `noteTitleLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): Not currently used.
- `color` (`PDColorValue`): If non-`NULL`, the color attribute of imported annotations. `color` indicates the color space (PDDeviceGray, PDDeviceRGB, PDDeviceCMYK), and color values for the annotation.
- `progMon` (`void *`): If supplied, it is a procedure to call regularly to update a progress bar for the user.
- `monClientData` (`void *`): If supplied, it is a pointer to the private data buffer used by `progMon`.
- `importFilter` ([`PDDocWillImportAnnotCallback`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocWillImportAnnotCallback)): A user-supplied procedure that will be called to provide a filtering process, allowing only desired annotations to import.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of notes imported. @notify PDDocDidImportAnnots @notify PDDocWillImportAnnots

**See also:** [`PDDocImportNotes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocImportNotes), [`PDDocExportNotes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocExportNotes)

#### PDDocImportNotes

```cpp
ASInt32 PDDocImportNotes(PDDoc doc, PDDoc sourceDoc, void *progMon, void *monClientData, PDDocWillImportAnnotCallback importFilter)
```

Header: `PDProcs.h:7411`

Adds text annotations (notes) from `sourceDoc` to `doc`. It raises an exception if the given object has the wrong Cos type. Also raises exceptions if storage is exhausted or file access fails.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document to which the notes are exported.
- `sourceDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document from which the notes are exported.
- `progMon` (`void *`): A user-supplied progress monitor.
- `monClientData` (`void *`): Data supplied by the monitoring routine.
- `importFilter` ([`PDDocWillImportAnnotCallback`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocWillImportAnnotCallback)): A user-supplied filter which determines what type of notes will be exported.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of notes imported. @notify PDDocDidImportAnnots @notify PDDocWillImportAnnots

**See also:** [`PDDocExportNotes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocExportNotes), [`PDDocImportCosDocNotes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocImportCosDocNotes)

#### PDDocInsertPages

```cpp
void PDDocInsertPages(PDDoc doc, ASInt32 mergeAfterThisPage, PDDoc doc2, ASInt32 startPage, ASInt32 numPages, ASUns16 insertFlags, ProgressMonitor progMon, void *progMonClientData, CancelProc cancelProc, void *cancelProcClientData)
```

Header: `PDProcs.h:1753`

Inserts `numPages` pages from `doc2` into `doc`. All annotations, and anything else associated with the page (such as a thumbnail image) are copied from the `doc2` pages to the new pages in `doc`. This method does not insert pages if `doc` equals `doc2`. The `insertFlags` parameter controls whether bookmarks and threads are inserted along with the specified pages. Setting The PDInsertAll flag has two effects: The parameters indicating which pages to insert are ignored: all the pages of `doc2` are inserted. In addition to inserting the pages themselves, it also merges other document data from `doc2` into `doc`: Named destinations from `doc2` (of PDF 1.1 and later) are copied into `doc`. If there are named destinations in `doc2` with the same name as some named destination in `doc`, the ones in `doc` retain their names and the copied named destinations are given new names based on the old ones, with distinguishing digits added. Actions and bookmarks referring to the old names are made to refer to the new names after being copied into `doc`. If it is also the case that `mergeAfterThisPage` denotes the last page of the document, then document metadata is merged, and the optional content properties are merged in a more symmetrical manner than would otherwise be the case. Document logical structure from `doc2` is copied into `doc`. If less than the whole of `doc2` is being inserted, only those structure elements having content on the copied pages, and the ancestors of those elements, are copied into the logical structure tree of `doc`. The top-level children of the structure tree root of `doc2` are copied as new top-level children of the structure tree root of `doc`; a structure tree root is created in `doc` if there was none before. The role maps of the two structure trees are merged, with name conflicts resolved in favor of the role mappings present in `doc`. Attribute objects having scalar values, or values that are arrays of scalar values, are copied. Class map information from `doc2` is also merged into that for `doc`. Constant Description PDInsertBookmarks Inserts bookmarks as well as pages. The bookmark tree of `doc2` is merged into the bookmark tree of `doc` by copying it as a new first-level subtree of the `doc` parameter's bookmark tree root, of which it becomes the last child. If `doc` has no bookmark tree, it acquires one identical to the bookmark tree from `doc2`. PDInsertThreads Inserts threads as well as pages. PDInsertAll Inserts document data from pages.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document into which pages are inserted. This document must have at least one page.
- `mergeAfterThisPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number in `doc` after which pages from `doc2` are inserted. The first page is `0`. If PDBeforeFirstPage (see `PDExpT.h`) is used, the pages are inserted before the first page in `doc`. Use PDLastPage to insert pages after the last page in `doc`.
- `doc2` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document containing the pages that are inserted into `doc`.
- `startPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number of the first page in `doc2` to insert into `doc`. The first page is `0` If PDAllPages is used, all pages from doc2 are inserted into doc.
- `numPages` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of pages in `doc2` to insert into `doc`. Use PDAllPages to insert all pages from `startPage` of `doc2` into `doc`.
- `insertFlags` ([`ASUns16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)): Flags that determine what additional information is copied from `doc2` into `doc`. It is an `OR` of the following constants (see `PDExpT.h`):
- `progMon` ([`ProgressMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ProgressMonitor)): A progress monitor. Use AVAppGetDocProgressMonitor() to obtain the default progress monitor. `NULL` may be passed, in which case no progress monitor is used.
- `progMonClientData` (`void *`): A pointer to user-supplied data to pass to `progMon` each time it is called. It should be `NULL` if `progMon` is `NULL`.
- `cancelProc` ([`CancelProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#CancelProc)): A cancel procedure. Use AVAppGetCancelProc() to obtain the current cancel procedure. It may be `NULL`, in which case no cancel proc is used.
- `cancelProcClientData` (`void *`): A pointer to user-supplied data to pass to `cancelProc` each time it is called. It should be `NULL` if `cancelProc` is `NULL`.

**Returns:** `void`

**Exceptions**

- `pdErrOpNotPermitted`: is raised unless `doc` is editable and `doc2` is not encrypted or the owner opened it.
- `pdErrCantUseNewVersion`: is raised if `doc2` is a newer major version than the Acrobat viewer understands.
- `pdErrTooManyPagesForInsert`: is raised if the insertion would result in a document with too many pages.
- `genErrBadParm`: is raised if `mergeAfterThisPage` is an invalid page number or `doc` has no pages.
- `genErrNoMemory`: is raised if there is insufficient memory to perform the insertion.
- `pdErrWhileRecoverInsertPages`: is raised if an error occurs while trying to recover from an error during inserting. @notify PDDocWillInsertPages @notify PDDocDidInsertPages @notify PDDocDidChangePages @notify PDDocPrintingTiledPage @notify PDDocDidChangeThumbs @notify PDDocDidAddThread

**See also:** `AVAppGetCancelProc`, `AVAppGetDocProgressMonitor`, [`PDDocCreatePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreatePage), [`PDDocDeletePages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocDeletePages), [`PDDocMovePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocMovePage), [`PDDocReplacePages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocReplacePages)

#### PDDocMovePage

```cpp
void PDDocMovePage(PDDoc doc, ASInt32 moveToAfterThisPage, ASInt32 pageToMove)
```

Header: `PDProcs.h:1635`

Moves one page in a document. @notify PDDocWillMovePages @notify PDDocDidMovePages @notify PDDocDidChangePages @notify PDDocWillChangePages

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the page is moved.
- `moveToAfterThisPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The new location of the page
  to move. The first page is `0`. It may either be a page number,
  or the constant PDBeforeFirstPage (see PDExpT.h).
- `pageToMove` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number of the page to move.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if `moveAfterThisPage` or
  `pageToMove` is invalid. Other exceptions may be raised as well.

**See also:** [`PDDocInsertPages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocInsertPages), [`PDDocReplacePages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocReplacePages), [`PDDocDeletePages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocDeletePages)

#### PDDocNewSecurityData

```cpp
void * PDDocNewSecurityData(PDDoc doc)
```

Header: `PDProcs.h:2456`

Creates a security data structure appropriate for the specified document's new security handler. The new security handler must have been previously set using PDDocSetNewCryptHandler(). The structure is created by calling the new security handler's PDCryptNewSecurityDataProc(). After calling PDDocNewSecurityData(), fill the structure as appropriate, call PDDocSetNewSecurityData() with the structure, and then free the structure using ASfree().

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document for which a security data structure is created.

**Returns:** `void *`

The newly created security data structure.

**Exceptions**

- `pdErrOpNotPermitted`: is raised if pdPermSecure (see PDPerms) has not been granted for `doc`.
- `pdErrNeedCryptHandler`: is raised if the document does not have a new security handler.

**See also:** [`PDDocSetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandler), [`PDDocSetNewSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewSecurityData)

#### PDDocOpen

```cpp
PDDoc PDDocOpen(ASPathName fileName, ASFileSys fileSys, PDAuthProc authProc, ASBool doRepair)
```

Header: `PDProcs.h:1228`

Opens the specified document. If the document is already open, it returns a reference to the already opened PDDoc. You must call PDDocClose() once for every successful open. If the call fails and the exception is pdErrNeedRebuild, then call again with `doRepair` set to `true`. This allows the application to decide whether to perform the time-consuming repair operation.

**Parameters**

- `fileName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): A path name to the file, specified in whatever format is correct for `fileSys`.
- `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): A pointer to an `ASFileSysRec` containing the file system in which the file resides. If it is `NULL`, it uses the default file system.
- `authProc` ([`PDAuthProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAuthProc)): An authorization callback, called only if the file has been secured (that is, if the file has either the user or the master password set). This callback should obtain whatever information is needed to determine whether the user is authorized to open the file, then call PDDocPermRequest(). The Acrobat viewer's built-in authorization procedure requires the user to enter a password, and allows the user to try three times before giving up. If the `authProc` requires data, use PDDocOpenEx() instead of PDDocOpen().
- `doRepair` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, attempt to repair the file if it is damaged. If `false`, do not attempt to repair the file if it is damaged.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

The newly-opened document.

**Exceptions**

- `pdErrNeedPassword`: or other errors are raised if the file is encrypted and `authProc` is `NULL` or returns `false`.
- `pdErrNotEnoughMemoryToOpenDoc`: or genErrNoMemory is raised if there is insufficient memory to open the document.
- `pdErrNeedRebuild`: is raised if the document needs to be rebuilt and `doRepair` is `false`.
- `pdErrBadOutlineObj`: is raised if the Outlines object appears to be invalid (if the value of the Outlines key in the Catalog is not a `NULL` or dictionary object).
- `pdErrBadRootObj`: is raised if the Catalog object (as returned by CosDocGetRoot()) is not a dictionary.
- `pdErrBadBaseObj`: is raised if the Pages tree appears to be invalid (if the value of the Pages key in the Catalog is not a `NULL` or dictionary object).
- `pdErrTooManyPagesForOpen`: is raised if the document contains too many pages.
- `cosSynErrNoHeader`: is raised if the document's header appears to be bad.
- `cosSynErrNoStartXRef`: is raised if no end-of-file line can be located.
- `cosErrRebuildFailed`: is raised if `doRepair` is `true` and rebuild failed.

**See also:** [`PDDocClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClose), [`PDDocCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreate), [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest), [`PDDocOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenEx), [`PDDocOpenFromASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenFromASFile), [`PDDocOpenFromASFileEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenFromASFileEx)

#### PDDocOpenEx

```cpp
PDDoc PDDocOpenEx(ASPathName fileName, ASFileSys fileSys, PDAuthProcEx authProcEx, void *authProcClientData, ASBool doRepair)
```

Header: `PDProcs.h:6033`

Opens the specified document. If the document is already open, it returns a reference to the already opened PDDoc. You must call PDDocClose() once for every successful open. If the call fails and the exception is pdErrNeedRebuild, then call again with `doRepair` equal to `true`. This allows the application to decide whether to perform the time-consuming repair operation.

**Parameters**

- `fileName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): A path name to the file, specified in whatever format is correct for `fileSys`.
- `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): A pointer to an `ASFileSysRec` containing the file system in which the file resides.
- `authProcEx` ([`PDAuthProcEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAuthProcEx)): An authorization callback, called only if the file has been secured (meaning that the file has either the user or the master password set). This callback should obtain whatever information is needed to determine whether the user is authorized to open the file, then call PDDocAuthorize()() (which returns the permissions that the authentication data enables). The Acrobat viewer's built-in authorization procedure requires the user to enter a password, and allows the user to try three times before giving up.
- `authProcClientData` (`void *`): A pointer to user-supplied data to pass to authProcEx() each time it is called.
- `doRepair` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, attempt to repair the file if it is damaged. If `false`, do not attempt to repair the file if it is damaged.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

The newly-opened document.

**Exceptions**

- `pdErrNeedPassword`: is raised if the file is encrypted and `authProc`Ex() is `NULL` or returns `false`.
- `pdErrNotEnoughMemoryToOpenDoc`: or genErrNoMemory is raised if there is insufficient memory to open the document.
- `pdErrNeedRebuild`: is raised if the document needs to be rebuilt and `doRepair` is `false`.
- `pdErrBadOutlineObj`: is raised if the Outlines object appears to be invalid (if the value of the Outlines key in the Catalog is not a `NULL` or dictionary object).
- `pdErrBadRootObj`: is raised if the Catalog object (as returned by CosDocGetRoot()) is not a dictionary.
- `pdErrBadBaseObj`: is raised if the Pages tree appears to be invalid (if the value of the Pages key in the Catalog is not a `NULL` or dictionary object).
- `pdErrTooManyPagesForOpen`: is raised if the document contains too many pages.
- `cosSynErrNoHeader`: is raised if the document's header appears to be bad.
- `cosSynErrNoStartXRef`: is raised if no end-of-file line can be located.
- `cosErrRebuildFailed`: is raised if `doRepair` is `true` and rebuild failed.

**See also:** [`PDDocClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClose), [`PDDocCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreate), [`PDDocAuthorize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAuthorize), [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocOpenFromASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenFromASFile), [`PDDocOpenFromASFileEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenFromASFileEx)

#### PDDocOpenFromASFile

```cpp
PDDoc PDDocOpenFromASFile(ASFile aFile, PDAuthProc authProc, ASBool doRepair)
```

Header: `PDProcs.h:5548`

Opens the document specified by the ASFile. `aFile` must be a valid ASFile. It is the caller's responsibility to dispose of the ASFile after calling PDDocClose(). This method is useful when the document referenced by the ASFile is not on the local machine, and is being retrieved incrementally using the multi-read protocol of an ASFileSys. If the bytes required to open a PDDoc are not yet available, this method will raise the exception fileErrBytesNotReady. The client should call PDDocOpenFromASFile() until this exception is no longer raised.

**Parameters**

- `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The ASFile to open. The ASFile should be released after the PDDoc is closed.
- `authProc` ([`PDAuthProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAuthProc)): An authorization callback, called only if the file is encrypted. This callback should obtain whatever information is needed to determine whether the user is authorized to open the file, then call PDDocAuthorize() (which returns the permissions that the authentication data enables). The Acrobat viewer's built-in authorization procedure requires the user to enter a password, and allows the user to try three times before giving up.
- `doRepair` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, attempt to repair the file if it is damaged. If `false`, do not attempt to repair the file if it is damaged.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

A valid PDDoc if successfully opened.

**Exceptions**

- `pdErrNeedPassword`: is raised if the file is encrypted and `authProc` is `NULL` or returns `false`.
- `fileErrBytesNotReady`: is raised if the bytes required to open a PDDoc are not yet available.

**See also:** [`PDDocClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClose), [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenEx), [`PDDocOpenFromASFileEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenFromASFileEx)

#### PDDocOpenFromASFileEx

```cpp
PDDoc PDDocOpenFromASFileEx(ASFile aFile, PDAuthProcEx authProcEx, void *authProcClientData, ASBool doRepair)
```

Header: `PDProcs.h:6074`

Opens the document specified by the ASFile. `aFile` must be a valid ASFile. It is the caller's responsibility to dispose of the ASFile after calling PDDocClose(). This method is useful when the document referenced by the ASFile is not on the local machine, and is being retrieved incrementally using the multiread protocol of an ASFileSys. If the bytes required to open a PDDoc are not yet available, this method will raise the exception fileErrBytesNotReady. The client should call PDDocOpenFromASFile() until this exception is no longer raised.

**Parameters**

- `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The ASFile to open. The ASFile should be released after the PDDoc is closed.
- `authProcEx` ([`PDAuthProcEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAuthProcEx)): An authorization callback, called only if the file is encrypted. This callback should obtain whatever information is needed to determine whether the user is authorized to open the file, then call PDDocAuthorize() (which returns the permissions that the authentication data enables). The Acrobat viewer's built-in authorization procedure requires the user to enter a password, and allows the user to try three times before giving up.
- `authProcClientData` (`void *`): A pointer to user-supplied data to pass to authProcEx() each time it is called.
- `doRepair` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, attempt to repair the file if it is damaged. If `false`, do not attempt to repair the file if it is damaged.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

A valid PDDoc if successfully opened.

**Exceptions**

- `pdErrNeedPassword`: is raised if the file is encrypted and `authProc` is `NULL` or returns `false`.
- `fileErrBytesNotReady`: is raised if the bytes required to open a PDDoc are not yet available.

**See also:** [`PDDocClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClose), [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenEx), [`PDDocOpenFromASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenFromASFile)

#### PDDocOpenWithParams

```cpp
PDDoc PDDocOpenWithParams(PDDocOpenParams openParams)
```

Header: `PDProcs.h:7322`

Opens the document specified by the ASFile or ASFileSys/ASPathName. If both are set, the ASFile is used and the `fileSys` and `pathName` are ignored.

**Parameters**

- `openParams` ([`PDDocOpenParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenParams)): IN/OUT A structure that defines which PDF file is opened. It contains parameters such as a file name, a file system, an authorization procedure, and a set of flags that define what permissions the user has on a file.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

The PDDoc for the PDF document described by the structure passed in `openParams`.

**See also:** [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenEx), [`PDDocOpenFromASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenFromASFile), [`PDDocOpenFromASFileEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenFromASFileEx)

#### PDDocPermRequest

```cpp
PDPermReqStatus PDDocPermRequest(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void *authData)
```

Header: `PDProcs.h:7860`

This method supersedes PDDocGetPermissions(). Checks the permissions associated with the specified document using the latest permissions format, and determines whether the requested operation is allowed for the specified object in the document. This method first checks the requested object and operation in a cached permissions list. If a value is not found, it calls the document's permission handlers, followed by security handlers via PDCryptAuthorizeExProc() to request permissions for the operation. The final permission is a logical `AND` of the permissions granted by individual permissions and/or security handlers. If the document's security handler does not support this Acrobat 5.0 call, the method calls PDCryptAuthorizeProc() instead. The method then interprets the returned `PDPerms` to determine whether the requested operation is allowed for the specified object in the document. This method may throw exceptions. @since

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The PDDoc whose permissions are being requested.
- `reqObj` ([`PDPermReqObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPermReqObj)): The target object of the permissions request.
- `reqOpr` ([`PDPermReqOpr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPermReqOpr)): The target operation of the permissions
  request.
- `authData` (`void *`): A pointer to an authorization data structure.

**Returns:** [`PDPermReqStatus`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPermReqStatus)

**See also:** [`PDDocAuthorize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAuthorize), [`PDDocGetPermissions`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPermissions), [`PDDocGetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewCryptHandler), [`PDDocSetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandler), [`PDDocSetNewCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandlerEx), [`PDRegisterCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandler), [`PDRegisterCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandlerEx)

#### PDDocPermRequestNoUB

```cpp
PDPermReqStatus PDDocPermRequestNoUB(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void *authData)
```

Header: `PDProcs.h:11265`

PDDocPermRequestNoUB() indicates whether the permission would have been granted had the document not been Rights Enabled. This may throw numerous exceptions.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The PDDoc whose permissions are being requested.
- `reqObj` ([`PDPermReqObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPermReqObj)): The target object of the permissions request.
- `reqOpr` ([`PDPermReqOpr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPermReqOpr)): The target operation of the permissions request.
- `authData` (`void *`): A pointer to an authorization data structure.

**Returns:** [`PDPermReqStatus`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPermReqStatus)

The request status constant: `0` if the requested operation is allowed, a non-zero status code otherwise.

**See also:** [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest)

#### PDDocReadAhead

```cpp
void PDDocReadAhead(PDDoc doc, ASUns32 flags, void *clientData)
```

Header: `PDProcs.h:5974`

Used for page-at-a-time downloading and byte-serving Acrobat data. If a document is being viewed over a slow file system, PDDocReadAhead() issues a byte range request for all the data associated with the flags in flags.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document being read.
- `flags` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): IN/OUT Flags describing type of data to read ahead. It must be an `OR` of flags in PDDocReadAhead() Flags.
- `clientData` (`void *`): IN/OUT Currently unused.

**Returns:** `void`

#### PDDocReadAheadEmbeddedFile

```cpp
void PDDocReadAheadEmbeddedFile(PDDoc doc, CosObj embeddedFileObj)
```

Header: `PDProcs.h:10986`

Used for page-at-a-time downloading and byte-serving Acrobat data. If a document is being viewed over a slow file system, the method issues a byte range request for all the data associated with an embedded file.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document being read.
- `embeddedFileObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object of the embedded file stream (the stream referenced by entries in the EF dictionary).

**Returns:** `void`

#### PDDocReadAheadPages

```cpp
void PDDocReadAheadPages(PDDoc doc, ASInt32 startPage, ASInt32 nPages)
```

Header: `PDProcs.h:7337`

Reads ahead `nPages` starting at `startPage` (if the file is linearized).

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document for which pages are read ahead.
- `startPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The page for which read ahead is initiated.
- `nPages` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The number of pages to read ahead.

**Returns:** `void`

#### PDDocRelease

```cpp
void PDDocRelease(PDDoc doc)
```

Header: `PDProcs.h:1406`

Decrements a document's reference count. The document will not be closed until the reference count is zero, or the application terminates.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose reference count is decremented.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`

**See also:** [`PDDocAcquire`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAcquire)

#### PDDocRemoveNameTree

```cpp
void PDDocRemoveNameTree(PDDoc thePDDoc, ASAtom theTree)
```

Header: `PDProcs.h:7095`

Removes the name tree inside the Names dictionary with the specified key name. It does nothing if no object with that name exists.

**Parameters**

- `thePDDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document from which a name tree is removed.
- `theTree` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): IN/OUT The name tree to remove.

**Returns:** `void`

**See also:** [`PDDocCreateNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateNameTree), [`PDDocGetNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNameTree)

#### PDDocRemoveOpenAction

```cpp
void PDDocRemoveOpenAction(PDDoc doc)
```

Header: `PDProcs.h:7942`

Removes the value of the OpenAction key in the Catalog dictionary. The value is the action performed when the document is opened.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose open action is removed.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`
- `pdErrOpNotPermitted`

**See also:** [`PDDocGetOpenAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOpenAction), [`PDDocSetOpenAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetOpenAction)

#### PDDocRemovePageLabel

```cpp
void PDDocRemovePageLabel(PDDoc pdDoc, ASInt32 pageNum)
```

Header: `PDProcs.h:7302`

Removes the page label that is attached to the specified page, effectively merging the specified range with the previous page label sequence.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document from which a page label is removed.
- `pageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page from which the page label is removed.

**Returns:** `void`

**See also:** [`PDDocSetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetPageLabel), [`PDDocGetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageLabel), [`PDPageLabelNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelNew)

#### PDDocRemoveThread

```cpp
void PDDocRemoveThread(PDDoc doc, ASInt32 index)
```

Header: `PDProcs.h:1881`

Removes an article thread from a document. If you also wish to destroy the thread, use PDThreadDestroy() after calling PDDocRemoveThread().

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document from which the thread is removed.
- `index` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The index of the thread to remove. @notify PDDocWillRemoveThread @notify PDDocDidRemoveThread

**Returns:** `void`

**See also:** [`PDThreadDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadDestroy), [`PDDocAddThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAddThread), [`PDBeadGetThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetThread)

#### PDDocReplaceOCG

```cpp
void PDDocReplaceOCG(PDOCG replaceOCG, PDOCG keepOCG)
```

Header: `PDProcs.h:10372`

In the document associated with a specified optional-content group, replaces that group with another group.

**Parameters**

- `replaceOCG` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The OCG to replace.
- `keepOCG` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The replacement OCG.

**Returns:** `void`

**See also:** [`PDDocHasOC`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocHasOC), [`PDDocGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCGs), [`PDDocEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCGs), [`PDDocGetNumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNumOCGs), [`PDDocGetOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCConfig), [`PDDocGetOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCContext)

#### PDDocReplacePages

```cpp
void PDDocReplacePages(PDDoc doc, ASInt32 startPage, PDDoc doc2, ASInt32 startPageDoc2, ASInt32 numPages, ASBool mergeTextAnnots, ProgressMonitor progMon, void *progMonClientData, CancelProc cancelProc, void *cancelProcClientData)
```

Header: `PDProcs.h:1814`

Replaces the specified range of pages in one document with pages from another. The contents, resources, size and rotation of the pages are replaced. The bookmarks are not copied, because they are attached to the document, not to individual pages. **Note:** Annotations in the replaced pages are not replaced and remain with the page. Use PDDocDeletePages() to remove annotations.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which pages are replaced.
- `startPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The first page number in `doc` to replace. The first page is `0`.
- `doc2` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document from which pages are copied into `doc`.
- `startPageDoc2` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number of the first page in `doc2` to copy. The first page is `0`.
- `numPages` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of pages to replace.
- `mergeTextAnnots` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, text annotations from `doc2` are appended if they are different than all existing annotations on the page in `doc`. No other types of annotations are copied.
- `progMon` ([`ProgressMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ProgressMonitor)): A progress monitor. Use AVAppGetDocProgressMonitor() to obtain the default progress monitor. `NULL` may be passed, in which case no progress monitor is used.
- `progMonClientData` (`void *`): A pointer to user-supplied data to pass to `progMon` each time it is called. It should be `NULL` if `progMon` is `NULL`.
- `cancelProc` ([`CancelProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#CancelProc)): Currently unused. A cancel procedure. Use AVAppGetCancelProc() to obtain the current cancel procedure. It may be `NULL`, in which case no cancel proc is used.
- `cancelProcClientData` (`void *`): A pointer to user-supplied data to pass to `cancelProc` each time it is called. It should be `NULL` if `cancelProc` is `NULL`.

**Returns:** `void`

**Exceptions**

- `pdErrOpNotPermitted`: is raised unless `doc` is editable and `doc2` is not encrypted or the owner opened it.
- `pdErrCantUseNewVersion`: is raised if `doc2` is a newer major version than the Acrobat viewer understands.
- `genErrBadParm`: is raised if one of the following conditions is true:

  • `numPages < 1`

  • `startPage < 0`

  • `startPage + numPages` is greater than the number of pages in `doc`

  • `startPageDoc2 < 0`

  • `startPageDoc2 + numPages` is greater than the number of pages in `doc2`
- `genErrNoMemory`: is raised if there is insufficient memory to perform the insertion. @notify PDDocWillReplacePages @notify PDDocDidReplacePages @notify PDDocDidChangePages @notify PDDocWillChangePages

**See also:** [`PDDocInsertPages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocInsertPages), [`PDDocMovePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocMovePage), [`PDDocDeletePages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocDeletePages), [`PDDocCreatePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreatePage)

#### PDDocRequestEntireFile

```cpp
void PDDocRequestEntireFile(PDDoc doc, PDDocRequestEntireFileProc requestProc, void *clientData)
```

Header: `PDProcs.h:10872`

Requests the document file and performs the specified procedure on it.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document for which pages are read ahead.
- `requestProc` ([`PDDocRequestEntireFileProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRequestEntireFileProc)): The procedure to call to process the request.
- `clientData` (`void *`): A pointer to user-defined data to pass to the `requestProc`.

**Returns:** `void`

#### PDDocRequestPages

```cpp
void PDDocRequestPages(PDDoc doc, ASInt32 startPage, ASInt32 nPages, PDDocRequestPagesProc requestProc, void *clientData)
```

Header: `PDProcs.h:10860`

Requests `nPages` starting at `startPage`, and performs a specified procedure on them.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document for which pages are read ahead.
- `startPage` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The first page requested.
- `nPages` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of pages requested.
- `requestProc` ([`PDDocRequestPagesProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRequestPagesProc)): The procedure to call to process the request.
- `clientData` (`void *`): A pointer to user-defined data to pass to the `requestProc`.

**Returns:** `void`

#### PDDocResetInkUsage

```cpp
void PDDocResetInkUsage(PDDoc doc)
```

Header: `PDProcs.h:11984`

Resets the cached ink (spot color) usage information in a document. This should be called when the set of non-process colorants for a document have been changed. Calling this will force the cached information to be recomputed.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN The document on which to reset set the ink usage.

**Returns:** `void`

#### PDDocSave

```cpp
void PDDocSave(PDDoc doc, PDSaveFlags saveFlags, ASPathName newPath, ASFileSys fileSys, ProgressMonitor progMon, void *progMonClientData)
```

Header: `PDProcs.h:1360`

Saves a document to disk. If a full save is requested to the original path, the file is saved to a file system-determined temporary file, the old file is deleted, and the temporary file is renamed to `newPath`. You must call PDDocClose() to release resources; do not call PDDocRelease(). If the document was created with PDDocCreate(), at least one page must be added using PDDocCreatePage() or PDDocInsertPages() before Acrobat can save the document. You can replace this method with your own version, using HFTReplaceEntry(). A full save with linearization optimizes the PDF file. During optimization, all objects in a PDF file are rearranged, many of them acquiring not only a new file position, but also a new Cos object number. At the end of the save operation, Acrobat flushes its information of the PD layer and below to synchronize its in-memory state with the new disk file just written. It is crucial that all objects that have been acquired from a PDDoc be released before Acrobat attempts to flush its in-memory state. This includes any object that was acquired with a `PD*Acquire` method, such as PDDocAcquirePage() or PDBeadAcquirePage(). Failing to release these objects before the full save results in a save error, and the resulting PDF file is not valid. In addition, all PD level objects and Cos objects derived from the PDDoc are no longer valid after the full save. Attempting to use these objects after a full save produces undefined results. Clients and applications should register for the PDDocWillSaveEx() and PDDocDidSave() notifications so that they can clean up appropriately. See these notifications for more information on releasing and reacquiring objects from the PDDoc. @ingroup ReplaceableMethods

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document to save.`OR` of the
  PDSaveFlags values.
- `saveFlags` ([`PDSaveFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDSaveFlags))
- `newPath` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The path to which the file is saved. A
  path must be specified when either PDSaveFull or PDSaveCopy
  are used for saveFlags. If PDSaveIncremental is specified
  in saveFlags, then `newPath` should be `NULL`. If PDSaveFull
  is specified and `newPath` is the same as the file's original
  path, the new file is saved to a file system-determined
  temporary path, then the old file is deleted and the new
  file is renamed to `newPath`.`NULL`, uses the `fileSys`
  of the document's current backing file. Files can only be
  saved to the same file system. `fileSys` must be either `NULL`
  or the default file system obtained with ASGetDefaultFileSys(),
  otherwise an error is raised.
- `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys))
- `progMon` ([`ProgressMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ProgressMonitor)): A progress monitor. Use AVAppGetDocProgressMonitor()
  to obtain the default. `NULL` may be passed, in which case
  no progress monitor is used.
- `progMonClientData` (`void *`): A pointer to user-supplied data
  to pass to `progMon` each time it is called. It should be `NULL`
  if `progMon` is `NULL`.

**Returns:** `void`

**Exceptions**

- `pdErrAlreadyOpen`: is raised if PDSaveFull is used, and the file specified by `newPath` is already open. @notify PDDocWillSave @notify PDDocDidSave
- `pdErrAfterSave`: is raised if the save was completed successfully,
  but there were problems cleaning up afterwards. The document is no longer
  consistent and cannot be changed. It must be closed and reopened.
- `pdErrOpNotPermitted`: is raised if saving is not permitted. Saving
  is permitted if either `edit` or `editNotes` (see PDPerms) is allowed,
  or you are doing a full save and saveAs is allowed.

  **Note:** Not replaceable in Adobe Reader.

**See also:** [`PDDocClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClose), [`PDDocSaveWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSaveWithParams)

#### PDDocSaveWithParams

```cpp
void PDDocSaveWithParams(PDDoc doc, PDDocSaveParams inParams)
```

Header: `PDProcs.h:6165`

Saves a document to disk as specified in a parameter's structure. This is essentially the same as PDDocSave() with two additional parameters: a cancel proc and cancel proc client data (so you could cut and paste description information and other information from PDDocSave()). You can replace this method with your own version, using HFTReplaceEntry(). **Note:** Saving a PDDoc invalidates all objects derived from it. See PDDocSave() for important information about releasing objects that you may have acquired or used from a PDDoc before it is saved. **Note:** Not replaceable in Adobe Reader.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document to save.
- `inParams` ([`PDDocSaveParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSaveParams)): A PDDocSaveParams structure specifying how the document should be saved.

**Returns:** `void`

**See also:** [`PDDocSave`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSave)

#### PDDocSetAdobePDFVersion

```cpp
void PDDocSetAdobePDFVersion(PDDoc doc, const AdobePDFVersion version)
```

Header: `PDProcs.h:12815`

PDDocSetAdobePDFVersion() sets the current version of the document in the AdobePDFVersion define in CosExp.T

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose version is to be updated.
- `version` ([`const AdobePDFVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#AdobePDFVersion)): IN/OUT version to which document is updated.

**Returns:** `void`

#### PDDocSetFlags

```cpp
void PDDocSetFlags(PDDoc doc, ASInt32 flags)
```

Header: `PDProcs.h:1434`

Sets information about the document's file and its state. This method can only be used to set, not clear, flags. As a result, it is not possible, for example, to use this method to clear the flag that indicates that a document has been modified and needs to be saved. Instead, use PDDocClearFlags() to clear flags.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose flags are set.
- `flags` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT A bit field composed of an `OR` of the PDDocFlags values.

**Returns:** `void`

**See also:** [`PDDocGetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetFlags), [`PDDocClearFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClearFlags)

#### PDDocSetFullScreen

```cpp
void PDDocSetFullScreen(PDDoc pdDoc, ASBool fs)
```

Header: `PDProcs.h:6141`

Sets whether this document opens in full-screen mode. This provides an alternative to calling PDDocSetPageMode() with PDFullScreen.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document to set.
- `fs` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): `true` if the document is set to open in full-screen mode, `false` otherwise.

**Returns:** `void`

**See also:** [`PDDocGetFullScreen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetFullScreen)

#### PDDocSetLayoutMode

```cpp
void PDDocSetLayoutMode(PDDoc doc, PDLayoutMode mode)
```

Header: `PDProcs.h:11331`

Sets the value of the PageLayout key in the Catalog dictionary.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN The document whose page mode is set.
- `mode` ([`PDLayoutMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLayoutMode)): IN The layout mode to set.

**Returns:** `void`

**See also:** [`PDDocGetLayoutMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetLayoutMode)

#### PDDocSetMinorVersion

```cpp
void PDDocSetMinorVersion(PDDoc pdDoc, ASInt16 minor)
```

Header: `PDProcs.h:11846`

Sets the PDF minor version to the greater of its current value and the requested value. This function should be called when any feature requiring a PDF version of 1.7 or higher is applied to a document.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document.
- `minor` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): The minimum required minor version

**Returns:** `void`

#### PDDocSetNewCryptFilterData

```cpp
void PDDocSetNewCryptFilterData(PDDoc doc, ASAtom filterName, char *cryptData, ASInt32 cryptDataLen)
```

Header: `PDProcs.h:10795`

Sets the encrypted data for the specified document's encryption filter to decrypt. Call this before accessing the stream to be decrypted. @product_exclude RDR

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose new encrypted data is set.
- `filterName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom corresponding to the name of the security filter used by the document.
- `cryptData` (`char *`): The new encrypted data for the document.
- `cryptDataLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length of `cryptData` in bytes.

**Returns:** `void`

**Exceptions**

- `pdErrNoCryptHandler`: is raised if there is no security handler registered for the document.
- `pdErrOpNotPermitted`: is raised if the document's permissions do not allow its data to be modified.

**See also:** [`PDCryptAuthorizeFilterAccess`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptAuthorizeFilterAccess), [`PDDocSetNewCryptFilterMethod`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptFilterMethod), [`PDDocSetNewDefaultFilters`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewDefaultFilters)

#### PDDocSetNewCryptFilterMethod

```cpp
void PDDocSetNewCryptFilterMethod(PDDoc doc, ASAtom filterName, ASAtom method)
```

Header: `PDProcs.h:10771`

Sets or resets the specified document's security filter method, used for encryption and decryption of the document's data. @product_exclude RDR

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose new security filter method is set.
- `filterName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom corresponding to the name of the security filter to use.
- `method` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): One of five supported security methods:

  • None (default)

  • V2 (RC4)

  • V3 (RC4)

  • AESV1

  • AESV2 (128 bit)

  • AESV3 (256 bit)

**Returns:** `void`

**Exceptions**

- `pdErrNoCryptHandler`: is raised if there is no security handler registered for the document.

**See also:** [`PDCryptAuthorizeFilterAccess`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptAuthorizeFilterAccess), [`PDDocSetNewCryptFilterData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptFilterData), [`PDDocSetNewDefaultFilters`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewDefaultFilters)

#### PDDocSetNewCryptHandler

```cpp
void PDDocSetNewCryptHandler(PDDoc pdDoc, ASAtom newCryptHandler)
```

Header: `PDProcs.h:2508`

Sets the specified document's new security handler (that is, the security handler that will be used after the document is saved). This method returns with no action if the new security handler is the same as the old one. Otherwise, it calls the new security handler's PDCryptNewSecurityDataProc() to set the document's `newSecurityData` field. If the new security handler does not have this callback, the document's `newSecurityData` field is set to `0`.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose new security handler is set.
- `newCryptHandler` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom for the name of the new security handler to use for the document. This name must be the same as the `pdfName` used when the security handler was registered using PDRegisterCryptHandler(). Use ASAtomNull to remove security from the document.

**Returns:** `void`

**Exceptions**

- `pdErrNoCryptHandler`: is raised if there is no security handler registered with the specified name and the name is not ASAtomNull.
- `pdErrOpNotPermitted`: is raised if the document's permissions do not allow its security to be modified.

**See also:** [`PDDocGetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewCryptHandler), [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest), [`PDDocSetNewCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandlerEx), [`PDRegisterCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandler), [`PDRegisterCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandlerEx)

#### PDDocSetNewCryptHandlerEx

```cpp
void PDDocSetNewCryptHandlerEx(PDDoc pdDoc, ASAtom newCryptHandler, void *currentAuthData)
```

Header: `PDProcs.h:11026`

Extends PDDocSetNewCryptHandler() for Acrobat 6.0. It sets the specified document's new security handler (that is, the security handler that will be used after the document is saved). This method should be called when the current document's security handler requires authorization data to validate permission to change security handlers. This method returns with no action if the new security handler is the same as the old one. Otherwise, the new security handler's PDCryptNewSecurityDataProc() is called to set the document's `newSecurityData` field. If the new security handler does not have this callback, the document's `newSecurityData` field is set to `0`.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose new security handler is set.
- `newCryptHandler` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom corresponding to the name of the new security handler to use for the document. This name must be the same as the `pdfName` used when the security handler was registered using PDRegisterCryptHandler(). Use ASAtomNull to remove security from the document.
- `currentAuthData` (`void *`): A pointer to authorization data to be passed to the PDCryptAuthorizeProc() callback for the document's current security handler. For the Acrobat viewer's built-in security handler, the password is passed in the `authData` parameter.

**Returns:** `void`

**Exceptions**

- `pdErrNoCryptHandler`: is raised if there is no security handler registered with the specified name and the name is not ASAtomNull.
- `pdErrOpNotPermitted`: is raised if the document's permissions do not allow its security to be modified.

**See also:** [`PDDocGetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewCryptHandler), [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest), [`PDDocSetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandler), [`PDRegisterCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandler), [`PDRegisterCryptHandlerEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterCryptHandlerEx)

#### PDDocSetNewDefaultFilters

```cpp
void PDDocSetNewDefaultFilters(PDDoc doc, ASAtom defaultStmFilterName, ASAtom defaultStrFilterName)
```

Header: `PDProcs.h:10818`

Sets or resets the document's default security filter methods for streams and strings, used to encrypt and decrypt the document's data. This method is only valid with version 4 algorithms (/V 4 in the Encrypt dictionary).

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose new security filter is set.
- `defaultStmFilterName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom corresponding to the name of the default security filter to use for streams. The filter must exist and be registered.
- `defaultStrFilterName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom corresponding to the name of the default security filter to use for strings. The filter must exist and be registered.

**Returns:** `void`

**Exceptions**

- `pdErrNoCryptHandler`: is raised if there is no security handler registered for the document.

**See also:** [`PDCryptAuthorizeFilterAccess`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptAuthorizeFilterAccess), [`PDDocSetNewCryptFilterData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptFilterData), `PDDocSetNewCryptFilterMethod @product_exclude RDR`

#### PDDocSetNewSecurityData

```cpp
void PDDocSetNewSecurityData(PDDoc pdDoc, void *secData)
```

Header: `PDProcs.h:2477`

Sets the security data structure for the specified document's new security handler. Use PDDocSetNewCryptHandler() to set a new security handler for a document.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose new security data structure is set.
- `secData` (`void *`): IN/OUT A pointer to the new security data structure to set for `doc`. See PDDocNewSecurityData() for information on creating and filling this structure.

**Returns:** `void`

**Exceptions**

- `pdErrNeedCryptHandler`: is raised if the document does not have a new security handler.
- `pdErrOpNotPermitted`: is raised if the document's permissions cannot be changed.

**See also:** [`PDDocGetNewSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNewSecurityData), [`PDDocGetSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetSecurityData), [`PDDocNewSecurityData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocNewSecurityData), [`PDDocSetNewCryptHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetNewCryptHandler)

#### PDDocSetOpenAction

```cpp
void PDDocSetOpenAction(PDDoc doc, PDAction action)
```

Header: `PDProcs.h:1255`

Sets the value of the OpenAction key in the Catalog dictionary, which is the action performed when the document is opened.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose open action is set.
- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): The open action you want to set.

**Returns:** `void`

**See also:** [`PDDocGetOpenAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOpenAction)

#### PDDocSetPageLabel

```cpp
void PDDocSetPageLabel(PDDoc pdDoc, ASInt32 pageNum, PDPageLabel pgLabel)
```

Header: `PDProcs.h:7288`

Attaches a label to a page. This establishes the numbering scheme for that page and all pages following it, until another page label is encountered. This label allows PDF producers to define a page numbering system other than the Acrobat default. If `pageNum` is less than `0` or greater than the number of pages in `pdDoc`, the method does nothing. @notify PDDocPageLabelDidChange

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document containing the page to label.
- `pageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of the page to label.
- `pgLabel` ([`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)): The label for the page specified by `pageNum`.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if `pgLabel` is not a valid PDPageLabel.

**See also:** [`PDDocFindPageNumForLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocFindPageNumForLabel), [`PDDocGetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageLabel), [`PDDocGetLabelForPageNum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetLabelForPageNum), [`PDDocRemovePageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemovePageLabel), [`PDPageLabelNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelNew)

#### PDDocSetPageMode

```cpp
void PDDocSetPageMode(PDDoc doc, PDPageMode mode)
```

Header: `PDProcs.h:1458`

Sets the value of the PageMode key in the Catalog dictionary.

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The document whose page mode is set.
- `mode` ([`PDPageMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageMode)): IN/OUT The page mode to set.

**Returns:** `void`

**See also:** [`PDDocGetPageMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageMode), `AVDocSetViewMode`

#### PDDocSetTrapped

```cpp
void PDDocSetTrapped(PDDoc pdDoc, ASAtom newValue)
```

Header: `PDProcs.h:11058`

Sets the value of the Trapped key in the Info dictionary to the specified ASAtom. This method causes the corresponding XMP metadata item to be set to a string reflecting the characters in the ASAtom.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document whose Trapped key value to set.
- `newValue` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The new value of the Trapped key in the Info dictionary, or ASAtomNull to remove any existing entry. The method does not check that the value is one of the allowed values for the key.

**Returns:** `void`

**See also:** [`PDDocGetTrapped`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetTrapped)

#### PDEnumDocs

```cpp
void PDEnumDocs(PDDocEnumProc proc, void *clientData)
```

Header: `PDProcs.h:1171`

Enumerates the PDDoc objects that are currently open, calling a user-supplied procedure for each open document.

**Parameters**

- `proc` ([`PDDocEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumProc)): IN/OUT A user-supplied callback to call for each open PDDoc. Enumeration halts if `proc` returns `false`.
- `clientData` (`void *`): IN/OUT A pointer to user-supplied data to pass to `proc` each time it is called.

**Returns:** `void`

**See also:** `AVAppEnumDocs`, [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen)

### Typedefs (22)

#### PDDocFlags

```cpp
typedef ASInt32 PDDocFlags
```

Header: `PDExpT.h:103`

A `signed int` (which is never negative), for historical reasons.

**See also:** [`PDDocClearFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClearFlags), [`PDDocGetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetFlags), [`PDDocSetFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetFlags)

#### PDDocOCChangeType

```cpp
typedef ASUns8 PDDocOCChangeType
```

Header: `PDExpT.h:5830`

#### PDDocRequestReason

```cpp
typedef ASEnum8 PDDocRequestReason
```

Header: `PDExpT.h:6533`

#### PDDocVersion

```cpp
typedef ASInt16 PDDocVersion
```

Header: `PDExpT.h:95`

A `signed int` (which is never negative), for historical reasons.

#### PDLayoutMode

```cpp
typedef ASEnum8 PDLayoutMode
```

Header: `PDExpT.h:2064`

#### PDPermReqObj

```cpp
typedef ASUns32 PDPermReqObj
```

Header: `PDExpT.h:4190`

#### PDPermReqOpr

```cpp
typedef ASUns32 PDPermReqOpr
```

Header: `PDExpT.h:4269`

#### PDPermReqStatus

```cpp
typedef ASInt16 PDPermReqStatus
```

Header: `PDExpT.h:4129`

The set of valid PDPermRequestStatus values providing the status of PDDoc-related permissions methods.

**See also:** [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest), [`PDCryptAuthorizeExProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptAuthorizeExProc), [`PDCryptGetAuthDataExProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptGetAuthDataExProc)

#### PDPerms

```cpp
typedef ASUns32 PDPerms
```

Header: `PDExpT.h:1436`

Constant values that specify permissions which allow operations on a document file.

**See also:** `AVCryptGetPassword`, [`PDDocAuthorize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAuthorize), `PDDocGetPermissions (obsolete)`, [`PDDocPermRequest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocPermRequest), [`PDCryptAuthorizeProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptAuthorizeProc), [`PDCryptGetAuthDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptGetAuthDataProc)

#### PDPrintWhat

```cpp
typedef ASEnum8 PDPrintWhat
```

Header: `PDExpT.h:5644`

#### PDSaveFlags

```cpp
typedef ASEnum16 PDSaveFlags
```

Header: `PDExpT.h:1506`

#### PDAuthProc

```cpp
typedef ASBool(*) PDAuthProc(PDDoc pdDoc)(PDDoc pdDoc)
```

Header: `PDExpT.h:1264`

A callback used by PDDocOpen. It is called when an encrypted document is being opened to determine whether the user is authorized to open the file. This callback implements whatever authorization strategy you choose and calls the callbacks of the appropriate security handler (the one that was used to secure the document) to obtain and check authorization data. The PDAuthProc() must call the security handler's PDCryptGetAuthDataProc() to obtain whatever authorization data is needed (such as a password), then call PDDocAuthorize() (which is mostly a call to the security handler's PDCryptAuthorizeProc()) to determine whether this data authorizes access to the file (for example, it verifies if the user provided the correct password). The PDAuthProc() must also free the authorization data by calling the security handler's PDCryptFreeAuthDataProc() (or ASfree(), if the handler does not have a PDCryptFreeAuthDataProc()). For Acrobat 3.0 and earlier, the correct way to obtain the security handler in a PDAuthProc() is to call PDDocGetNewCryptHandler(), relying on the fact that it returns the security handler if the document has no new security handler, and the fact that at the time the file is opened, it cannot yet have a new security handler (in the future, one or more new methods may be added to make this procedure more straightforward). The Acrobat viewer's built-in authorization procedure works according to the following algorithm: Call the security handler's PDCryptAuthorizeProc() with `NULL` authorization data to automatically handle the case where no authorization data is needed (for example, the file has a `NULL` password). If PDCryptAuthorizeProc() returns `true`, open the file. If PDCryptAuthorizeProc() returns `false` then Loop for `i = 1 to 3` {Call the security handler's PDCryptGetAuthDataProc(). If PDCryptGetAuthDataProc returns `true` { Call PDDocAuthorize(). If it returns `true` (authorized) call the security handler's PDCryptFreeAuthDataProc(). Exit the loop and return from PDAuthProc().} Call the security handler's PDCryptFreeAuthDataProc().} If it failed to get authorization after three attempts, display a dialog box indicating that user is not authorized to open the file. }return from PDAuthProc().

**See also:** [`PDDocAuthorize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAuthorize), [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenEx)

#### PDAuthProcEx

```cpp
typedef ASBool(*) PDAuthProcEx(PDDoc pdDoc, void *clientData)(PDDoc pdDoc, void *clientData)
```

Header: `PDExpT.h:1298`

A callback used by PDDocOpenEx(). It is called when an encrypted document is opened, to determine whether the user is authorized to open the file. This callback implements whatever authorization strategy you choose and calls the callbacks of the appropriate security handler (the one that was used to secure the document) to obtain and check authorization data. The PDAuthProcEx() should obtain the authorization data (usually a password) and call PDDocAuthorize(). PDDocAuthorize() in turn calls the document encryption handler's `Authorize` function, which returns the permissions that the authorization data enables. PDDocAuthorize() adds these permissions to those currently allowed, and returns the new set of allowed permissions.

**See also:** [`PDDocAuthorize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAuthorize), [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenEx)

#### PDDocEnumProc

```cpp
typedef ASBool(*) PDDocEnumProc(PDDoc pdDoc, void *clientData)(PDDoc pdDoc, void *clientData)
```

Header: `PDExpT.h:3689`

A callback for PDEnumDocs(). It is called once for each open PDDoc.

**See also:** [`PDEnumDocs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDEnumDocs)

#### PDDocPreSaveProc

```cpp
typedef void(*) PDDocPreSaveProc(PDDoc pdDoc, PDDocPreSaveInfo preSaveInfo, void *clientData)(PDDoc pdDoc, PDDocPreSaveInfo preSaveInfo, void *clientData)
```

Header: `PDExpT.h:1684`

A callback in the PDDocSaveParams structure used by PDDocSaveWithParams(). Use this callback to flag Cos objects you wish to access while a PDDoc is being saved.

**See also:** [`PDDocSaveWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSaveWithParams)

#### PDDocPreWriteProc

```cpp
typedef void(*) PDDocPreWriteProc(PDDoc pdDoc, void *clientData)(PDDoc pdDoc, void *clientData)
```

Header: `PDExpT.h:1694`

A callback in the PDDocSaveParams structure. It is invoked by PDDocSaveWithParams() immediately before a PDDoc is saved to disk.

**See also:** [`PDDocSaveWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSaveWithParams)

#### PDDocRequestEntireFileProc

```cpp
typedef ASInt32(*) PDDocRequestEntireFileProc(PDDoc pdDoc, PDDocRequestReason reason, void *clientData)(PDDoc pdDoc, PDDocRequestReason reason, void *clientData)
```

Header: `PDExpT.h:6557`

A callback used by PDDocRequestEntireFile. Use this callback to process a document file.

**See also:** [`PDDocRequestEntireFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRequestEntireFile)

#### PDDocRequestPagesProc

```cpp
typedef ASInt32(*) PDDocRequestPagesProc(PDDoc pdDoc, ASInt32 startPage, ASInt32 nPages, PDDocRequestReason reason, void *clientData)(PDDoc pdDoc, ASInt32 startPage, ASInt32 nPages, PDDocRequestReason reason, void *clientData)
```

Header: `PDExpT.h:6536`

A callback for PDDocRequestPages().

#### PDDocWillExportAnnotCallback

```cpp
typedef ASBool(*) PDDocWillExportAnnotCallback(PDDoc doc, PDPage pdpage, PDAnnot src, CosObj dict)(PDDoc doc, PDPage pdpage, PDAnnot src, CosObj dict)
```

Header: `PDExpT.h:6224`

A callback for PDDocExportNotes. It determines whether an annotation is exported. **Note:** This is a different callback than PDDocWillExportAnnotProc().

**See also:** [`PDDocWillImportAnnotCallback`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocWillImportAnnotCallback)

#### PDDocWillExportAnnotProc

```cpp
typedef ASBool(*) PDDocWillExportAnnotProc(PDAnnotHandler pdanh, PDAnnot src, PDAnnot dst)(PDAnnotHandler pdanh, PDAnnot src, PDAnnot dst)
```

Header: `PDExpT.h:628`

A callback for PDAnnotHandler. It determines whether an annotation is exported. **Note:** This is a different callback than PDDocWillImportAnnotCallback().

**See also:** [`PDAnnotWillPrintProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotWillPrintProc), [`PDDocWillImportAnnotProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocWillImportAnnotProc), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

#### PDDocWillImportAnnotCallback

```cpp
typedef ASBool(*) PDDocWillImportAnnotCallback(PDDoc doc, PDPage pdPage, PDAnnot annot)(PDDoc doc, PDPage pdPage, PDAnnot annot)
```

Header: `PDExpT.h:6241`

A callback for PDDocImportCosDocNotes() and PDDocImportNotes(). It determines whether an annotation will be imported. **Note:** This is a different callback than PDDocWillImportAnnotProc().

**See also:** [`PDDocWillExportAnnotCallback`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocWillExportAnnotCallback)

#### PDDocWillImportAnnotProc

```cpp
typedef ASBool(*) PDDocWillImportAnnotProc(PDAnnotHandler pdanh, PDDoc doc, PDPage pdpage, PDAnnot annot)(PDAnnotHandler pdanh, PDDoc doc, PDPage pdpage, PDAnnot annot)
```

Header: `PDExpT.h:646`

A callback for PDAnnotHandler. It determines whether an annotation will be imported. **Note:** This is a different callback than PDDocWillImportAnnotCallback().

**See also:** [`PDAnnotWillPrintProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotWillPrintProc), [`PDDocWillExportAnnotProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocWillExportAnnotProc), [`PDRegisterAnnotHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterAnnotHandler)

### Structures (4)

#### PDDoc

```cpp
typedef struct _t_PDDoc* PDDoc
```

Header: `PDBasicExpT.h:68`

The underlying PDF representation of a document. There is a correspondence between a PDDoc and an ASFile; the PDDoc object is the hidden object behind every AVDoc. An ASFile may have zero or more underlying files, so a PDF file does not always correspond to a single disk file. For example, an ASFile may provide access to PDF data in a database. Through PDDoc objects, your application can perform most of the menu items for pages from Acrobat (delete, replace, and so on). Thumbnails can be created and deleted through this object. You can set and retrieve document information fields through this object as well. The first page in a PDDoc is page `0`.

**See also:** `AVDocGetPDDoc`, [`PDDocFromCosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocFromCosDoc), [`PDDocOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpen), [`PDDocOpenFromASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenFromASFile), [`PDDocOpenWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenWithParams), [`PDDocCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreate), [`PDPageGetDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetDoc), [`PDFileSpecGetDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecGetDoc), [`PDEnumDocs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDEnumDocs), [`PDDocClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocClose), [`PDDocRelease`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRelease), [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts), [`PDDocEnumLoadedFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumLoadedFonts)

#### PDDocInsertPagesParams

```cpp
typedef struct _t_PDDocInsertPagesParams* PDDocInsertPagesParams
```

Header: `PDExpT.h:1938`

#### PDDocOpenParams

```cpp
typedef struct _t_PDDocOpenParams* PDDocOpenParams
```

Header: `PDExpT.h:1946`

A structure used by PDDocOpenWithParams() to specify file open information. The parameters are very similar to those in PDDocOpenEx() and PDDocOpenFromASFileEx().

**See also:** [`PDDocOpenWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocOpenWithParams)

#### PDDocSaveParams

```cpp
typedef struct _t_PDDocSaveParams* PDDocSaveParams
```

Header: `PDExpT.h:1854`

### Enums (5)

#### PDDocOCChangeTypes

Header: `PDExpT.h:5795`

PDDocOCChangeType is an enumeration of types of changes to the optional content structures of a PDDoc. These types of changes may effect visibility in *all* PDOCContext objects. This enumeration is used in the `PDDocOCWillChange()` and `PDDocOCDidChange()` notifications. These notifications typically pass in the affected page, or `PDAllPages` if all pages may be affected.

**Values**

- `kPDOCGCreate = 0`: Optional Content Groups (OCGs) created.
- `kPDOCGProperties = 1`: OCG properties changed.
- `kPDOCGReplace = 2`: An OCG was replaced by another.
- `kPDOCGDestroy = 3`: An OCG was destroyed.
- `kPDOCMDAttach = 4`: Content was made optional.
- `kPDOCMDRemove = 5`: Content was made optional.
- `kPDOCConfigCreate = 6`: An OC config was created.
- `kPDOCConfigChange = 7`: An OC config was changed.
- `kPDOCConfigDestroy = 8`: An OC config was destroyed.
- `kPDDocRemoveOC = 9`: OC was removed from document.
- `kPDOC_LastDocChangeType = kPDDocRemoveOC`

#### PDDocRequestReasons

Header: `PDExpT.h:6519`

This tells the callback why it is being called.

**Values**

- `kPDDocRequestUnderway = 0`: The request is still being processed.
- `kPDDocRequestComplete = 1`: The requested data has arrived.
- `kPDDocRequestCancelled = 2`: The request is cancelled because the file is being closed.
- `kPDDocRequestError = 3`: An error occurred.

#### PDDocSaveFlags

Header: `PDExpT.h:1449`

Flags for the PDDocSave `saveFlags` parameter. All undefined flags should be set to zero.

**Values**

- `PDSaveIncremental = 0x00`: Save only those portions of the document that have changed. This is provided only as the *opposite* of `PDSaveFull`, since there is no bit value of `0`.
- `PDSaveFull = 0x01`: Save the entire document. Plug-ins that set `PDSaveFull` are also encouraged to set `PDSaveCollectGarbage`.
- `PDSaveCopy = 0x02`: Save a copy of the document (the PDDoc continues to use the old file). This flag is ignored if `PDSaveFull` is off.
- `PDSaveLinearized = 0x04`: Write the PDF file in a format that is optimized for page-served remote (network) access (*linearized*). This flag is ignored if `PDSaveFull` is off.

  Linearizing a file used to cause Cos objects to be invalidated, which required that some plug-ins use notifications to release and re-acquire objects. But Cos objects are no longer invalidated after a linearized save.
- `PDSaveWithPSHeader = 0x08`: (Obsolete. In effect, it is always off). Write a PostScript header as part of the saved file.
- `PDSaveBinaryOK = 0x10`: (Obsolete. In effect, it is always on). It is okay to store binary data in the PDF file.
- `PDSaveCollectGarbage = 0x20`: Remove unreferenced objects, often reducing file size. Plug-ins are encouraged to use this flag. This flag is ignored if `PDSaveFull` is off.
- `PDSaveForceIncremental = 0x40`: Perform an incremental save even if the save is to a different file or the document's version number has changed.
- `PDSaveKeepModDate = 0x80`: Do not update ModDate in InfoDict.
- `PDSaveLeaveOpen = 0x100`: Leave the file open after the save (do not Close the file)
- `PDSaveLinearizedNoOptimizeFonts = 0x200`: Save the document as Linearized the same as PDSaveLinearized but inherently PDSaveOptimizeFonts is disabled. For documents with a large number of fonts, font optimization can have poor performance and is often uncessary.

**See also:** [`PDDocSave`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSave), [`PDSaveFlags2`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDSaveFlags2)

#### PDDocSaveFlags2

Header: `PDExpT.h:1516`

More flags for the PDDocSave() `saveFlags` parameter (`PDSaveFlags2`). All undefined flags should be set to zero. The first three flags, `PDSaveUncompressed`, `PDSaveCompressed`, and `PDSaveCompressStructureOnly`, are mutually exclusive; they can all be off, but at most one can be on.

**Values**

- `PDSaveUncompressed = 1 << 0`: Do not use object streams when saving the document (*decompress* all objects). The result is compatible with all versions of PDF and Acrobat. This flag is ignored if `PDSaveFull` is off.
- `PDSaveCompressed = 1 << 1`: Compress objects, without restrictions about which objects to compress. This flag is ignored if `PDSaveFull` is off.
- `PDSaveCompressStructureOnly = 1 << 2`: Compress only those objects that are related to logical structure (for example, tagged PDF). The result is compatible with any version of PDF or Acrobat, but the compressed objects are not usable. This flag is ignored if `PDSaveFull` is off.
- `PDSaveRemoveASCIIFilters = 1 << 3`: Remove ASCII85 filters from all streams. This flag is ignored if `PDSaveFull` is off.
- `PDSaveAddFlate = 1 << 4`: Encode any unencoded stream with Flate, except for metadata streams, which are never encoded, and for streams that would be larger if encoded. This flag is ignored if `PDSaveFull` is off. If `PDSaveAddFlate` and `PDSaveAddBrotli` are both set, only Flate is used.
- `PDSaveReplaceLZW = 1 << 5`: Replace all LZW filters with FlateEncode filters, or, if `PDSaveAddBrotli` is also set, with BrotliEncode filters. This flag is ignored if `PDSaveFull` is off.
- `PDSaveOptimizeXObjects = 1 << 6`: Merge identical forms and images, as determined by an MD5 hash of their contents (it causes OptimizeXObjects() to be called).
- `PDSaveOptimizeContentStreams = 1 << 7`: Look for common initial sub-sequences among content streams (the sequences of marking operators), and generate *substreams* that can be shared (it causes OptimizeGraphics() to be called).
- `PDSaveOptimizeFonts = 1 << 8`: Merge identical font descriptors and encodings. Does not merge the top-level font dictionary (it causes OptimizeFonts() to be called).
- `PDSaveOptimizeMarkedJBIG2Dictionaries = 1 << 9`: Delete symbols specific to deleted images from JBIG2 dictionaries that could not be processed at the time of image deletion. It is currently only effective after deleting pages or extracting pages (it causes OptimizeMarkedJBIG2Dictionaries() to be called).
- `PDSaveEnsure7bitASCII = 1 << 10`: (Obsolete. In effect, it is always off).
- `PDSaveAutoSave = 1 << 11`: The `PDSaveAutoSave` flag is used to indicate that the save that occurred is an auto-save event. It is only set when an auto-save occurs. It is a read-only flag.
- `PDSaveOverrideCollections = 1 << 12`: The `PDSaveOverrideCollections` flag controls whether `CosObjCollection` objects set up prior to saving are honored when doing a non-linearized save. Linearized save always uses its own rules for assigning objects to collections and object streams, so this flag is only used when the `PDSaveLinearized` flag is off. Furthermore, it is only used if either the `PDSaveCompressed` or `PDSaveCompressStructureOnly` flags is set. If this flag is set, the `PDDocSave` will remove all `CosObj` objects from their `CosObjCollection` objects and reassign objects to `CosObjCollection` objects (and object streams) using its own partitioning algorithms. If the flag is not set, the partitioning algorithms will preserve `CosObj` objects' existing membership in collections.
- `PDDoNotSaveFileAttributes = 1 << 13`: Do not save the new file output with the file attributes of the original
- `PDSaveOriginalMetaData = 1 << 14`: Save the new file Metadata stream with the Metadata stream of the original
- `PDSaveOptimizeObjects = 1 << 15`: Merge identical objects, as determined by an MD5 hash of their contents.
- `PDSaveAddBrotli = 1 << 16`: Encode any unencoded stream with Brotli, except for metadata streams, which are never encoded, and for streams that would be larger if encoded. Object streams and cross-reference streams written by the save are Brotli-encoded as well, and, when `PDSaveReplaceLZW` is also set, LZW filters are replaced with BrotliEncode rather than FlateEncode. This flag is ignored if `PDSaveFull` is off. It is also ignored when `PDSaveAddFlate` is set, which takes precedence.

  Brotli compressed stream data (IETF RFC 7932) is written with the `BrotliDecode` filter, an extension to PDF 2.0 published by the PDF Association. It is not part of ISO 32000-2:2020 itself, so PDF processors that do not implement the extension cannot read the affected streams. Use it only when the consumers of the output are known to support it.

**See also:** [`PDDocSave`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSave), [`PDSaveFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDSaveFlags)

#### PDOperations

Header: `PDExpT.h:974`

An enumerated data type that specifies the type of changes that occurred for the PDDocPrintingTiledPage() and PDDocDidChangePages() notifications. Not all `Did` notifications have corresponding `Will` notifications.

**Values**

- `pdOpInsertPages = 0`: Page insertion.
- `pdOpDeletePages = 1`: Page deletion.
- `pdOpReplacePages = 2`: Page replacement.
- `pdOpMovePages = 3`: Page rearrangment.
- `pdOpRotatePages = 4`: Page rotation.
- `pdOpCropPages = 5`: Page cropping.
- `pdOpAddResources = 6`: Only PDDocDidChangePages() exists, not PDDocWillChangePages().
- `pdOpRemoveResources = 7`: Only PDDocDidChangePages() exists, not PDDocWillChangePages().
- `pdOpAddContents = 8`: Only PDDocDidChangePages() exists, not PDDocWillChangePages().
- `pdOpRemoveContents = 9`: Only PDDocDidChangePages() exists, not PDDocWillChangePages().
- `pdOpSetMediaBox = 10`: Page media box modification.
- `pdOpSetBleedBox = 11`: Page bleed box modification.
- `pdOpSetTrimBox = 12`: Page trim box modification.
- `pdOpSetArtBox = 13`: Page art box modification.
- `pdOpSetTabOrder = 14`: Page tab order modification.

**See also:** [`PDDocDeletePages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocDeletePages), [`PDDocInsertPages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocInsertPages), [`PDDocMovePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocMovePage), [`PDPageAddCosContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddCosContents), [`PDPageAddCosResource`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddCosResource), [`PDPageRemoveCosContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveCosContents), [`PDPageRemoveCosResource`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveCosResource), [`PDPageSetRotate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetRotate), [`PDPageSetCropBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetCropBox), [`PDPageSetMediaBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetMediaBox)

### Definitions (59)

#### PDDocCreateTextSelect

Header: `PDCalls.h:157`

Value: `PDDocCreateTextSelectHost`

#### PDDocGetWordFinder

Header: `PDCalls.h:156`

Value: `PDDocGetWordFinderHost`

#### PDPermReqDenied

Header: `PDExpT.h:4131`

Value: `(PDPermReqStatus)(-1)`

`-1` The request was denied.

#### PDPermReqGranted

Header: `PDExpT.h:4133`

Value: `(PDPermReqStatus)(0)`

`0` The request was granted.

#### PDPermReqOperationNA

Header: `PDExpT.h:4139`

Value: `(PDPermReqStatus)(3)`

`3` The operation is not applicable for the specified object.

#### PDPermReqPending

Header: `PDExpT.h:4143`

Value: `(PDPermReqStatus)(4)`

The handler does not have enough information to determine an answer at this point. Try again later.

#### PDPermReqUnknownObject

Header: `PDExpT.h:4135`

Value: `(PDPermReqStatus)(1)`

`1` The object is unknown.

#### PDPermReqUnknownOperation

Header: `PDExpT.h:4137`

Value: `(PDPermReqStatus)(2)`

`2` The operation is unknown.

#### PDPermReqVersion

Header: `PDExpT.h:4146`

Value: `0x0004`

#### STDSEC_CryptRevision1

Header: `PDExpT.h:4386`

Value: `1`

#### STDSEC_CryptRevision2

Header: `PDExpT.h:4387`

Value: `2`

#### STDSEC_CryptRevision3

Header: `PDExpT.h:4388`

Value: `3`

#### STDSEC_CryptRevision4

Header: `PDExpT.h:4389`

Value: `4`

#### STDSEC_CryptRevision5

Header: `PDExpT.h:4397`

Value: `5`

#### STDSEC_CryptRevision6

Header: `PDExpT.h:4399`

Value: `6`

#### STDSEC_CryptVersionV1

Header: `PDExpT.h:4377`

Value: `1`

#### STDSEC_CryptVersionV2

Header: `PDExpT.h:4378`

Value: `2`

#### STDSEC_CryptVersionV3

Header: `PDExpT.h:4379`

Value: `3`

#### STDSEC_CryptVersionV4

Header: `PDExpT.h:4381`

Value: `4`

#### STDSEC_CryptVersionV5

Header: `PDExpT.h:4383`

Value: `5`

New encryption method for Acrobat 9.0

#### STDSEC_KEYLENGTH_AES128

Header: `PDExpT.h:4372`

Value: `16`

#### STDSEC_KEYLENGTH_AES256

Header: `PDExpT.h:4374`

Value: `32`

New encryption method for Acrobat 9.0

#### STDSEC_KEYLENGTH_RC4_V1

Header: `PDExpT.h:4370`

Value: `5`

#### STDSEC_KEYLENGTH_RC4_V2

Header: `PDExpT.h:4371`

Value: `16`

#### STDSEC_METHOD_AES_V1

Header: `PDExpT.h:4365`

Value: `5`

#### STDSEC_METHOD_AES_V2

Header: `PDExpT.h:4366`

Value: `6`

#### STDSEC_METHOD_AES_V3

Header: `PDExpT.h:4368`

Value: `7`

New encryption method for Acrobat 9.0

#### STDSEC_METHOD_RC4_V2

Header: `PDExpT.h:4364`

Value: `2`

#### kPDDocReadAheadAcroForms

Header: `PDExpT.h:4089`

Value: `0x0001`

Allows the AcroForm client to request that all the AcroForm data be read *ahead*, before the viewer needs it. This flag is ignored if the PDF file does not contain a Forms hint table. See the description of the Forms Hint Table in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, Annex F, section F.4.5, on page 693. You can find this document on the web store of the International Standards Organization (ISO).

#### kPDDocReadAheadPageLabels

Header: `PDExpT.h:4105`

Value: `0x0004`

Requests that the PDF file's page label data be read *ahead*, before the viewer needs it. There is currently no page label hint table defined, so this flag simply causes the rest of the file to be read.

#### kPDDocReadAheadRenditions

Header: `PDExpT.h:4116`

Value: `0x0010`

#### kPDDocReadAheadStructure

Header: `PDExpT.h:4112`

Value: `0x0008`

Requests that the PDF file's logical structure data be read *ahead*, before the viewer needs it. There is currently no logical structure hint table defined, so this flag simply causes the rest of the file to be read.

#### kPDDocReadAheadTemplates

Header: `PDExpT.h:4097`

Value: `0x0002`

Requests that the PDF file's Forms Template data be read *ahead*, before the viewer needs it. There is currently no Template hint table defined, so this flag simply causes the rest of the file to be read.

#### pdInfoCanCopy

Header: `PDExpT.h:4301`

Value: `pdPermCopy`

The document text and graphics can be copied to the clipboard.

#### pdInfoCanEdit

Header: `PDExpT.h:4296`

Value: `pdPermEdit`

The document can be modified (for example, by adding notes, links, or bookmarks).

**See also:** [`pdInfoCanEditNotes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#pdInfoCanEditNotes)

#### pdInfoCanEditNotes

Header: `PDExpT.h:4307`

Value: `pdPermEditNotes`

The document's notes, but nothing else, can be modified.

**See also:** [`pdInfoCanEdit`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#pdInfoCanEdit)

#### pdInfoCanPrint

Header: `PDExpT.h:4290`

Value: `pdPermPrint`

The document can be printed.

#### pdInfoHasOwnerPW

Header: `PDExpT.h:4285`

Value: `pdPermSecure`

The document has an owner password.

#### pdInfoHasUserPW

Header: `PDExpT.h:4280`

Value: `pdPermOpen`

The document has a user password.

#### pdOpAddResource

Header: `PDExpT.h:1024`

Value: `pdOpAddResources`

#### pdOpRemoveResource

Header: `PDExpT.h:1023`

Value: `pdOpRemoveResources`

#### pdPermAll

Header: `PDExpT.h:1415`

Value: `0xFFFFFFFF`

#### pdPermCopy

Header: `PDExpT.h:1331`

Value: `0x10`

The user can copy information from the document to the clipboard. In the document restrictions, this corresponds to the Content Copying or Extraction entry.

#### pdPermEdit

Header: `PDExpT.h:1324`

Value: `0x08`

The user can edit the document more than adding or modifying text notes (see also pdPermEditNotes). In the Document Security dialog, this corresponds to the Changing the Document entry.

#### pdPermEditNotes

Header: `PDExpT.h:1338`

Value: `0x20`

The user can add, modify, and delete text notes (see also pdPermEdit). In the document restrictions, this corresponds to the Authoring Comments and Form Fields entry.

#### pdPermExt

Header: `PDExpT.h:1353`

Value: `0x80`

#### pdPermOpen

Header: `PDExpT.h:1304`

Value: `0x01`

The user can open and decrypt the document.

#### pdPermOwner

Header: `PDExpT.h:1398`

Value: `0x8000`

The user is permitted to perform all operations, regardless of the permissions specified by the document. Unless this permission is set, the document's permissions will be reset to those in the document after a full save.

#### pdPermPrint

Header: `PDExpT.h:1317`

Value: `0x04`

The user can print the document. Page Setup access is unaffected by this permission, since that affects Acrobat's preferences - not the document's. In the Document Security dialog, this corresponds to the Printing entry.

#### pdPermSaveAs

Header: `PDExpT.h:1348`

Value: `0x40`

The user can perform a Save As.... If both pdPermEdit and pdPermEditNotes are disallowed, Save will be disabled but Save As... will be enabled. The Save As... menu item is not necessarily disabled even if the user is not permitted to perform a Save As.... **Note:** This cannot be set by clients.

#### pdPermSecure

Header: `PDExpT.h:1309`

Value: `0x02`

The user can change the document's security settings.

#### pdPermSettable

Header: `PDExpT.h:1421`

Value: `(pdPermPrint + pdPermEdit + pdPermCopy + pdPermEditNotes)`

The OR of all operations that can be set by the user in the security restrictions (pdPermPrint + pdPermEdit + pdPermCopy + pdPermEditNotes).

#### pdPermUser

Header: `PDExpT.h:1426`

Value: `(pdPermAll - pdPermOpen - pdPermSecure)`

All permissions.

#### pdPrivPermAccessible

Header: `PDExpT.h:1372`

Value: `0x200`

Overrides pdPermCopy to enable the Accessibility API. If a document is saved in Rev2 format (Acrobat 4.0 compatible), only the pdPermCopy bit is checked to determine the Accessibility API state.

#### pdPrivPermDocAssembly

Header: `PDExpT.h:1378`

Value: `0x400`

Overrides various pdPermEdit bits and allows the following operations: page insert/delete/rotate and create bookmark and thumbnail.

#### pdPrivPermFillandSign

Header: `PDExpT.h:1365`

Value: `0x100`

Overrides other PDPerm bits. It allows the user to fill in or sign existing form or signature fields.

#### pdPrivPermFormSpawnTempl

Header: `PDExpT.h:1410`

Value: `0x20000`

This should be set if the user can spawn template pages. This bit will allow page template spawning even if pdPermEdit and pdPermEditNotes are clear.

#### pdPrivPermFormSubmit

Header: `PDExpT.h:1404`

Value: `0x10000`

This should be set if the user can submit forms outside of the browser. This bit is a supplement to pdPrivPermFillandSign.

#### pdPrivPermHighPrint

Header: `PDExpT.h:1385`

Value: `0x800`

This bit is a supplement to pdPermPrint. If it is clear (disabled) only low quality printing (Print As Image) is allowed. On UNIX platforms where Print As Image doesn't exist, printing is disabled.

## PDEFont

### Structures (1)

#### PDEFont

```cpp
typedef struct _t_PDEFont* PDEFont
```

Header: `PDExpT.h:6565`

## PDEObject

### Enums (1)

#### PDEObjectStatusFlags

Header: `PDExpT.h:7114`

**Values**

- `kStatus_UnpairedMC = 0x1`

## PDFLPrint

### Structures (1)

#### PDTile

```cpp
typedef  struct PDTileRec * PDTile
```

Header: `PDExpT.h:6356`

## PDFileAttachment

### Functions (23)

#### PDFileAttachmentFromCosObj

```cpp
PDFileAttachment PDFileAttachmentFromCosObj(CosObj cosAttachment)
```

Header: `PDProcs.h:12156`

Converts a file specification dictionary to a `PDFileAttachment` object. An exception is raised if the parameter is not a file specification dictionary.

**Parameters**

- `cosAttachment` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj))

**Returns:** [`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)

The file attachment object.

#### PDFileAttachmentGetCosObj

```cpp
CosObj PDFileAttachmentGetCosObj(PDFileAttachment attachment)
```

Header: `PDProcs.h:12162`

Returns a `CosObj` representing the file specification dictionary of the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment object.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The `CosObj` representation of the file attachment.

#### PDFileAttachmentGetCreationDate

```cpp
ASBool PDFileAttachmentGetCreationDate(PDFileAttachment attachment, ASTimeRec *date)
```

Header: `PDProcs.h:12189`

Gets the creation date of the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment object.
- `date` (`ASTimeRec *`): A pointer to a date that will receive the creation date.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the file attachment has a creation date, `false` otherwise. A creation date may be absent for various reasons. For example, the file attachment may have originated from a file system that does not provide creation date information, such as Unix.

#### PDFileAttachmentGetFieldDate

```cpp
ASBool PDFileAttachmentGetFieldDate(PDFileAttachment attachment, ASAtom fieldID, ASTimeRec *date)
```

Header: `PDProcs.h:12287`

Gets the value of the specified date field in the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `date` (`ASTimeRec *`): The date that will receive the field value.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field value was found, `false` otherwise.

#### PDFileAttachmentGetFieldNumber

```cpp
ASBool PDFileAttachmentGetFieldNumber(PDFileAttachment attachment, ASAtom fieldID, float *number)
```

Header: `PDProcs.h:12270`

Gets the value of the specified numeric field in the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `number` (`float *`): The number that will receive the field value.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field value was found, `false` otherwise.

#### PDFileAttachmentGetFieldPrefix

```cpp
ASBool PDFileAttachmentGetFieldPrefix(PDFileAttachment attachment, ASAtom fieldName, ASText prefix)
```

Header: `PDProcs.h:12304`

Gets the specified prefix field in the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom))
- `prefix` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object that will receive the prefix.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

#### PDFileAttachmentGetFieldStyle

```cpp
ASBool PDFileAttachmentGetFieldStyle(PDFileAttachment attachment, ASAtom fieldID, ASCab styles)
```

Header: `PDProcs.h:12253`

Gets the value of the specified text field in the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `styles` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): ASCab object that will receive the field styles

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field value was found, `false` otherwise.

#### PDFileAttachmentGetFieldStyledText

```cpp
ASBool PDFileAttachmentGetFieldStyledText(PDFileAttachment attachment, ASAtom fieldID, ASText text)
```

Header: `PDProcs.h:12236`

Gets the value of the specified text field in the file attachment as styled text, in XML Text Layout Format.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object that will receive the field value.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field value was found, `false` otherwise.

#### PDFileAttachmentGetFieldText

```cpp
ASBool PDFileAttachmentGetFieldText(PDFileAttachment attachment, ASAtom fieldID, ASText text)
```

Header: `PDProcs.h:12228`

Gets the value of the specified text field in the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object that will receive the field value.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field value was found, `false` otherwise.

#### PDFileAttachmentGetFileName

```cpp
ASText PDFileAttachmentGetFileName(PDFileAttachment attachment)
```

Header: `PDProcs.h:12202`

Gets the file name of the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.

**Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)

An `ASText` copy of the file name of the file attachment.

#### PDFileAttachmentGetFileSize

```cpp
ASUns32 PDFileAttachmentGetFileSize(PDFileAttachment attachment)
```

Header: `PDProcs.h:12179`

Returns the size, in bytes, that the file will occupy if exported to disk.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment object

**Returns:** [`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)

The size of the file attachment. It returns `0` if the `PDFileAttachment` object does not specify a file size and one cannot be determined.

#### PDFileAttachmentGetModDate

```cpp
ASBool PDFileAttachmentGetModDate(PDFileAttachment attachment, ASTimeRec *date)
```

Header: `PDProcs.h:12196`

Gets the modification date of the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment object.
- `date` (`ASTimeRec *`): A pointer to a date that will receive the modification date.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the file attachment has a modification date, `false` otherwise.

#### PDFileAttachmentIsValid

```cpp
ASBool PDFileAttachmentIsValid(PDFileAttachment attachment)
```

Header: `PDProcs.h:12070`

Tests a file attachment for validity.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the file attachment is a dictionary, `false` otherwise.

#### PDFileAttachmentNewFromFile

```cpp
PDFileAttachment PDFileAttachmentNewFromFile(CosDoc parentDoc, ASFile sourceFile, const ASAtom *filterNames, const ASArraySize numFilters, CosObj filterParams, ASProgressMonitor monitor, ASConstText monitorText, void *monitorData)
```

Header: `PDProcs.h:12115`

Creates a new file attachment from the given file. The resulting file specification dictionary is created for the given document, but is not referenced. The client must reference the resulting file specification dictionary by attaching it to another object in the PDF file, such as an annotation or name tree. An exception is raised if the file could not be read or the attachment stream could not be created. Note that permissions must be checked by the caller before invoking this function. For example, to have an attachment flate compressed and then ASCII base-85 encoded: ASAtom filterNames[2]; filterNames[0] = ASAtomFromString("ASCII85Decode"); filterNames[1] = ASAtomFromString("FlateDecode"); PDFileAttachmentNewFromFile(parentDoc, sourceFile, filterNames, 2, CosNewNull(), NULL, NULL, NULL); You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `parentDoc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The `CosDoc` in which the file attachment dictionary will be created.
- `sourceFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The `ASFile` from which to create the file attachment.
- `filterNames` ([`const ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): An array of filters to apply to the file attachment stream. Filters are indentified by name. See the description of Filters in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.4, page 22.
- `numFilters` ([`const ASArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASArraySize)): The number of elements in `filterNames`.
- `filterParams` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The filter parameters, represented as a `CosArray` or `CosNull`. When the array form is used, the array must contain the same number of elements as `filterNames`. Each element in the `CosArray` is a `CosDict` representing the filter parameters for the corresponding filter in the `filterNames` array, or `CosNull` to indicate that default parameters should be used for that filter. When the `CosNull` form is used for `filterParams`, default parameters are used for every filter in the filterNames array.
- `monitor` (`ASProgressMonitor`): The `ASProgressMonitor` to use for the duration of the call. The monitor object is owned by the caller. `NULL` indicates that no progress updates are needed.
- `monitorText` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The text for the monitor to display, or `NULL` if no text is needed. The text object is owned by the caller.
- `monitorData` (`void *`): Opaque data that is specific to the monitor object.

**Returns:** [`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)

The new file attachment.

#### PDFileAttachmentOpenStream

```cpp
ASStm PDFileAttachmentOpenStream(PDFileAttachment attachment)
```

Header: `PDProcs.h:12170`

Returns a stream for reading the data from an existing file attachment. An exception is raised if the file attachment does not have a stream (it is not embedded) or the stream could not be opened. The caller is responsible for closing the returned stream.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment object.

**Returns:** [`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)

The file attachment stream.

#### PDFileAttachmentSaveToFile

```cpp
void PDFileAttachmentSaveToFile(PDFileAttachment attachment, ASFile destFile)
```

Header: `PDProcs.h:12149`

Copies the data embedded in the file attachment to the specified file. The file must be open for write or append. The caller is responsible for closing the file after this call returns. If an error is encountered during the write, some data may have been written to the destination file. This call will make no attempt at restoring the file after failure. An exception is raised if the file attachment has no embedded stream or if a file write error occurs.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `destFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file that will be written with the file attachment data.

**Returns:** `void`

#### PDFileAttachmentSetFieldDate

```cpp
void PDFileAttachmentSetFieldDate(PDFileAttachment attachment, ASAtom fieldID, const ASTimeRec *date)
```

Header: `PDProcs.h:12279`

Sets the specified date field in the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `date` (`const ASTimeRec *`): The date to use as the new value for the specified field.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema or the field type is not `D` (date).

#### PDFileAttachmentSetFieldNumber

```cpp
void PDFileAttachmentSetFieldNumber(PDFileAttachment attachment, ASAtom fieldID, float number)
```

Header: `PDProcs.h:12262`

Sets the specified numeric field in the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `number` (`float`): The number to use as the new value for the specified field.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema or the field type is not `N` (number).

#### PDFileAttachmentSetFieldPrefix

```cpp
void PDFileAttachmentSetFieldPrefix(PDFileAttachment attachment, ASAtom fieldName, ASText text)
```

Header: `PDProcs.h:12297`

Sets the specified prefix field in the file attachment. The prefix allows additional text to be prepended to the visual appearance of a field without affecting its actual value.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The prefix to use as the new value for the specified field. Note that if a `NULL` value is passed into this parameter, the prefix is removed and an exception will not be thrown.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema.

#### PDFileAttachmentSetFieldStyle

```cpp
void PDFileAttachmentSetFieldStyle(PDFileAttachment attachment, ASAtom fieldID, ASConstCab styles)
```

Header: `PDProcs.h:12245`

Sets the specified text field in the file attachment using styled text.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `styles` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): ASConstCab containing field styles for the specified field.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema or the field type is not `S` (text).

#### PDFileAttachmentSetFieldStyledText

```cpp
void PDFileAttachmentSetFieldStyledText(PDFileAttachment attachment, ASAtom fieldID, ASConstText text)
```

Header: `PDProcs.h:12220`

Sets the specified text field in the file attachment using styled text.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `text` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): Text Layout Format XML containing the text to use as the new value for the specified field.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema or the field type is not `S` (text).

#### PDFileAttachmentSetFieldText

```cpp
void PDFileAttachmentSetFieldText(PDFileAttachment attachment, ASAtom fieldID, ASText text)
```

Header: `PDProcs.h:12211`

Sets the specified text field in the file attachment.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text to use as the new value for the specified field.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema or the field type is not `S` (text).

#### PDFileAttachmentUpdateFromFile

```cpp
void PDFileAttachmentUpdateFromFile(PDFileAttachment attachment, ASFile sourceFile, ASProgressMonitor monitor, ASConstText monitorText, void *monitorData)
```

Header: `PDProcs.h:12135`

Updates a file attachment from the given file. The attachment uses the filters specified in the attachment to encode the data. An exception is raised if the file could not be read or the attachment stream could not be updated. Note that permissions must be checked by the caller before invoking this function.

**Parameters**

- `attachment` ([`PDFileAttachment`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachment)): The file attachment.
- `sourceFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file to use as input for the update operation.
- `monitor` (`ASProgressMonitor`): The `ASProgressMonitor` to use for the duration of the call. The monitor object is owned by the caller. `NULL` indicates that no progress updates are needed.
- `monitorText` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The text for the monitor to display, or `NULL` if no text is needed. The text object is owned by the caller.
- `monitorData` (`void *`): Opaque data that is specific to the monitor object.

**Returns:** `void`

### Typedefs (1)

#### PDFileAttachment

```cpp
typedef OPAQUE_64_BITS PDFileAttachment
```

Header: `PDExpT.h:6997`

A `PDFileAttachment` represents an embedded file stored in a PDF file, and may be stored at various locations in a PDF file, including the `EmbeddedFiles` name tree, `FileAttachment` annotation types, and `Multimedia` annotations.

**See also:** [`PDFileAttachmentNewFromFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachmentNewFromFile), [`PDFileAttachmentUpdateFromFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachmentUpdateFromFile), [`PDFileAttachmentSaveToFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileAttachmentSaveToFile)

## PDFileSpec

### Functions (14)

#### PDFileSpecAcquireASPath

```cpp
ASPathName PDFileSpecAcquireASPath(PDFileSpec fileSpec, ASPathName relativeToThisPath)
```

Header: `PDProcs.h:5264`

Acquires an ASPathName for the specified file specification and relative path.

**Parameters**

- `fileSpec` ([`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)): IN/OUT The file specification for which an ASPathName
  is acquired.
- `relativeToThisPath` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT A path name relative to which
  the `fileSpec` is interpreted. If it is `NULL`, `fileSpec`
  is assumed to be an absolute, not a relative, path.

  After you are done using the ASPathName, you must free it using ASFileSysReleasePath().

**Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)

The ASPathName corresponding to `fileSpec`.

**See also:** [`ASFileSysReleasePath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePath)

#### PDFileSpecAcquireASPathEx

```cpp
ASPathName PDFileSpecAcquireASPathEx(PDFileSpec fileSpec, ASFileSys relPathFileSys, ASPathName relativeToThisPath, ASFileSys *retFileSys, ASBool pathMustExist)
```

Header: `PDProcs.h:11411`

Acquires an ASPathName for the specified file specification and relative path. After you are done using the ASPathName, you must free it using ASFileSysReleasePath().

**Parameters**

- `fileSpec` ([`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)): IN/OUT The file specification for which an ASPathName is acquired.
- `relPathFileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): The file system that owns `relativeToThisPath`.
- `relativeToThisPath` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT A path name relative to which the `fileSpec` is interpreted. If it is `NULL`, `fileSpec` is assumed to be an absolute, not a relative, path. If it is not `NULL` and `fileSys` and `relPathFileSys` are not the same, then an attempt is made to fabricate a `relPathName` in terms of `fileSys`, and if that is not possible, `NULL` is used.
- `retFileSys` ([`ASFileSys *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT The file system that owns the returned ASPathName.
- `pathMustExist` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): IN/OUT If it is `true` and the result ASPathName does not exist, then the return value is `NULL`.

**Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)

The ASPathName corresponding to `fileSpec`.

**See also:** [`ASFileSysReleasePath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePath)

#### PDFileSpecFromCosObj

```cpp
PDFileSpec PDFileSpecFromCosObj(CosObj obj)
```

Header: `PDProcs.h:5233`

Converts an appropriate string or dictionary Cos object to a file specification. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The Cos object to convert to a file specification.

**Returns:** [`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)

The file specification corresponding to `obj`.

**Exceptions**

- `pdErrBadFileSpec`: is raised if the file specification is not valid, as determined by PDFileSpecIsValid().

**See also:** [`PDFileSpecGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecGetCosObj), [`PDFileSpecIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecIsValid)

#### PDFileSpecGetCosObj

```cpp
CosObj PDFileSpecGetCosObj(PDFileSpec fileSpec)
```

Header: `PDProcs.h:5278`

Gets the Cos object associated with a file specification. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `fileSpec` ([`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)): IN/OUT The file specification whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The string or dictionary Cos object corresponding to the file specification.

**See also:** [`PDFileSpecFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecFromCosObj)

#### PDFileSpecGetDIPath

```cpp
ASInt32 PDFileSpecGetDIPath(PDFileSpec fileSpec, char *buffer, ASInt32 bufLen)
```

Header: `PDProcs.h:5336`

Gets the device-independent path name from a file specification.

**Parameters**

- `fileSpec` ([`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)): IN/OUT The file specification whose device-independent path name is obtained.
- `buffer` (`char *`): IN/OUT (Filled by the method) `NULL`-terminated device- independent path name. If `buffer` is `NULL`, the method simply returns the length of the path name.
- `bufLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The length of `buffer` in bytes. If the device- independent path name is longer than this, only the first `bufLen - 1` bytes are copied into `buffer`, plus a `NULL` at the end of the buffer.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of characters (excluding the `NULL`) copied into `buffer`.

#### PDFileSpecGetDIPathEx

```cpp
void PDFileSpecGetDIPathEx(PDFileSpec fileSpec, ASText diPath)
```

Header: `PDProcs.h:11425`

Gets the device-independent path name from a file specification.

**Parameters**

- `fileSpec` ([`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)): IN The file specification whose device-independent path name is obtained.
- `diPath` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT An existing ASText object whose content is set to the path name obtained from from `fileSpec`.

**Returns:** `void`

#### PDFileSpecGetDoc

```cpp
PDDoc PDFileSpecGetDoc(PDFileSpec fileSpec)
```

Header: `PDProcs.h:5558`

Gets the PDDoc that contains `fileSpec`.

**Parameters**

- `fileSpec` ([`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)): IN/OUT A PDFileSpec in a document.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

A PDDoc or `NULL` if the file specification CosObj is not in a document.

#### PDFileSpecGetFileSys

```cpp
ASFileSys PDFileSpecGetFileSys(PDFileSpec fileSpec)
```

Header: `PDProcs.h:5245`

Gets the file system that services the specified file specification.

**Parameters**

- `fileSpec` ([`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)): IN/OUT The file specification whose file system is obtained.

**Returns:** [`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)

The file system that services `fileSpec`.

**See also:** [`PDFileSpecGetFileSysName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecGetFileSysName)

#### PDFileSpecGetFileSysName

```cpp
ASAtom PDFileSpecGetFileSysName(PDFileSpec fileSpec)
```

Header: `PDProcs.h:5578`

Gets the name of the file system that a PDFileSpec belongs to. For a simple `fileSpec` (string form), the name of the file system is the name of the document's file system if the CosObj that is the `fileSpec` is contained in a document. For a complex `fileSpec` (dictionary form) with an FS key, the name of the file system is the atom associated with the FS key. The file system returned by PDFileSpecGetFileSys() is the file system that has registered a PDFileSpecHandler() for the file specification's file system name (if there is one), and is not necessarily the same as `ASFileGetFileSysByName(PDFileSpecGetFileSysName(fileSpec));` .

**Parameters**

- `fileSpec` ([`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)): A PDFileSpec.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

An ASAtom representing the file system of `fileSpec`.

**See also:** [`PDFileSpecGetFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecGetFileSys)

#### PDFileSpecIsValid

```cpp
ASBool PDFileSpecIsValid(PDFileSpec fileSpec)
```

Header: `PDProcs.h:5290`

Tests whether a file specification is valid. This is intended only to ensure that the file specification has not been deleted, not to ensure that all necessary information is present and valid.

**Parameters**

- `fileSpec` ([`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)): The file specification whose validity is tested.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if `fileSpec` is valid, `false` otherwise.

#### PDFileSpecNewFromASPath

```cpp
PDFileSpec PDFileSpecNewFromASPath(PDDoc pdDoc, ASFileSys fileSys, ASPathName path, ASPathName relativeToThisPath)
```

Header: `PDProcs.h:5217`

Creates a new file specification from the specified ASPathName, using the PDFileSpecNewFromASPathProc() of the specified file system's file specification handler.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the new file specification will be used.
- `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): A pointer to an `ASFileSysRec` specifying the file system responsible for the newly created file specification.
- `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The path to convert into a file specification.
- `relativeToThisPath` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): A path name relative to which `path` is interpreted. If it is `NULL`, `path` is interpreted as an absolute path name, not a relative path name.

**Returns:** [`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)

The newly created file spec, or an invalid file spec if the ASPathName cannot be converted to a PDFileSpec (use PDFileSpecIsValid() to test whether the conversion was successful).

**See also:** [`PDFileSpecIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecIsValid)

#### PDFileSpecNewFromASPathEx

```cpp
PDFileSpec PDFileSpecNewFromASPathEx(PDDoc pdDoc, ASFileSys fileSys, ASPathName path, ASFileSys relPathFileSys, ASPathName relativeToThisPath)
```

Header: `PDProcs.h:11385`

Creates a new file specification from the specified ASPathName, using the PDFileSpecNewFromASPathProc() of the specified file system's file specification handler.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the new file specification will be used.
- `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): A pointer to an `ASFileSysRec` specifying the file system responsible for the newly created file specification.
- `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The path to convert into a file specification.
- `relPathFileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): The file system that owns `relativeToThisPath`.
- `relativeToThisPath` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): A path name relative to which the `fileSpec` is interpreted. If it is `NULL`, `fileSpec` is assumed to be an absolute, not a relative, path. If it is not `NULL` and `fileSys` and `relPathFileSys` are not the same, then an attempt is made to fabricate a `relPathName` in terms of `fileSys`, and if that is not possible, `NULL` is used.

**Returns:** [`PDFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpec)

The newly created file specification, or an invalid file specification if the ASPathName cannot be converted to a PDFileSpec (use PDFileSpecIsValid() to test whether the conversion was successful).

**See also:** [`PDFileSpecIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecIsValid)

#### PDRegisterFileSpecHandler

```cpp
void PDRegisterFileSpecHandler(ASFileSys contextFileSys, PDFileSpecHandler fileSpecHandler, void *fileSpecHandlerObj)
```

Header: `PDProcs.h:5317`

Registers a new file specification handler with the Acrobat viewer. In version 3.0 and later of the Acrobat viewer, use the PDRegisterFileSpecHandlerByName method instead.

**Parameters**

- `contextFileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): The file system that specifies the context in which the file specification handler is used. This is the file system on which the PDF document resides. It is sometimes necessary to use different file specification handlers depending on the file system in which the document is open. For example, when a document is opened in a web browser, the Acrobat viewer may use the browser's HTTP stack when it needs to use HTTP. When a document is opened outside of the browser, however, the Acrobat viewer must use a different HTTP stack.
- `fileSpecHandler` (`PDFileSpecHandler`): A pointer to a structure that contains the handler's callbacks. This structure must not be freed after calling PDRegisterFileSpecHandler().
- `fileSpecHandlerObj` (`void *`): A pointer to user-supplied data to pass to the file specification handler's callbacks each time they are called.

**Returns:** `void`

**Exceptions**

- `genErrNoMemory`

**See also:** [`PDRegisterFileSpecHandlerByName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterFileSpecHandlerByName)

#### PDRegisterFileSpecHandlerByName

```cpp
void PDRegisterFileSpecHandlerByName(ASAtom specSysName, ASFileSys contextFileSys, PDFileSpecHandler fileSpecHandler, void *fileSpecHandlerObj)
```

Header: `PDProcs.h:5616`

Registers a new file specification handler with the Acrobat viewer. The viewer calls the appropriate file specification handler when it encounters a file specification in a PDF file. The appropriate file specification handler is the one whose `specSysName` matches the value of the FS key in the file specification and whose `contextFileSys` matches the file system on which the PDF file resides. The file specification handler's file system, (passed as the `fileSys` field of `fileSpecHandler`), is used to obtain data from, or write data to, the file referred to by the file specification.

**Parameters**

- `specSysName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The name (as an ASAtom) of a file system with which this file specification works.
- `contextFileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): The file system that specifies the context in which the file specification handler is used. This is the file system on which the PDF document resides. It is sometimes necessary to use different file specification handlers depending on the file system in which the document is open. For example, when a document is opened in a web broswer, the Acrobat viewer may use the browser's HTTP stack when it needs to use HTTP. When a document is opened outside of the browser, however, the Acrobat viewer must use a different HTTP stack.
- `fileSpecHandler` (`PDFileSpecHandler`): A pointer to a structure that contains the handler's callbacks. This structure must not be freed after calling PDRegisterFileSpecHandlerByName().
- `fileSpecHandlerObj` (`void *`): A pointer to user-supplied data to pass to the file specification handler's callbacks each time they are called.

**Returns:** `void`

**Exceptions**

- `genErrNoMemory`

**See also:** [`PDRegisterFileSpecHandler`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRegisterFileSpecHandler)

### Typedefs (3)

#### PDFileSpec

```cpp
typedef OPAQUE_64_BITS PDFileSpec
```

Header: `PDExpT.h:1123`

The PDF file specification object. It is used to specify a file in an action (see PDAction). A file specification in a PDF file can take two forms: • A single platform-independent path. • A data structure containing one or more alternative ways to locate the file on different platforms. PDFileSpec objects can be created from ASPathName objects or from Cos objects.

**See also:** [`PDActionGetFileSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionGetFileSpec), [`PDFileSpecNewFromASPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecNewFromASPath), [`PDFileSpecFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecFromCosObj)

#### PDFileSpecAcquireASPathProc

```cpp
typedef ASPathName(*) PDFileSpecAcquireASPathProc(void *fileSpecHandlerObj, PDFileSpec fileSpec, ASPathName relativeToThisPath)(void *fileSpecHandlerObj, PDFileSpec fileSpec, ASPathName relativeToThisPath)
```

Header: `PDExpT.h:1164`

A callback for PDFileSpecHandler. It aquires the ASPath corresponding to a file specification.

**See also:** [`PDFileSpecAcquireASPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecAcquireASPath)

#### PDFileSpecNewFromASPathProc

```cpp
typedef PDFileSpec(*) PDFileSpecNewFromASPathProc(void *fileSpecHandlerObj, PDDoc pdDoc, ASPathName path, ASPathName relativeToThisPath)(void *fileSpecHandlerObj, PDDoc pdDoc, ASPathName path, ASPathName relativeToThisPath)
```

Header: `PDExpT.h:1147`

A callback for PDFileSpecHandler. It creates a file specification from an ASPath.

**Parameters**

- `fileSpecHandlerObj`: User-supplied data passed in
  the call to PDRegisterFileSpecHandler().
- `pdDoc`: The PDDoc in which the file specification
  is created.
- `path`: The ASPathName for which a corresponding file
  specification is created.
- `relativeToThisPath`: A path name relative to which
  path is interpreted. If `NULL`, `path` is assumed to be an absolute
  path, not a relative path.

**See also:** [`PDFileSpecNewFromASPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecNewFromASPath)

## PDFolder

### Functions (27)

#### PDFolderGetCreationDate

```cpp
ASBool PDFolderGetCreationDate(PDFolder folder, ASTimeRec *date)
```

Header: `PDProcs.h:12536`

Gets the creation date of the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `date` (`ASTimeRec *`): A pointer to an `ASTimeRec` that will be filled with the folder creation date.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the folder has a creation date, `false` otherwise.

#### PDFolderGetDescription

```cpp
ASBool PDFolderGetDescription(PDFolder folder, ASText text)
```

Header: `PDProcs.h:12549`

Gets the description of the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): A text object that will receive the folder description.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the folder has a description, `false` otherwise.

#### PDFolderGetDescriptionStyled

```cpp
ASBool PDFolderGetDescriptionStyled(PDFolder folder, ASText text)
```

Header: `PDProcs.h:12556`

Gets the description of the folder as styled text, in XML Text Layout Format.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): A text object that will receive the folder description.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the folder has a description, `false` otherwise.

#### PDFolderGetFieldDate

```cpp
ASBool PDFolderGetFieldDate(PDFolder folder, ASAtom fieldID, ASTimeRec *date)
```

Header: `PDProcs.h:12645`

Gets the value of the specified date field in the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `date` (`ASTimeRec *`): The date that will receive the field value

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field value was found, `false` otherwise.

#### PDFolderGetFieldNumber

```cpp
ASBool PDFolderGetFieldNumber(PDFolder folder, ASAtom fieldID, float *number)
```

Header: `PDProcs.h:12628`

Gets the value of the specified numeric field in the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `number` (`float *`): The number that will receive the field value.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field value was found, `false` otherwise.

#### PDFolderGetFieldStyle

```cpp
ASBool PDFolderGetFieldStyle(PDFolder folder, ASAtom fieldID, ASCab styles)
```

Header: `PDProcs.h:12620`

Gets the style dictionary for the specified field in the folder

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `styles` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): ASCab object that will receive the field styles

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field value was found, `false` otherwise.

#### PDFolderGetFieldStyledText

```cpp
ASBool PDFolderGetFieldStyledText(PDFolder attachment, ASAtom fieldID, ASText text)
```

Header: `PDProcs.h:12603`

Gets the value of the specified text field in the folder as styled text, in XML Text Layout Format.

**Parameters**

- `attachment` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder))
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object that will receive the field value.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field value was found, `false` otherwise.

#### PDFolderGetFieldText

```cpp
ASBool PDFolderGetFieldText(PDFolder folder, ASAtom fieldID, ASText text)
```

Header: `PDProcs.h:12577`

Gets the value of the specified text field in the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object that will receive the field value.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the field value was found, `false` otherwise.

#### PDFolderGetFirstChild

```cpp
PDFolder PDFolderGetFirstChild(PDFolder folder)
```

Header: `PDProcs.h:12486`

Gets the first child of a folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.

**Returns:** [`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)

The first child of the folder. If no child exists, the returned folder is invalid.

#### PDFolderGetID

```cpp
ASInt32 PDFolderGetID(PDFolder folder)
```

Header: `PDProcs.h:12510`

Gets the ID number of a folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The folder ID.

#### PDFolderGetModDate

```cpp
ASBool PDFolderGetModDate(PDFolder folder, ASTimeRec *date)
```

Header: `PDProcs.h:12523`

Gets the modification date of the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `date` (`ASTimeRec *`): A pointer to an `ASTimeRec` that will be filled with the folder modification date.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the folder has a modification date, `false` otherwise.

#### PDFolderGetName

```cpp
void PDFolderGetName(PDFolder folder, ASText name)
```

Header: `PDProcs.h:12504`

Gets the name of a folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `name` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText))

**Returns:** `void`

#### PDFolderGetNextSibling

```cpp
PDFolder PDFolderGetNextSibling(PDFolder folder)
```

Header: `PDProcs.h:12492`

Gets the next sibling of a folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.

**Returns:** [`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)

The next sibling of the folder. If no next sibling exists, the returned folder is invalid.

#### PDFolderGetParent

```cpp
PDFolder PDFolderGetParent(PDFolder folder)
```

Header: `PDProcs.h:12474`

Gets the parent of the specified folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder object.

**Returns:** [`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)

The parent of the specified folder. If no parent exists, the returned folder is invalid.

#### PDFolderGetPathText

```cpp
void PDFolderGetPathText(PDFolder folder, ASText path)
```

Header: `PDProcs.h:12516`

Gets the path of the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `path` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The folder path.

**Returns:** `void`

#### PDFolderIsValid

```cpp
ASBool PDFolderIsValid(PDFolder folder)
```

Header: `PDProcs.h:12416`

Determines if a `PDFolder` is valid.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder object

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the folder is a dictionary, `false` otherwise.

#### PDFolderSetCreationDate

```cpp
void PDFolderSetCreationDate(PDFolder folder, const ASTimeRec *date)
```

Header: `PDProcs.h:12542`

Sets the creation date of the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `date` (`const ASTimeRec *`): A pointer to an `ASTimeRec` will be used to set the creation date.

**Returns:** `void`

#### PDFolderSetDescription

```cpp
void PDFolderSetDescription(PDFolder folder, ASConstText text)
```

Header: `PDProcs.h:12562`

Sets the description of the folder. Removes a styled version if present.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `text` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The new description for the folder.

**Returns:** `void`

#### PDFolderSetDescriptionStyled

```cpp
void PDFolderSetDescriptionStyled(PDFolder folder, ASConstText text)
```

Header: `PDProcs.h:12569`

Sets the description of the folder using styled text. Keeps the non-styled description in sync. with the styled version.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `text` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The new description for the folder in XML Text Layout Format.

**Returns:** `void`

#### PDFolderSetFieldDate

```cpp
void PDFolderSetFieldDate(PDFolder folder, ASAtom fieldID, const ASTimeRec *date)
```

Header: `PDProcs.h:12654`

Sets the specified date field in the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `date` (`const ASTimeRec *`): The date to use as the new value for the specified field.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema or the field type is not `D` (date).

#### PDFolderSetFieldNumber

```cpp
void PDFolderSetFieldNumber(PDFolder folder, ASAtom fieldID, float number)
```

Header: `PDProcs.h:12637`

Sets the specified numeric field in the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `number` (`float`): The number to use as the new value for the specified field.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema or the field type is not `N` (number).

#### PDFolderSetFieldStyle

```cpp
void PDFolderSetFieldStyle(PDFolder folder, ASAtom fieldID, ASConstCab styles)
```

Header: `PDProcs.h:12612`

Sets the style dictionary for the specified field in the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `styles` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): ASConstCab containing field styles for the specified field.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema or the field type is not `S` (text).

#### PDFolderSetFieldStyledText

```cpp
void PDFolderSetFieldStyledText(PDFolder folder, ASAtom fieldID, ASConstText text)
```

Header: `PDProcs.h:12595`

Sets the specified text field in the folder

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `text` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): Text Layout Format XML containing the text to use as the new value for the specified field.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema or the field type is not `S` (text).

#### PDFolderSetFieldText

```cpp
void PDFolderSetFieldText(PDFolder folder, ASAtom fieldID, ASConstText text)
```

Header: `PDProcs.h:12586`

Sets the specified text field in the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `fieldID` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The field identifier.
- `text` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The text to use as the new value for the specified field.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the field does not exist in the collection schema or the field type is not `S` (text).

#### PDFolderSetModDate

```cpp
void PDFolderSetModDate(PDFolder folder, const ASTimeRec *date)
```

Header: `PDProcs.h:12529`

Sets the modification date of the folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `date` (`const ASTimeRec *`): A pointer to an `ASTimeRec` that will be used to set the modification date.

**Returns:** `void`

#### PDFolderSetName

```cpp
void PDFolderSetName(PDFolder folder, ASConstText folderName)
```

Header: `PDProcs.h:12498`

Sets the name of a folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder.
- `folderName` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The name of the folder.

**Returns:** `void`

#### PDFolderSetParent

```cpp
void PDFolderSetParent(PDFolder folder, PDFolder parent)
```

Header: `PDProcs.h:12480`

Sets the parent of the specified folder.

**Parameters**

- `folder` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The folder that will receive a new parent.
- `parent` ([`PDFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFolder)): The new parent folder.

**Returns:** `void`

### Typedefs (1)

#### PDFolder

```cpp
typedef OPAQUE_64_BITS PDFolder
```

Header: `PDExpT.h:7111`

An opaque object representing a collection folder dictionary. Folders are used to provide grouping for files in a portable collection.

## PDFont

### Functions (36)

#### PDCharProcEnumWithParams

```cpp
void PDCharProcEnumWithParams(PDCharProc obj, PDGraphicEnumParams params)
```

Header: `PDProcs.h:10576`

Enumerates the graphic description of a single character procedure for a Type 3 font, for those contents that are visible in a given optional-content context. The parameters include both the monitor and data you would pass to PDCharProcEnum(), and an optional-content context that determines which contents are visible.

**Parameters**

- `obj` ([`PDCharProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharProc)): The character procedure whose graphic descriptions are enumerated.
- `params` (`PDGraphicEnumParams`): The parameters, including the optional-content context to use for content visibility.

**Returns:** `void`

**Exceptions**

- `pdPErrUnableToCreateRasterPort`

**See also:** [`PDCharProcEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharProcEnum), [`PDFormEnumPaintProcWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumPaintProcWithParams), [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

#### PDFontAcquireEncodingArray

```cpp
ASUns8 ** PDFontAcquireEncodingArray(PDFont font)
```

Header: `PDProcs.h:2795`

Acquires a font's encoding array (the mapping of character codes to glyphs). When you are done with this array, call PDFontEncodingArrayRelease() to release it. The array contains 256 pointers. If a pointer is not `NULL`, it points to a C string containing the name of the glyph for the code point corresponding to the index. If it is `NULL`, then the name of the glyph is unchanged from that specified by the font's built-in encoding. For a Type 3 font, all glyph names will be present in the encoding array, and `NULL` entries correspond to un-encoded code points. For non-Roman character set viewers, it is not appropriate to call this method.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): The font whose encoding array is obtained.

**Returns:** [`ASUns8 **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)

The font's encoding array. It returns `NULL` if there is no encoding array associated with the font.

**See also:** [`PDFontEncodingArrayRelease`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontEncodingArrayRelease), [`PDFontGetEncodingIndex`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetEncodingIndex)

#### PDFontAcquireEncodingArrayFull

```cpp
ASUns8 ** PDFontAcquireEncodingArrayFull(PDFont font)
```

Header: `PDProcs.h:12870`

This function fills in the base encoding, differences, and standard encoding for a font. Acquires a font's encoding array (the mapping of character codes to glyphs). When you are done with this array, call PDFontEncodingArrayRelease() to release it. The array contains 256 pointers. If a pointer is not `NULL`, it points to a C string containing the name of the glyph for the code point corresponding to the index. If it is `NULL`, then the name of the glyph is unchanged from that specified by the font's built-in encoding. For a Type 3 font, all glyph names will be present in the encoding array, and `NULL` entries correspond to un-encoded code points. For non-Roman character set viewers, it is not appropriate to call this method.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): The font whose encoding array is obtained.

**Returns:** [`ASUns8 **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)

The font's encoding array. It returns `NULL` if there is no encoding array associated with the font.

**See also:** `PDFontGetEncodingDelta`

#### PDFontAcquireXlateTable

```cpp
ASInt16 * PDFontAcquireXlateTable(PDFont font)
```

Header: `PDProcs.h:2991`

Increments the specified font's XlateTable reference count and also returns the XlateTable, which is a 256-entry table that maps characters from their encoding in the PDF file to host encoding. If a character cannot be mapped to host encoding, then the table entry will (for that character) contain `-1`. When you are done using the XlateTable, call PDFontXlateTableRelease() to release it. For non-Roman character set viewers, it is not appropriate to call this method.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose XlateTable is obtained.

**Returns:** [`ASInt16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)

A pointer to the font's XlateTable, if any. Otherwise it returns `NULL`.

**See also:** [`PDFontXlateTableRelease`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateTableRelease), [`PDFontXlateString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateString)

#### PDFontEnumCharProcs

```cpp
void PDFontEnumCharProcs(PDFont font, PDCharProcEnumProc proc, void *clientData)
```

Header: `PDProcs.h:4015`

Enumerates a Type 3 font's character drawing procedures. The elements of a single character procedure can be enumerated using PDCharProcEnum().

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The Type 3 font's character drawing procedures are being enumerated.
- `proc` ([`PDCharProcEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharProcEnumProc)): IN/OUT A user-supplied callback to call for each character in the font. Enumeration ends if `proc` returns `false`. If the font contains no characters, `proc` will not be called.
- `clientData` (`void *`): IN/OUT A pointer to user-supplied data passed to `proc` each time it is called.

**Returns:** `void`

**See also:** [`PDCharProcEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharProcEnum), [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts), [`PDDocEnumLoadedFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumLoadedFonts)

#### PDFontFromCosObj

```cpp
PDFont PDFontFromCosObj(CosObj fontObj)
```

Header: `PDProcs.h:7790`

Converts a dictionary Cos object to a font. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `fontObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The dictionary Cos object for the font.

**Returns:** [`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)

#### PDFontGetASTextName

```cpp
void PDFontGetASTextName(PDFont font, ASBool removePrefix, ASText nameToFill)
```

Header: `PDProcs.h:11122`

Fills in an ASText object with the font name, to be used in displaying lists or menus. In PDF 1.5, the font name can be represented with a UTF8 byte sequence. In previous versions of Acrobat the name could also be represented by host encodings such as Shift- JIS, Big5, KSC, and so on. This routine tries to return a text object that uses the correct script, but cannot always do so. The ASText object is owned by the caller.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): The font whose name is obtained.
- `removePrefix` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Whether to remove the subset prefix, if present. For example, when `true`, the name `"ABCDEF+Myriad"` is returned as `"Myriad"`.
- `nameToFill` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The ASText object for the font's name.

**Returns:** `void`

#### PDFontGetBBox

```cpp
void PDFontGetBBox(PDFont font, ASFixedRect *bboxP)
```

Header: `PDProcs.h:2841`

Gets a Type 3 font's bounding box, which is the smallest rectangle that would enclose every character in the font if they were overlaid and painted.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose bounding box is obtained.
- `bboxP` (`ASFixedRect *`): IN/OUT (Filled by the method) A pointer to a rectangle specifying the font's bounding box.

**Returns:** `void`

#### PDFontGetCIDSystemInfo

```cpp
ASAtom PDFontGetCIDSystemInfo(PDFont font)
```

Header: `PDProcs.h:6324`

Gets an ASAtom representing Registry and Ordering for a CIDFont. This information resides in the CIDSystemInfo entry of the CIDFont dictionary, which describes a CIDFont. PDFontGetCIDSystemInfo() takes either a Type 0 font or a descendant font (CIDType0 or CIDType2) as an argument. This information is always present for any Type 0 font; the actual registry ordering information is a part of the descendant font. This method provides one way to identify a font's language. The CIDSystemInfo entry uses three components to identify a character collection uniquely: • A registry name to identify an issuer of ordering information. • An ordering name to identify an ordered character collection. • A supplement number to indicate that the ordered character collection for a registry, ordering, and previous supplement has been changed to add new characters assigned CIDs beginning with the next available CID. The PDFontGetCIDSystemInfo() method obtains the first two of these components. A CIDFont is designed to contain a large number of glyph procedures. Instead of being accessed by a name, each glyph procedure is accessed by an integer known as a character identifier or CID. Instead of a font encoding, CIDFonts use a CMap with a Type 0 composite font to define the mapping from character codes to a font number and a character selector. For more information on Type 0 fonts, CIDFonts, and CMaps, See the description of Composite Fonts in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7, page 267. You can find this document on the web store of the International Standards Organization (ISO). For detailed information on CIDFonts, see: Technical Note #5092, CID-Keyed Font Technology Overview [https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5092.CID_Overview.pdf](https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5092.CID_Overview.pdf) Technical Note #5014, Adobe CMap and CIDFont Files Specification [https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf](https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf)

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose Registry and Ordering information is obtained.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

The ASAtom representing the CIDFont's Registry and Ordering information (for example, `"Adobe-Japan1"`).

**See also:** [`PDFontGetCIDSystemSupplement`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetCIDSystemSupplement), [`PDFontGetDescendant`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetDescendant)

#### PDFontGetCIDSystemSupplement

```cpp
ASInt32 PDFontGetCIDSystemSupplement(PDFont font)
```

Header: `PDProcs.h:6378`

Gets the SystemSupplement number of a CIDFont. This field resides in the CIDSystemInfo entry of the CIDFont dictionary, which describes a CIDFont. The CIDSystemInfo entry uses three components to identify a character collection uniquely: • A registry name to identify an issuer of orderings. • An ordering name to identify an ordered character collection. • A supplement number to indicate that the ordered character collection for a registry, ordering, and previous supplement has been changed to add new characters assigned CIDs beginning with the next available CID. PDFontGetCIDSystemInfo() provides character collection information, and PDFontGetCIDSystemSupplement() specifies the version of the ordering. A CIDFont is designed to contain a large number of glyph procedures. Instead of being accessed by a name, each glyph procedure is accessed by an integer known as a character identifier or CID. Instead of a font encoding, CIDFonts use a CMap with a Type 0 composite font to define the mapping from character codes to a font number and a character selector. For more information on Type 0 fonts, CIDFonts, and CMaps, see the description of Composite Fonts in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7, page 267. You can find this document on the web store of the International Standards Organization (ISO). For detailed information on CIDFonts, see: Technical Note #5092, CID-Keyed Font Technology Overview [https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5092.CID_Overview.pdf](https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5092.CID_Overview.pdf) Technical Note #5014, Adobe CMap and CIDFont Files Specification [https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf](https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf)

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose `SystemSupplement` field is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The `SystemSupplement` field from the CIDFont.

**See also:** [`PDFontGetDescendant`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetDescendant), [`PDFontGetCIDSystemInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetCIDSystemInfo)

#### PDFontGetCharSet

```cpp
PDCharSet PDFontGetCharSet(PDFont font)
```

Header: `PDProcs.h:2753`

Gets the font's character set. This is derived from the 'Uses Adobe standard encoding' bit in the font descriptor (if the font has a font descriptor) or from the font's name (if the font is one of the base 14 fonts and does not have a font descriptor). For non-Roman character set viewers, call PDFontGetEncodingName() instead.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose character set is obtained.

**Returns:** [`PDCharSet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharSet)

The font's character set. For non-Roman character set viewers, it returns PDUnknownCharSet.

**See also:** [`PDFontGetEncodingName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetEncodingName)

#### PDFontGetCosObj

```cpp
CosObj PDFontGetCosObj(PDFont font)
```

Header: `PDProcs.h:3054`

Gets the Cos object for a font. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The dictionary Cos object for the font. The dictionary's contents may be enumerated with CosObjEnum().

**See also:** [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts)

#### PDFontGetDescendant

```cpp
PDFont PDFontGetDescendant(PDFont font)
```

Header: `PDProcs.h:6225`

Gets a Type 0 font's descendant, which may be a CIDType0 or CIDType2 font. Type 0 fonts support single-byte or multi-byte encodings and can refer to one or more descendant fonts. These fonts are analogous to the Type 0 or composite fonts supported by Level 2 PostScript interpreters. However, PDF Type 0 fonts only support character encodings defined by a CMap. The CMap specifies the mappings between character codes and the glyphs in the descendant fonts. For information about Type 0 fonts, see the description of Composite Fonts in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7, page 267. You can find this document on the web store of the International Standards Organization (ISO). For more information on CMAPS, see page 272 of the same document. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose descendant is obtained.

**Returns:** [`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)

The font's descendant font.

**See also:** [`PDFontGetCIDSystemInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetCIDSystemInfo), [`PDFontGetCIDSystemSupplement`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetCIDSystemSupplement)

#### PDFontGetEncodingIndex

```cpp
ASInt32 PDFontGetEncodingIndex(PDFont font)
```

Header: `PDProcs.h:2769`

Gets a font's encoding index. For non-Roman character set viewers, call PDFontGetEncodingName() instead.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose encoding index is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

A font encoding index. If the index is greater than PDLastKnownEncoding, it is a custom encoding, and is unique within the document. If the index is less than PDLastKnownEncoding, it must be one of the PDFontEncoding values.

**See also:** [`PDFontAcquireEncodingArray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontAcquireEncodingArray)

#### PDFontGetEncodingName

```cpp
const ASUns8 * PDFontGetEncodingName(PDFont font)
```

Header: `PDProcs.h:6262`

Gets a string representing a font's encoding. Use PDFontGetEncodingIndex() to get encoding information for Roman viewers. Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is `WinAnsiEncoding` on Windows and `MacRomanEncoding` on Mac OS. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`. For descriptions of `WinAnsiEncoding`, `MacRomanEncoding`, and `PDFDocEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). See a list of predefined CMaps in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7.5, page 272. You can find this document on the web store of the International Standards Organization (ISO). In this case, the encoding string contains values such as `"90ms-RKSJ-H"`, `"90msp-RKSJ-H"`, `"Identity-V"`, or `"90pv-RKSJ-H"`; it does not return a string like `"Shift-JIS"`. @since

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): The font whose encoding name is obtained.

**Returns:** [`const ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)

**See also:** [`PDFontGetEncodingIndex`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetEncodingIndex), [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding)

#### PDFontGetFontMatrix

```cpp
void PDFontGetFontMatrix(PDFont fontP, ASFixedMatrix *matrixP)
```

Header: `PDProcs.h:3019`

Gets a font's matrix, which specifies the transformation from character space to text space. See Section 5.5.4 in the *PDF Reference*. This is only valid for Type 3 fonts.

**Parameters**

- `fontP` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose matrix is obtained.
- `matrixP` (`ASFixedMatrix *`): IN/OUT (Filled by the method) A pointer to the font's matrix.

**Returns:** `void`

**See also:** [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts)

#### PDFontGetMetrics

```cpp
void PDFontGetMetrics(PDFont font, PDFontMetricsP metricsP, ASSize_t sizeMetrics)
```

Header: `PDProcs.h:2830`

Gets a font's metrics, which provide the information needed to create a substitute Multiple Master font when the original font is unavailable. See the description of Font Descriptors in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.8, page 281. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose metrics are being obtained.
- `metricsP` (`PDFontMetricsP`): IN/OUT (Filled by the method) A pointer to a `PDFontMetrics` structure containing the font's metrics. The font metric values may be patched before being returned. If the actual values in the PDF file are required, use Cos instead to get trustworthy metrics.
- `sizeMetrics` ([`ASSize_t`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASSize_t)): IN/OUT It must be `sizeof(PDFontMetrics)`.

**Returns:** `void`

**See also:** [`PDFontGetWidths`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetWidths), [`PDFontSetMetrics`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontSetMetrics)

#### PDFontGetName

```cpp
ASInt32 PDFontGetName(PDFont font, char *buffer, ASInt32 bufSize)
```

Header: `PDProcs.h:2725`

Gets the name of a font. The behavior depends on the font type; for a Type 3 font it gets the value of the Name key in a PDF Font resource. See the description of font types in "Introduction to Font Data Structures" in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.5, page 253. You can find this document on the web store of the International Standards Organization (ISO). For other types it gets the value of the BaseFont key in a PDF font resource.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose name is obtained.
- `buffer` (`char *`): IN/OUT (Filled by the method) The buffer into which the font's name is stored. The client may pass in `NULL` to obtain the buffer size, excluding the terminating `NULL`, and then call the method with a buffer of the appropriate size. You must pass at least the `bufSize + 1` as the buffer size
- `bufSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The length of `buffer` in bytes. The maximum font name length that the Acrobat viewer will return is `PSNAMESIZE` (see PDExpT. h).

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of characters in the font name. If the font name is too long to fit into `buffer`, `bufSize - 1` bytes are copied into `buffer`, and `buffer` is `NULL`-terminated.

**See also:** [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts), [`PDFontGetEncodingName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetEncodingName)

#### PDFontGetSubtype

```cpp
ASAtom PDFontGetSubtype(PDFont font)
```

Header: `PDProcs.h:2736`

Gets a font's subtype.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose subtype is obtained.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

The font's subtype. The ASAtom returned can be converted to a string using ASAtomGetString(). It must be one of the Font Subtypes.

**See also:** `PDDocEnumFonts FontSubtypes`

#### PDFontGetWidths

```cpp
void PDFontGetWidths(PDFont font, ASInt16 *widths)
```

Header: `PDProcs.h:2867`

Gets the advance width of every glyph in a font. The advance width is the amount by which the current point advances when the glyph is drawn. The advance width may not correspond to the visible width of the glyph (for example, a glyph representing an accent mark might have an advance width of zero so that characters can be drawn under it). For this reason, the advance width cannot be used to determine the glyphs' bounding boxes. For non-Roman character set viewers, this method gets the width for a single byte range (`0` through `255`).

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose glyph advance widths are obtained.
- `widths` ([`ASInt16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): IN/OUT (Filled by the method) An array of glyph advance widths, measured in character space units. Un-encoded code points will have a width of zero. For non-Roman character set viewers, an array for a single byte range (`0` through `255`).

**Returns:** `void`

**See also:** [`PDFontGetMetrics`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetMetrics), [`PDFontSetMetrics`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontSetMetrics), [`PDFontXlateWidths`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateWidths)

#### PDFontIsEmbedded

```cpp
ASBool PDFontIsEmbedded(PDFont font)
```

Header: `PDProcs.h:2919`

Tests whether the specified font is embedded in the PDF file, meaning that the font is stored as a font file, which is a stream embedded in the PDF file. Only Type 1 and TrueType fonts can be embedded.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): The font to test.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the font is embedded in the file, `false` otherwise.

**See also:** [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts)

#### PDFontSetMetrics

```cpp
void PDFontSetMetrics(PDFont font, PDFontMetricsP metricsP, ASSize_t sizeMetrics)
```

Header: `PDProcs.h:3041`

Sets a font's metrics, which provide the information needed to create a substitute Multiple Master font when the original font is unavailable. See the description of Font Descriptors in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.8, page 281. You can find this document on the web store of the International Standards Organization (ISO). This method can only be used on Type 1, Multiple Master Type 1, and TrueType fonts; it cannot be used on Type 3 fonts.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose metrics are being set.
- `metricsP` (`PDFontMetricsP`): IN/OUT A pointer to a `PDFontMetrics` structure containing the font's metrics.
- `sizeMetrics` ([`ASSize_t`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASSize_t)): IN/OUT It must be `sizeof(PDFontMetrics)`.

**Returns:** `void`

**See also:** [`PDFontGetMetrics`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetMetrics)

#### PDFontXlateString

```cpp
ASBool PDFontXlateString(PDFont font, ASUns8 *inP, ASUns8 *outP, ASInt32 len)
```

Header: `PDProcs.h:2970`

Translates a string from the PDFont's encoding into host encoding. If any characters cannot be represented in host encoding, they are replaced with space characters. If no XlateTable exists in the font, the function returns `false` and `outP` is not written. For non-Roman character set viewers, it is not appropriate to call this method. Instead call one of the following: PDFontXlateToHost(), PDFontXlateToUCS(), PDXlateToHostEx(), or PDXlateToPDFDocEncEx().

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): The font (and hence, the encoding) that `inP` uses.
- `inP` ([`ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): The string to translate.
- `outP` ([`ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): (Filled by the method) The translated string. `outP` may point to the same buffer as `inP`, to allow in-place translation.
- `len` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length of `inP` and `outP`.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if an XlateTable exists in the font, `false` otherwise. If no XlateTable exists in the font, `outP` is not written.

**See also:** [`PDFontXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToHost), [`PDFontAcquireXlateTable`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontAcquireXlateTable), [`PDFontXlateToUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToUCS), [`PDXlateToHostEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHostEx), [`PDXlateToPDFDocEncEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEncEx)

#### PDFontXlateTableRelease

```cpp
void PDFontXlateTableRelease(ASInt16 *table)
```

Header: `PDProcs.h:3005`

Decrements the specified font's XlateTable reference count. The XlateTable is a 256-entry table that maps characters from their encoding in the PDF file to host encoding. If a character cannot be mapped to host encoding, then the table entry will (for that character) contain `-1`.

**Parameters**

- `table` ([`ASInt16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): IN/OUT The XlateTable to release.

**Returns:** `void`

**See also:** [`PDFontAcquireXlateTable`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontAcquireXlateTable), [`PDFontXlateString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateString)

#### PDFontXlateToHost

```cpp
ASInt32 PDFontXlateToHost(PDFont fontP, ASUns8 *inP, ASInt32 inLen, ASUns8 *outP, ASInt32 outLen)
```

Header: `PDProcs.h:6674`

Translates a string from the PDFont's encoding to host encoding. This is useful for converting the text from a PDWord into host encoding. In the same way that PDXlateToHostEx() converts text from bookmark titles to host encoding, PDFontXlateToHost() converts text from a page contents stream to host encoding. Use PDFontXlateToUCS() to translate from the PDFont's encoding to Unicode. Non-Roman fonts, such as PostScript composite fonts, can be encoded in different ways, such as SHIFT-JIS, RKSJ, and so on. To use PDFontXlateToHost(), the caller does not need to know which encoding he is converting from, since that information is contained in the PDFont. Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is `WinAnsiEncoding` on Windows and `MacRomanEncoding` on Mac OS. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`. For descriptions of `WinAnsiEncoding`, `MacRomanEncoding`, and `PDFDocEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). For a list of predefined CMaps see the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7.5, page 272. You can find this document on the web store of the International Standards Organization (ISO). Use PDGetHostEncoding() to determine if a system's host encoding is Roman. @since

**Parameters**

- `fontP` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): The font used in the input string `inP`.
- `inP` ([`ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): A pointer to the string to translate.`inP` buffer in bytes.
- `inLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))
- `outP` ([`ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): (Filled by the method) A pointer to the translated
  string.`outP` buffer in bytes.`outP`.
- `outLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

**See also:** [`PDFontXlateString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateString), [`PDFontXlateToUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToUCS), [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding), [`PDXlateToHostEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHostEx), [`PDXlateToPDFDocEncEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEncEx)

#### PDFontXlateToUCS

```cpp
ASInt32 PDFontXlateToUCS(PDFont fontP, ASUns8 *inP, ASInt32 inLen, ASUns8 *outP, ASInt32 outLen)
```

Header: `PDProcs.h:6726`

Translates a string from whatever encoding the PDFont uses to Unicode encoding. This is useful for converting the text from a PDWord into Unicode. Use PDFontXlateToHost() to translate from the PDFont's encoding to host encoding. Non-Roman fonts, like PostScript composite fonts, can be encoded in different ways, such as SHIFT-JIS, RKSJ, and so on. The caller does not need to know which encoding they're converting from, since that information is contained in the PDFont. Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is `WinAnsiEncoding` on Windows and `MacRomanEncoding` on Mac OS. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`. For descriptions of `WinAnsiEncoding`, `MacRomanEncoding`, and `PDFDocEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). For a list of predefined CMaps see the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7.5, page 272. You can find this document on the web store of the International Standards Organization (ISO). Use PDGetHostEncoding() to determine if a system's host encoding is Roman. @since

**Parameters**

- `fontP` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): The font of the input string `inP`.
- `inP` ([`ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): A pointer to the string to translate.`inP` buffer in bytes.
- `inLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))
- `outP` ([`ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): (Filled by the method) A pointer to the translated
  string. If it is `NULL`, the method returns the size of the translated
  string.`outP` buffer in bytes.
  If it is `0`, the method returns the size of the translated string.`outP`.
- `outLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

**See also:** [`PDFontXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToHost), [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding), [`PDXlateToHostEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHostEx), [`PDXlateToPDFDocEncEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEncEx)

#### PDFontXlateWidths

```cpp
void PDFontXlateWidths(PDFont font, ASInt16 *inP, ASInt16 *outP)
```

Header: `PDProcs.h:2940`

Translates an array of 256 glyph advance widths (obtained from PDFontGetWidths()) from their order in the PDF file into host encoding order. If the widths are already in host encoding order, the widths are merely copied. All un-encoded code points are given a width of zero. For non-Roman character set viewers, it is not appropriate to call this method.

**Parameters**

- `font` ([`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)): IN/OUT The font whose glyph widths are translated.
- `inP` ([`ASInt16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): IN/OUT The array of glyph advance widths to rearrange.
- `outP` ([`ASInt16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): IN/OUT (Filled by the method) The rearranged array of glyph advance widths.

**Returns:** `void`

**See also:** [`PDFontGetWidths`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetWidths)

#### PDGetHostEncoding

```cpp
ASHostEncoding PDGetHostEncoding(void)
```

Header: `PDProcs.h:6550`

Indicates what kind of host encoding a system uses. It allows you to determine whether a system is Roman or non-Roman. (Non-Roman is also known as CJK-capable, which means that it is capable of handling multi-byte character sets such as Chinese, Japanese, or Korean). Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is `WinAnsiEncoding` on Windows and `MacRomanEncoding` on Mac OS. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`. For descriptions of `WinAnsiEncoding`, `MacRomanEncoding`, and `PDFDocEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). For a list of predefined CMaps see the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7.5, page 272. You can find this document on the web store of the International Standards Organization (ISO). Use PDGetHostEncoding() to determine if a system's host encoding is Roman.`0` for a Roman system, nonzero for a non-Roman system (a structure that depends on the host encoding). Users should simply test whether this value is `0`. @since

**Parameters**

- (unnamed) (`void`)

**Returns:** [`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding)

**See also:** [`PDGetPDFDocEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetPDFDocEncoding), `AVAppGetLanguageEncoding`

#### PDGetPDFDocEncoding

```cpp
ASUns8 ** PDGetPDFDocEncoding(void)
```

Header: `PDProcs.h:2906`

Gets an array describing the differences between the platform's host encoding and `PDFDocEncoding`. Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is `WinAnsiEncoding` on Windows and `MacRomanEncoding` on Mac OS. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`. For descriptions of `WinAnsiEncoding`, `MacRomanEncoding`, and `PDFDocEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). For a list of predefined CMaps see the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7.5, page 272. You can find this document on the web store of the International Standards Organization (ISO). Use PDGetHostEncoding() to determine whether a system's host encoding is Roman. If the element is `NULL`, the code point refers to the same glyph in both host encoding and `PDFDocEncoding`. If the element is non-`NULL`, it points to a string containing the glyph name for the code point.

**Parameters**

- (unnamed) (`void`)

**Returns:** [`ASUns8 **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)

An array containing 256 elements. Each element corresponds to a code point in the `PDFDocEncoding`, and is either `NULL` or a pointer to a string.

**See also:** [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding), `AVAppGetLanguageEncoding`

#### PDHostMBLen

```cpp
ASInt32 PDHostMBLen(const char *cp)
```

Header: `PDProcs.h:6513`

Gets the number of additional bytes required for the multi-byte character pointed to by `cp`. If `cp` points to a single-byte character, `0` is returned. This method makes it possible to determine the length of multi-byte character strings to allocate space for them. This function is similar to the ANSI-C code: `mblen(cp, MB_LEN_MAX) - 1` or the Windows function: `IsDBCSLeadByte(cp)`

**Parameters**

- `cp` (`const char *`): The character to examine.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of bytes in the multi-byte character.

#### PDXlateToASText

```cpp
void PDXlateToASText(const char *inHostString, ASInt32 inHostStringSize, ASText outPDFString)
```

Header: `PDProcs.h:11743`

Returns an ASText object corresponding to a host encoded string.

**Parameters**

- `inHostString` (`const char *`): A pointer to the string to translate (it may point to the same memory as `outPDFString`, allowing strings to translate in place).
- `inHostStringSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of bytes in the string to translate.
- `outPDFString` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The text object corresponding to `inHostStringSize`. The client must pass a valid ASText object title. The routine does not allocate it.

**Returns:** `void`

The number of bytes in the translated string `outPDFString`.

**See also:** [`PDFontXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToHost), [`PDFontXlateToUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToUCS), [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding), [`PDXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHost), [`PDXlateToHostEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHostEx), [`PDXlateToPDFDocEnc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEnc)

#### PDXlateToHost

```cpp
void PDXlateToHost(char *in, char *out, ASInt32 numBytes)
```

Header: `PDProcs.h:2694`

Translates a string from `PDFDocEncoding` to host encoding. This method is useful when setting or retrieving displayed text that must be in `PDFDocEncoding` (or Unicode), such as text that appears in a text annotation or bookmark. A character that cannot be converted to the destination encoding is replaced with a space. Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is `MacRomanEncoding` on Mac OS and `WinAnsiEncoding` on Windows. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`. For descriptions of `WinAnsiEncoding`, `MacRomanEncoding`, and `PDFDocEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). For a list of predefined CMaps see the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7.5, page 272. You can find this document on the web store of the International Standards Organization (ISO). Use PDGetHostEncoding() to determine if a system's host encoding is Roman. For non-Roman systems, use PDXlateToHostEx(). In general, PDXlateToHostEx() can be called instead of PDXlateToHost() since PDXlateToHostEx() works for any host encoding.

**Parameters**

- `in` (`char *`): The string to translate (it may point to the same memory as `out`, allowing strings to translate in place).
- `out` (`char *`): (Filled by the method) The translated string (it may point to the same memory as `in`).
- `numBytes` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of bytes in the string to translate.

**Returns:** `void`

**See also:** [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding), [`PDXlateToHostEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHostEx), [`PDXlateToPDFDocEnc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEnc), [`PDXlateToPDFDocEncEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEncEx)

#### PDXlateToHostASText

```cpp
ASInt32 PDXlateToHostASText(const ASText inPdfString, char *outHostString, ASInt32 outHostStringSize)
```

Header: `PDProcs.h:11721`

Returns a host encoded string corresponding to an ASText object.

**Parameters**

- `inPdfString` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object.
- `outHostString` (`char *`): (Filled by the method) A pointer to the translated string.
- `outHostStringSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length of the `outHostString` buffer, in bytes.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of bytes in the translated string `outHostString`.

**See also:** [`PDXlateToHostEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHostEx), [`PDFontXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToHost), [`PDFontXlateToUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToUCS), [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding), [`PDXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHost), [`PDXlateToPDFDocEnc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEnc), [`PDXlateToPDFDocEncEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEncEx)

#### PDXlateToHostEx

```cpp
ASInt32 PDXlateToHostEx(const char *inPdfStr, ASInt32 inPdfStrSize, char *outHostStr, ASInt32 outHostStrSize)
```

Header: `PDProcs.h:6432`

Translates a string from Unicode or `PDFDocEncoding` to host encoding. This method is useful when setting or retrieving displayed text that might be in Unicode, such as text that appears in a text annotation or bookmark. A character that cannot be converted to the destination encoding is replaced with a space. Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is `WinAnsiEncoding` on Windows and `MacRomanEncoding` on Mac OS. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`. For descriptions of `WinAnsiEncoding`, `MacRomanEncoding`, and `PDFDocEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). For a list of predefined CMaps see the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1:PDF 1.7, section 9.7.5, page 272. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, use PDXlatetoHostEx(). Use PDGetHostEncoding() to determine whether the host encoding for a system is Roman. In general, PDXlatetoHostEx() operates in the same way as PDXlateToHost() but requires an extra argument, since the sizes of the input and translated strings may differ. This method can be called instead of PDXlateToHost(), and must be called for multi-byte character set systems. @since

**Parameters**

- `inPdfStr` (`const char *`): IN/OUT A pointer to the string to translate (it may
  point to the same memory as `outHostStr`, allowing strings
  to translate in place).`inPdfStr` in bytes.
- `inPdfStrSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))
- `outHostStr` (`char *`): IN/OUT (Filled by the method) A pointer to the
  translated string (it may point to the same memory as `inPdfStr`).`outHostStr` buffer in bytes.`outHostStr`.
- `outHostStrSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

**See also:** [`PDFontXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToHost), [`PDFontXlateToUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToUCS), [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding), [`PDXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHost), [`PDXlateToPDFDocEnc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEnc), [`PDXlateToPDFDocEncEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEncEx)

#### PDXlateToPDFDocEnc

```cpp
void PDXlateToPDFDocEnc(char *in, char *out, ASInt32 numBytes)
```

Header: `PDProcs.h:2645`

Translates a string from host encoding to `PDFDocEncoding`. This method is useful when setting or retrieving displayed text that must be in `PDFDocEncoding` (or Unicode), such as text that appears in a text annotation or bookmark. A character that cannot be converted to the destination encoding is replaced with a space. For example, PDXlateToPDFDocEnc() converts `'\\n'` to a space character (`'\\r'` is present in `PDFDocEncoding` and is left unchanged). Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is `WinAnsiEncoding` on Windows and `MacRomanEncoding` on Mac OS. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`. For descriptions of `WinAnsiEncoding`, `MacRomanEncoding`, and `PDFDocEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). For a list of predefined CMaps see the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7.5, page 272. You can find this document on the web store of the International Standards Organization (ISO). Use PDGetHostEncoding() to determine if a system's host encoding is Roman. For non-Roman systems, use PDXlateToPDFDocEncEx(). In general, PDXlateToPDFDocEncEx() can be called instead of PDXlateToPDFDocEnc(), since PDXlateToPDFDocEncEx() works for PDFDocEncoding or Unicode. @since

**Parameters**

- `in` (`char *`): The string to translate (it may point to the same
  memory as `out`, allowing strings to translate in place).
- `out` (`char *`): (Filled by the method) The translated string
  (it may point to the same memory as `in`).
- `numBytes` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of bytes in the string to translate.

**Returns:** `void`

**See also:** [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding), [`PDXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHost), [`PDXlateToHostEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHostEx), [`PDXlateToPDFDocEncEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEncEx)

#### PDXlateToPDFDocEncEx

```cpp
ASInt32 PDXlateToPDFDocEncEx(ASBool bUseUnicode, const char *inHostStr, ASInt32 inHostStrSize, char *outPDFStr, ASInt32 outPDFStrSize)
```

Header: `PDProcs.h:6492`

Translates a string from host encoding to `PDFDocEncoding` or Unicode. This method is useful when using text that must be in `PDFDocEncoding` or Unicode, such as text in a text annotation, bookmark, or article title. A character that cannot be converted to the destination encoding is replaced with a space. For example, PDXlateToPDFDocEncEx() converts `'\\n'` to a space character (`'\\r'` is present in `PDFDocEncoding` and is left unchanged). Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is `WinAnsiEncoding` on Windows and `MacRomanEncoding` on Mac OS. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`. For descriptions of `WinAnsiEncoding`, `MacRomanEncoding`, and `PDFDocEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). For a list of predefined CMaps see the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.7.5, page 272. You can find this document on the web store of the International Standards Organization (ISO). For non-Roman systems, use PDXlateToPDFDocEncEx(). You can use PDGetHostEncoding() to determine whether a system's host encoding is Roman. In general, PDXlateToPDFDocEncEx() can be called instead of PDXlateToPDFDocEnc() since PDXlateToPDFDocEncEx() works for PDFDocEncoding or Unicode.`true`, translate the string to Unicode; otherwise use `PDFDocEncoding`. @since

**Parameters**

- `bUseUnicode` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool))
- `inHostStr` (`const char *`): A pointer to the string to translate (it may
  point to the same memory as `outPDFStr`, allowing strings
  to translate in place).
- `inHostStrSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of bytes in the string to
  translate.
- `outPDFStr` (`char *`): (Filled by the method) A pointer to the
  translated string (it may point to the same memory as `inHostStr`).`outPDFStr` buffer,
  in bytes.`outPDFStr`.
- `outPDFStrSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

**See also:** [`PDFontXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToHost), [`PDFontXlateToUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontXlateToUCS), [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding), [`PDXlateToHost`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHost), [`PDXlateToHostEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToHostEx), [`PDXlateToPDFDocEnc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEnc)

### Typedefs (6)

#### PDCharSet

```cpp
typedef ASEnum8 PDCharSet
```

Header: `PDExpT.h:2347`

#### PDFontAngle

```cpp
typedef ASInt16 PDFontAngle
```

Header: `PDExpT.h:77`

An italic angle value in degrees, for use in `PDFontMetrics`.

#### PDFontMetric

```cpp
typedef ASUns16 PDFontMetric
```

Header: `PDExpT.h:72`

An unsigned measurement of a font characteristic (for example, width).

#### PDFontOffset

```cpp
typedef ASInt16 PDFontOffset
```

Header: `PDExpT.h:82`

A font offset value, for use in `PDFontMetrics`.

#### PDCharProcEnumProc

```cpp
typedef ASBool(*) PDCharProcEnumProc(char *name, PDCharProc obj, void *clientData)(char *name, PDCharProc obj, void *clientData)
```

Header: `PDExpT.h:3108`

A callback for PDFontEnumCharProcs(). It is called once for each character in a Type 3 font.

**See also:** [`PDFontEnumCharProcs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontEnumCharProcs)

#### PDFontEnumProc

```cpp
typedef ASBool(*) PDFontEnumProc(PDFont font, PDFontFlags *fontFlags, void *clientData)(PDFont font, PDFontFlags *fontFlags, void *clientData)
```

Header: `PDExpT.h:2257`

A callback used by PDDocEnumFonts() and PDDocEnumLoadedFonts(). It is called once for each font.

**See also:** [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts), [`PDDocEnumLoadedFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumLoadedFonts)

### Structures (2)

#### PDCharProc

```cpp
typedef struct _t_PDCharProc* PDCharProc
```

Header: `PDExpT.h:2509`

#### PDFont

```cpp
typedef struct _t_PDFont* PDFont
```

Header: `PDBasicExpT.h:107`

A font that is used to draw text on a page. It corresponds to a Font Resource in a PDF file. Applications can get a list of PDFont objects used on a PDPage or a range of PDPage objects. More than one PDPage may reference the same PDFont object. A PDFont has a number of attributes whose values can be read or set, including an array of widths, the character encoding, and the font's resource name.

**See also:** [`PDDocEnumFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumFonts), [`PDDocEnumLoadedFonts`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumLoadedFonts), [`PDFontGetDescendant`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontGetDescendant), [`PDStyleGetFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyleGetFont), [`PDFontEnumCharProcs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontEnumCharProcs)

### Definitions (17)

#### PDFONTFLAGS_USEDBYFORM

Header: `PDExpT.h:2229`

Value: `0x00000001`

#### PDFontGetDescendant

Header: `PDCalls.h:164`

Value: `PDFontGetDescendantInt`

#### PDLastOneByteEncoding

Header: `PDExpT.h:2323`

Value: `PDLastKnownEncoding`

#### PDUnicodeEncoding

Header: `PDExpT.h:2324`

Value: `PDLastKnownEncoding`

#### PD_ALL_CAP

Header: `PDExpT.h:2273`

Value: `0x00010000`

#### PD_FIXED_WIDTH

Header: `PDExpT.h:2267`

Value: `0x00000001`

#### PD_FORCE_BOLD

Header: `PDExpT.h:2275`

Value: `0x00040000`

#### PD_ITALIC

Header: `PDExpT.h:2272`

Value: `0x00000040`

#### PD_PI

Header: `PDExpT.h:2269`

Value: `0x00000004`

#### PD_SCRIPT

Header: `PDExpT.h:2270`

Value: `0x00000008`

#### PD_SEGASCII

Header: `PDExpT.h:2350`

Value: `((ASUns8)1)`

#### PD_SEGBINARY

Header: `PDExpT.h:2351`

Value: `((ASUns8)2)`

#### PD_SEGEOF

Header: `PDExpT.h:2352`

Value: `((ASUns8)3)`

#### PD_SERIF

Header: `PDExpT.h:2268`

Value: `0x00000002`

#### PD_SMALL_CAP

Header: `PDExpT.h:2274`

Value: `0x00020000`

#### PD_STD_ENCODING

Header: `PDExpT.h:2271`

Value: `0x00000020`

#### PSNAMESIZE

Header: `PDExpT.h:2262`

Value: `128`

## PDFontEncoding

### Functions (1)

#### PDFontEncodingArrayRelease

```cpp
void PDFontEncodingArrayRelease(ASUns8 **array)
```

Header: `PDProcs.h:2806`

Releases a font's encoding array (the mapping of character codes to glyphs). Call this method after you are done using an encoding array acquired using PDFontAcquireEncodingArray().

**Parameters**

- `array` ([`ASUns8 **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): IN/OUT The encoding array to release.

**Returns:** `void`

**See also:** [`PDFontAcquireEncodingArray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFontAcquireEncodingArray)

### Typedefs (1)

#### PDFontEncoding

```cpp
typedef ASEnum8 PDFontEncoding
```

Header: `PDExpT.h:2321`

### Enums (1)

#### PDFontEncodings

Header: `PDExpT.h:2282`

An enumerated data type that specifies a font's encoding. To learn more about MacRoman Encoding, see: You can find this document on the web store of the International Standards Organization (ISO).

**Values**

- `PDBuiltInEncoding = -1`: The encoding specified internally in the font. In the case of a Type 1 or MMType 1 font, this is specified by the Encoding value in the font's `fontdict`. In the case of TrueType fonts, this is the encoding specified by the default one-byte `CMap` for the platform.
- `PDMacRomanEncoding = 0`: MacRomanEncoding, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651.
- `PDMacExpertEncoding = 1`: MacExpertEncoding, see Annex D, "Character Sets and Encodings," page 651.
- `PDWinAnsiEncoding = 2`: WinAnsiEncoding, see Annex D, "Character Sets
  and Encodings," page 651.
- `PDStdEncoding = 3`: StandardEncoding, see Annex D, "Character Sets
  and Encodings," page 651.
- `PDFDocEncoding = 4`: PDFDocEncoding, see Annex D, "Character Sets
  and Encodings," page 651. This will never be returned for a font; it is used internally.
- `PDLastKnownEncoding = 5`

## PDGraphic

### Functions (3)

#### PDGraphicGetBBox

```cpp
void PDGraphicGetBBox(PDGraphic obj, ASFixedRect *bboxP)
```

Header: `PDProcs.h:3633`

Gets a bounding box for the specified graphic object.

**Parameters**

- `obj` ([`PDGraphic`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGraphic)): The graphic object whose bounding box is obtained.
- `bboxP` (`ASFixedRect *`): (Filled by the method) A pointer to a rectangle containing the bounding box for `obj`. If it is called during PDFormEnumPaintProc() or PDCharProcEnum(), the coordinates are specified in the object space, meaning that they are relative to the object's matrix.

**Returns:** `void`

**See also:** [`PDCharProcEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCharProcEnum), [`PDFormEnumPaintProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFormEnumPaintProc)

#### PDGraphicGetCurrentMatrix

```cpp
void PDGraphicGetCurrentMatrix(PDGraphic obj, ASFixedMatrix *matrix)
```

Header: `PDProcs.h:3645`

Gets the current transformation matrix in effect for a graphic object; the matrix is relative to user space.

**Parameters**

- `obj` ([`PDGraphic`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGraphic)): IN/OUT The graphic object for which transformation matrix is obtained.
- `matrix` (`ASFixedMatrix *`): IN/OUT (Filled by the method) A pointer to a matrix containing the transformation matrix for `obj`.

**Returns:** `void`

#### PDGraphicGetState

```cpp
void PDGraphicGetState(PDGraphic obj, PDGraphicStateP stateP, ASInt32 stateLen)
```

Header: `PDProcs.h:3659`

Gets the graphics state associated with a graphic object. See Section 4.3 in the *PDF Reference* for a discussion of the graphics state parameters.

**Parameters**

- `obj` ([`PDGraphic`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGraphic)): IN/OUT The graphic object whose graphics state is obtained.
- `stateP` (`PDGraphicStateP`): IN/OUT (Filled by the method) A pointer to a `PDGraphicState` structure containing the graphics state.
- `stateLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT It must be `sizeof(PDGraphicsState)`.

**Returns:** `void`

### Typedefs (9)

#### PDGraphicEnumCacheDeviceProc

```cpp
typedef ASBool(*) PDGraphicEnumCacheDeviceProc(ASFixed *parms, void *clientData)(ASFixed *parms, void *clientData)
```

Header: `PDExpT.h:2864`

A callback for PDGraphicEnumMonitor. It is called for every d1 (`setcachedevice`) operator.

**See also:** [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

#### PDGraphicEnumCharWidthProc

```cpp
typedef ASBool(*) PDGraphicEnumCharWidthProc(ASFixedPoint width, void *clientData)(ASFixedPoint width, void *clientData)
```

Header: `PDExpT.h:2852`

A callback for PDGraphicEnumMonitor. It is called for every d0 (`setcharwidth`) operator.

**See also:** [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

#### PDGraphicEnumImageProc

```cpp
typedef ASBool(*) PDGraphicEnumImageProc(PDInlineImage obj, void *clientData)(PDInlineImage obj, void *clientData)
```

Header: `PDExpT.h:2802`

A callback for PDGraphicEnumMonitor. It is called for every image operator.

**See also:** [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

#### PDGraphicEnumPathProc

```cpp
typedef ASBool(*) PDGraphicEnumPathProc(PDPath obj, void *clientData)(PDPath obj, void *clientData)
```

Header: `PDExpT.h:2790`

A callback for PDGraphicEnumMonitor. It is called for every path operator.

**See also:** [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

#### PDGraphicEnumRestoreProc

```cpp
typedef ASBool(*) PDGraphicEnumRestoreProc(void *clientData)(void *clientData)
```

Header: `PDExpT.h:2841`

A callback for PDGraphicEnumMonitor. It is called for every Q (restore) operator.

**See also:** [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

#### PDGraphicEnumSaveProc

```cpp
typedef ASBool(*) PDGraphicEnumSaveProc(void *clientData)(void *clientData)
```

Header: `PDExpT.h:2830`

A callback for PDGraphicEnumMonitor. It is called for every Q (save) operator.

**See also:** [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

#### PDGraphicEnumTextProc

```cpp
typedef ASBool(*) PDGraphicEnumTextProc(PDText obj, void *clientData)(PDText obj, void *clientData)
```

Header: `PDExpT.h:2778`

A callback for PDGraphicEnumMonitor. It is called for every text operator.

**See also:** [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

#### PDGraphicEnumXObjectRefMatrixProc

```cpp
typedef ASBool(*) PDGraphicEnumXObjectRefMatrixProc(ASFixedMatrix *matrix, void *clientData)(ASFixedMatrix *matrix, void *clientData)
```

Header: `PDExpT.h:2879`

A callback for PDGraphicEnumMonitor. It gets the current matrix for the subsequent XObject. It is called immediately before PDGraphicEnumXObjectRefProc().

**See also:** [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

#### PDGraphicEnumXObjectRefProc

```cpp
typedef ASBool(*) PDGraphicEnumXObjectRefProc(char *name, ASFixedRect *bbox, void *clientData)(char *name, ASFixedRect *bbox, void *clientData)
```

Header: `PDExpT.h:2819`

A callback for PDGraphicEnumMonitor. It is called for every XObject (Do) operator.

**See also:** [`PDPageEnumContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumContents)

### Structures (2)

#### PDGraphic

```cpp
typedef struct _t_PDGraphic* PDGraphic
```

Header: `PDExpT.h:2497`

All graphic objects that comprise page, charproc, and PDForm descriptions.

**See also:** [`PDGraphicEnumMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGraphicEnumMonitor)

#### PDGraphicEnumMonitor

```cpp
typedef struct _t_PDGraphicEnumMonitor* PDGraphicEnumMonitor
```

Header: `PDExpT.h:2881`

## PDInlineImage

### Functions (3)

#### PDInlineImageColorSpaceGetIndexLookup

```cpp
void PDInlineImageColorSpaceGetIndexLookup(PDInlineImage image, ASUns8 *data, ASInt32 dataLen)
```

Header: `PDProcs.h:3802`

Gets the lookup table for an indexed color space. The table will contain the number of entries specified by the index size, and there will be 1 byte for each color component for each entry. The number of color components depends on the color space: Color Number of components gray 1 RGB 3 CMYK 4 Lab 3 For additional information on indexed color space, see the Special Color Spaces section in the ISO 32000-1:2008, Document Management- Portable Document Format-Part 1: PDF 1.7, section 8.6.6, page 155. You can find this document on the web store of the International Standards Organization (ISO). There is also some useful discussion in the *PostScript Language Reference Manual* under indexed color spaces. [https://www.adobe.com/jp/print/postscript/pdfs/PLRM.pdf](https://www.adobe.com/jp/print/postscript/pdfs/PLRM.pdf)

**Parameters**

- `image` ([`PDInlineImage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDInlineImage)): IN/OUT The inline image whose lookup table is obtained.
- `data` ([`ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): IN/OUT (Filled by the method) The lookup table for image.
- `dataLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The length of `data` in bytes.

**Returns:** `void`

**See also:** [`PDImageColorSpaceGetIndexLookup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDImageColorSpaceGetIndexLookup)

#### PDInlineImageGetAttrs

```cpp
void PDInlineImageGetAttrs(PDInlineImage obj, PDImageAttrsP attrsP, ASInt32 attrsLen)
```

Header: `PDProcs.h:3751`

Gets an inline image's attributes. **Note:** This method is provided only for backwards compatibility. It has not been updated beyond PDF Version 1.1 and may not work correctly for newly created PDF 1.2 or later files. You should use the PDFEdit API to enumerate page contents. **Note:** The attribute for a color space is a CosObj. Cos objects that are the result of parsing inline dictionaries in the PDF page contents are a special class of Cos objects. You should never depend on these objects lasting the lifetime of the document. You should extract the information you need from the object immediately and refer to it no further in your code.

**Parameters**

- `obj` ([`PDInlineImage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDInlineImage)): IN/OUT The inline image whose attributes are obtained.
- `attrsP` (`PDImageAttrsP`): IN/OUT (Filled by the method) A pointer to a `PDImageAttrs` structure containing the image attributes. Note that this structure contains a Cos object that is subject to the warning below.
- `attrsLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT It must be `sizeof(PDImageAttrs)`.

**Returns:** `void`

**See also:** [`PDImageGetAttrs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDImageGetAttrs), [`PDInlineImageGetData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDInlineImageGetData)

#### PDInlineImageGetData

```cpp
void PDInlineImageGetData(PDInlineImage obj, ASUns8 *data, ASInt32 dataLen)
```

Header: `PDProcs.h:3766`

Gets the image data for an inline image.

**Parameters**

- `obj` ([`PDInlineImage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDInlineImage)): IN/OUT The inline image whose data is obtained.
- `data` ([`ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): IN/OUT (Filled by the method) A buffer into which the image data will be placed.
- `dataLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The number of bytes that `data` can hold. It must be large enough to hold the entire inline image. Use PDInlineImageGetAttrs() to determine how much data is in the image.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if `dataLen` is less than the amount of data in the image.

**See also:** [`PDInlineImageGetAttrs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDInlineImageGetAttrs)

### Structures (1)

#### PDInlineImage

```cpp
typedef struct _t_PDGraphic * PDInlineImage
```

Header: `PDExpT.h:2499`

## PDLinkAnnot

### Functions (5)

#### PDLinkAnnotGetAction

```cpp
PDAction PDLinkAnnotGetAction(PDLinkAnnot aLinkAnnot)
```

Header: `PDProcs.h:703`

Gets a link annotation's action. After you obtain the action, you can execute it with AVDocPerformAction().

**Parameters**

- `aLinkAnnot` ([`PDLinkAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnot)): IN/OUT The link annotation whose action is obtained.

**Returns:** [`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)

The link annotation's action.

**See also:** `AVDocPerformAction`, [`PDLinkAnnotSetAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnotSetAction)

#### PDLinkAnnotGetBorder

```cpp
void PDLinkAnnotGetBorder(PDLinkAnnot aLinkAnnot, PDLinkAnnotBorder *border)
```

Header: `PDProcs.h:663`

Gets the border of a link annotation.

**Parameters**

- `aLinkAnnot` ([`PDLinkAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnot)): IN/OUT The link annotation whose border is obtained.
- `border` (`PDLinkAnnotBorder *`): IN/OUT (Filled by the method) A pointer to a structure containing the link border. Link corner radii are ignored by the Acrobat viewers.

**Returns:** `void`

**See also:** [`PDLinkAnnotSetBorder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnotSetBorder)

#### PDLinkAnnotRemoveAction

```cpp
void PDLinkAnnotRemoveAction(PDLinkAnnot aLinkAnnot)
```

Header: `PDProcs.h:7918`

Removes a link annotation's action.

**Parameters**

- `aLinkAnnot` ([`PDLinkAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnot)): The link annotation whose action is removed.

**Returns:** `void`

**Exceptions**

- `pdErrBadAction`: @notify PDAnnotWillChange @notify PDAnnotDidChange

**See also:** [`PDLinkAnnotGetAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnotGetAction), [`PDLinkAnnotSetAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnotSetAction)

#### PDLinkAnnotSetAction

```cpp
void PDLinkAnnotSetAction(PDLinkAnnot aLinkAnnot, PDAction action)
```

Header: `PDProcs.h:691`

Sets a link annotation's action.

**Parameters**

- `aLinkAnnot` ([`PDLinkAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnot)): IN/OUT The link annotation whose action is set.
- `action` ([`PDAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAction)): IN/OUT The new action for the link annotation. @notify PDAnnotWillChange @notify PDAnnotDidChange

**Returns:** `void`

**See also:** [`PDLinkAnnotGetAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnotGetAction)

#### PDLinkAnnotSetBorder

```cpp
void PDLinkAnnotSetBorder(PDLinkAnnot aLinkAnnot, const PDLinkAnnotBorder *border)
```

Header: `PDProcs.h:679`

Sets a link annotation's border.

**Parameters**

- `aLinkAnnot` ([`PDLinkAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnot)): IN/OUT The link annotation whose border is set.
- `border` (`const PDLinkAnnotBorder *`): IN/OUT A pointer to a structure containing the link border. Link corner radii are ignored by the Acrobat viewers.

**Returns:** `void`

**Exceptions**

- `PDAnnotDidChange`
- `PDAnnotWillChange`: @notify PDAnnotWillChange @notify PDAnnotDidChange

**See also:** [`PDLinkAnnotGetBorder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDLinkAnnotGetBorder)

### Typedefs (1)

#### PDLinkAnnot

```cpp
typedef OPAQUE_64_BITS PDLinkAnnot
```

Header: `PDExpT.h:366`

A link annotation on a page in a PDF file. You can use any PDAnnot method on a PDLinkAnnot. Applications can: Get and set the bounding rectangle and color using PDAnnot methods. Get and set the action that occurs when the link is activated, and the link's border, using PDLinkAnnot methods. Create new link annotations and delete existing ones using the PDPage methods. To obtain a link annotation, use any of the PDAnnot calls, followed by CastToPDLinkAnnot(). The annotation passed to CastToPDLinkAnnot() must be a link annotation; other annotation types are not converted into link annotations.

**See also:** [`CastToPDLinkAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#CastToPDLinkAnnot), [`PDPageRemoveAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveAnnot)

### Definitions (1)

#### CastToPDLinkAnnot

Header: `PDExpT.h:449`

Value: `*(PDLinkAnnot *)&(a)`

Casts a generic annotation or a text annotation to a link annotation.

**See also:** [`CastToPDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#CastToPDAnnot), [`CastToPDTextAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#CastToPDTextAnnot)

## PDNameTree

### Functions (12)

#### PDNameTreeEnum

```cpp
void PDNameTreeEnum(PDNameTree theTree, CosObjEnumProc proc, void *clientData)
```

Header: `PDProcs.h:7046`

Enumerates the entries in the tree.

**Parameters**

- `theTree` ([`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)): IN/OUT A name tree.
- `proc` ([`CosObjEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEnumProc)): IN/OUT A procedure to call once for each name/object pair in `theTree`. The obj/value pair in `proc` correspond to the Cos string and CosObj values of each leaf in the tree.
- `clientData` (`void *`): IN/OUT Data used by the enumeration procedure. `clientData` is passed to the enumeration procedure proc each time an entry is encountered.

**Returns:** `void`

**See also:** [`PDNameTreeGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeGet), [`PDNameTreePut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreePut), [`PDNameTreeRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeRemove)

#### PDNameTreeEqual

```cpp
ASBool PDNameTreeEqual(PDNameTree tree1, PDNameTree tree2)
```

Header: `PDProcs.h:6976`

Compares two name trees to determine if they are the same object.

**Parameters**

- `tree1` ([`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)): A name tree.
- `tree2` ([`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)): Another name tree.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the two name trees are equivalent, `false` otherwise.

**See also:** [`PDNameTreeIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeIsValid)

#### PDNameTreeFromCosObj

```cpp
PDNameTree PDNameTreeFromCosObj(CosObj obj)
```

Header: `PDProcs.h:6938`

Creates a type cast of the CosObj to a name tree. This does not copy the object.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The CosObj for which a PDNameTree representation is desired.

**Returns:** [`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)

A PDNameTree representation of `obj`.

**See also:** [`PDNameTreeNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeNew), [`PDNameTreeGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeGetCosObj)

#### PDNameTreeGet

```cpp
ASBool PDNameTreeGet(PDNameTree theTree, const char *name, ASInt32 nameLen, CosObj *value)
```

Header: `PDProcs.h:7011`

Retrieves an object from the name tree.

**Parameters**

- `theTree` ([`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)): The PDNameTree from which an object is retrieved.
- `name` (`const char *`): The name of the object within `theTree` to get. This is a Cos-style string, not a C string.
- `nameLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length of `name`.
- `value` ([`CosObj *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): (Filled by the method) The Cos object corresponding to `name` within `theTree`.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the object was retrieved, `false` if no object with this name exists.

**See also:** [`PDNameTreePut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreePut), [`PDNameTreeRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeRemove)

#### PDNameTreeGetCosObj

```cpp
CosObj PDNameTreeGetCosObj(PDNameTree theTree)
```

Header: `PDProcs.h:6951`

Creates a type cast of the name tree to a CosObj. This does not copy the object.

**Parameters**

- `theTree` ([`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)): IN/OUT The PDNameTree for which a CosObj representation is desired.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

A CosObj representation of `theTree`.

**See also:** [`PDNameTreeNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeNew), [`PDNameTreeFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeFromCosObj)

#### PDNameTreeIsValid

```cpp
ASBool PDNameTreeIsValid(PDNameTree theTree)
```

Header: `PDProcs.h:6964`

Validates whether a PDNameTree is a CosDict Cos object.

**Parameters**

- `theTree` ([`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)): The PDNameTree whose validity is desired.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the name tree is a CosDict, `false` otherwise.

**See also:** [`PDDocCreateNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateNameTree), [`PDDocGetNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetNameTree), [`PDNameTreeEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeEqual)

#### PDNameTreeLookup

```cpp
CosObj PDNameTreeLookup(CosObj nameTree, char *string, ASInt32 stringLen)
```

Header: `PDProcs.h:6192`

Given a name tree (such as the Dests tree in the Names dictionary) and a string, find the CosObj in the tree that matches the string. See the description of Name Trees in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.9.6, page 88. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `nameTree` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The name tree in which to search.
- `string` (`char *`): The name to search for. The name tree uses Cos-style strings, which may use Unicode encoding, and these may contain bytes with zeroes in them (high bytes of ASCII characters). Note that `name` is not a C-style string. Cos string objects can contain `NULL` chars. Standard C string-handling functions may not work as expected.
- `stringLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length of `name` in bytes.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The Cos object associated with the specified name, which is the array element following the name.

**See also:** [`PDNameTreeGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeGet), [`PDNameTreePut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreePut)

#### PDNameTreeNew

```cpp
PDNameTree PDNameTreeNew(PDDoc pdDoc)
```

Header: `PDProcs.h:6925`

Creates a new name tree in the document. PDNameTreeIsValid() should be called to determine if the name tree returned by PDNameTreeNew() is usable.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document for which a new name tree is desired.

**Returns:** [`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)

The newly created name tree or a `NULL` CosObj if Acrobat is unable to create a PDNameTree for the document specified by `pdDoc`.

**See also:** [`PDNameTreeFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeFromCosObj), [`PDNameTreeGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeGetCosObj), [`PDNameTreeIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeIsValid), [`PDNameTreeRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeRemove)

#### PDNameTreeNotifyNameAdded

```cpp
void PDNameTreeNotifyNameAdded(PDNameTree theTree, CosObj key, CosObj value)
```

Header: `PDProcs.h:7956`

Sends a PDNameTreeNameAdded() notification.

**Parameters**

- `theTree` ([`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)): The PDNameTree to which a name had been added.
- `key` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The name of the object within `theTree` that was added. This is a Cos string, not a C string.
- `value` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): (Filled by the method) The Cos object corresponding to the object name that was added to `theTree`. @notify PDNameTreeNameAdded

**Returns:** `void`

**See also:** [`PDNameTreeNotifyNameRemoved`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeNotifyNameRemoved)

#### PDNameTreeNotifyNameRemoved

```cpp
void PDNameTreeNotifyNameRemoved(PDNameTree theTree, CosObj removedName)
```

Header: `PDProcs.h:7967`

Sends a PDNameTreeNameRemoved() notification.

**Parameters**

- `theTree` ([`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)): The PDNameTree from which the name had been removed.
- `removedName` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The name within `theTree` that was removed. @notify PDNameTreeNameRemoved

**Returns:** `void`

**See also:** [`PDNameTreeNotifyNameAdded`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeNotifyNameAdded)

#### PDNameTreePut

```cpp
void PDNameTreePut(PDNameTree theTree, CosObj key, CosObj value)
```

Header: `PDProcs.h:6994`

Puts a new entry in the name tree. If an entry with this name is already in the tree, it is replaced. @notify PDNameTreeNameAdded

**Parameters**

- `theTree` ([`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)): IN/OUT The name tree for which a new entry is added.
- `key` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The name of the object to put in the tree. This is a Cos-style string, not a C string. This allows the use of an existing indirect object for the key rather than forcing the creation of a new object.
- `value` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The Cos object to be associated with `key`.

**Returns:** `void`

**See also:** [`PDNameTreeGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeGet)

#### PDNameTreeRemove

```cpp
void PDNameTreeRemove(PDNameTree theTree, const char *key, ASInt32 keyLen)
```

Header: `PDProcs.h:7027`

Removes the specified object from the tree. It does nothing if no object with that name exists.

**Parameters**

- `theTree` ([`PDNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTree)): IN/OUT The name tree from which an entry is removed.
- `key` (`const char *`): IN/OUT The name of the entry to remove. This is a Cos- style string, not a C string.
- `keyLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The length of `key` in bytes. @notify PDNameTreeNameRemoved

**Returns:** `void`

**See also:** [`PDNameTreeGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeGet), [`PDNameTreePut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreePut)

### Typedefs (1)

#### PDNameTree

```cpp
typedef OPAQUE_64_BITS PDNameTree
```

Header: `PDExpT.h:5539`

The dictionary used to store all of the Named Destinations in a PDF file. A name tree is used to map Cos strings to Cos objects just as a Cos dictionary is used to map Cos names to Cos objects. However, a name tree can have many more entries than a Cos dictionary can. You create a PDNameTree and locate it where you think is appropriate (perhaps under a page, but most often right under the catalog). Name trees use Cos-style strings (not `NULL`-terminated C strings), which may use Unicode encoding, and these may contain bytes with zeroes in them (high bytes of ASCII characters).

**See also:** [`PDDocCreateNameTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateNameTree), [`PDNameTreeNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeNew), [`PDNameTreeFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeFromCosObj), [`PDNameTreeEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNameTreeEnum)

## PDNumTree

### Functions (9)

#### PDNumTreeEnum

```cpp
void PDNumTreeEnum(PDNumTree theTree, CosObjEnumProc proc, void *clientData)
```

Header: `PDProcs.h:7778`

Enumerates the entries in the tree.

**Parameters**

- `theTree` ([`PDNumTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTree)): IN/OUT A number tree.
- `proc` ([`CosObjEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEnumProc)): IN/OUT A procedure to call once for each number destination pair in `theTree`.
- `clientData` (`void *`): IN/OUT Data used by the enumeration procedure. `clientData` is passed to the enumeration procedure proc each time a number tree is encountered.

**Returns:** `void`

**See also:** [`PDNumTreeGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeGet), [`PDNumTreePut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreePut)

#### PDNumTreeEqual

```cpp
ASBool PDNumTreeEqual(PDNumTree tree1, PDNumTree tree2)
```

Header: `PDProcs.h:7719`

Compares two number trees to determine if they are the same object.

**Parameters**

- `tree1` ([`PDNumTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTree)): A number tree.
- `tree2` ([`PDNumTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTree)): Another number tree.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the two number trees are equivalent, `false` otherwise.

**See also:** [`PDNumTreeIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeIsValid)

#### PDNumTreeFromCosObj

```cpp
PDNumTree PDNumTreeFromCosObj(CosObj obj)
```

Header: `PDProcs.h:7684`

Creates a type cast of the CosObj to a number tree.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The CosObj for which a PDNumTree representation is desired.

**Returns:** [`PDNumTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTree)

A PDNumTree representation of `obj`.

**See also:** [`PDNumTreeNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeNew), [`PDNumTreeGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeGetCosObj)

#### PDNumTreeGet

```cpp
ASBool PDNumTreeGet(PDNumTree theTree, ASInt32 key, CosObj *value)
```

Header: `PDProcs.h:7748`

Retrieves an object from the number tree.

**Parameters**

- `theTree` ([`PDNumTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTree)): The PDNumTree requested.
- `key` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of the entry to retrieve.
- `value` ([`CosObj *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): (Filled by the method) The value associated with `key`.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the object was retrieved, `false` if no object with this number exists.

**See also:** [`PDNumTreePut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreePut), [`PDNumTreeRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeRemove)

#### PDNumTreeGetCosObj

```cpp
CosObj PDNumTreeGetCosObj(PDNumTree theTree)
```

Header: `PDProcs.h:7696`

Creates a type cast of the number tree to a CosObj.

**Parameters**

- `theTree` ([`PDNumTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTree)): IN/OUT The PDNumTree for which a CosObj representation is desired.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

A CosObj representation of `theTree`.

**See also:** [`PDNumTreeNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeNew), [`PDNumTreeFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeFromCosObj)

#### PDNumTreeIsValid

```cpp
ASBool PDNumTreeIsValid(PDNumTree theTree)
```

Header: `PDProcs.h:7707`

Validates whether a PDNumTree is a CosDict Cos object.

**Parameters**

- `theTree` ([`PDNumTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTree)): The PDNumTree whose validity is desired.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the number tree is a CosDict, `false` otherwise.

**See also:** [`PDNumTreeEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeEqual)

#### PDNumTreeNew

```cpp
PDNumTree PDNumTreeNew(PDDoc pdDoc)
```

Header: `PDProcs.h:7672`

Creates a new number tree in the document. PDNumTreeIsValid() should be called to determine if the number tree returned by PDNumTreeNew() is usable.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document for which a new number tree is desired.

**Returns:** [`PDNumTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTree)

The newly created number tree, or a `NULL` CosObj if Acrobat is unable to create a PDNumTree for the document specified by `pdDoc`.

**See also:** [`PDNumTreeFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeFromCosObj), [`PDNumTreeGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeGetCosObj), [`PDNumTreeIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeIsValid)

#### PDNumTreePut

```cpp
void PDNumTreePut(PDNumTree theTree, ASInt32 key, CosObj value)
```

Header: `PDProcs.h:7734`

Puts a new entry in the number tree. If an entry with this number is already in the tree, it is replaced.

**Parameters**

- `theTree` ([`PDNumTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTree)): IN/OUT The number tree for which a new entry is added
- `key` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The number of the entry.
- `value` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The value associated with `key`. @notify PDNumTreeNumAdded

**Returns:** `void`

**See also:** [`PDNumTreeGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeGet), [`PDNumTreeRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeRemove)

#### PDNumTreeRemove

```cpp
void PDNumTreeRemove(PDNumTree theTree, ASInt32 key)
```

Header: `PDProcs.h:7762`

Removes the specified object from the tree. It does nothing if no object with that number exists.

**Parameters**

- `theTree` ([`PDNumTree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTree)): IN/OUT The number tree from which an entry is removed.
- `key` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The number of the entry to remove. @notify PDNumTreeNumRemoved

**Returns:** `void`

**See also:** [`PDNumTreeGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeGet), [`PDNumTreePut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreePut)

### Typedefs (1)

#### PDNumTree

```cpp
typedef OPAQUE_64_BITS PDNumTree
```

Header: `PDExpT.h:5554`

An object that points to the root node of a number tree inside a PDF file. A number tree is used to map integers to arbitrary Cos objects just as a Cos dictionary is used to map Cos names to Cos objects. However, a number tree can have many more entries than a Cos dictionary can.

**See also:** [`PDNumTreeNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeNew), [`PDNumTreeFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeFromCosObj), [`PDNumTreeEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDNumTreeEnum)

## PDOCConfig

### Functions (19)

#### PDOCConfigCreate

```cpp
PDOCConfig PDOCConfigCreate(PDDoc pdDoc)
```

Header: `PDProcs.h:9998`

Creates a new optional-content configuration object.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the configuration is used.

**Returns:** [`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)

The newly created configuration object.

**See also:** [`PDOCConfigDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigDestroy)

#### PDOCConfigDestroy

```cpp
void PDOCConfigDestroy(PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:10009`

Removes an optional-content configuration object and destroys the Cos objects associated with it. If you pass this method the document's default configuration object (as returned by PDDocGetOCConfig()), nothing happens.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration to destroy.

**Returns:** `void`

**See also:** [`PDOCConfigCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigCreate)

#### PDOCConfigGetAllRadioButtonGroups

```cpp
PDOCG ** PDOCConfigGetAllRadioButtonGroups(PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:10133`

Returns an array of pointers to sets of optional-content groups in the configuration that are configured to be mutually exclusive. A set behaves like a radio button group, where only one member can be `ON` at one time.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration.

**Returns:** [`PDOCG **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)

A `NULL`-terminated array of pointers to `NULL`-terminated arrays of optional-content groups (OCGs). The client is responsible for freeing all arrays using ASfree().

**See also:** [`PDOCConfigGetRadioButtonGroupForOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetRadioButtonGroupForOCG), [`PDOCConfigMakeRadioButtonGroup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigMakeRadioButtonGroup)

#### PDOCConfigGetCosObj

```cpp
CosObj PDOCConfigGetCosObj(PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:10044`

Gets the Cos object associated with the optional-content configuration.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which a CosObj representation is desired.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

A CosObj representation of pdOCCfg.

#### PDOCConfigGetCreator

```cpp
ASText PDOCConfigGetCreator(PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:10229`

Gets the creator property for an optional-content configuration.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which a creator is desired.

**Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)

An ASText object containing the creator string from the Creator entry in the configuration's Cos dictionary, or `NULL` if there is no such entry. The client is responsible for freeing the ASText using ASTextDestroy().

**See also:** [`PDOCConfigSetCreator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetCreator), [`PDOCConfigGetName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetName)

#### PDOCConfigGetInitState

```cpp
void PDOCConfigGetInitState(PDOCConfig pdOCCfg, PDOCConfigBaseState *bs, PDOCG **onOCGs, PDOCG **offOCGs)
```

Header: `PDProcs.h:10175`

Gets the initial `ON-OFF` states of optional-content groups in an optional-content configuration. The client is responsible for freeing storage for the arrays using ASfree().

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which the initial state is desired.
- `bs` ([`PDOCConfigBaseState *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigBaseState)): (Filled by the method) An existing PDOCConfigBaseState structure in which to store the initialization information.
- `onOCGs` ([`PDOCG **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): (Filled by the method) A `NULL`-terminated array of OCGs that have an initial state of `ON`, or `NULL` if there are no such groups.
- `offOCGs` ([`PDOCG **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): (Filled by the method) A `NULL`-terminated array of OCGs that have an initial state of `OFF`, or `NULL` if there are no such groups.

**Returns:** `void`

**See also:** [`PDOCConfigSetInitState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetInitState), [`PDOCGGetInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetInitialState)

#### PDOCConfigGetIntent

```cpp
ASAtom * PDOCConfigGetIntent(PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:10287`

Gets the Intent entry for an optional-content configuration. An intent is an ASAtom value broadly describing the intended use, either `View` or `Design`. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration. The intent array contains entries (atoms) terminated by ASAtomNull. If the configuration has no Intent entry, the default value of `View` is used. In this case, optional content is disabled for contexts initialized with this configuration.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which an intent list is desired.

**Returns:** [`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

The ASAtomNull-terminated intent array. The client is responsible for freeing it using ASfree().

**See also:** [`PDOCConfigSetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetIntent), [`PDOCContextGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetIntent), [`PDOCGGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetIntent), [`PDOCGUsedInOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCConfig), [`PDOCGUsedInOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCContext)

#### PDOCConfigGetLockedArray

```cpp
PDOCG * PDOCConfigGetLockedArray(PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:11180`

Returns a PDOCConfig object's list of locked OCGs. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The optional-content configuration.

**Returns:** [`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)

A `NULL`-terminated array of PDOCG objects, or `NULL` if the specified configuration does not contain a list of locked OCGs. The client is responsible for freeing the array using ASfree().

**See also:** [`PDOCConfigSetLockedArray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetLockedArray), [`PDOCGGetLocked`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetLocked), [`PDOCGSetLocked`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetLocked)

#### PDOCConfigGetName

```cpp
ASText PDOCConfigGetName(PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:10201`

Gets the name of an optional-content configuration.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which a name is desired.

**Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)

An ASText object containing the name string from Name entry of the configuration's Cos dictionary, or `NULL` if there is no Name entry. The client is responsible for freeing the ASText object using ASTextDestroy().

**See also:** [`PDOCConfigSetName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetName), [`PDOCConfigGetCreator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetCreator)

#### PDOCConfigGetOCGOrder

```cpp
ASBool PDOCConfigGetOCGOrder(PDOCConfig pdOCCfg, CosObj *orderObj)
```

Header: `PDProcs.h:10085`

Gets the user interface display order of optional-content groups (OCGs) in an optional-content configuration. This is the order in which the group names are displayed in the Layers panel of Acrobat 6.0 and later. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which an OCG display order is desired.
- `orderObj` ([`CosObj *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): (Filled by the method) A pointer to the Cos object containing the OCG order array. See the description of the Optional Content Groups (OCG) in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 8.11.2, page 222.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the order belongs directly to this configuration, `false` if it is inherited from the document's default configuration.

**See also:** [`PDOCConfigSetOCGOrder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetOCGOrder)

#### PDOCConfigGetPDDoc

```cpp
PDDoc PDOCConfigGetPDDoc(PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:10034`

Gets the document to which the optional-content configuration belongs.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which a document is desired.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

The document object.

**See also:** [`PDDocGetOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCConfig)

#### PDOCConfigGetRadioButtonGroupForOCG

```cpp
PDOCG * PDOCConfigGetRadioButtonGroupForOCG(PDOCConfig pdOCCfg, PDOCG ocg)
```

Header: `PDProcs.h:10118`

Returns an array of optional-content groups in the configuration that contains the specified group, and is configured to behave like a radio button group, where only one member of the set can be `ON` at one time.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The optional-content configuration.
- `ocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group for which to obtain the radio-button group.

**Returns:** [`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)

A `NULL`-terminated array of PDOCG objects, or `NULL` if the specified group does not belong to any radio button group. The client is responsible for freeing the array using ASfree().

**See also:** [`PDOCConfigGetAllRadioButtonGroups`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetAllRadioButtonGroups), [`PDOCConfigMakeRadioButtonGroup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigMakeRadioButtonGroup)

#### PDOCConfigMakeRadioButtonGroup

```cpp
void PDOCConfigMakeRadioButtonGroup(PDOCConfig pdOCCfg, PDOCG *ocgs)
```

Header: `PDProcs.h:10100`

Configures a mutually exclusive set of optional-content groups in an optional-content configuration. The set behaves like a radio button group, where only one OCG from the set can be `ON` at a time. A client must enforce this in the user interface-level code, not the PD-level code.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The optional-content configuration.
- `ocgs` ([`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): A `NULL`-terminated array of optional-content groups to be included in the group.

**Returns:** `void`

**See also:** [`PDOCConfigGetAllRadioButtonGroups`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetAllRadioButtonGroups), [`PDOCConfigGetRadioButtonGroupForOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetRadioButtonGroupForOCG)

#### PDOCConfigSetCreator

```cpp
void PDOCConfigSetCreator(PDOCConfig pdOCCfg, ASConstText creator)
```

Header: `PDProcs.h:10214`

Sets the creator property of an optional-content configuration. Stores the specified string as the Creator entry in the configuration's Cos dictionary.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which to set a creator.
- `creator` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The new creator string.

**Returns:** `void`

**See also:** [`PDOCConfigGetCreator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetCreator), [`PDOCConfigSetName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetName)

#### PDOCConfigSetInitState

```cpp
void PDOCConfigSetInitState(PDOCConfig pdOCCfg, PDOCConfigBaseState bs, PDOCG *onOCGs, PDOCG *offOCGs)
```

Header: `PDProcs.h:10152`

Sets the initial `ON-OFF` states of optional-content groups to be saved in an optional-content configuration.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which to set the initial state.
- `bs` ([`PDOCConfigBaseState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigBaseState)): An existing PDOCConfigBaseState structure containing the initialization information.
- `onOCGs` ([`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): A `NULL`-terminated array of optional-content groups (OCGs) that have an initial state of `ON` when that is not the base state, or `NULL`.
- `offOCGs` ([`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): A `NULL`-terminated array of OCGs that have an initial state of `OFF` when that is not the base state, or `NULL`.

**Returns:** `void`

**See also:** [`PDOCConfigGetInitState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetInitState), [`PDOCGSetInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetInitialState)

#### PDOCConfigSetIntent

```cpp
void PDOCConfigSetIntent(PDOCConfig pdOCCfg, ASAtom *intent)
```

Header: `PDProcs.h:10258`

Sets the Intent entry in an optional-content configuration's Cos dictionary. An intent is an ASAtom value broadly describing the intended use, either `View` or `Design`. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration. If the configuration has no Intent entry, the default value of `View` is used. In this case, optional content is disabled for contexts initialized with this configuration.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which to set an intent.
- `intent` ([`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The new Intent entry value, an array of atoms terminated with ASAtomNull. To remove the Intent entry, pass an array with only one element, ASAtom`NULL`.

**Returns:** `void`

**See also:** [`PDOCConfigGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetIntent), [`PDOCContextSetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetIntent), [`PDOCGSetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetIntent), [`PDOCGUsedInOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCConfig), [`PDOCGUsedInOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCContext)

#### PDOCConfigSetLockedArray

```cpp
void PDOCConfigSetLockedArray(PDOCConfig pdOCCfg, PDOCG *lockedOCGs)
```

Header: `PDProcs.h:11195`

Sets a PDOCConfig's list of locked OCGs. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The optional-content configuration.
- `lockedOCGs` ([`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): A `NULL`-terminated array of PDOCG objects to be used as the locked OCGs for the specified configuration, or `NULL` if the configuration should not contain a list of locked OCGs.

**Returns:** `void`

**See also:** [`PDOCConfigGetLockedArray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetLockedArray), [`PDOCGGetLocked`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetLocked), [`PDOCGSetLocked`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetLocked)

#### PDOCConfigSetName

```cpp
void PDOCConfigSetName(PDOCConfig pdOCCfg, ASConstText name)
```

Header: `PDProcs.h:10188`

Sets the name of an optional-content configuration. It stores the specified string as the Name entry in the configuration's Cos dictionary.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which to set the name.
- `name` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The new name string.

**Returns:** `void`

**See also:** [`PDOCConfigGetName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetName), [`PDOCConfigSetCreator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetCreator)

#### PDOCConfigSetOCGOrder

```cpp
void PDOCConfigSetOCGOrder(PDOCConfig pdOCCfg, CosObj orderArray)
```

Header: `PDProcs.h:10063`

Sets the user interface display order of optional-content groups (OCGs) in an optional-content configuration. This is the order in which the group names are displayed in the Layers panel of Acrobat 6.0 and later. You can find this document on the web store of the International Standards Organization (ISO). Pass NULL to remove any existing order entry.

**Parameters**

- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which a OCG is desired.
- `orderArray` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object containing the OCG order array. See the description of the Optional Content Groups (OCG) in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 8.11.2, page 222.

**Returns:** `void`

**See also:** [`PDOCConfigGetOCGOrder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetOCGOrder)

### Typedefs (2)

#### PDOCConfigBaseState

```cpp
typedef ASUns8 PDOCConfigBaseState
```

Header: `PDExpT.h:5729`

#### PDOCConfigEnumProc

```cpp
typedef ASBool(*) PDOCConfigEnumProc(PDOCConfig occonfig, void *clientData)(PDOCConfig occonfig, void *clientData)
```

Header: `PDExpT.h:5858`

A callback used for enumerating optional-content configurations. Enumeration stops when all configurations have been enumerated, or when the callback returns `false`.

**See also:** [`PDDocEnumOCConfigs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCConfigs)

### Structures (1)

#### PDOCConfig

```cpp
typedef struct _t_PDOCConfig* PDOCConfig
```

Header: `PDExpT.h:5681`

A PDOCConfig represents a set of states and other information that is saved in a PDF file for future use. There is a document default configuration, saved in the /D entry in the OCProperties dictionary, and a list of other client configurations, saved as an array of configurations in the /Configs entry in the OCProperties dictionary. PDOCConfig objects are typically used to initialize the OCG states for a client's PDOCContext.

### Enums (1)

#### PDOCConfigBaseStates

Header: `PDExpT.h:5721`

PDOCBaseState enumerates the three legal values for the BaseState key in an optional content configuration dictionary (PDOCConfig). When initializing a PDOCContext using KOCCInit_FromConfig(), this enumeration represents the starting state of the Optional Content Groups (OCGs) before the contents of the config's ON and OFF OCG lists are processed. If the BaseState is Unchanged, and the PDOCConfig is just being constructed, the current states of the OCGs from the PDDoc's own PDOCConfig are used.

**Values**

- `kPDOCBaseState_OFF = 0`
- `kPDOCBaseState_ON = 1`
- `kPDOCBaseState_Unchanged = 2`

## PDOCContext

### Functions (24)

#### PDOCContextApplyAutoStateChanges

```cpp
ASBool PDOCContextApplyAutoStateChanges(PDOCContext ctx, PDOCConfig cfg, ASAtom event)
```

Header: `PDProcs.h:9709`

Calls PDOCContextFindAutoStateChanges() to find optional-content groups whose `ON-OFF` states should be toggled, based on usage application directives contained in the configuration's AS array, and applies the changes within the given context. The AS array defines how usage entries are used to automatically manipulate the OCG states. It associates an event (`View`, `Print`, or `Export`) with a list of OCGs and a category, or list of usage keys identifying OCG usage dictionary entries. See the description of the Optional Content Groups (OCG) in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 8.11.2, page 222. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `ctx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the visibility state is changed.
- `cfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration whose usage directives are used.
- `event` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The event for which an `ON-OFF` state is automatically changed. Events are `View`, `Export`, and `Print`.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if successful, `false` otherwise.

**See also:** [`PDOCContextFindAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextFindAutoStateChanges), [`PDOCContextMakeCopyWithAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextMakeCopyWithAutoStateChanges), [`PDOCContextClearAllUserOverrides`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextClearAllUserOverrides), [`PDOCGGetUserOverride`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetUserOverride), [`PDOCGSetUserOverride`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetUserOverride)

#### PDOCContextClearAllUserOverrides

```cpp
void PDOCContextClearAllUserOverrides(PDOCContext ctx)
```

Header: `PDProcs.h:10463`

Removes usage override marks in all optional-content groups in the given context. When an optional-content group is marked as having had its state set explicitly in a specified context, automatic state changes caused by the `View` event are prevented. When a group's automatic state change is caused by the `Export` or `Print` event, the user-override setting for the group is ignored. A configuration's AS array defines how usage entries are used to automatically manipulate the OCG states. It associates an event (`View`, `Print`, or `Export`) with a list of OCGs and a category, or list of usage keys identifying OCG usage dictionary entries. See the description of the Optional Content Groups (OCG) in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 8.11.2, page 222. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `ctx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the user override marks are removed.

**Returns:** `void`

**See also:** [`PDOCGGetUserOverride`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetUserOverride), [`PDOCGSetUserOverride`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetUserOverride), [`PDOCContextApplyAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextApplyAutoStateChanges), [`PDOCContextFindAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextFindAutoStateChanges), [`PDOCContextMakeCopyWithAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextMakeCopyWithAutoStateChanges)

#### PDOCContextContentIsVisible

```cpp
ASBool PDOCContextContentIsVisible(PDOCContext ocContext)
```

Header: `PDProcs.h:9966`

Tests whether content is visible in the optional-content context. The method considers the context's current OCMD stack, the group `ON-OFF` states, the non-OC drawing status, the drawing and enumeration type, and the intent. Use this method in conjunction with the OCMD stack methods.

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the visibility state is desired.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the content is visible, `false` otherwise.

**See also:** [`PDOCContextPopOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextPopOCMD), [`PDOCContextPushOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextPushOCMD), [`PDOCContextResetOCMDStack`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextResetOCMDStack), [`PDOCContextXObjectIsVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextXObjectIsVisible)

#### PDOCContextFindAutoStateChanges

```cpp
PDOCG * PDOCContextFindAutoStateChanges(PDOCContext ctx, PDOCConfig cfg, ASAtom event)
```

Header: `PDProcs.h:9677`

Finds optional-content groups whose `ON-OFF` states should be toggled in the context, based on usage application directives contained in the configuration's AS array. The AS array defines how usage entries are used to automatically manipulate the OCG states. It associates an event (`View`, `Print`, or `Export`) with a list of OCGs and a category, or list of usage keys identifying OCG usage dictionary entries.

**Parameters**

- `ctx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the visibility state should be changed.
- `cfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration whose usage directives are used.
- `event` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The event for which an `ON-OFF` state is automatically changed. Events are `View`, `Export`, and `Print`.

**Returns:** [`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)

A `NULL`-terminated array of optional-content group objects. The client is responsible for freeing it using ASfree().

**See also:** [`PDOCContextApplyAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextApplyAutoStateChanges), [`PDOCContextMakeCopyWithAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextMakeCopyWithAutoStateChanges), [`PDOCContextClearAllUserOverrides`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextClearAllUserOverrides), [`PDOCGGetUserOverride`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetUserOverride), [`PDOCGSetUserOverride`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetUserOverride)

#### PDOCContextFree

```cpp
void PDOCContextFree(PDOCContext ocContext)
```

Header: `PDProcs.h:9481`

Destroys an optional-content context object and frees the associated memory as needed.

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context object to free.

**Returns:** `void`

**See also:** [`PDOCContextInit`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextInit), [`PDOCContextNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextNew)

#### PDOCContextGetIntent

```cpp
ASAtom * PDOCContextGetIntent(PDOCContext ocContext)
```

Header: `PDProcs.h:9797`

Gets the intent list for an optional-content context. An intent is an ASAtom value broadly describing the intended use, either `View` or `Design`. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which an intent is desired.

**Returns:** [`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

An array containing intent entries (ASAtom objects) terminated by ASAtomNull. The client is responsible for freeing it using ASfree().

**See also:** [`PDOCContextSetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetIntent), [`PDOCConfigGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetIntent), [`PDOCGGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetIntent), [`PDOCGUsedInOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCConfig), [`PDOCGUsedInOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCContext)

#### PDOCContextGetNonOCDrawing

```cpp
ASBool PDOCContextGetNonOCDrawing(PDOCContext ocContext)
```

Header: `PDProcs.h:9838`

Gets the non-OC drawing status for an optional-content context. Content that is not marked as optional content is drawn when NonOCDrawing is `true`, and not drawn when NonOCDrawing is `false`. Together, this value and the PDOCDrawEnumType value of the context determine how both optional and non-optional content on a page is drawn or enumerated. See PDOCDrawEnumType().

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the non-OC drawing
  status is desired.`true` if the context's NonOCDrawing is `true`,
  `false` otherwise.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

**See also:** [`PDOCContextSetNonOCDrawing`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetNonOCDrawing), [`PDOCContextGetOCDrawEnumType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCDrawEnumType), [`PDOCContextNewWithOCDisabled`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextNewWithOCDisabled)

#### PDOCContextGetOCDrawEnumType

```cpp
PDOCDrawEnumType PDOCContextGetOCDrawEnumType(PDOCContext ocContext)
```

Header: `PDProcs.h:9747`

Gets the drawing and enumeration type for an optional-content context. This type, together with the visibility determined by the OCG and Optional Content Membership Dictionary (OCMD) states, controls whether content that is marked as optional content is drawn or enumerated. Together, this value and the NonOCDrawing value of the context determine how both optional and non-optional content on a page is drawn or enumerated. See PDOCDrawEnumType(). @since

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the drawing and
  enumeration type is desired.

**Returns:** [`PDOCDrawEnumType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCDrawEnumType)

**See also:** [`PDOCContextGetNonOCDrawing`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetNonOCDrawing), [`PDOCContextSetOCDrawEnumType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetOCDrawEnumType)

#### PDOCContextGetOCGStates

```cpp
void PDOCContextGetOCGStates(PDOCContext ocContext, PDOCG *pdocgs, ASBool *states)
```

Header: `PDProcs.h:9604`

Gets the `ON-OFF` states for the given optional-content groups (OCGs) in the given optional-content context. It returns the states in the `states` array, which must be large enough to hold as many ASBool values as there are OCGs.

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the OCG states are desired.
- `pdocgs` ([`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): A `NULL`-terminated array of optional-content groups whose states are obtained.
- `states` ([`ASBool *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): (Filled by the method) An array of OCG states corresponding to the array of OCGs, `true` for ON and `false` for `OFF`. The array must be large enough to hold as many states as there are non-`NULL` OCGs.

**Returns:** `void`

**See also:** [`PDOCContextSetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetOCGStates)

#### PDOCContextGetPDDoc

```cpp
PDDoc PDOCContextGetPDDoc(PDOCContext ocContext)
```

Header: `PDProcs.h:9505`

Gets the document that contains an optional-content context.

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which a document is desired.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

The document object.

**See also:** [`PDDocGetOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCContext)

#### PDOCContextInit

```cpp
void PDOCContextInit(PDOCContext ocContext, PDOCContextInitPolicy policy, PDOCContext otherCtx, PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:9524`

Initializes the `ON-OFF` states of all optional-content groups (OCGs) within an existing context.

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context to initialize.
- `policy` ([`PDOCContextInitPolicy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextInitPolicy)): The initialization policy for the context. This value determines whether optional-content groups are initially `ON` or `OFF`.
- `otherCtx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): Another context from which to take initial OCG states when the policy is kOCCInit_FromOtherContext. It is ignored for other policies.
- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): A configuration from which to take initial OCG states when the policy is kOCCInit_FromConfig. It is ignored for other policies.

**Returns:** `void`

**See also:** [`PDOCContextNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextNew), [`PDOCContextFree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextFree)

#### PDOCContextMakeCopy

```cpp
PDOCContext PDOCContextMakeCopy(PDOCContext ocContext)
```

Header: `PDProcs.h:9543`

Creates a new context object to represent an optional-content state of the document, using an existing context as a template. This is the same as the following call: `PDOCCOntextNew(kOCCInit_FromOtherContext, ocContext, NULL, PDOCContextGetPDDoc(ocContext));`

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context to copy.

**Returns:** [`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

**See also:** [`PDDocGetOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCContext), [`PDOCContextInit`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextInit), [`PDOCContextNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextNew), [`PDOCContextFree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextFree)

#### PDOCContextMakeCopyWithAutoStateChanges

```cpp
PDOCContext PDOCContextMakeCopyWithAutoStateChanges(PDOCContext inCtx, PDOCConfig cfg, ASAtom event)
```

Header: `PDProcs.h:9650`

Creates a new context object that represents an optional-content state of the document, using an existing context as a template, but applying an automatic state change for the specified event. An automatic state change toggles all groups' `ON-OFF` states when the triggering event occurs. A configuration's AS array defines how usage entries are used to automatically manipulate the OCG states. It associates an event (`View`, `Print`, or `Export`) with a list of OCGs and a category, or list of usage keys identifying OCG usage dictionary entries. @since

**Parameters**

- `inCtx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context to copy.
- `cfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration in which the automatic state
  change applies.
- `event` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The event for which state will automatically
  change. Events are `View`, `Export`, and `Print`.

**Returns:** [`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)

**See also:** [`PDOCContextApplyAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextApplyAutoStateChanges), [`PDOCContextFindAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextFindAutoStateChanges), [`PDOCContextClearAllUserOverrides`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextClearAllUserOverrides), [`PDOCGGetUserOverride`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetUserOverride), [`PDOCGSetUserOverride`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetUserOverride)

#### PDOCContextNew

```cpp
PDOCContext PDOCContextNew(PDOCContextInitPolicy policy, PDOCContext otherCtx, PDOCConfig pdOCCfg, PDDoc pdDoc)
```

Header: `PDProcs.h:9471`

Creates a context object that represents an optional-content state of the document, initializing it in the same way as PDOCContextInit().

**Parameters**

- `policy` ([`PDOCContextInitPolicy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextInitPolicy)): The initialization policy for the new context. This value determines whether optional-content groups (OCGs) are initially `ON` or `OFF`.
- `otherCtx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): Another context from which to take initial OCG states when the policy is kOCCInit_FromOtherContext. It is ignored for other policies.
- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): A configuration from which to take initial OCG states when the policy is kOCCInit_FromConfig. It is ignored for other policies.
- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document for which to create a context.

**Returns:** [`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

**See also:** [`PDOCContextInit`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextInit), [`PDOCContextFree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextFree)

#### PDOCContextNewWithInitialState

```cpp
PDOCContext PDOCContextNewWithInitialState(PDDoc pdDoc)
```

Header: `PDProcs.h:9586`

Creates a context object that represents an optional-content state of the document, using the current state as the initial state for each group (OCG), as determined by the document's optional-content configuration (returned by `PDDocGetOCConfig(pdDoc)`).

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document for which to create a context.

**Returns:** [`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

**See also:** [`PDDocGetOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCConfig), [`PDOCContextInit`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextInit), [`PDOCContextNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextNew), [`PDOCContextNewWithOCDisabled`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextNewWithOCDisabled), [`PDOCContextFree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextFree)

#### PDOCContextNewWithOCDisabled

```cpp
PDOCContext PDOCContextNewWithOCDisabled(PDDoc pdDoc)
```

Header: `PDProcs.h:9568`

Creates a context object that represents an optional-content state of the document, with the PDOCDrawEnumType property set to kPDOC_NoOC, so that no content marked as optional content is drawn, regardless of the visibility according to the OCGs and OCMDs. Content that is not marked as optional content may still be drawn, depending on the NonOCDrawing property.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document for which to create a context.

**Returns:** [`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

**See also:** [`PDOCContextInit`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextInit), [`PDOCContextNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextNew), [`PDOCContextNewWithInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextNewWithInitialState), [`PDOCContextFree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextFree), [`PDOCContextGetNonOCDrawing`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetNonOCDrawing), [`PDOCContextGetOCDrawEnumType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCDrawEnumType), [`PDOCContextSetNonOCDrawing`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetNonOCDrawing), [`PDOCContextSetOCDrawEnumType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetOCDrawEnumType)

#### PDOCContextPopOCMD

```cpp
void PDOCContextPopOCMD(PDOCContext ocContext)
```

Header: `PDProcs.h:9946`

Pops the optional-content membership dictionary (OCMD) stack for an optional-content context. The stack is used to track nesting of optional-content states as contents are enumerated or drawn: • Call the PDOCContextPushOCMD() method when entering BDC for optional content or beginning to process a form or annotation that has a OC entry. • Call this method to pop the stack when encountering EMC, or finishing the processing of a form or annotation appearance. To track nested content that is not for optional content, pass in `NULL` for pdOCMD when pushing the OCMD stack for BMC, patterns, and charprocs, for BDC with no optional content, or for forms or annotations that do not have an OC entry. When finished processing any of these objects, you can call PDOCContextPopOCMD() without worrying about whether the content was optional.

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which to pop the OCMD stack.

**Returns:** `void`

**See also:** [`PDOCContextPushOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextPushOCMD), [`PDOCContextResetOCMDStack`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextResetOCMDStack), [`PDOCContextContentIsVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextContentIsVisible), [`PDOCContextXObjectIsVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextXObjectIsVisible)

#### PDOCContextPushOCMD

```cpp
void PDOCContextPushOCMD(PDOCContext pdOCContext, PDOCMD pdOCMD)
```

Header: `PDProcs.h:9914`

Pushes a new optional-content membership dictionary (OCMD) onto the stack for an optional-content context. The stack is used to track nesting of optional-content states as contents are enumerated or drawn. Call this method when entering the BDC for optional content or beginning to process a form or annotation that has a OC entry. Call PDOCContextPopOCMD() when encountering an EMC, or finishing the processing of a form or annotation appearance. To make it easier to track nested content that is not for optional content, pass `NULL` for pdOCMD when encountering BMC, patterns, and charprocs. Also pass `NULL` for a BDC with no optional content or for forms or annotations that do not have an OC entry. When finished processing any of these objects, you can call PDOCContextPopOCMD() without worrying about whether the content was optional.

**Parameters**

- `pdOCContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context containing the OCMD stack.
- `pdOCMD` ([`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)): The OCMD to push onto the stack.

**Returns:** `void`

**See also:** [`PDOCContextPopOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextPopOCMD), [`PDOCContextResetOCMDStack`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextResetOCMDStack), [`PDOCContextContentIsVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextContentIsVisible), [`PDOCContextXObjectIsVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextXObjectIsVisible)

#### PDOCContextResetOCMDStack

```cpp
void PDOCContextResetOCMDStack(PDOCContext pdOCContext)
```

Header: `PDProcs.h:9884`

Clears the Optional Content Membership Dictionary (OCMD) stack for an optional-content context, and resets the current visibility for the context based on the context's non-OC drawing setting (see PDOCContextSetNonOCDrawing()). Call this method at the start of an enumeration or drawing operation that uses a given context. The OCMD stack contains optional-content membership dictionary objects. The OCMD stack methods and the various methods that test visibility (such as PDAnnotIsCurrentlyVisible()) work together as content is being enumerated or drawn to determine whether particular graphical elements are visible or not. Visibility is based on the context's collection of `ON-OFF` states for optional-content groups, the context's current settings for NonOCDrawing and PDOCDrawEnumType, and the state of the OCMD stack. Any custom drawing or enumerating code that needs to keep track of visibility of content must make a private copy of the PDOCContext if that context could be accessed by some other client, in order to avoid conflicting state changes. In particular, you must copy the document's default context (as returned by PDDocGetOCContext()). To enforce this, this reset method does nothing when given a document's default context. Similarly, the push and pop stack operations raise an error for the default context. If you are using the PD-level draw and enumeration methods, you do not need to copy the context or explicitly call the OCMD stack methods, as the PD-level methods do this internally. Clients of PDFEdit and other libraries that enumerate contents need to use these three methods when traversing the PDEContent structure. When entering a new PDEContent, call PDOCContextPushOCMD() (passing an OCMD object or `NULL`). Upon finishing the traversal, call PDOCContextPopOCMD(). @since

**Parameters**

- `pdOCContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which to reset the OCMD
  stack.

**Returns:** `void`

**See also:** [`PDOCContextPopOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextPopOCMD), [`PDOCContextPushOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextPushOCMD), [`PDOCContextContentIsVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextContentIsVisible), [`PDOCContextXObjectIsVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextXObjectIsVisible)

#### PDOCContextSetIntent

```cpp
void PDOCContextSetIntent(PDOCContext ocContext, ASAtom *intent)
```

Header: `PDProcs.h:9773`

Sets the Intent entry in an optional-content context's Cos dictionary. An intent is an ASAtom value broadly describing the intended use, either `View` or `Design`. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration. It raises an exception if the context is busy.

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which to set the intent.
- `intent` ([`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The new Intent entry value, an array of atoms terminated with ASAtomNull.

**Returns:** `void`

**See also:** [`PDOCContextGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetIntent), [`PDOCConfigSetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetIntent), [`PDOCGSetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetIntent), [`PDOCGUsedInOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCConfig), [`PDOCGUsedInOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCContext)

#### PDOCContextSetNonOCDrawing

```cpp
void PDOCContextSetNonOCDrawing(PDOCContext ocContext, ASBool drawNonOC)
```

Header: `PDProcs.h:9817`

Sets the non-OC status for an optional-content context. Content that is not marked as optional content is drawn when NonOCDrawing is `true`, and not drawn when NonOCDrawing is `false`. Together, this value and the PDOCDrawEnumType value of the context determine how both optional and non-optional content on a page is drawn or enumerated. See PDOCDrawEnumType().

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which to set the non-OC drawing status.
- `drawNonOC` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): The new value for the non-OC drawing status, `true` or `false`.

**Returns:** `void`

**See also:** [`PDOCContextGetNonOCDrawing`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetNonOCDrawing), [`PDOCContextGetOCDrawEnumType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCDrawEnumType)

#### PDOCContextSetOCDrawEnumType

```cpp
void PDOCContextSetOCDrawEnumType(PDOCContext ocContext, PDOCDrawEnumType dt)
```

Header: `PDProcs.h:9728`

Sets the drawing and enumeration type for an optional-content context. This type, together with the visibility determined by the OCG and OCMD states, controls whether content that is marked as optional content is drawn or enumerated. Together, this value and the NonOCDrawing value of the context determine how both optional and non-optional content on a page is drawn or enumerated. See PDOCDrawEnumType().

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the drawing and enumeration type is desired.
- `dt` ([`PDOCDrawEnumType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCDrawEnumType)): The new drawing and enumeration type.

**Returns:** `void`

**See also:** [`PDOCContextGetOCDrawEnumType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCDrawEnumType), [`PDOCContextSetNonOCDrawing`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetNonOCDrawing)

#### PDOCContextSetOCGStates

```cpp
void PDOCContextSetOCGStates(PDOCContext ocContext, PDOCG *pdocgs, ASBool *newStates)
```

Header: `PDProcs.h:9622`

Sets the `ON-OFF` states for the given optional-content groups (OCGs) in the given optional-content context. The `newStates` array must be large enough to hold as many ASBool values as there are OCGs.

**Parameters**

- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the OCG states are set.
- `pdocgs` ([`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): A `NULL`-terminated array of optional-content groups.
- `newStates` ([`ASBool *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): An array of new OCG states corresponding to the array of OCGs, `true` for ON and `false` for `OFF`. The array must contain as many states as there are non-`NULL` OCGs in the `pdocgs` array.

**Returns:** `void`

**See also:** [`PDOCContextGetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCGStates)

#### PDOCContextXObjectIsVisible

```cpp
ASBool PDOCContextXObjectIsVisible(PDOCContext pdOCContext, CosObj obj)
```

Header: `PDProcs.h:9988`

Tests whether an XObject form or image contained in `obj` is visible in the optional-content context. The method considers the context's current OCMD stack, optional-content group `ON-OFF` states, the non-OC drawing status, the drawing and enumeration type, the intent, and the specific OCG. Use this method in conjunction with the OCMD stack methods.

**Parameters**

- `pdOCContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which to test visibility.
- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The external object.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the external object is visible, `false` otherwise.

**See also:** [`PDOCContextContentIsVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextContentIsVisible), [`PDOCContextPopOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextPopOCMD), [`PDOCContextPushOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextPushOCMD), [`PDOCContextResetOCMDStack`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextResetOCMDStack)

### Typedefs (3)

#### PDOCContextChangeType

```cpp
typedef ASUns8 PDOCContextChangeType
```

Header: `PDExpT.h:5787`

#### PDOCContextInitPolicy

```cpp
typedef ASUns8 PDOCContextInitPolicy
```

Header: `PDExpT.h:5712`

#### PDOCDrawEnumType

```cpp
typedef ASUns8 PDOCDrawEnumType
```

Header: `PDExpT.h:5769`

### Structures (1)

#### PDOCContext

```cpp
typedef struct _t_PDOCContext* PDOCContext
```

Header: `PDExpT.h:5672`

A PDOCContext is an object that keeps track the on/off states of all of the OCGs in a document. There can be more than one PDOCContext object, representing different combinations of OCG states. The PDDoc contains an internal PDOCContext that is used for on-screen drawing and as the default state used for any other drawing or content enumeration. Clients can change the states of OCGs within any PDOCContext. Clients can build (and save in the PDF file) PDOCContext objects with their own combination of OCG states, and issue drawing or enumeration commands using their own PDOCContext instead of the document's internal PDOCContext. All discussion of *visibility* of content is therefore meant to be with respect to the OCG states stored in a specific PDOCContext.

### Enums (3)

#### PDOCContextChangeTypes

Header: `PDExpT.h:5773`

The optional-content group (OCG) state is changing.

**Values**

- `kPDOCGState = 0`: The OCGs' states are changing.
- `kPDOCContextDrawEnumType = 1`: The PDOCContext object's PDDrawEnumType is changing.
- `kPDOCContextNonOCDrawing = 2`: The PDOCContext object's non-optional content drawing is changing.
- `kPDOCContextIntent = 3`: The PDOCContext object's intent is changing.
- `kPDOCContextInit = 4`: The PDOCContext is being reset using PDOCContextInit().
- `kPDOC_LastContextChangeType = kPDOCContextInit`

#### PDOCContextInitPolicies

Header: `PDExpT.h:5702`

PDOCContextInitPolicy is used to specify how to initialize the states of Optional Content Groups (OCGs) when calling PDOCContextNew() or PDOCContextInit().

**Values**

- `kOCCInit_OFF = 0`
- `kOCCInit_ON = 1`
- `kOCCInit_FromOtherContext = 2`
- `kOCCInit_FromConfig = 3`

#### PDOCDrawEnumTypes

Header: `PDExpT.h:5750`

PDOCDrawEnumType controls drawing or enumerating the page with respect to optional content. It is an enumerated type that, together with the `NonOCDrawing` value, controls drawing or enumerating content on a page with optional content: • Content that is marked as optional content is drawn or not drawn according to the PDOCDrawEnumType and the visibility state as determined by the Optional Content Groups (OCGs) and OCMDs. • Content that is not marked as optional content is drawn when `NonOCDrawing` is `true`, and not drawn when `NonOCDrawing` is `false`.

**Values**

- `kPDOC_VisibleOC = 0`: Draw or enumerate optional content that is visible, according to the current state of Optional Content Groups (OCGs) and Optional Content Membership Dictionaries (OCMDs). This is the normal default mode.
- `kPDOC_AllOC = 1`: Draw or enumerate all optional content, regardless of its visibility state. If the context's `NonOCDrawing` is `true`, all contents of document are shown.
- `kPDOC_NoOC = 2`: Draw or enumerate no optional content, regardless of its visibility state. If the context's `NonOCDrawing` is `false`, nothing is drawn, resulting in a blank page.
- `kPDOC_LastDrawEnumType = kPDOC_NoOC`

**See also:** [`PDOCContextGetOCDrawEnumType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCDrawEnumType), [`PDOCContextSetOCDrawEnumType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetOCDrawEnumType), [`PDOCContextGetNonOCDrawing`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetNonOCDrawing), [`PDOCContextSetNonOCDrawing`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetNonOCDrawing)

## PDOCG

### Functions (24)

#### PDOCGCreate

```cpp
PDOCG PDOCGCreate(PDDoc pdDoc, ASConstText name)
```

Header: `PDProcs.h:8805`

Creates a new optional-content group (OCG) object in the document. The order of the groups (as returned by PDDocGetOCGs()) is not guaranteed, and is not the same as the display order (see PDOCConfigGetOCGOrder()).

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the group is used.
- `name` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The name of the optional-content group.

**Returns:** [`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)

The newly created group object.

**See also:** [`PDDocGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCGs), [`PDOCGCreateFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGCreateFromCosObj), [`PDOCGDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGDestroy)

#### PDOCGCreateFromCosObj

```cpp
PDOCG PDOCGCreateFromCosObj(CosObj ocgObj)
```

Header: `PDProcs.h:8817`

Creates a new optional-content group (OCG) object from a Cos object.

**Parameters**

- `ocgObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object.

**Returns:** [`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)

The newly created OCG object.

**See also:** [`PDOCGCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGCreate), [`PDOCGGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetCosObj), [`PDOCGDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGDestroy)

#### PDOCGDestroy

```cpp
void PDOCGDestroy(PDOCG pdocg)
```

Header: `PDProcs.h:8829`

Destroys an optional-content group (OCG) object. This does not delete any content, but deletes the PDOCG object, destroys the corresponding Cos object, and invalidates references from optional-content membership dictionaries (OCMDs).

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.

**Returns:** `void`

**See also:** [`PDOCGCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGCreate), [`PDOCGCreateFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGCreateFromCosObj)

#### PDOCGGetCosObj

```cpp
CosObj PDOCGGetCosObj(PDOCG pdocg)
```

Header: `PDProcs.h:8839`

Gets the Cos object associated with the optional-content group (OCG) object.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The Cos object.

**See also:** [`PDOCGCreateFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGCreateFromCosObj)

#### PDOCGGetCurrentState

```cpp
ASBool PDOCGGetCurrentState(PDOCG pdocg, PDOCContext ocContext)
```

Header: `PDProcs.h:9093`

Gets the current `ON-OFF` state of the optional-content group (OCG) object in a given context.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which to get the group's state.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the state is `ON`, `false` if it is `OFF`.

**See also:** [`PDOCGGetInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetInitialState), [`PDOCGGetUsageEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetUsageEntry), [`PDOCContextGetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCGStates), [`PDOCContextSetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetOCGStates), [`PDOCGSetCurrentState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetCurrentState)

#### PDOCGGetFromCosObj

```cpp
PDOCG PDOCGGetFromCosObj(CosObj obj)
```

Header: `PDProcs.h:8853`

Gets an optional-content group (OCG) object from the associated Cos object. If you call this multiple times for the same PDOCG, it returns the same object.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object.

**Returns:** [`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)

The OCG object.

**See also:** [`PDOCGCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGCreate), [`PDOCGCreateFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGCreateFromCosObj), [`PDOCGGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetCosObj), [`PDOCGDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGDestroy)

#### PDOCGGetInitialState

```cpp
ASBool PDOCGGetInitialState(PDOCG pdocg, PDOCConfig pdOCCfg, ASBool *initState)
```

Header: `PDProcs.h:8928`

Gets a initial state (`ON` or `OFF`) of the optional-content group (OCG) object in a given configuration. If the configuration has a `BaseState` of `Unchanged`, and the OCG is not listed explicitly in its `ON` list or `OFF` list, then the initial state is taken from the OCG's current state in the document's default context, and the method returns `false`.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which to get the group's initial state.
- `initState` ([`ASBool *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): (Filled by the method) The initial state, `true` if the state is `ON`, `false` if it is `OFF`.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the initial state is unambiguously defined in the configuration, `false` otherwise.

**See also:** [`PDOCGGetCurrentState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetCurrentState), [`PDOCGGetUsageEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetUsageEntry), [`PDOCGRemoveInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGRemoveInitialState), [`PDOCGSetInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetInitialState), [`PDOCContextGetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCGStates), [`PDOCContextSetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetOCGStates)

#### PDOCGGetIntent

```cpp
ASAtom * PDOCGGetIntent(PDOCG pdocg)
```

Header: `PDProcs.h:9077`

Gets the intent list for an optional-content group. An intent is an ASAtom value broadly describing the intended use, either `View` or `Design`. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object for which the intent is desired.

**Returns:** [`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

An array containing intent entries (ASAtom objects) terminated by ASAtomNull. The client is responsible for freeing it using ASfree().

**See also:** [`PDOCGSetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetIntent), [`PDOCContextGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetIntent), [`PDOCConfigGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetIntent), [`PDOCGUsedInOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCConfig), [`PDOCGUsedInOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCContext)

#### PDOCGGetLocked

```cpp
ASBool PDOCGGetLocked(PDOCG ocg, PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:11150`

Returns the locked state of an OCG in a given configuration. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

**Parameters**

- `ocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): IN The PDOCG whose locked state is requested.
- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): IN The optional-content configuration.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

An ASBool that is `true` if the OCG is locked, and `false` if it is unlocked.

**See also:** [`PDOCGSetLocked`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetLocked), [`PDOCConfigGetLockedArray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetLockedArray), [`PDOCConfigSetLockedArray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetLockedArray)

#### PDOCGGetName

```cpp
ASText PDOCGGetName(PDOCG pdocg)
```

Header: `PDProcs.h:8886`

Gets the name of an optional-content group. The returned ASText is a copy of the OCG's name. The client is free to modify it and responsible for destroying it.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object for which the name is desired.

**Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)

The name string.

**See also:** [`PDOCGSetName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetName)

#### PDOCGGetPDDoc

```cpp
PDDoc PDOCGGetPDDoc(PDOCG pdocg)
```

Header: `PDProcs.h:8865`

Gets the document that contains an optional-content group.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object for which the document is desired.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

The document object.

**See also:** [`PDDocGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCGs), [`PDOCMDGetPDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDGetPDDoc)

#### PDOCGGetUsageEntry

```cpp
CosObj PDOCGGetUsageEntry(PDOCG pdocg, ASAtom entry)
```

Header: `PDProcs.h:9028`

Gets usage information from an optional-content group (OCG) object. A Usage dictionary entry provides more specific intended usage information than an intent entry. The possible key values are: `CreatorInfo` `Language` `Export` `Zoom` `Print` `View` `User` `PageElement`

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `entry` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The usage key in the usage dictionary entry.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The usage information associated with the given key in the Usage dictionary for the group, or a `NULL` Cos object if the operation fails (because the OCG is malformed or has no dictionary, or because the dictionary has no entry corresponding to the given key).

**See also:** [`PDOCGHasUsageInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGHasUsageInfo), [`PDOCGSetUsageDictEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetUsageDictEntry)

#### PDOCGGetUserOverride

```cpp
ASBool PDOCGGetUserOverride(PDOCG ocg, PDOCContext ctx)
```

Header: `PDProcs.h:10431`

Tests whether the optional-content group is marked as having had its state set directly by client code in the specified context (as opposed to automatically by the optional-content AutoState mechanism). When a group is so marked, automatic state changes caused by the `View` event are prevented. When a group's automatic state change is caused by the `Export` or `Print` event, the user-override setting for the group is ignored. A configuration's AS array defines how usage entries are used to automatically manipulate the OCG states. It associates an event (`View`, `Print`, or `Export`) with a list of OCGs and a category, or list of usage keys identifying OCG usage dictionary entries. @since

**Parameters**

- `ocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `ctx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the group is tested.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

**See also:** [`PDOCGSetUserOverride`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetUserOverride), [`PDOCContextClearAllUserOverrides`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextClearAllUserOverrides), [`PDOCContextFindAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextFindAutoStateChanges), [`PDOCContextApplyAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextApplyAutoStateChanges), [`PDOCContextMakeCopyWithAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextMakeCopyWithAutoStateChanges)

#### PDOCGHasUsageInfo

```cpp
ASBool PDOCGHasUsageInfo(PDOCG pdocg)
```

Header: `PDProcs.h:8998`

Tests whether an optional-content group (OCG) object is associated with a Usage dictionary.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the group has a Usage dictionary, `false` otherwise.

**See also:** [`PDOCGGetUsageEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetUsageEntry), [`PDOCGSetUsageDictEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetUsageDictEntry)

#### PDOCGRemoveInitialState

```cpp
void PDOCGRemoveInitialState(PDOCG pdocg, PDOCConfig pdOCCfg)
```

Header: `PDProcs.h:8945`

Removes the initial `ON-OFF` state information for the optional-content group (OCG) object in a given configuration.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which to remove the group's initial state.

**Returns:** `void`

**See also:** [`PDOCGGetCurrentState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetCurrentState), [`PDOCGGetInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetInitialState), [`PDOCGGetUsageEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetUsageEntry), [`PDOCContextGetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCGStates), [`PDOCContextSetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetOCGStates), [`PDOCGSetCurrentState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetCurrentState), [`PDOCGSetInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetInitialState)

#### PDOCGSetCurrentState

```cpp
void PDOCGSetCurrentState(PDOCG pdocg, PDOCContext ocContext, ASBool newState)
```

Header: `PDProcs.h:9111`

Sets the current `ON-OFF` state of the optional-content group (OCG) object in a given context.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which to set the group's state.
- `newState` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): The new state.

**Returns:** `void`

**See also:** [`PDOCContextGetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCGStates), [`PDOCContextSetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetOCGStates), [`PDOCGGetCurrentState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetCurrentState), [`PDOCGGetInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetInitialState), [`PDDocGetOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCContext), [`PDOCGRemoveInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGRemoveInitialState), [`PDOCGSetInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetInitialState)

#### PDOCGSetInitialState

```cpp
void PDOCGSetInitialState(PDOCG pdocg, PDOCConfig pdOCCfg, ASBool onOff)
```

Header: `PDProcs.h:8904`

Sets the initial state (`ON` or `OFF`) of the optional-content group (OCG) object in a given configuration.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The configuration for which to set the group's initial state.
- `onOff` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): The new initial state, `true` if the state is `ON`, `false` if it is `OFF`.

**Returns:** `void`

**See also:** [`PDOCContextGetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetOCGStates), [`PDOCContextSetOCGStates`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetOCGStates), [`PDOCGGetCurrentState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetCurrentState), [`PDOCGGetInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetInitialState), [`PDOCGRemoveInitialState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGRemoveInitialState), [`PDOCGSetCurrentState`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGSetCurrentState)

#### PDOCGSetIntent

```cpp
void PDOCGSetIntent(PDOCG pdocg, ASAtom *intent)
```

Header: `PDProcs.h:9052`

Sets the Intent entry in an optional-content group's Cos dictionary. An intent is an ASAtom value broadly describing the intended use, which can be either `View` or `Design`. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object for which the intent is desired.
- `intent` ([`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The new Intent entry value, an array of atoms terminated with ASAtomNull.

**Returns:** `void`

**See also:** [`PDOCGGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetIntent), [`PDOCContextSetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextSetIntent), [`PDOCConfigSetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetIntent), [`PDOCGUsedInOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCConfig), [`PDOCGUsedInOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCContext)

#### PDOCGSetLocked

```cpp
void PDOCGSetLocked(PDOCG ocg, PDOCConfig pdOCCfg, ASBool locked)
```

Header: `PDProcs.h:11165`

Sets the locked state of an OCG in a given configuration. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

**Parameters**

- `ocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): IN The PDOCG whose locked state is to be set.
- `pdOCCfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): IN/OUT The optional-content configuration.
- `locked` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): IN An ASBool that is `true` if the OCG should be locked, and `false` if it should be unlocked.

**Returns:** `void`

**See also:** [`PDOCGGetLocked`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetLocked), [`PDOCConfigGetLockedArray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetLockedArray), [`PDOCConfigSetLockedArray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigSetLockedArray)

#### PDOCGSetName

```cpp
void PDOCGSetName(PDOCG pdocg, ASConstText name)
```

Header: `PDProcs.h:8874`

Sets the name of an optional-content group.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `name` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The new name string.

**Returns:** `void`

**See also:** [`PDOCGGetName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetName)

#### PDOCGSetUsageDictEntry

```cpp
void PDOCGSetUsageDictEntry(PDOCG pdocg, ASAtom usagekey, CosObj usageinfo)
```

Header: `PDProcs.h:8986`

Sets a Usage dictionary entry in an optional-content group (OCG) object. The entry associates usage information with an entry key for retrieval. If a dictionary does not exist, the method creates one. A Usage dictionary entry provides more specific intended usage information than an intent entry. The possible key values are: • `CreatorInfo` • `Language` • `Export` • `Zoom` • `Print` • `View` • `User` • `PageElement` The usage value can act as a kind of metadata, describing the sort of things that belong to the group, such as text in French, fine detail on a map, or a watermark. The usage values can also be used by the `AutoState` mechanism to make decisions about what groups should be on and what groups should be off. The `AutoState` mechanism considers the usage information in the OCGs, the AS array of the configuration, and external factors; for example, the language the application is running in, the current zoom level on the page, or if the page is being printed.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `usagekey` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The usage entry key.
- `usageinfo` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The usage information to associate with the key.

**Returns:** `void`

**See also:** [`PDOCGGetUsageEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetUsageEntry), [`PDOCGHasUsageInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGHasUsageInfo)

#### PDOCGSetUserOverride

```cpp
void PDOCGSetUserOverride(PDOCG ocg, PDOCContext ctx, ASBool overridden)
```

Header: `PDProcs.h:10402`

Marks the optional-content group as having had its state set directly by client code in the specified context (as opposed to automatically by the optional-content AutoState mechanism). When a group is so marked, automatic state changes caused by the `View` event are prevented. When a group's automatic state change is caused by the `Export` or `Print` event, the user-override setting for the group is ignored. A configuration's AS array defines how usage entries are used to automatically manipulate the OCG states. It associates an event (`View`, `Print`, or `Export`) with a list of OCGs and a category, or list of usage keys identifying OCG usage dictionary entries. @since

**Parameters**

- `ocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `ctx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context for which the group is marked.
- `overridden` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): `true` to mark the group as having had
  its state set manually, `false` to clear the mark.

**Returns:** `void`

**See also:** [`PDOCGGetUserOverride`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetUserOverride), [`PDOCContextClearAllUserOverrides`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextClearAllUserOverrides), [`PDOCContextFindAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextFindAutoStateChanges), [`PDOCContextApplyAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextApplyAutoStateChanges), [`PDOCContextMakeCopyWithAutoStateChanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextMakeCopyWithAutoStateChanges)

#### PDOCGUsedInOCConfig

```cpp
ASBool PDOCGUsedInOCConfig(PDOCG pdocg, PDOCConfig pdoccfg)
```

Header: `PDProcs.h:9157`

Tests whether an optional-content group (OCG) object is used in a context initialized using the given configuration. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `pdoccfg` ([`PDOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfig)): The optional-content configuration.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the group is taken into consideration when determining the visibility of content, `false` otherwise.

**See also:** [`PDOCConfigGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetIntent), [`PDOCContextGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetIntent), [`PDOCGGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetIntent), [`PDOCGUsedInOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCContext)

#### PDOCGUsedInOCContext

```cpp
ASBool PDOCGUsedInOCContext(PDOCG pdocg, PDOCContext pdocctx)
```

Header: `PDProcs.h:9134`

Tests whether an optional-content group (OCG) object is used in a given context. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

**Parameters**

- `pdocg` ([`PDOCG`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): The optional-content group object.
- `pdocctx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The optional-content context.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the group is taken into consideration when determining the visibility of content, `false` otherwise.

**See also:** [`PDOCConfigGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCConfigGetIntent), [`PDOCContextGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContextGetIntent), [`PDOCGGetIntent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetIntent), [`PDOCGUsedInOCConfig`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGUsedInOCConfig)

### Typedefs (1)

#### PDOCGEnumProc

```cpp
typedef ASBool(*) PDOCGEnumProc(PDOCG ocg, void *clientData)(PDOCG ocg, void *clientData)
```

Header: `PDExpT.h:5845`

A callback used for enumerating optional-content groups (OCGs). Enumeration stops when all OCGs have been enumerated, or when the callback returns `false`.

**See also:** [`PDDocEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCGs), [`PDPageEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumOCGs)

### Structures (1)

#### PDOCG

```cpp
typedef struct _t_PDOCG* PDOCG
```

Header: `PDExpT.h:5654`

A PDOCG represents a named object whose state can be toggled in a user interface to affect changes in visibility of content.

## PDOCMD

### Functions (12)

#### PDOCMDCreate

```cpp
PDOCMD PDOCMDCreate(PDDoc pdDoc, PDOCG *ocgs, PDOCMDVisPolicy policy)
```

Header: `PDProcs.h:9230`

Creates a new optional-content membership dictionary (OCMD) object in the given document for the given groups and visibility policy. To add a group to an existing OCMD, get the current OCG list, modify it, then create a new OCMD with the new list of groups.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the dictionary is used.
- `ocgs` ([`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): A `NULL`-terminated array of optional-content groups (OCGs) to be members of the dictionary.
- `policy` ([`PDOCMDVisPolicy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDVisPolicy)): The visibility policy that determines the visibility of content with respect to the `ON-OFF` state of OCGs listed in the dictionary.

**Returns:** [`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)

The newly created dictionary object, or `NULL` if no groups are supplied.

**See also:** [`PDOCMDFindOrCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDFindOrCreate), [`PDOCMDGetFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDGetFromCosObj)

#### PDOCMDFindOrCreate

```cpp
PDOCMD PDOCMDFindOrCreate(PDDoc pdDoc, PDOCG *ocgs, PDOCMDVisPolicy policy)
```

Header: `PDProcs.h:9264`

Locates an existing optional-content membership dictionary (OCMD) object that references the given groups, and that uses the same visibility policy. If no such dictionary is found, the method creates one. If only one group is supplied, the policy is kOCMDVisibility_AnyOn or kOCMDVisibility_AllOn, and no matching dictionary is found, the method creates an OCMD that directly contains the group without the level of indirection normally introduced by an OCMD. If the indirection is needed to add more groups to the OCMD, use PDOCMDCreate(). To add a group to an existing OCMD, get the current OCG list, modify it, then create a new OCMD with the new list of groups.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the dictionary is used.
- `ocgs` ([`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): A `NULL`-terminated array of optional-content groups (OCGs) to be members of the dictionary.
- `policy` ([`PDOCMDVisPolicy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDVisPolicy)): The visibility policy that determines the visibility of content with respect to the `ON-OFF` state of OCGs listed in the dictionary.

**Returns:** [`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)

The newly created or existing dictionary object, or `NULL` if no groups are supplied.

**See also:** [`PDOCMDCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDCreate), [`PDOCMDGetFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDGetFromCosObj), [`PDAnnotGetOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotGetOCMD), [`PDEElementGetOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDEElementGetOCMD)

#### PDOCMDFindOrCreateEx

```cpp
PDOCMD PDOCMDFindOrCreateEx(PDDoc pdDoc, PDOCG *ocgs, PDOCMDVisPolicy policy, CosObj veObj)
```

Header: `PDProcs.h:11215`

Locates an existing optional-content membership dictionary (PDOCMD) object that references the given groups, uses the same visibility policy, and uses the same visibility expression. If no such PDOCMD is found, the method creates one. The fourth parameter, `veObj` must be a CosNull object or a CosArray object. If it is a CosNull object, this call is identical to PDOCMDFindOrCreate(). If it is an array object, it is used as the OCMD's visibility expression.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The PDDoc in which to create the PDOCMD.
- `ocgs` ([`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)): A list of OCGs, or `NULL` if only a visibility expression is to be used.
- `policy` ([`PDOCMDVisPolicy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDVisPolicy)): The visibility policy to use. unused if `ocgs` is `NULL`.
- `veObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): A CosObj containing a visibility expression.

**Returns:** [`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)

**See also:** [`PDOCMDFindOrCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDFindOrCreate)

#### PDOCMDGetCosObj

```cpp
CosObj PDOCMDGetCosObj(PDOCMD pdocmd)
```

Header: `PDProcs.h:9274`

Gets the Cos object associated with the optional-content membership dictionary (OCMD) object.

**Parameters**

- `pdocmd` ([`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)): The dictionary object.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The Cos object.

**See also:** [`PDOCMDGetFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDGetFromCosObj)

#### PDOCMDGetFromCosObj

```cpp
PDOCMD PDOCMDGetFromCosObj(CosObj obj)
```

Header: `PDProcs.h:9297`

Gets an optional-content membership dictionary (OCMD) object from the associated Cos object.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object.

**Returns:** [`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)

The dictionary object.

**See also:** [`PDOCMDCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDCreate), [`PDOCMDGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDGetCosObj)

#### PDOCMDGetOCGs

```cpp
PDOCG * PDOCMDGetOCGs(PDOCMD pdocmd)
```

Header: `PDProcs.h:9309`

Gets the optional-content groups listed in a membership dictionary.

**Parameters**

- `pdocmd` ([`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)): The membership dictionary whose OCGs are obtained.

**Returns:** [`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)

A `NULL`-terminated array of the document's optional-content groups. The client is responsible for freeing the array using ASfree().

#### PDOCMDGetPDDoc

```cpp
PDDoc PDOCMDGetPDDoc(PDOCMD pdocmd)
```

Header: `PDProcs.h:9286`

Gets the document that contains an optional-content membership dictionary.

**Parameters**

- `pdocmd` ([`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)): The dictionary for which the document is desired.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

The document object.

**See also:** [`PDDocGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCGs), [`PDOCGGetPDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGGetPDDoc)

#### PDOCMDGetVisPolicy

```cpp
PDOCMDVisPolicy PDOCMDGetVisPolicy(PDOCMD pdocmd)
```

Header: `PDProcs.h:9322`

Gets the optional-content membership dictionary's visibility policy, which determines the visibility of content with respect to the `ON-OFF` state of OCGs listed in the dictionary.

**Parameters**

- `pdocmd` ([`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)): The dictionary whose policy is obtained.

**Returns:** [`PDOCMDVisPolicy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDVisPolicy)

The visibility policy.

**See also:** [`PDOCMDIsCurrentlyVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDIsCurrentlyVisible), [`PDOCMDsAreCurrentlyVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDsAreCurrentlyVisible)

#### PDOCMDGetVisibilityExpression

```cpp
ASBool PDOCMDGetVisibilityExpression(PDOCMD ocmd, CosObj *veObj)
```

Header: `PDProcs.h:11229`

If the PDOCMD has a visibility expression entry, the function returns `true`, and if `veObj` is non-`NULL`, `*veObj` is set to the CosObj for the visibility expression. If the PDOCMD does not have a visibility expression entry, the function returns `false`.

**Parameters**

- `ocmd` ([`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)): The PDOCMD in which to check for a visibility expression.
- `veObj` ([`CosObj *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The cos object in which to return the visibility expression.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if there is a visibility expression, `false` otherwise.

**See also:** [`PDOCMDFindOrCreateEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDFindOrCreateEx)

#### PDOCMDIsCurrentlyVisible

```cpp
ASBool PDOCMDIsCurrentlyVisible(PDOCMD pdocmd, PDOCContext ocContext)
```

Header: `PDProcs.h:9382`

Based on the optional-content groups listed in the dictionary, the current `ON-OFF` state of those groups within the specified context, and the dictionary's visibility policy, test whether the content tagged with this dictionary would be visible. It ignores the context's current PDOCDrawEnumType and NonOCDrawing settings.

**Parameters**

- `pdocmd` ([`PDOCMD`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)): The dictionary.
- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context in which the visibility of content is tested.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if content tagged with this dictionary is visible in the given context, `false` if it is hidden.

**See also:** [`PDOCMDGetVisPolicy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDGetVisPolicy), [`PDOCMDsAreCurrentlyVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDsAreCurrentlyVisible)

#### PDOCMDsAreCurrentlyVisible

```cpp
ASBool PDOCMDsAreCurrentlyVisible(PDOCMD *pdocmds, PDOCContext ocContext)
```

Header: `PDProcs.h:9401`

Tests a set of optional-content membership dictionaries to determine whether contents tagged with any of them is visible in a given optional-content context. The method calls PDOCMDIsCurrentlyVisible() on each of the dictionaries. If content is visible in the given context in any of the dictionaries, this method returns `true`.

**Parameters**

- `pdocmds` ([`PDOCMD *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)): A `NULL`-terminated array of dictionaries to test.
- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context in which visibility is tested.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if content using any of the dictionaries is visible in the given context, `false` if it is hidden for all of the dictionaries.

**See also:** [`PDOCMDGetVisPolicy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDGetVisPolicy), [`PDOCMDIsCurrentlyVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDIsCurrentlyVisible)

#### PDOCMDsMakeContentVisible

```cpp
ASBool PDOCMDsMakeContentVisible(PDOCMD *ocmds, PDOCContext ocContext)
```

Header: `PDProcs.h:9449`

Makes content that uses any of a set of optional-content membership dictionaries visible in a given optional-content context. The method manipulates the states of optional-content groups in the dictionaries so that any content controlled by any of the dictionaries will be visible in the given context. There can be more than one combination of states that satisfies the request. The particular combination of states is not guaranteed from one call to the next. The method returns `false` if it is not possible to make the content visible (for example, if there are nested dictionaries where one specifies `"show if the group state is ON"` and the other specifies `"show if the group state is OFF"`). In such a case, visibility is always off, so no state setting can make the content visible. This method ignores the context's draw type.

**Parameters**

- `ocmds` ([`PDOCMD *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMD)): A `NULL`-terminated array of dictionaries to act upon.
- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context in which the contents are made visible.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if successful or if the OCMD list is empty, `false` otherwise.

**See also:** [`PDOCMDGetVisPolicy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDGetVisPolicy), [`PDOCMDIsCurrentlyVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCMDIsCurrentlyVisible)

### Typedefs (1)

#### PDOCMDVisPolicy

```cpp
typedef ASUns8 PDOCMDVisPolicy
```

Header: `PDExpT.h:5697`

### Structures (1)

#### PDOCMD

```cpp
typedef struct _t_PDOCMD* PDOCMD
```

Header: `PDExpT.h:5659`

A PDOCMD is an object that is attached to content to indicate membership in an OCG or group of OCGs.

### Enums (1)

#### PDOCMDVisPolicies

Header: `PDExpT.h:5687`

PDOCMDVisPolicy represents the four legal values for the /P key in an Optional Content Membership Dictionary (OCMD) dictionary. They specify the visibility of content with respect to the on/off state of the Optional Content Groups (OCGs) listed in the OCMD.

**Values**

- `kOCMDVisibility_AllOn = 0`
- `kOCMDVisibility_AnyOn = 1`
- `kOCMDVisibility_AnyOff = 2`
- `kOCMDVisibility_AllOff = 3`

## PDPage

### Functions (72)

#### PDPageAcquirePDEContent

```cpp
PDEContent PDPageAcquirePDEContent(IN PDPage pdPage, IN ASExtension self)
```

Header: `PgCntProcs.h:50`

Creates a PDEContent from the PDPage object's contents and resources. The PDEContent is cached, so that subsequent calls on the same PDPage return the same PDEContent, even if the request is from another PDFEdit client. The PDEContent remains in the cache as long as someone has it acquired - until someone not using the PDFEdit API changes the PDPage object's contents, such as the viewer rotating a page 90 degrees. Requires ‘Export’ permission on PDDoc. Do not call PDERelease() on PDEContent you have acquired with PDPageAcquirePDEContent(); call PDPageReleasePDEContent() to release it.

**Parameters**

- `pdPage` (`IN PDPage`): The page whose content object is acquired.
- `self` (`IN ASExtension`): Identifies the caller or client. For plug-ins, this should be the gExtensionID extension. For the Adobe PDF Library, if there is only one client of the PDFEdit subsystem, this should be zero. If there are multiple clients, each should specify a nonzero, non-negative value. (A negative value is reserved for the implementation.)

**Returns:** [`PDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDEContent)

A PDEContent representing the page's contents.

**See also:** [`PDEContentCreateFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDEContentCreateFromCosObj), [`PDPageReleasePDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageReleasePDEContent), [`PDPageSetPDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetPDEContent)

#### PDPageAcquirePage

```cpp
void PDPageAcquirePage(PDPage pdPage)
```

Header: `PDProcs.h:11135`

Increments the page's reference count. After you are done using the page, release it using PDPageRelease(). If PDPageRelease() is not called, it could block the document containing the page from being closed. To avoid such problems use the CSmartPDPage class as it ensures that the page is released as it goes out of scope.

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN The page whose reference count is to be incremented.

**Returns:** `void`

**See also:** `CSmartPDPage`, [`PDPageRelease`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRelease)

**Since:** `0 .`

#### PDPageAddAnnot

```cpp
void PDPageAddAnnot(PDPage aPage, ASInt32 addAfter, PDAnnot annot)
```

Header: `PDProcs.h:3412`

Adds an annotation at the specified location in a page's annotation array. You can find this document on the web store of the International Standards Organization (ISO). The first annotation in the array has an index of zero. Passing a value of `-2` adds the annotation to the end of the array. Passing other negative values produces undefined results.

**Parameters**

- `aPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to which the annotation is added.
- `addAfter` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The index into the page's annotation array where the annotation is added. See the description of Annotations in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.5, page 381.
- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation to add.

**Returns:** `void`

**Exceptions**

- `pdErrOpNotPermitted`: is raised if:

  • The annotation is of subtype Text and the document's permissions do not include pdPermEditNotes (see PDPerms).

  • The annotation is of any other subtype and the document's permissions do not include pdPermEdit.

  @notify PDPageWillAddAnnot @notify PDPageDidAddAnnot

**See also:** [`PDPageCreateAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageCreateAnnot), [`PDPageAddNewAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddNewAnnot), [`PDPageRemoveAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveAnnot)

#### PDPageAddCosContents

```cpp
void PDPageAddCosContents(PDPage page, CosObj newContents)
```

Header: `PDProcs.h:3541`

Completely replaces the contents of the specified page with `newContents`.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose Cos contents are replaced.
- `newContents` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT A stream Cos object or an array Cos object containing the new contents (stream Cos objects) for `page`. @notify PDDocDidChangePages

**Returns:** `void`

**See also:** [`PDPageRemoveCosContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveCosContents)

#### PDPageAddCosResource

```cpp
void PDPageAddCosResource(PDPage page, const char *resType, const char *resName, CosObj resObj)
```

Header: `PDProcs.h:3527`

Adds a Cos resource to a page object. See the description of Resource Dictionaries in ISO 32000-1:2008, Document Management- Portable Document Format-Part 1: PDF 1.7, section 7.8.3, page 82. You can find this document on the web store of the International Standards Organization (ISO). The necessary dictionaries are created automatically if the page does not already have any resources of the type specified by `resType`, or does not have a Resources dictionary. For example, if you specify a font resource, but the page does not already have a font resource dictionary, this method automatically creates one and puts the font you specify into it. ProcSet resources cannot be added using this method; they must be added using Cos-level methods to: • Get the page's Resources dictionary. • Get the ProcSet array from the Resources dictionary. • Add an element to the ProcSet array.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to which a resource is added.
- `resType` (`const char *`): The resource type. The named resource types in PDF are: ExtGState, ColorSpace, Pattern, Shading, XObject, Font, and Properties. Although ProcSet is also a valid resource type, it cannot be added by this method.
- `resName` (`const char *`): The resource name (for example, the name of a font might be `F1`).
- `resObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object being added as a resource to page. @notify PDDocDidChangePages

**Returns:** `void`

**See also:** [`PDPageRemoveCosResource`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveCosResource), [`PDPageGetCosResources`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetCosResources)

#### PDPageAddNewAnnot

```cpp
PDAnnot PDPageAddNewAnnot(PDPage aPage, ASInt32 addAfter, ASAtom subType, const ASFixedRect *initialRect)
```

Header: `PDProcs.h:3381`

Adds an annotation to the page. To make the annotation visible after adding it, convert the coordinates of `initialRect` to device coordinates using AVPageViewRectToDevice(), then call AVPageViewInvalidateRect() using the converted rectangle. This method is equivalent to calling PDPageCreateAnnot() followed by PDPageAddAnnot(). The PDPageWillAddAnnot() and PDPageDidAddAnnot() notifications are broadcast before the PDPageAddNewAnnot() method returns. If you want to finish formatting the annotation before these notifications are called, for example, by adding additional key-value pairs to the annotation dictionary, you should call PDPageCreateAnnot() followed by PDPageAddAnnot() instead of PDPageAddNewAnnot(). You can find this document on the web store of the International Standards Organization (ISO). Passing a value of `-2` adds the annotation to the end of the array (this is generally what you should do unless you have a need to place the annotation at a special location in the array). Passing a value of `-1` adds the annotation to the beginning of the array. Passing other negative values produces undefined results. • The annotation is of subtype Text and the document's permissions do not include pdPermEditNotes (see PDPerms). • The annotation is of any other subtype and the document's permissions do not include pdPermEdit. @notify PDPageWillAddAnnot @notify PDPageDidAddAnnot

**Parameters**

- `aPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to which the annotation is added.
- `addAfter` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): Where to add the annotation in the page's annotation array. See the description of Annotations in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.5, page 381.
- `subType` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The subtype of the annotation to add.
- `initialRect` (`const ASFixedRect *`): A pointer to a rectangle specifying the annotation's bounds, specified in user space coordinates.

**Returns:** [`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)

The newly created annotation.

**Exceptions**

- `pdErrOpNotPermitted`: is raised if:

**See also:** [`PDPageCreateAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageCreateAnnot), [`PDPageAddAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddAnnot), [`PDPageRemoveAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveAnnot)

#### PDPageCreateAnnot

```cpp
PDAnnot PDPageCreateAnnot(PDPage aPage, ASAtom subType, const ASFixedRect *initialLocation)
```

Header: `PDProcs.h:312`

Creates a new annotation, associated with the specified page's CosDoc, but not added to the page. Use PDPageAddAnnot() to add the annotation to the page. If you want to create an annotation that prints even if the annotation handler is not present, you must provide an appearance for it. To do this, add an appearance key (AP) to the annotation dictionary, in which you place the Forms XObject for the Normal (N), Rollover (R), and Down (D) appearances; only the Normal appearance is required. Also, add a flags field (F) to the annotation dictionary and set the appropriate value for the bit field. A value of `4`, which displays the annotation if the handler is not present, shows the annotation, and allows printing it, is recommended. @notify PDAnnotWasCreated

**Parameters**

- `aPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to whose PDDoc the annotation is added.
- `subType` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The subtype of annotation to create.
- `initialLocation` (`const ASFixedRect *`): A pointer to a rectangle specifying the annotation's bounds, specified in user space coordinates.

**Returns:** [`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)

The newly created annotation.

**Exceptions**

- `pdErrOpNotPermitted`: is raised if:

  • The annotation is of subtype Text and the document's permissions do not include pdPermEditNotes (see PDPerms), or

  • The annotation is of any other subtype and the document's permissions do not include pdPermEdit.

**See also:** [`PDPageAddAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddAnnot), [`PDPageAddNewAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddNewAnnot)

#### PDPageDrawContentsToWindow

```cpp
void PDPageDrawContentsToWindow(PDPage page, void *window, void *displayContext, ASBool isDPS, ASFixedMatrix *matrix, ASFixedRect *updateRect, CancelProc cancelProc, void *cancelProcClientData)
```

Header: `PDProcs.h:3314`

Draws the contents of a page into the specified window. This method just draws a bitmap to the window. If you want a live document, you need to open an AVDoc for the PDF file. The page can also be derived from a PDDoc. On UNIX, this method cannot be used to draw into a window. UNIX developers should instead use AVDocOpenFromASFileWithParamString() to draw PDF files into their own window from a client. **Note:** This method cannot be reliably used to print to a device. **Note:** Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to draw into `window`.
- `window` (`void *`): A pointer to a platform-dependent window object (`HWND` on Windows, or `WindowPtr`). On Windows, to draw into an offscreen `DC`, pass `NULL` for `window`.
- `displayContext` (`void *`): A platform-dependent display context structure (`HDC` on Windows). Note that `displayContext` cannot be reliably used as the `hDC` for a printer device.
- `isDPS` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Currently unused. Always set it to `false`.
- `matrix` (`ASFixedMatrix *`): A pointer to the matrix to concatenate onto the default page matrix. It is useful for converting from page to window coordinates and for scaling.
- `updateRect` (`ASFixedRect *`): A pointer to the rectangle to draw, defined in user space coordinates. Any objects outside of `updateRect` will not be drawn. All objects are drawn if `updateRect` is `NULL`.
- `cancelProc` ([`CancelProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#CancelProc)): The procedure called periodically to check for the user's cancelling of the drawing operation. The default cancel proc can be obtained using AVAppGetCancelProc(). It may be `NULL`, in which case no cancel proc is used.
- `cancelProcClientData` (`void *`): A pointer to user-supplied data to pass to `cancelProc` each time it is called. It should be `NULL` if `cancelProc` is `NULL`.

**Returns:** `void`

**See also:** `AVAppGetCancelProc`, [`PDDrawCosObjToWindow`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDrawCosObjToWindow), [`PDPageDrawContentsToWindowEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageDrawContentsToWindowEx)

#### PDPageDrawContentsToWindowEx

```cpp
void PDPageDrawContentsToWindowEx(PDPage page, void *window, void *displayContext, ASBool isDPS, ASFixedMatrix *matrix, ASUns32 flags, ASFixedRect *updateRect, CancelProc cancelProc, void *cancelProcClientData)
```

Header: `PDProcs.h:8045`

Provides control over the rendering of annotations on the page to be drawn into `window`. It provides the ability to specify the flags passed in to the PDPageDrawContentsToWindows() function. **Note:** This function can only be called with a flags value of `0`. The function is not supported with any other values for `flags`. `flags = 0` means do not render the annotation faces. If you want to draw to a window with annotations, you should call the original PDPageDrawContentsToWindow(). In general, Adobe recommends that you not use PDPageDrawContentsToWindowsEx() unless you have a specific need to prevent the drawing of annotations. **Note:** Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to draw into `window`.
- `window` (`void *`): A pointer to a platform-dependent window object (`HWND` on Windows, or `WindowPtr`). On Windows, to draw into an offscreen `DC`, pass `NULL` for `window`.
- `displayContext` (`void *`): A platform-dependent display context structure (`HDC` on Windows). Note that `displayContext` cannot be reliably used as the `hDC` for a printer device.
- `isDPS` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Currently unused. Always set it to `false`.
- `matrix` (`ASFixedMatrix *`): A pointer to the matrix to concatenate onto the default page matrix. It is useful for converting from page to window coordinates and for scaling.
- `flags` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): See PDPageDrawFlagsPI for possible values.
- `updateRect` (`ASFixedRect *`): A rectangle represented by the coordinates of its four sides.
- `cancelProc` ([`CancelProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#CancelProc)): A procedure called periodically to check for the user's cancelling of the drawing operation. The default cancel procedure can be obtained using AVAppGetCancelProc(). It may be `NULL` in which case no cancel procedure is used.
- `cancelProcClientData` (`void *`): A pointer to user-supplied data to pass to `cancelProc` each time it is called. It should be `NULL` if `cancelProc` is `NULL`.

**Returns:** `void`

**Exceptions**

- `pdPErrUnableToCreateRasterPort`

**See also:** `AVAppGetCancelProc`, [`PDDrawCosObjToWindow`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDrawCosObjToWindow), [`PDPageDrawContentsToWindow`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageDrawContentsToWindow)

#### PDPageDrawContentsToWindowEx2

```cpp
void PDPageDrawContentsToWindowEx2(PDPage page, void *window, void *displayContext, ASBool isDPS, ASDoubleMatrix *matrix, ASCab flags, ASDoubleRect *updateRect, ASCancelProc cancelProc, void *cancelProcClientData)
```

Header: `PDProcs.h:12780`

Draws the contents of a page into the specified window. This method just draws a bitmap to the window. If you want a live document, you need to open an AVDoc for the PDF file. The page can also be derived from a PDDoc. On UNIX, this method cannot be used to draw into a window. UNIX developers should instead use AVDocOpenFromASFileWithParamString() to draw PDF files into their own window from a client. **Note:** This method cannot be reliably used to print to a device. **Note:** Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to draw into `window`.
- `window` (`void *`): A pointer to a platform-dependent window object (`HWND` on Windows, or `WindowPtr`). On Windows, to draw into an offscreen `DC`, pass `NULL` for `window`.
- `displayContext` (`void *`): A platform-dependent display context structure (`HDC` on Windows). Note that `displayContext` cannot be reliably used as the `hDC` for a printer device.
- `isDPS` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Currently unused. Always set it to `false`.
- `matrix` (`ASDoubleMatrix *`): A pointer to the matrix to concatenate onto the default page matrix. It is useful for converting from page to window coordinates and for scaling.
- `flags` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): See PDPageDrawFlagsPI for possible values.
- `updateRect` (`ASDoubleRect *`): A pointer to the rectangle to draw, defined in user space coordinates. Any objects outside of `updateRect` will not be drawn. All objects are drawn if `updateRect` is `NULL`.
- `cancelProc` ([`ASCancelProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCancelProc)): The procedure called periodically to check for the user's cancelling of the drawing operation. The default cancel proc can be obtained using AVAppGetCancelProc(). It may be `NULL`, in which case no cancel proc is used.
- `cancelProcClientData` (`void *`): A pointer to user-supplied data to pass to `cancelProc` each time it is called. It should be `NULL` if `cancelProc` is `NULL`.

**Returns:** `void`

**See also:** `AVAppGetCancelProc`, [`PDDrawCosObjToWindow`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDrawCosObjToWindow), [`PDPageDrawContentsToWindowEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageDrawContentsToWindowEx)

#### PDPageDrawContentsWithParams

```cpp
void PDPageDrawContentsWithParams(PDPage page, PDDrawParams params)
```

Header: `PDProcs.h:10514`

Provides control over the rendering of contents on the page, including both those parameters you would pass to PDPageDrawContentsToWindowEx(), and an optional-content context that determines which contents are visible. **Note:** Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to draw.
- `params` (`PDDrawParams`): The parameters with which to draw the page, including the optional-content context to use for content visibility.

**Returns:** `void`

**Exceptions**

- `pdPErrUnableToCreateRasterPort`

**See also:** [`PDPageDrawContentsToWindow`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageDrawContentsToWindow), [`PDPageDrawContentsToWindowEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageDrawContentsToWindowEx)

#### PDPageEnumContents

```cpp
void PDPageEnumContents(PDPage page, PDGraphicEnumMonitor mon, void *clientData)
```

Header: `PDProcs.h:3619`

Enumerates the contents of a page, calling a procedure for each drawing object in the page description. **Note:** This method is provided only for backwards compatibility. It has not been updated beyond PDF Version 1.1 and may not work correctly for newly created PDF 1.2 or later files. You should use the PDFEdit API to enumerate page contents.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose contents are enumerated.
- `mon` ([`PDGraphicEnumMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGraphicEnumMonitor)): IN/OUT A pointer to a structure containing user-supplied callbacks that are called for each drawing operator on a page. Enumeration ends if any procedure returns `false`.
- `clientData` (`void *`): IN/OUT A pointer to user-supplied data to pass to `mon` each time it is called.

**Returns:** `void`

#### PDPageEnumInks

```cpp
void PDPageEnumInks(PDPage pdPage, PDPageEnumInksCallback proc, void *clientData, ASBool includeOPI)
```

Header: `PDProcs.h:8322`

Enumerates the inks for a page, calling the supplied procedure for each PDPageInk structure. For the DeviceCMYK_K process color model, it always finds the four inks Cyan, Magenta, Yellow, and Black, which are marked as process inks. The RGB values in the PDPageInk structure are the RGB equivalents (in system monitor space) of 100% of the ink, which can be used to show color swatches for a given ink. If the inks are part of a DeviceN colorspace which has not been defined in a Colorants dictionary or elsewhere in a Separation colorspace, the color of the swatch is undefined. This call finds all color spaces that are in a color space dictionary within the page, even if they are not used by the page contents.

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose contents are enumerated.
- `proc` ([`PDPageEnumInksCallback`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumInksCallback)): The user-supplied callback procedure to be applied to each ink. Enumeration ends if any procedure returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `proc` each time it is called.
- `includeOPI` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, enumerate inks contained in OPI dictionaries.

**Returns:** `void`

**See also:** [`PDPageMakeSeparations`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageMakeSeparations), `AVPageViewGetNumVisibleInks`, `AVPageViewGetVisibleInks`, `AVPageViewGetPixelInformationAtPoint`, `AVPageViewSetInkPreview`, `AVPageViewSetVisibleInks`

#### PDPageEnumInksEx

```cpp
void PDPageEnumInksEx(PDPage pdPage, PDPageEnumInksCallback proc, void *clientData, ASBool includeOPI, ASAtom colorModel)
```

Header: `PDProcs.h:11305`

Enumerates the inks for a page, calling the supplied procedure for each PDPageInk structure. This differs from PDPageEnumInks() in that it allows the process color model to be passed in. For the DeviceCMYK_K process color model, it always finds the four inks Cyan, Magenta, Yellow, and Black, which are marked as process inks. The RGB values in the PDPageInk structure are the RGB equivalents (in system monitor space) of 100% of the ink, which can be used to show color swatches for a given ink. If the inks are part of a DeviceN color space which has not been defined in a Colorants dictionary or elsewhere in a Separation color space, the color of the swatch is undefined. This call finds all color spaces that are in a color space dictionary within the page, even if they are not used by the page contents.

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose contents are enumerated.
- `proc` ([`PDPageEnumInksCallback`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumInksCallback)): The user-supplied callback procedure to be applied to each ink. Enumeration ends if any procedure returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `proc` each time it is called.
- `includeOPI` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, enumerate inks contained in OPI dictionaries.
- `colorModel` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): `CMYK_K`, `RGB_K`, or `Gray_K`.

**Returns:** `void`

**See also:** [`PDPageMakeSeparations`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageMakeSeparations), `AVPageViewGetNumVisibleInks`, `AVPageViewGetVisibleInks`, `AVPageViewGetPixelInformationAtPoint`, `AVPageViewSetInkPreview`, `AVPageViewSetVisibleInks`

#### PDPageEnumOCGs

```cpp
void PDPageEnumOCGs(PDPage pdPage, PDOCGEnumProc enumProc, void *clientData)
```

Header: `PDProcs.h:9174`

Enumerates the optional-content groups for the page, calling the supplied procedure for each one. Enumeration continues until all groups have been enumerated, or until `enumProc` returns `false`. Each group is reported once, even if it is referenced multiple times in the page.

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose groups are enumerated.
- `enumProc` ([`PDOCGEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCGEnumProc)): A user-supplied callback to call for each group. Enumeration terminates if `proc` returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `enumProc` each time it is called.

**Returns:** `void`

**See also:** [`PDDocEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCGs), [`PDPageGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetOCGs)

#### PDPageEnumResources

```cpp
void PDPageEnumResources(PDPage page, PDResourceEnumMonitor mon, void *clientData)
```

Header: `PDProcs.h:3599`

(Obsolete, provided only for backwards compatibility) Enumerates the page's resources, calling an enumeration procedure for each resource. Instead of this method, use PDDocEnumOCGs(). **Note:** This method is provided only for backwards compatibility. It has not been updated beyond PDF Version 1.1 and may not work correctly for newly created PDF 1.2 or later files.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose Cos resources are enumerated.
- `mon` ([`PDResourceEnumMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDResourceEnumMonitor)): A pointer to a structure containing user-supplied callbacks that are called for each of the page's resources. Enumeration ends if any procedure returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to each procedure in `mon` when it is called.

**Returns:** `void`

**See also:** [`PDDocEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCGs), [`PDPageGetCosResources`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetCosResources)

#### PDPageFlattenOC

```cpp
ASBool PDPageFlattenOC(PDPage pdPage, PDOCContext context)
```

Header: `PDProcs.h:10477`

Replaces the page's contents with a version that has no optional content, containing only what was visible on the page when the call was made.

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to be modified.
- `context` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The optional-content context in which content is checked for visibility.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the operation is successful, `false` otherwise.

**See also:** [`PDDocFlattenOC`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocFlattenOC), [`PDEContentFlattenOC`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDEContentFlattenOC)

#### PDPageGetAnnot

```cpp
PDAnnot PDPageGetAnnot(PDPage aPage, ASInt32 annotIndex)
```

Header: `PDProcs.h:3332`

Gets the `annotIndex` annotation on the page.

**Parameters**

- `aPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page on which the annotation is located.
- `annotIndex` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The index of the annotation to get on a page. The first annotation on a page has an index of zero.

**Returns:** [`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)

The indexed annotation object.

**See also:** [`PDPageGetNumAnnots`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetNumAnnots)

#### PDPageGetAnnotIndex

```cpp
ASInt32 PDPageGetAnnotIndex(PDPage aPage, PDAnnot anAnnot)
```

Header: `PDProcs.h:3457`

Gets the index of a given annotation object on a given page.

**Parameters**

- `aPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page to which the annotation is attached.
- `anAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The annotation whose index is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The annotation's index. It returns `-1` if the annotation is not on the page.

**See also:** [`PDPageGetAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetAnnot), [`PDPageGetAnnotSequence`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetAnnotSequence)

#### PDPageGetAnnotSequence

```cpp
ASInt32 PDPageGetAnnotSequence(PDPage page, PDAnnot annot)
```

Header: `PDProcs.h:6867`

Returns the sequence number of the specified annotation for the given page. It is applicable only to annotations that are listed in Acrobat's Comments pane and therefore cannot be summarized using Summarize command (as would be the case for link and widget annotations, for example). This method is similar to PDPageGetAnnotIndex() but it checks the information flags from the annotation handler's PDAnnotHandlerGetAnnotInfoFlagsProc() to determine whether the PDAnnotOperationSummarize flag is set, meaning that the annotation has a sequence number. **Note:** The sequence number is one-based, while the index returned by PDPageGetAnnotIndex() is zero-based.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page on which the annotation exists.
- `annot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): The annotation for which the sequence number is desired.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The sequence number of the specified annotation; or `-1` if the annotation is not in the page or if it is an annotation that cannot be summarized.

**See also:** [`PDPageGetAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetAnnot), [`PDPageGetAnnotIndex`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetAnnotIndex)

#### PDPageGetBBox

```cpp
void PDPageGetBBox(PDPage page, ASFixedRect *bboxP)
```

Header: `PDProcs.h:3237`

Gets the bounding box for a page. The bounding box is the rectangle that encloses all text, graphics, and images on the page.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose bounding box is obtained.
- `bboxP` (`ASFixedRect *`): (Filled by the method) A pointer to a rectangle specifying the page's bounding box, specified in user space coordinates.

**Returns:** `void`

**See also:** [`PDPageGetMediaBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetMediaBox), [`PDPageGetCropBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetCropBox), [`PDPageGetVisibleBBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetVisibleBBox)

#### PDPageGetBox

```cpp
ASBool PDPageGetBox(PDPage page, ASAtom boxName, ASFixedRect *box)
```

Header: `PDProcs.h:7879`

Returns the box specified for the page object intersected with the media box. If the value for `boxName` is `CropBox`, this call is equivalent to PDPageGetCropBox(); if the value is `MediaBox`, this call is equivalent to PDPageGetMediaBox().

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose box is obtained.
- `boxName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): An ASAtom representing the type of box. It can have values such as `ArtBox`, `BleedBox`, `CropBox`, `TrimBox`, or `MediaBox`.
- `box` (`ASFixedRect *`): (Filled by the method) An `ASFixedRect` specifying the page's box.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the requested box was specified for the page, `false` otherwise.

**See also:** [`PDPageSetBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetBox)

#### PDPageGetCosObj

```cpp
CosObj PDPageGetCosObj(PDPage page)
```

Header: `PDProcs.h:3122`

Gets the dictionary Cos object associated with a page. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The dictionary Cos object associated with page.

#### PDPageGetCosResources

```cpp
CosObj PDPageGetCosResources(PDPage page)
```

Header: `PDProcs.h:3487`

Gets the Cos object corresponding to a page's resource dictionary. A page's resource Cos object may either be directly in the Page Cos object and apply only to the page. Or, it may be in the Pages tree, be shared by multiple pages, and applies to all Page nodes below the point in the Pages tree where it is located.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose Cos resources are obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The dictionary Cos object associated with the page's resource.

**See also:** [`PDPageAddCosResource`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddCosResource)

#### PDPageGetCropBox

```cpp
void PDPageGetCropBox(PDPage page, ASFixedRect *cropBoxP)
```

Header: `PDProcs.h:3206`

Gets the crop box for a page. The crop box is the region of the page to display and print.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose crop box is obtained.
- `cropBoxP` (`ASFixedRect *`): (Filled by the method) A pointer to a rectangle specifying the page's crop box, specified in user space coordinates.

**Returns:** `void`

**See also:** [`PDPageSetCropBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetCropBox), [`PDPageGetMediaBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetMediaBox), [`PDPageGetBBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetBBox)

#### PDPageGetDefaultMatrix

```cpp
void PDPageGetDefaultMatrix(PDPage pdPage, ASFixedMatrix *defaultMatrix)
```

Header: `PDProcs.h:3252`

Gets the matrix that transforms user space coordinates to rotated and cropped coordinates. The origin of this space is the bottom-left of the rotated, cropped page. `Y` is increasing.

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose default transformation matrix is obtained.
- `defaultMatrix` (`ASFixedMatrix *`): (Filled by the method) A pointer to the default transformation matrix.

**Returns:** `void`

**See also:** [`PDPageGetFlippedMatrix`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetFlippedMatrix)

#### PDPageGetDoc

```cpp
PDDoc PDPageGetDoc(PDPage page)
```

Header: `PDProcs.h:3111`

Gets the document that contains the specified page.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose document is obtained.

**Returns:** [`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)

The document that contains the page.

**See also:** [`PDDocAcquirePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAcquirePage)

#### PDPageGetDuration

```cpp
ASFixed PDPageGetDuration(PDPage pdp)
```

Header: `PDProcs.h:5867`

Gets the page's automatic-advance timing value, which is the maximum amount of time the page is displayed before the viewer automatically advances to the next page.

**Parameters**

- `pdp` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose timing value is obtained.

**Returns:** [`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)

The automatic-advance timing for the page, in seconds. If the page does not have an advance timing value, fxDefaultPageDuration is returned (representing positive infinity, meaning that it never advances).

**See also:** [`PDPageSetDuration`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetDuration)

#### PDPageGetFlippedMatrix

```cpp
void PDPageGetFlippedMatrix(PDPage pdPage, ASFixedMatrix *flipped)
```

Header: `PDProcs.h:3267`

Gets the matrix that transforms user space coordinates to rotated and cropped coordinates. The origin of this space is the top-left of the rotated, cropped page. `Y` is decreasing.

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose flipped transformation matrix is obtained.
- `flipped` (`ASFixedMatrix *`): (Filled by the method) A pointer to the flipped transformation matrix.

**Returns:** `void`

**See also:** [`PDPageGetDefaultMatrix`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetDefaultMatrix)

#### PDPageGetMediaBox

```cpp
void PDPageGetMediaBox(PDPage page, ASFixedRect *mediaBoxP)
```

Header: `PDProcs.h:3175`

Gets the media box for a page. The media box is the *natural size* of the page (for example, the dimensions of an A4 sheet of paper).

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose media box is obtained.
- `mediaBoxP` (`ASFixedRect *`): IN/OUT (Filled by the method) A pointer to a rectangle specifying the page's media box, specified in user space coordinates.

**Returns:** `void`

**See also:** [`PDPageSetMediaBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetMediaBox), [`PDPageGetCropBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetCropBox), [`PDPageGetBBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetBBox)

#### PDPageGetNumAnnots

```cpp
ASInt32 PDPageGetNumAnnots(PDPage aPage)
```

Header: `PDProcs.h:3470`

Gets the number of annotations on a page. Annotations associated with pop-up windows (such as strikeouts) are counted as two annotations. Widget annotations (form fields) are included in the count.

**Parameters**

- `aPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page for which the number of annotations is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of annotations on `aPage`.

**See also:** [`PDPageGetAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetAnnot)

#### PDPageGetNumber

```cpp
ASInt32 PDPageGetNumber(PDPage page)
```

Header: `PDProcs.h:3090`

Gets the page number for the specified page.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose page number is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The page within the document. The first page is `0`.

**See also:** [`PDPageNumFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageNumFromCosObj)

#### PDPageGetOCGs

```cpp
PDOCG * PDPageGetOCGs(PDPage pdPage)
```

Header: `PDProcs.h:9206`

Gets the optional-content groups for the document.

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose OCGs are obtained.

**Returns:** [`PDOCG *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCG)

A `NULL`-terminated array of PDOCG objects. The client is responsible for freeing the array with ASfree().

**See also:** [`PDDocGetOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetOCGs), [`PDPageEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumOCGs)

#### PDPageGetPDEContentFilters

```cpp
ASBool PDPageGetPDEContentFilters(IN PDPage pdPage, OUT ASInt32 *numFilters, OUT ASAtom **filters)
```

Header: `PgCntProcs.h:260`

Gets filters used by PDPageSetPDEContent(). The caller is responsible for allocating the filter array `filters` that receives the filters. `filters` can be `NULL` to just obtain the number of filters.

**Parameters**

- `pdPage` (`IN PDPage`): The page whose content filters are obtained.
- `numFilters` (`OUT ASInt32 *`): (Filled by the method) The number of filters
  used by PDPageSetPDEContent().
- `filters` (`OUT ASAtom **`): (Filled by the method) The filters used by
  PDPageSetPDEContent(). If it is `NULL`, `numFilters` contains the
  number of filters.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if `filters` are obtained, `false` if the page's contents are not cached.

**See also:** [`PDPageSetPDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetPDEContent), [`PDPageSetPDEContentFilters`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetPDEContentFilters)

#### PDPageGetPDEContentFlags

```cpp
ASBool PDPageGetPDEContentFlags(IN PDPage pdPage, OUT ASUns32 *flags)
```

Header: `PgCntProcs.h:218`

Gets flags used by PDPageSetPDEContent().

**Parameters**

- `pdPage` (`IN PDPage`): The page whose content flags are obtained.
- `flags` (`OUT ASUns32 *`): (Filled by the method) PDEContentToCosObjFlags flags.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if flags obtained, `false` if the page's contents are not cached.

**See also:** [`PDPageSetPDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetPDEContent), [`PDPageSetPDEContentFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetPDEContentFlags)

#### PDPageGetPalette

```cpp
ASBool PDPageGetPalette(PDPage page, void *displayContext, char *table)
```

Header: `PDProcs.h:8280`

Useful for obtaining the static, platform-specific palette; the bitmap must be already selected into the `displayContext` to get the palette. This API was exposed for the purpose of the ImageConversion plug-in. When that code uses PDPageDrawContentsToWindow() to get a bitmap from AGM, it needs the palette that AGM used in order to get the correct results. **Note:** Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose palette is obtained.
- `displayContext` (`void *`): The bitmap.
- `table` (`char *`): (Filled by the method) The palette.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the palette was returned, `false` otherwise.

#### PDPageGetRotate

```cpp
PDRotate PDPageGetRotate(PDPage page)
```

Header: `PDProcs.h:3146`

Gets the rotation value for a page.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose rotation is obtained.

**Returns:** [`PDRotate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRotate)

Rotation value for the given page. It must be one of the PDRotate values.

**See also:** [`PDPageSetRotate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetRotate)

#### PDPageGetTransition

```cpp
PDTrans PDPageGetTransition(PDPage pdp)
```

Header: `PDProcs.h:5842`

Gets the transition for a given page.

**Parameters**

- `pdp` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose transition is obtained.

**Returns:** [`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)

The page's transition. If the page has no transition, it returns a `NULL` transition.

**See also:** [`PDPageSetTransition`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetTransition), [`PDTransNull`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransNull)

#### PDPageGetUserUnitSize

```cpp
float PDPageGetUserUnitSize(PDPage page)
```

Header: `PDProcs.h:11238`

Returns the UserUnit value for the page. If the key is not present in the page dictionary the default of `1.0` is returned.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose UserUnit value is being obtained.

**Returns:** `float`

The value of UserUnit from the page dictionary, or a default value of `1.0` if not present.

#### PDPageGetVisibleBBox

```cpp
void PDPageGetVisibleBBox(PDPage page, PDOCContext ocContext, ASBool includeAnnots, ASFixedRect *fr)
```

Header: `PDProcs.h:10741`

Gets the bounding box for a given page for those contents that are visible in the given optional-content context. The bounding box is the rectangle that encloses the visible text, graphics, and images on the page.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose visible-content bounding box is obtained.
- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context within which the contents are visible.
- `includeAnnots` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): When `true`, include annotations as content that must be visible to affect the bounding box. When `false`, annotations are not considered at all.
- `fr` (`ASFixedRect *`): (Filled by the method) A pointer to a rectangle specifying the page's visible content bounding box, specified in user space coordinates. The client must not pass `NULL`.

**Returns:** `void`

**See also:** [`PDPageGetBBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetBBox)

#### PDPageHasOverprintExt

```cpp
ASBool PDPageHasOverprintExt(PDPage pdPage)
```

Header: `PDProcs.h:11836`

Checks whether a page contains overprint (with qualifications).

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to check.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` only if the page contains overprint.

#### PDPageHasTransition

```cpp
ASBool PDPageHasTransition(PDPage pdp)
```

Header: `PDProcs.h:5830`

Tests whether a page has a transition.

**Parameters**

- `pdp` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to test.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the page has a transition, `false` otherwise.

#### PDPageHasTransparency

```cpp
ASBool PDPageHasTransparency(PDPage pdPage, ASBool includeAnnotAppearances)
```

Header: `PDProcs.h:8157`

Checks whether a page uses any transparency features. **Note:** To determine whether the page uses transparency, the resources of the page must be enumerated (though the page contents do not need to be parsed). The page resources may not be optimized for slow (browser-based) connections, so calling PDPageHasTransparency() before the page has been downloaded may cause unpleasant read behavior and performance problems.

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page to check.
- `includeAnnotAppearances` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, annotation appearances are included in the check; if `false` annotation appearances will be ignored.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` only if the page uses any transparency features.

#### PDPageMakeSeparations

```cpp
void PDPageMakeSeparations(PDPage pdPage, PDHostSepsSpec spec)
```

Header: `PDProcs.h:8352`

Generates print color separations for a page. This is the entry point for creating separations for a single page. The spec structure contains an array of PDHostSepsPlate pointers, (typically based on the page inks reported by PDPageEnumInks()), with settings such as what to do on each plate and the output stream for plates that are being produced. The client owns the memory for the array and all of the records in it, and is responsible for disposing of all allocated memory. On completion, the marked flags in the `wasColorSet` field of the plates indicate whether each plate was marked, meaning that any marking operation happened, even if it was clipped away or knocked out later. The special All colorant in a Separation color space does not affect the marked flags. For Adobe Reader and Acrobat, this method does nothing.

**Parameters**

- `pdPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page.
- `spec` (`PDHostSepsSpec`): The separation specification structure containing parameters for the generation.

**Returns:** `void`

**See also:** `AVDocPrintSeparations`, [`PDPageEnumInks`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageEnumInks), [`PDPageMakeSeparations`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageMakeSeparations)

#### PDPageNotifyContentsDidChange

```cpp
void PDPageNotifyContentsDidChange(PDPage page)
```

Header: `PDProcs.h:3080`

Broadcasts a PDPageContentsDidChange() notification. If the Acrobat viewer is version 2.1 or later, also broadcasts a PDPageContentsDidChangeEx() notification with `invalidateViews` set to `true`. You must use this method after using Cos methods to change a page's contents. Do not use this method if you use PDPageAddCosContents() or PDPageRemoveCosContents() to change a page's contents, because those methods automatically generate the appropriate notifications. Use PDPageNotifyContentsDidChangeEx() instead of this method if you wish to suppress the Acrobat viewer's immediate redraw of the page.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page that changed. @notify PDPageContentsDidChange @notify PDPageContentsDidChangeEx (in version 2.1 and later)

**Returns:** `void`

**See also:** [`PDPageAddCosContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddCosContents), [`PDPageRemoveCosContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveCosContents), [`PDPageNotifyContentsDidChangeEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageNotifyContentsDidChangeEx)

#### PDPageNotifyContentsDidChangeEx

```cpp
void PDPageNotifyContentsDidChangeEx(PDPage page, ASBool invalidateViews)
```

Header: `PDProcs.h:5418`

Broadcasts a PDPageContentsDidChange() notification and a PDPageContentsDidChangeEx() notification. These notify the Acrobat viewer that a page's contents have been modified, and tells the Acrobat viewer whether to redraw the page immediately. You must use this method after using Cos methods to change a page's contents. Do not use this method if you use PDPageAddCosContents() or PDPageRemoveCosContents() to change a page's contents, because those methods automatically generate the appropriate notifications. If your plug-in must be compatible with version 2.0 of the Acrobat viewer, you must use PDPageNotifyContentsDidChange() instead.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page that changed.
- `invalidateViews` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): `true` if the Acrobat viewer redraws the page view, `false` otherwise. This allows plug-ins to make a sequence of modifications to a page's contents, without having the entire page flash after each modification. Passing `true` for `invalidateViews` is equivalent to calling PDPageNotifyContentsDidChange(). @notify PDPageContentsDidChange @notify PDPageContentsDidChangeEx

**Returns:** `void`

**See also:** [`PDPageAddCosContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddCosContents), [`PDPageRemoveCosContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveCosContents), [`PDPageNotifyContentsDidChange`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageNotifyContentsDidChange)

#### PDPageNumFromCosObj

```cpp
ASInt32 PDPageNumFromCosObj(CosObj pageObj)
```

Header: `PDProcs.h:3135`

Gets the page number of the page specified by a Cos object. **Note:** Do not call this method with a `NULL` Cos object.

**Parameters**

- `pageObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The dictionary Cos object for the page whose number is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The page within the document (the first page in a document is page number zero).

**See also:** [`PDPageGetNumber`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetNumber)

#### PDPagePDEContentWasChanged

```cpp
void PDPagePDEContentWasChanged(IN PDPage pdPage, IN ASExtension self)
```

Header: `PgCntProcs.h:125`

Indicates a page's PDEContent has changed. Call this after you alter a PDPage object's PDEContent but do not call PDPageSetPDEContent(), so others who have acquired the PDEContent know it has changed.

**Parameters**

- `pdPage` (`IN PDPage`): The page whose content was changed.
- `self` (`IN ASExtension`): Identifies the caller or client. For plug-ins, this should be the gExtensionID extension. For the Adobe PDF Library, if there is only one client of the PDFEdit subsystem, this should be zero. If there are multiple clients, each should specify a nonzero, non-negative value. (A negative value is reserved for the implementation.) @notify PagePDEContentDidChange

**Returns:** `void`

**See also:** [`PDPageSetPDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetPDEContent)

#### PDPageRegisterForPDEContentChanged

```cpp
void PDPageRegisterForPDEContentChanged(IN PagePDEContentDidChangeNPROTO proc, IN ASExtension self)
```

Header: `PgCntProcs.h:143`

Registers for the PagePDEContentDidChange() notification.

**Parameters**

- `proc` (`IN PagePDEContentDidChangeNPROTO`): A callback for the function to call when an acquired PDPage object's PDEContent has changed.
- `self` (`IN ASExtension`): Identifies the caller or client. For plug-ins, this should be the gExtensionID extension. For the Adobe PDF Library, if there is only one client of the PDFEdit subsystem, this should be zero. If there are multiple clients, each should specify a nonzero, non-negative value. (A negative value is reserved for the implementation.) @notify PagePDEContentDidChange

**Returns:** `void`

**See also:** [`PDPageRegisterForPDEContentNotCached`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRegisterForPDEContentNotCached), [`PDPageUnRegisterForPDEContentChanged`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageUnRegisterForPDEContentChanged)

#### PDPageRegisterForPDEContentNotCached

```cpp
void PDPageRegisterForPDEContentNotCached(IN PagePDEContentNotCachedNPROTO proc, IN ASExtension self)
```

Header: `PgCntProcs.h:187`

Register for the PagePDEContentNotCached() notification. This notification is also sent when others change (or delete) a PDPage object's contents without using PDFEdit methods. For instance, rotating or deleting a page in the viewer results in this notification being sent. PDFEdit registers for almost a half dozen different notifications for the different ways Acrobat can alter page contents; you may need only this notification.

**Parameters**

- `proc` (`IN PagePDEContentNotCachedNPROTO`): A callback for the function to call when an acquired PDPage object's PDEContent is no longer valid.
- `self` (`IN ASExtension`): Identifies the caller or client. For plug-ins, this should be the gExtensionID extension. For the Adobe PDF Library, if there is only one client of the PDFEdit subsystem, this should be zero. If there are multiple clients, each should specify a nonzero, non-negative value. (A negative value is reserved for the implementation.) @notify PagePDEContentNotCached

**Returns:** `void`

**See also:** [`PDPageRegisterForPDEContentChanged`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRegisterForPDEContentChanged), [`PDPageUnRegisterForPDEContentNotCached`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageUnRegisterForPDEContentNotCached)

#### PDPageRelease

```cpp
void PDPageRelease(PDPage page)
```

Header: `PDProcs.h:3101`

Decrements the specified page's reference count.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose reference count is decremented.

**Returns:** `void`

**See also:** [`PDBeadAcquirePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadAcquirePage), [`PDDocAcquirePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAcquirePage)

#### PDPageReleasePDEContent

```cpp
ASInt32 PDPageReleasePDEContent(IN PDPage pdPage, IN ASExtension self)
```

Header: `PgCntProcs.h:77`

Decrements a PDPage object's PDEContent internal reference count. The PDEContent is not automatically deleted when the reference count becomes zero: it remains in the cache until the cache slot is needed for another PDPage. Thus, you do not need to keep a PDEContent acquired for performance reasons. There is a notification for which you can register that is sent when a PDEContent is actually removed from the cache, thus enabling the use of PDFEdit object's tagging methods PDEAddTag(), PDEGetTag(), and PDERemoveTag() on the PDEContent object.

**Parameters**

- `pdPage` (`IN PDPage`): The page whose content object's use count is decremented.
- `self` (`IN ASExtension`): Identifies the caller or client. For plug-ins, this should be the gExtensionID extension. For the Adobe PDF Library, if there is only one client of the PDFEdit subsystem, this should be zero. If there are multiple clients, each should specify a nonzero, non-negative value. (A negative value is reserved for the implementation.)

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The updated reference count.

**See also:** [`PDPageAcquirePDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAcquirePDEContent), [`PDPageSetPDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetPDEContent)

#### PDPageRemoveAnnot

```cpp
void PDPageRemoveAnnot(PDPage aPage, ASInt32 annotIndex)
```

Header: `PDProcs.h:3441`

Removes an annotation from the specified page. Annotations are stored in Cos arrays, which are automatically compressed when an annotation is removed (see CosArrayRemove()). For this reason, if you use a loop in which you remove annotations, structure the code so the loop processes from the highest to the lowest index. If you loop the other direction, you will skip over annotations immediately following ones you remove.

**Parameters**

- `aPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page from which the annotation is removed.
- `annotIndex` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The index (into the page's annotation array) of the annotation to remove.

**Returns:** `void`

**Exceptions**

- `pdErrOpNotPermitted`: is raised if:

  • The annotation is of subtype Text and the document's permissions do not include pdPermEditNotes (see PDPerms).

  • The annotation is of any other subtype and the document's permissions do not include pdPermEdit.

  @notify PDPageWillRemoveAnnot @notify PDPageDidRemoveAnnot

**See also:** [`PDPageGetAnnotIndex`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetAnnotIndex), [`PDPageAddNewAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddNewAnnot), [`PDPageAddAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddAnnot)

#### PDPageRemoveCosContents

```cpp
void PDPageRemoveCosContents(PDPage page)
```

Header: `PDProcs.h:3572`

Removes the contents of the specified page.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose Cos contents are removed. @notify PDDocDidChangePages

**Returns:** `void`

**See also:** [`PDPageAddCosContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddCosContents)

#### PDPageRemoveCosResource

```cpp
void PDPageRemoveCosResource(PDPage page, const char *resType, const char *resName)
```

Header: `PDProcs.h:3562`

Removes a Cos resource from a page object. See the description of Resource Dictionaries in ISO 32000-1:2008, Document Management- Portable Document Format-Part 1: PDF 1.7, section 7.8.3, page 82. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose Cos resources are removed.
- `resType` (`const char *`): The resource type. The named resource types in PDF are: ExtGState, ColorSpace, Pattern, Shading, XObject, Font, ProcSet, and Properties.
- `resName` (`const char *`): The resource name (for example, the name of a font might be `F1`). @notify PDDocDidChangePages

**Returns:** `void`

**See also:** [`PDPageAddCosResource`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAddCosResource), [`PDPageGetCosResources`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetCosResources)

#### PDPageResumePDEContentChanged

```cpp
void PDPageResumePDEContentChanged(IN PDPage pdPage)
```

Header: `PgCntProcs.h:303`

Resumes destruction of PDEContent objects when a PDPageContentsDidChange() notification occurs. Only use this API if you called PDPageSuspendPDEContentChanged().

**Parameters**

- `pdPage` (`IN PDPage`): IN/OUT The page whose content is changed.

**Returns:** `void`

**See also:** [`PDPageSuspendPDEContentChanged`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSuspendPDEContentChanged)

#### PDPageSetBox

```cpp
void PDPageSetBox(PDPage page, ASAtom boxName, ASFixedRect box)
```

Header: `PDProcs.h:7905`

Sets the box specified by `boxName` for the page. This method may throw exceptions.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page for which the box is to be set.
- `boxName` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): IN/OUT An ASAtom representing the type of box. The box names are:

  • `ArtBox`

  • `BleedBox`

  • `CropBox`

  • `TrimBox`

  • `MediaBox`
- `box` (`ASFixedRect`): IN/OUT An `ASFixedRect` specifying the coordinates to set for the box. @notify PDDocWillChangePages @notify PDDocDidChangePages

**Returns:** `void`

**See also:** [`PDPageGetBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetBox)

#### PDPageSetCropBox

```cpp
void PDPageSetCropBox(PDPage page, ASFixedRect cropBox)
```

Header: `PDProcs.h:3222`

Sets the crop box for a page. The crop box is the region of the page to display and print. This method ignores the request if either the width or height of cropBox is less than 72 points (one inch).

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose crop box is set.
- `cropBox` (`ASFixedRect`): A rectangle specifying the page's crop box, specified in user space coordinates. @notify PDDocWillChangePages @notify PDDocDidChangePages

**Returns:** `void`

**See also:** [`PDPageGetCropBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetCropBox), [`PDPageSetMediaBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetMediaBox)

#### PDPageSetDuration

```cpp
void PDPageSetDuration(PDPage pdp, ASFixed fxDuration)
```

Header: `PDProcs.h:5881`

Sets the page's automatic-advance timing value, which is the maximum amount of time the page is displayed before the viewer automatically advances to the next page.

**Parameters**

- `pdp` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose timing is set.
- `fxDuration` ([`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): The auto-advance timing, in seconds. If no advance timing is desired, `fxDuration` should be set to fxDefaultPageDuration.

**Returns:** `void`

**See also:** [`PDPageGetDuration`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetDuration)

#### PDPageSetMediaBox

```cpp
void PDPageSetMediaBox(PDPage page, ASFixedRect mediaBox)
```

Header: `PDProcs.h:3192`

Sets the media box for a page. The media box is the *natural size* of the page, for example, the dimensions of an A4 sheet of paper.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page whose media box is set.
- `mediaBox` (`ASFixedRect`): IN/OUT Rectangle specifying the page's media box, specified in user space coordinates. @notify PDDocWillChangePages @notify PDDocDidChangePages

**Returns:** `void`

**See also:** [`PDPageGetMediaBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetMediaBox), [`PDPageSetCropBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetCropBox), [`PDPageGetBBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetBBox)

#### PDPageSetPDEContent

```cpp
ASBool PDPageSetPDEContent(IN PDPage pdPage, IN ASExtension self)
```

Header: `PgCntProcs.h:105`

Sets the page's PDEContent back into the PDPage object's Cos object, using the same compression filters with which the content was previously encoded. In order to properly synchronize the page's contents after setting them with PDPageSetPDEContent(), you must call PDPageNotifyContentsDidChange(). If you do not call PDPageNotifyContentsDidChange(), the page displayed will use the old page contents. @notify PDPageContentsDidChangeEx

**Parameters**

- `pdPage` (`IN PDPage`): The page whose PDEContent is set.
- `self` (`IN ASExtension`): Identifies the caller or client. For plug-ins, this should be the gExtensionID extension. For the Adobe PDF Library, if there is only one client of the PDFEdit subsystem, this should be zero. If there are multiple clients, each should specify a nonzero, non-negative value. (A negative value is reserved for the implementation.)

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if PDEContent successfully set, `false` otherwise.

**See also:** [`PDEContentToCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDEContentToCosObj), [`PDPageAcquirePDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAcquirePDEContent), [`PDPageGetPDEContentFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetPDEContentFlags), [`PDPageNotifyContentsDidChange`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageNotifyContentsDidChange)

#### PDPageSetPDEContentCanRaise

```cpp
void PDPageSetPDEContentCanRaise(IN PDPage pdPage, IN ASExtension self)
```

Header: `PgCntProcs.h:328`

Sets the page's PDEContent back into the PDPage object's Cos object, using the same compression filters with which the content was previously encoded. This method calls PDPageNotifyContentsDidChangeEx(). This method differs from PDPageSetPDEContent() in that it returns no value, but does raise an exception if it is unable to set the content.

**Parameters**

- `pdPage` (`IN PDPage`): The page whose PDEContent is set.
- `self` (`IN ASExtension`): Identifies the caller or client. For plug-ins, this should be the gExtensionID extension. For the Adobe PDF Library, if there is only one client of the PDFEdit subsystem, this should be zero. If there are multiple clients, each should specify a nonzero, non-negative value. (A negative value is reserved for the implementation.) @notify PDPageContentsDidChangeEx

**Returns:** `void`

**See also:** [`PDEContentToCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdelayer.md#PDEContentToCosObj), [`PDPageAcquirePDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageAcquirePDEContent), [`PDPageGetPDEContentFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetPDEContentFlags), [`PDPageSetPDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetPDEContent)

#### PDPageSetPDEContentFilters

```cpp
ASBool PDPageSetPDEContentFilters(IN PDPage pdPage, IN ASInt32 numFilters, IN ASAtom *filters)
```

Header: `PgCntProcs.h:276`

Sets the filters used by PDPageSetPDEContent(). The filters are not instantiated until PDPageSetPDEContent() is called.

**Parameters**

- `pdPage` (`IN PDPage`): The page whose content filters are set.
- `numFilters` (`IN ASInt32`): The number of filters used by PDPageSetPDEContent().
- `filters` (`IN ASAtom *`): An array of filters to use by PDPageSetPDEContent().

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if filters were set, `false` if the page's contents are not cached (meaning that nothing was done).

**See also:** [`PDPageGetPDEContentFilters`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetPDEContentFilters), [`PDPageSetPDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetPDEContent)

#### PDPageSetPDEContentFlags

```cpp
ASBool PDPageSetPDEContentFlags(IN PDPage pdPage, IN ASUns32 flags)
```

Header: `PgCntProcs.h:238`

Sets flags used by PDPageSetPDEContent(). The flags are not instantiated until PDPageSetPDEContent() is called.

**Parameters**

- `pdPage` (`IN PDPage`): The page whose content flags are set.
- `flags` (`IN ASUns32`): PDEContentToCosObjFlags flags. The following
  flags are ignored, since the content is always a page:

  kPDEContentToForm
  kPDEContentToCharProc

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

**See also:** [`PDPageGetPDEContentFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetPDEContentFlags), [`PDPageSetPDEContent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetPDEContent)

#### PDPageSetRotate

```cpp
void PDPageSetRotate(PDPage page, PDRotate angle)
```

Header: `PDProcs.h:3159`

Sets the rotation value for a page.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose rotation is set.
- `angle` ([`PDRotate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRotate)): Rotation value to be set for a given page. It must be one of the PDRotate values. @notify PDDocWillChangePages @notify PDDocDidChangePages

**Returns:** `void`

**See also:** [`PDPageGetRotate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetRotate)

#### PDPageSetTransition

```cpp
void PDPageSetTransition(PDPage pdp, PDTrans pdt)
```

Header: `PDProcs.h:5853`

Sets the transition for a given page.

**Parameters**

- `pdp` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose transition is set.
- `pdt` ([`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)): The transition for the page.

**Returns:** `void`

**See also:** [`PDPageGetTransition`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetTransition), [`PDTransNull`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransNull)

#### PDPageSetUserUnitSize

```cpp
void PDPageSetUserUnitSize(PDPage page, float unitSize)
```

Header: `PDProcs.h:11246`

Set the UserUnit value for a page.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page whose UserUnit value is being set.
- `unitSize` (`float`): UserUnit value to be set for the page dictionary. The default value is `1.0`.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if `unitSize <= 0.0` .

#### PDPageStmGetInlineImage

```cpp
ASUns32 PDPageStmGetInlineImage(ASStm stm, ASUns32 flags, CosDoc cosDoc, CosObj resDict, PDPageStmImageDataProc proc, void *procClientData, ASUns32 *imageRawDataStmOffsetP, ASUns32 *imageRawDataLenP, CosObj *imageDict)
```

Header: `PDProcs.h:5720`

Reads a PDF page content inline image from a stream. The stream is typically obtained by getting the Cos stream for a page contents or a Form contents, and calling CosStreamOpenStm() to open the stream using the *filtered* mode. This method is called after a BI token has been read from the stream. BI indicates that the following tokens comprise an inline image dictionary and data. It begins reading at the current stream position. It returns the number of bytes read. This is the number of bytes read from the stream and indicates the amount by which the stream position has advanced. The image attributes dictionary is returned in `imageDict`. The image data is passed to the PDPageStmImageDataProc(); if `proc` is not provided, the image data is discarded. `imageRawDataStmOffsetP` and `imageRawDataLenP` may be `NULL`, in which case they are ignored. The caller should call CosObjDestroy() on `imageDict` when it is done. This method can raise memory, I/O, and parsing exceptions. @since

**Parameters**

- `stm` ([`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)): The stream from which data is read.
- `flags` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): Currently unused by this method (used by
  PDPageStmGetToken().)
- `cosDoc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The CosDoc with the PDPage that contains
  the inline image.
- `resDict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Resources dictionary in which to look up
  ColorSpace resources for inline images.
- `proc` ([`PDPageStmImageDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageStmImageDataProc)): A callback method to handle inline image data.`proc`.
- `procClientData` (`void *`)
- `imageRawDataStmOffsetP` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): (Filled by the method) The offset
  of the data stream, after BI, relative to the beginning
  of `stm`.
- `imageRawDataLenP` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): (Filled by the method) The offset
  of the last byte of the data stream between the BI and EI
  PDF operators.
- `imageDict` ([`CosObj *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): (Filled by the method) The returned image
  dictionary.`stm`.

**Returns:** [`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)

**See also:** [`CosStreamOpenStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamOpenStm), [`PDPageGetBox`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetBox), [`PDPageStmGetToken`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageStmGetToken)

#### PDPageStmGetToken

```cpp
ASUns32 PDPageStmGetToken(ASStm stm, ASUns32 flags, PDPageStmStringOverflowProc proc, void *procClientData, PDPageStmToken pageStmToken)
```

Header: `PDProcs.h:5669`

Reads a PDF page content token from a stream. The stream is typically obtained by getting the Cos stream for a page contents or a Form contents, and calling CosStreamOpenStm() to open the stream using the *filtered* mode. It begins reading at the current stream position, and reads exactly one token. It returns the number of bytes read. This is the number of bytes read from the stream and indicates the amount by which the stream position has advanced. The end-of-stream criteria (loop terminating condition) is the following: A `NULL` object is returned (an object of type CosNull). The number of bytes read (return value) is `1`. If the token is an integer, real (ASFixed), or ASBool, then the value is returned in `pageStmToken.iVal`. If the token is a string or a name, the value is returned in `pageStmToken.sVal`, and the length of the token is in `pageStmToken.sValLen`. Strings are not `NULL`-terminated, but names are `NULL`-terminated. If a string length is greater than kPDPageStmStringMax, the PDPageStmStringOverflowProc() is called repeatedly with portions of the string. On return from PDPageStmGetToken, the value of `pageStmToken.sValLen` is zero, and `pageStmToken.sVal` is empty (`ival`, `sVal`, and `sValLen` are components of the PDPageStmToken). If there is no overflow proc, then the first kPDPageStmStringMax bytes of the string will be returned in `pageStmToken.sVal`, and the remaining bytes are lost. The value of `pageStmToken.sValLen` is kPDPageStmStringMax in this case. If the token is BI (begin inline image), PDPageStmGetInlineImage() should be called to parse the inline image. This method can raise memory, I/O, and parsing exceptions. @since

**Parameters**

- `stm` ([`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)): The stream from which data is read.
- `flags` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): A bit field of options such as 'skip comments'
  (kPDPageStmSkipComments means skip comments during
  token generation).
- `proc` ([`PDPageStmStringOverflowProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageStmStringOverflowProc)): A callback method to handle long strings.
- `procClientData` (`void *`): Client data passed to the callback
  method.
- `pageStmToken` (`PDPageStmToken`): The returned token.

**Returns:** [`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)

**See also:** [`CosStreamOpenStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamOpenStm), [`PDPageGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetCosObj), [`PDPageStmGetInlineImage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageStmGetInlineImage)

#### PDPageSuspendPDEContentChanged

```cpp
void PDPageSuspendPDEContentChanged(IN PDPage pdPage)
```

Header: `PgCntProcs.h:292`

Suspends destruction of PDEContent objects when a PagePDEContentDidChange() notification occurs. Only use this API if you are about to call PDPageNotifyContentsDidChange() and you do not want PDFEdit to destroy all PDEContent objects associated with that PDPage. This is used, for example, when AVAppSetPreference() is called. Make sure to call PDPageSuspendPDEContentChanged() on the PDPage object after you call PDPageNotifyContentsDidChange().

**Parameters**

- `pdPage` (`IN PDPage`): IN/OUT The page whose content is changed.

**Returns:** `void`

**See also:** [`PDPageResumePDEContentChanged`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageResumePDEContentChanged)

#### PDPageUnRegisterForPDEContentChanged

```cpp
void PDPageUnRegisterForPDEContentChanged(IN PagePDEContentDidChangeNPROTO proc, IN ASExtension self)
```

Header: `PgCntProcs.h:160`

Un-registers for the PagePDEContentDidChange() notification.

**Parameters**

- `proc` (`IN PagePDEContentDidChangeNPROTO`): A callback for the function to call when an acquired PDPage object's PDEContent has changed.
- `self` (`IN ASExtension`): Identifies the caller or client. For plug-ins, this should be the gExtensionID extension. For the Adobe PDF Library, if there is only one client of the PDFEdit subsystem, this should be zero. If there are multiple clients, each should specify a nonzero, non-negative value. (A negative value is reserved for the implementation.) @notify PagePDEContentDidChange

**Returns:** `void`

**See also:** [`PDPageRegisterForPDEContentChanged`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRegisterForPDEContentChanged)

#### PDPageUnRegisterForPDEContentNotCached

```cpp
void PDPageUnRegisterForPDEContentNotCached(IN PagePDEContentNotCachedNPROTO proc, IN ASExtension self)
```

Header: `PgCntProcs.h:205`

Un-registers for the PagePDEContentNotCached() notification. @notify PagePDEContentNotCached

**Parameters**

- `proc` (`IN PagePDEContentNotCachedNPROTO`): IN/OUT A callback for the function to call when an acquired PDPage object's PDEContent is no longer valid.
- `self` (`IN ASExtension`): IN/OUT Identifies the caller/client. For plug-ins, this should be the gExtensionID extension. For the Adobe PDF Library, if there is only one client of the PDFEdit subsystem, `clientID` should be zero. If there are multiple clients, each should specify a nonzero, non-negative `clientID`. (A negative `clientID` is reserved for the implementation.)

**Returns:** `void`

**See also:** [`PDPageRegisterForPDEContentNotCached`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRegisterForPDEContentNotCached)

### Typedefs (8)

#### PDPageArea

```cpp
typedef ASEnum16 PDPageArea
```

Header: `PDExpT.h:6374`

#### PDPageDrawFlagsPI

```cpp
typedef ASUns32 PDPageDrawFlagsPI
```

Header: `PDExpT.h:6821`

#### PDPageMode

```cpp
typedef ASEnum8 PDPageMode
```

Header: `PDExpT.h:2027`

#### PDPageNumber

```cpp
typedef ASInt32 PDPageNumber
```

Header: `PDExpT.h:61`

A `0`-based page number for use in AVPageView and AVDoc methods. Negative for special values.

**See also:** `AVDocGetPageText`, `AVDocGetViewDef`, `AVPageViewGetFirstVisiblePageNum`, `AVPageViewGetLastVisiblePageNum`, `AVPageViewGetNextView`, `AVPageViewGetPageNum`, `AVPageViewGetSelectedAnnotPageNum`, `AVPageViewGetVisibleAnnotPage`, `AVPageViewGoTo`, `AVPageViewPageNumIsVisible`, `AVPageViewSetPageNum`, `AVDocSelectionGetAVRectProc`, `AVSelectionPageRangeEnumProc`

#### PDRotate

```cpp
typedef ASEnum16 PDRotate
```

Header: `PDExpT.h:2492`

#### PDPageEnumInksCallback

```cpp
typedef ASBool(*) PDPageEnumInksCallback(PDPageInk ink, void *clientData)(PDPageInk ink, void *clientData)
```

Header: `PDExpT.h:6026`

Used for enumerating the inks on a page via PDPageEnumInks().

#### PDPageStmImageDataProc

```cpp
typedef ASBool(*) PDPageStmImageDataProc(ASUns8 *data, ASSize_t dataLen, void *clientData)(ASUns8 *data, ASSize_t dataLen, void *clientData)
```

Header: `PDExpT.h:4057`

A callback for PDPageStmGetInlineImage(). It should be called when inline image data is encountered in PDPageStmGetToken(). This method may be called multiple times for one inline image. If so, each call provides sequential data for the image.

**See also:** [`PDPageStmGetInlineImage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageStmGetInlineImage), [`PDPageStmGetToken`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageStmGetToken)

#### PDPageStmStringOverflowProc

```cpp
typedef void(*) PDPageStmStringOverflowProc(char *sVal, ASSize_t sValLen, void *clientData)(char *sVal, ASSize_t sValLen, void *clientData)
```

Header: `PDExpT.h:4033`

A callback used by PDPageStmGetToken(). It is called when the length of a string token exceeds `kPDPageStmStringMax` bytes (see `PDExpT.h`) in PDPageStmGetToken().

**See also:** [`PDPageStmGetToken`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageStmGetToken)

### Structures (1)

#### PDPage

```cpp
typedef struct _t_PDPage* PDPage
```

Header: `PDBasicExpT.h:88`

A single page in the PDF representation of a document. Just as PDF files are partially composed of their pages, PDDoc objects are composed of PDPage objects. A page contains a series of objects representing the objects drawn on the page (PDGraphic), a list of resources used in drawing the page, annotations (PDAnnot), an optional thumbnail image of the page, and the beads used in any articles that occur on the page. The first page in a PDDoc is page `0`.

**See also:** [`PDDocCreatePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreatePage), [`PDBeadAcquirePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadAcquirePage), [`PDDocAcquirePage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAcquirePage), `AVPageViewGetPage`, [`PDDocDeletePages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocDeletePages), [`PDPageRelease`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRelease)

### Enums (4)

#### PDPageAreas

Header: `PDExpT.h:6363`

Different logical areas on a page.

**Values**

- `kPDPageArea = 0`
- `kPDClipArea = 1`
- `kPDNumAreas = 2`

#### PDPageDrawFlagsPIs

Header: `PDExpT.h:6762`

**Values**

- `kPDPageDoLazyErasePI = 0x00000001`: Erase the page while rendering only as needed.
- `kPDPageIgnoreIsolatedAndKnockoutTransparencyGroupPI = 0x00000010`: Ignore Isolated and Knockout transparency at page boundary.
- `kPDPageUseAnnotFacesPI = 0x00000040`: Draw annotation appearances.
- `kPDPageIsPrintingPI = 0x00000080`: The page is being printed.
- `kPDPageDisplayOverPrintPreviewPI = 0x00000100`: Display overprint preview.
- `kPDPageUseTrapAnnotsPI = 0x00002000`: Use trap network annotations.
- `kPDPageDirectlyImposedPI = 0x00004000`: Directly imposed page.
- `kPDPageIsPSPrintingPI = 0x00008000`: PostScript printing.
- `kPDPageEmitPageGroupPI = 0x00010000`: Emit a page group.
- `kPDPageUsePrinterMarkAnnotsPI = 0x00020000`: User printer's mark annotations.
- `kPDPagePassOPItoAGMPortPI = 0x00040000`: Pass open prepress interface (OPI) to AGM port.
- `kPDPagePassMetadatatoAGMPortPI = 0x00080000`: Pass metadata to AGM port.
- `kPDPagePassOCtoAGMPortPI = 0x00100000`: Pass optional content to AGM port.
- `kPDPageDoNotSubstituteWorkingSpacesPI = 0x00800000`: Do not substitute working spaces.
- `kPDPageSwapComponentsPI = 0x01000000`: Render colors in BGR order rather than RGB. It is only valid for calls to PDPageDrawContentsToMemory() and only when outputing to an RGB colorspace.
- `kPDPageSuppressRasterAlphaPI = 0x02000000`: Suppress raster alpha.
- `kPDPageWorkingSpacesOnlyForChangePI = 0x04000000`: If this is set, only use a working space instead of a device space if the process color model of the target device is different than that of the source
- `kPDPageUseStampAnnotsOnlyPI = 0x08000000`: If set, only consider Stamp annotations. This overrides kPDPageUseAnnotFaces.

#### PDPageModes

Header: `PDExpT.h:1998`

An enumerated data type that specifies whether thumbnail images or bookmarks are shown.

**Values**

- `PDDontCare = 0`: Leaves the view mode as is.
- `PDUseNone = 1`: Displays the document, but displays neither thumbnails nor bookmarks.
- `PDUseThumbs = 2`: Displays the document plus thumbnails.
- `PDUseBookmarks = 3`: Displays the document plus bookmarks.
- `PDFullScreen = 4`: Displays the document in full-screen viewing mode. This is equivalent to AVAppBeginFullScreen().
- `PDContents = 5`
- `PDUseOC = 6`: Displays the document plus layers.
- `PDUseAttachments = 7`: Displays the document plus attachments.

**See also:** `AVDocGetViewMode`, `AVDocSetViewMode`, [`PDDocGetPageMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageMode), [`PDDocSetPageMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetPageMode)

#### PDPageRotation

Header: `PDExpT.h:2479`

Specifies page rotation, in degrees. It is used for routines that set or get the value of a page's Rotate key.

**Values**

- `pdRotate0 = 0`
- `pdRotate90 = 90`
- `pdRotate180 = 180`
- `pdRotate270 = 270`

**See also:** [`PDPageGetRotate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetRotate), [`PDPageSetRotate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageSetRotate)

### Definitions (8)

#### PDAllPages

Header: `PDExpT.h:2182`

Value: `((PDPageNumber)-3)`

#### PDBeforeFirstPage

Header: `PDExpT.h:2180`

Value: `((PDPageNumber)-1)`

#### PDEvenPagesOnly

Header: `PDExpT.h:2184`

Value: `((PDPageNumber)-5)`

#### PDLastPage

Header: `PDExpT.h:2181`

Value: `((PDPageNumber)-2)`

#### PDOddPagesOnly

Header: `PDExpT.h:2183`

Value: `((PDPageNumber)-4)`

#### kPDPageStmSkipComments

Header: `PDExpT.h:3989`

Value: `0x0001`

#### kPDPageStmStringMax

Header: `PDExpT.h:3986`

Value: `256`

#### kPDPageStmTokenHexString

Header: `PDExpT.h:3995`

Value: `0x0001`

## PDPageLabel

### Functions (10)

#### PDPageLabelEqual

```cpp
ASBool PDPageLabelEqual(PDPageLabel pdlOne, PDPageLabel pdlTwo)
```

Header: `PDProcs.h:7132`

Compares two page labels to see if they are equivalent. Two labels are equivalent if they have the same style, starting number (the numeric value of the first page associated with the label), and prefix strings which are the same byte-for-byte.

**Parameters**

- `pdlOne` ([`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)): A page label.
- `pdlTwo` ([`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)): Another page label.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the two labels are valid and equivalent, `false` otherwise.

**See also:** [`PDPageLabelIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelIsValid)

#### PDPageLabelFromCosObj

```cpp
PDPageLabel PDPageLabelFromCosObj(CosObj cosLabel)
```

Header: `PDProcs.h:7159`

Creates a type cast of the CosObj to a PDPageLabel object.

**Parameters**

- `cosLabel` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The Cos object level representation of a page label.

**Returns:** [`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)

The page label representation of `cosLabel`.

**Exceptions**

- `pdErrBadBaseObj`: is raised if `cosLabel` is not a valid page label.

**See also:** [`PDPageLabelGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelGetCosObj)

#### PDPageLabelGetCosObj

```cpp
CosObj PDPageLabelGetCosObj(PDPageLabel pdl)
```

Header: `PDProcs.h:7145`

Creates a type cast of the page label object to a Cos object.

**Parameters**

- `pdl` ([`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)): IN/OUT A PDPageLabel representation of a page label.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

A CosObj representation of `pdl` if the page label is valid, `NULL` CosObj otherwise.

**See also:** [`PDPageLabelFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelFromCosObj)

#### PDPageLabelGetPrefix

```cpp
const char * PDPageLabelGetPrefix(PDPageLabel pgLabel, ASInt32 *prefixLen)
```

Header: `PDProcs.h:7189`

Returns the prefix string for the label. The prefix string is transitory and should be copied immediately.

**Parameters**

- `pgLabel` ([`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)): The label for the page whose prefix is desired.
- `prefixLen` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): (Filled by the method) The length, in bytes, of the prefix string. It is zero if the page label is not valid.

**Returns:** `const char *`

The prefix string for the label, or `NULL` if none is specified.

**See also:** [`PDPageLabelGetStart`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelGetStart), [`PDPageLabelGetStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelGetStyle)

#### PDPageLabelGetPrefixASText

```cpp
void PDPageLabelGetPrefixASText(PDPageLabel pgLabel, ASText prefix)
```

Header: `PDProcs.h:11797`

Returns the prefix string for the label as an ASText object. The prefix string is transitory and should be copied immediately.

**Parameters**

- `pgLabel` ([`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)): The label for the page whose prefix is desired.
- `prefix` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The text object containing the prefix string. The client must pass a valid ASText object title. The routine does not allocate it.

**Returns:** `void`

**See also:** [`PDPageLabelGetPrefix`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelGetPrefix), [`PDPageLabelGetStart`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelGetStart), [`PDPageLabelGetStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelGetStyle)

#### PDPageLabelGetStart

```cpp
ASInt32 PDPageLabelGetStart(PDPageLabel pgLabel)
```

Header: `PDProcs.h:7202`

Gets the starting number of a given page label.

**Parameters**

- `pgLabel` ([`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)): The page label for the page whose starting number is desired.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The starting number of the page label; that is, the numeric value of the first page associated with the label. It returns `1` if the page label is not valid or unknown.

**See also:** [`PDPageLabelGetPrefix`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelGetPrefix), [`PDPageLabelGetStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelGetStyle)

#### PDPageLabelGetStyle

```cpp
ASAtom PDPageLabelGetStyle(PDPageLabel pgLabel)
```

Header: `PDProcs.h:7174`

Returns an ASAtom for the style of the label. It raises an exception if storage is exhausted or file access fails.

**Parameters**

- `pgLabel` ([`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)): IN/OUT The page label whose style is desired.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

An ASAtom for the label style. If no style is specified, it returns `ASAtomFromString(" None")`.

**See also:** [`PDPageLabelGetPrefix`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelGetPrefix), [`PDPageLabelGetStart`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelGetStart)

#### PDPageLabelIsValid

```cpp
ASBool PDPageLabelIsValid(PDPageLabel pgLabel)
```

Header: `PDProcs.h:7117`

Determines whether a page label is valid. A page label is valid if its values correspond to the specification for page label dictionaries. See the description of Page labels in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.4.2, page 374. You can find this document on the web store of the International Standards Organization (ISO). It raises an exception if storage is exhausted or file access fails.

**Parameters**

- `pgLabel` ([`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)): The page label whose validity is determined.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the label is valid, `false` otherwise.

**See also:** [`PDPageLabelEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelEqual)

#### PDPageLabelNew

```cpp
PDPageLabel PDPageLabelNew(PDDoc pdDoc, ASAtom style, const char *prefix, ASInt32 prefixLen, ASInt32 startAt)
```

Header: `PDProcs.h:7262`

Constructs a new label object in the document with the specified style, prefix, and starting page number.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document that contains the new page label.
- `style` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The numbering system to use for the numeric portion of each label in this range of pages. The possible values are `D` for decimal numbers, `R` for upper-case Roman numbers, `r` for lower-case Roman numbers, `A` for upper-case alphabetic numbers, or `a` for lower-case alphabetic numbers. If it is `None`, the labels for this range will not have a numeric portion. None is specified by providing ASAtomFromString("None") as the style parameter.
- `prefix` (`const char *`): A string to prefix to the numeric portion of the page label. It may be a `NULL` string.
- `prefixLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length in bytes of the prefix string.
- `startAt` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The value to use when generating the numeric portion of the first label in this range; it must be greater than or equal to `1`.

**Returns:** [`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)

The newly created page label.

**Exceptions**

- `pdErrBadBaseObj`: is raised if the base pages object is missing or invalid.

**See also:** [`PDDocRemovePageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemovePageLabel), [`PDDocGetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageLabel), [`PDDocFindPageNumForLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocFindPageNumForLabel), [`PDDocGetLabelForPageNum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetLabelForPageNum), [`PDDocSetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetPageLabel)

#### PDPageLabelNewASText

```cpp
PDPageLabel PDPageLabelNewASText(PDDoc pdDoc, ASAtom style, const ASText prefix, ASInt32 startAt)
```

Header: `PDProcs.h:11782`

Constructs a new label object in the document with the specified style, prefix, and starting page number.

**Parameters**

- `pdDoc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document that contains the new page label.
- `style` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The numbering system to use for the numeric
  portion of each label in this range of pages. The possible values are:

  ValueDescription
  `D`Decimal numbers.
  `R`Upper-case Roman numbers.
  `r`Lower-case Roman numbers.
  `A`Upper-case alphabetic numbers.
  `a`Lower-case alphabetic numbers.

  If it is `None`, the labels for this range will not have a numeric portion.
  None is specified by providing ASAtomFromString("None") as the style parameter.
- `prefix` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the string to prefix to the numeric portion
  of the page label.
- `startAt` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The value to use when generating the numeric
  portion of the first label in this range; it must be greater
  than or equal to `1`.

**Returns:** [`PDPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabel)

**Exceptions**

- `pdErrBadBaseObj`: is raised if the base pages object is missing
  or invalid.

**See also:** [`PDPageLabelNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelNew), [`PDDocRemovePageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemovePageLabel), [`PDDocGetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageLabel), [`PDDocFindPageNumForLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocFindPageNumForLabel), [`PDDocGetLabelForPageNum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetLabelForPageNum), [`PDDocSetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetPageLabel)

### Typedefs (1)

#### PDPageLabel

```cpp
typedef OPAQUE_64_BITS PDPageLabel
```

Header: `PDExpT.h:5574`

A label used to describe a page. This is used to allow for non-sequential page numbering or the addition of arbitrary labels for a page (such as the inclusion of Roman numerals at the beginning of a book). A PDPageLabel specifies the numbering style to use (for example, upper-case or lower-case Roman, decimal, and so on), the starting number for the first page, and an arbitrary prefix to be preappended to each number (for example, `"A-"` is used to generate `"A-1"`, `"A-2"`, `"A-3"`, and so on).

**See also:** [`PDDocGetPageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetPageLabel), [`PDDocGetLabelForPageNum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetLabelForPageNum), [`PDPageLabelFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelFromCosObj), [`PDPageLabelNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageLabelNew), [`PDDocRemovePageLabel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemovePageLabel)

## PDPath

### Functions (2)

#### PDPathEnum

```cpp
void PDPathEnum(PDPath obj, PDPathEnumMonitor mon, void *clientData)
```

Header: `PDProcs.h:3708`

Enumerates the specified path's operators, calling one of several user-supplied callbacks for each operator. The callback that is called depends on which operator is encountered.

**Parameters**

- `obj` ([`PDPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPath)): IN/OUT The path whose operators are enumerated.
- `mon` ([`PDPathEnumMonitor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathEnumMonitor)): IN/OUT A pointer to a structure that contains callbacks. One of the callbacks will be called for each path segment operator in the path. Enumeration ends if any of the monitor's callbacks returns `false`.
- `clientData` (`void *`): IN/OUT A pointer to user-supplied data to pass to the monitor's callbacks each time one is called.

**Returns:** `void`

#### PDPathGetPaintOp

```cpp
ASInt32 PDPathGetPaintOp(PDPath obj)
```

Header: `PDProcs.h:3721`

Gets flags that indicate which paint/close/clip operators are used for the specified path. For a description of the path painting operators, see Section 4.4.2 in the *PDF Reference*.

**Parameters**

- `obj` ([`PDPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPath)): IN/OUT The path whose painting operators are obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

A bit-wise `OR` of the PDPathPaintOp flags.

### Typedefs (9)

#### PDPathPaintOp

```cpp
typedef ASEnum8 PDPathPaintOp
```

Header: `PDExpT.h:2560`

#### PDPathSegmentOp

```cpp
typedef ASEnum8 PDPathSegmentOp
```

Header: `PDExpT.h:2534`

#### PDPathClosePathProc

```cpp
typedef ASBool(*) PDPathClosePathProc(void *clientData)(void *clientData)
```

Header: `PDExpT.h:3025`

A callback for PDPathEnumMonitor. It is called for every path closing operator.

**See also:** [`PDPathEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathEnum)

#### PDPathCurveToProc

```cpp
typedef ASBool(*) PDPathCurveToProc(ASFixedPoint *p1, ASFixedPoint *p2, ASFixedPoint *p3, void *clientData)(ASFixedPoint *p1, ASFixedPoint *p2, ASFixedPoint *p3, void *clientData)
```

Header: `PDExpT.h:2974`

A callback for PDPathEnumMonitor. It is called for every c operator.

**See also:** [`PDPathEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathEnum)

#### PDPathLineToProc

```cpp
typedef ASBool(*) PDPathLineToProc(ASFixedPoint *p1, void *clientData)(ASFixedPoint *p1, void *clientData)
```

Header: `PDExpT.h:2960`

A callback for PDPathEnumMonitor. It is called for every l operator.

**See also:** [`PDPathEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathEnum)

#### PDPathMoveToProc

```cpp
typedef ASBool(*) PDPathMoveToProc(ASFixedPoint *p1, void *clientData)(ASFixedPoint *p1, void *clientData)
```

Header: `PDExpT.h:2947`

A callback for PDPathEnumMonitor. It is called for every m operator.

**See also:** [`PDPathEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathEnum)

#### PDPathRectProc

```cpp
typedef ASBool(*) PDPathRectProc(ASFixedPoint *p1, ASFixedPoint *p2, void *clientData)(ASFixedPoint *p1, ASFixedPoint *p2, void *clientData)
```

Header: `PDExpT.h:3014`

A callback for PDPathEnumMonitor. It is called for every re operator.

**See also:** [`PDPathEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathEnum)

#### PDPathVCurveToProc

```cpp
typedef ASBool(*) PDPathVCurveToProc(ASFixedPoint *p1, ASFixedPoint *p2, void *clientData)(ASFixedPoint *p1, ASFixedPoint *p2, void *clientData)
```

Header: `PDExpT.h:2988`

A callback for PDPathEnumMonitor. It is called for every v operator.

**See also:** [`PDPathEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathEnum)

#### PDPathYCurveToProc

```cpp
typedef ASBool(*) PDPathYCurveToProc(ASFixedPoint *p1, ASFixedPoint *p2, void *clientData)(ASFixedPoint *p1, ASFixedPoint *p2, void *clientData)
```

Header: `PDExpT.h:3001`

A callback for PDPathEnumMonitor. It is called for every y operator.

**See also:** [`PDPathEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathEnum)

### Structures (2)

#### PDPath

```cpp
typedef struct _t_PDGraphic * PDPath
```

Header: `PDExpT.h:2499`

#### PDPathEnumMonitor

```cpp
typedef struct _t_PDPathEnumMonitor* PDPathEnumMonitor
```

Header: `PDExpT.h:3027`

### Enums (2)

#### PDPathPaintOps

Header: `PDExpT.h:2544`

A path object consists of a sequence of segment operators (moveto, lineto, an so on), as well as a set of operations to be performed with the path. Note that the operations include doing nothing, closing, stroking, filling and using the path as a clip.

**Values**

- `pdPathNoPaint = 0`: The path is not painted.
- `pdPathOpClose = 1`: The path contains a closepath operator.
- `pdPathStroke = 2`: The path contains a stroke operator.
- `pdPathFill = 4`: The path contains a fill operator.
- `pdPathEOFill = 8`: The path contains an eofill operator.
- `pdPathClip = 16`: The path contains a clip operator.
- `pdPathEOClip = 32`: The path contains an eoclip operator.

**See also:** [`PDPathSegmentOp`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathSegmentOp), [`PDPathGetPaintOp`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathGetPaintOp)

#### PDPathSegmentOps

Header: `PDExpT.h:2518`

A path object consists of a sequence of segment operators (moveto, lineto, and so on), as well as a set of operations to be performed with the path. Note that the operations include doing nothing, closing, stroking, filling and using the path as a clip.

**Values**

- `pdSegMoveTo = 0`
- `pdSegLineTo = 1`
- `pdSegCurveTo = 2`
- `pdSegVCurveTo = 3`
- `pdSegYCurveTo = 4`
- `pdSegRect = 5`
- `pdSegClosePath = 6`

**See also:** [`PDPathPaintOp`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPathPaintOp)

## PDPref

### Functions (13)

#### PDPrefGetBlackPointCompensation

```cpp
ASBool PDPrefGetBlackPointCompensation(void)
```

Header: `PDProcs.h:11884`

Returns the black-point compensation flag.

**Parameters**

- (unnamed) (`void`)

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if black-point compensation is done.

**See also:** [`PDPrefSetBlackPointCompensation`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefSetBlackPointCompensation)

#### PDPrefGetColorCal

```cpp
ASBool PDPrefGetColorCal(PDColorCalP colorCal)
```

Header: `PDProcs.h:5385`

Gets the values to use for displaying the calibrated color and grayscale. These values are the chromaticity and gammas of the phosphors in the monitor. These values are used for rendering if calibrated color is enabled by the preferences file item avpDoCalibratedColor (see AVAppGetPreference()).

**Parameters**

- `colorCal` (`PDColorCalP`): IN/OUT (Filled by the method) A pointer to a structure that contains the color calibration information. For RGB devices, the red, green, and blue chromaticity and gammas are used; for grayscale, `whiteChrom` and `greenGamma` are used. You must allocate storage for the `colorCal` data structure and pass a pointer to the memory you allocated.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

Always returns `true`.

**See also:** [`PDPrefSetColorCal`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefSetColorCal), `AVAppGetPreference`

#### PDPrefGetDefaultBlendingColorSpace

```cpp
ASInt32 PDPrefGetDefaultBlendingColorSpace(void)
```

Header: `PDProcs.h:12796`

Get the default blending color space Index

**Parameters**

- (unnamed) (`void`)

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

value equal to 0 means default blending colorspace is Working CMYK, value equal to 1 means default blending colorspace is Working RGB.

#### PDPrefGetInstallPatternParentGState

```cpp
ASBool PDPrefGetInstallPatternParentGState(void)
```

Header: `PDProcs.h:12827`

Get the preference whether to install the graphics state that was in effect at the beginning of the pattern's parent content stream

**Parameters**

- (unnamed) (`void`)

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

value equal to 0 means apply current GState, value equal to 1 means install GState was in effect at the beginning of the pattern's parent content stream.

#### PDPrefGetUseOutputIntents

```cpp
ASBool PDPrefGetUseOutputIntents(void)
```

Header: `PDProcs.h:11863`

Returns the value of the Output Intent flag. When this flag is `true`, the system overrides the working space with the Output Intent, if it is present.

**Parameters**

- (unnamed) (`void`)

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

The Output Intent flag value.

**See also:** [`PDPrefSetUseOutputIntents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefSetUseOutputIntents)

#### PDPrefSetBlackPointCompensation

```cpp
void PDPrefSetBlackPointCompensation(ASBool kbpc)
```

Header: `PDProcs.h:11877`

Sets the black-point compensation flag, which controls whether to adjust for differences in black points when converting colors between color spaces. When enabled, the full dynamic range of the source space is mapped into the full dynamic range of the destination space. When disabled, the dynamic range of the source space is simulated in the destination space (which can result in blocked or gray shadows).

**Parameters**

- `kbpc` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): `true` to enable black-point compensation, `false` otherwise.

**Returns:** `void`

**See also:** [`PDPrefGetBlackPointCompensation`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefGetBlackPointCompensation)

#### PDPrefSetColorCal

```cpp
ASBool PDPrefSetColorCal(PDColorCalP colorCal)
```

Header: `PDProcs.h:5362`

Sets the values to use for displaying the calibrated color and grayscale. These values are the chromaticities and gammas of the phosphors in the monitor. These values do not necessarily correspond to the monitor being used; it is the responsibility of the client that sets these values to provide the correct values. These values are used for rendering if calibrated color is enabled by the preferences file item avpDoCalibratedColor (see AVAppSetPreference()).

**Parameters**

- `colorCal` (`PDColorCalP`): A pointer to a structure that contains the color calibration information. For RGB devices, the red, green, and blue chromaticities and gammas are used; for grayscale, `whiteChrom` and `greenGamma` are used.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the values were successfully set and installed for the currently active display device, `false` otherwise.

**See also:** [`PDPrefGetColorCal`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefGetColorCal), `AVAppSetPreference`

#### PDPrefSetDefaultBlendingColorSpace

```cpp
void PDPrefSetDefaultBlendingColorSpace(ASInt32 dBCSIndex)
```

Header: `PDProcs.h:12790`

Sets the default blending color space to working CMYK or working RGB

**Parameters**

- `dBCSIndex` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): An index to set blending color space. Pass 1 to set bcs as working RGB. Pass 0 or other value to set bcs as working CMYK.

**Returns:** `void`

#### PDPrefSetInstallPatternParentGState

```cpp
void PDPrefSetInstallPatternParentGState(ASBool bInstallPatternParentGStateFlag)
```

Header: `PDProcs.h:12821`

Sets the preference to install the graphics state that was in effect at the beginning of the pattern's parent content stream

**Parameters**

- `bInstallPatternParentGStateFlag` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Pass 1 to install GState was in effect at the beginning of the pattern's parent content stream

**Returns:** `void`

#### PDPrefSetUseOutputIntents

```cpp
void PDPrefSetUseOutputIntents(ASBool flag)
```

Header: `PDProcs.h:11854`

Sets the Output Intent flag.

**Parameters**

- `flag` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): When `true`, use Output Intent to override a working space if it is present.

**Returns:** `void`

**See also:** [`PDPrefGetUseOutputIntents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefGetUseOutputIntents)

#### PDPrefSetWorkingCMYK

```cpp
void PDPrefSetWorkingCMYK(void *profile, ASUns32 profileLength)
```

Header: `PDProcs.h:11908`

Sets the current CMYK working space to a given ICC profile. A CMYK working space in PDF is defined as a profile to substitute for a corresponding `/DeviceCMYK` space.

**Parameters**

- `profile` (`void *`): A pointer to a buffer containing the ICC color profile.
- `profileLength` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The length in bytes of the profile.

**Returns:** `void`

**See also:** [`PDPrefSetWorkingGray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefSetWorkingGray), [`PDPrefSetWorkingRGB`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefSetWorkingRGB)

#### PDPrefSetWorkingGray

```cpp
void PDPrefSetWorkingGray(void *profile, ASUns32 profileLength)
```

Header: `PDProcs.h:11922`

Sets the current gray working space to a given ICC profile. A Gray working space in PDF is defined as a profile to substitute for a corresponding `/DeviceGray` space. When rendering with overprint preview, the gray substitution is suppressed, to avoid converting grayscale to *rich black*.

**Parameters**

- `profile` (`void *`): A pointer to a buffer containing the ICC color profile.
- `profileLength` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The length in bytes of the profile.

**Returns:** `void`

**See also:** [`PDPrefSetWorkingCMYK`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefSetWorkingCMYK), [`PDPrefSetWorkingRGB`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefSetWorkingRGB)

#### PDPrefSetWorkingRGB

```cpp
void PDPrefSetWorkingRGB(void *profile, ASUns32 profileLength)
```

Header: `PDProcs.h:11896`

Set the current RGB working space to a given ICC profile. An RGB working space in PDF is defined as a profile to substitute for a corresponding `/DeviceRGB` space.

**Parameters**

- `profile` (`void *`): A pointer to a buffer containing the ICC color profile.
- `profileLength` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The length in bytes of the profile.

**Returns:** `void`

**See also:** [`PDPrefSetWorkingCMYK`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefSetWorkingCMYK), [`PDPrefSetWorkingGray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPrefSetWorkingGray)

## PDRedaction

### Functions (2)

#### PDRedactionGetProps

```cpp
ASBool PDRedactionGetProps(PDAnnot redactionAnnot, PDRedactParams redactionProps)
```

Header: `PDProcs.h:11964`

Retrieves a set of properties for a given redaction mark.

**Parameters**

- `redactionAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN The redaction mark whose properties are to be returned.
- `redactionProps` (`PDRedactParams`): OUT The set of properties to be filled by this method.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the properties were successfully returned, `false` otherwise.

**Exceptions**

- `pdErrBadAnnotation`

**See also:** [`PDDocApplyRedactions`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocApplyRedactions), [`PDDocCreateRedaction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateRedaction), [`PDRedactionSetProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRedactionSetProps)

#### PDRedactionSetProps

```cpp
ASBool PDRedactionSetProps(PDAnnot redactionAnnot, PDRedactParams redactionProps)
```

Header: `PDProcs.h:11976`

Assigns a set of properties to a given redaction mark.

**Parameters**

- `redactionAnnot` ([`PDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnot)): IN/OUT The redaction mark whose properties are to be assigned.
- `redactionProps` (`PDRedactParams`): IN The set of properties to be assigned by this method.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the properties were successfully assigned, `false` otherwise.

**Exceptions**

- `pdErrBadAnnotation`

**See also:** [`PDDocApplyRedactions`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocApplyRedactions), [`PDDocCreateRedaction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateRedaction), [`PDRedactionGetProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDRedactionGetProps)

## PDStyle

### Functions (3)

#### PDStyleGetColor

```cpp
void PDStyleGetColor(PDStyle obj, PDColorValue color)
```

Header: `PDProcs.h:5194`

Gets a style's color.

**Parameters**

- `obj` ([`PDStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyle)): IN/OUT The style whose color is obtained.
- `color` (`PDColorValue`): IN/OUT (Filled by the method) A pointer to a structure that contains the style's color.

**Returns:** `void`

**See also:** [`PDStyleGetFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyleGetFont), [`PDStyleGetFontSize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyleGetFontSize)

#### PDStyleGetFont

```cpp
PDFont PDStyleGetFont(PDStyle obj)
```

Header: `PDProcs.h:5172`

Gets the specified style's font.

**Parameters**

- `obj` ([`PDStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyle)): IN/OUT The style whose font is obtained.

**Returns:** [`PDFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFont)

The font for the specified style.

**See also:** [`PDStyleGetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyleGetColor), [`PDStyleGetFontSize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyleGetFontSize)

#### PDStyleGetFontSize

```cpp
ASFixed PDStyleGetFontSize(PDStyle obj)
```

Header: `PDProcs.h:5182`

Get a style's font size.

**Parameters**

- `obj` ([`PDStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyle)): The style whose font size is obtained.

**Returns:** [`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)

The size of the font in points.

**See also:** [`PDStyleGetColor`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyleGetColor), [`PDStyleGetFont`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyleGetFont)

### Structures (1)

#### PDStyle

```cpp
typedef struct _t_PDStyle* PDStyle
```

Header: `PDExpT.h:3398`

Provides access to information about the fonts, font sizes, and colors used in a PDWord.

**See also:** [`PDWordGetNthCharStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNthCharStyle)

## PDText

### Functions (2)

#### PDTextEnum

```cpp
void PDTextEnum(PDText text, PDStringEnumProc enumProc, void *clientData)
```

Header: `PDProcs.h:3676`

Enumerates the strings of a text object, calling a procedure for each string. The PDText object may be obtained from the PDGraphicEnumTextProc() callback of PDGraphicEnumMonitor.

**Parameters**

- `text` ([`PDText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDText)): IN/OUT The text object whose strings are enumerated.
- `enumProc` ([`PDStringEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStringEnumProc)): IN/OUT A user-supplied callback to call for each text string in the text object. Enumeration ends if `enumProc` returns `false`.
- `clientData` (`void *`): IN/OUT A pointer to user-supplied data to pass to `enumProc` each time it is called.

**Returns:** `void`

#### PDTextGetState

```cpp
void PDTextGetState(PDText obj, PDTextStateP stateP, ASInt32 stateLen)
```

Header: `PDProcs.h:3690`

Gets the text state for a text object. See Section 5.2 in the *PDF Reference* for a discussion of the text state parameters.

**Parameters**

- `obj` ([`PDText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDText)): IN/OUT The text object whose text state is obtained.
- `stateP` (`PDTextStateP`): IN/OUT (Filled by the method) A pointer to a `PDTextState` structure containing the text state information.
- `stateLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT It must be `sizeof(PDTextState)`.

**Returns:** `void`

### Typedefs (1)

#### PDStringEnumProc

```cpp
typedef ASBool(*) PDStringEnumProc(PDFont font, char *string, ASInt32 stringLen, ASFixed delta, void *clientData)(PDFont font, char *string, ASInt32 stringLen, ASFixed delta, void *clientData)
```

Header: `PDExpT.h:3079`

A callback for PDTextEnum(). It is called once for each string in a text object. You can find this document on the web store of the International Standards Organization (ISO).

**See also:** [`PDTextEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextEnum)

### Structures (1)

#### PDText

```cpp
typedef struct _t_PDGraphic * PDText
```

Header: `PDExpT.h:2499`

## PDTextAnnot

### Functions (6)

#### PDTextAnnotGetContents

```cpp
ASInt32 PDTextAnnotGetContents(PDTextAnnot aTextAnnot, char *buffer, ASInt32 bufSize)
```

Header: `PDProcs.h:588`

Gets the text of a text annotation. @note This text is stored in either PDFDocEncoding or in Unicode. If it is stored in Unicode, a valid Byte Order Mark must be present.

**Parameters**

- `aTextAnnot` ([`PDTextAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnot)): The text annotation whose text is obtained.
- `buffer` (`char *`): (Filled by the method) A buffer into which
  the text is placed. If the text is encoded using `PDFDocEncoding`,
  it can be converted to a platform's native encoding using
  PDXlateToHost() or PDXlateToHostEx().`buffer`
  can hold.`buffer`.
- `bufSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

**See also:** [`PDTextAnnotSetContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnotSetContents), [`PDXlateToPDFDocEnc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEnc), [`PDXlateToPDFDocEncEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEncEx)

#### PDTextAnnotGetContentsASText

```cpp
void PDTextAnnotGetContentsASText(PDTextAnnot aTextAnnot, ASText contents)
```

Header: `PDProcs.h:11479`

Gets the text of a text annotation as an ASText object.

**Parameters**

- `aTextAnnot` ([`PDTextAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnot)): The text annotation whose text is obtained.
- `contents` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The text object containing the contents. The client must pass a valid ASText object title. The routine does not allocate it.

**Returns:** `void`

**See also:** [`PDTextAnnotGetContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnotGetContents), [`PDTextAnnotSetContentsASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnotSetContentsASText), [`PDTextAnnotSetContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnotSetContents)

#### PDTextAnnotIsOpen

```cpp
ASBool PDTextAnnotIsOpen(PDTextAnnot aTextAnnot)
```

Header: `PDProcs.h:630`

Tests whether a text annotation is open. **Note:** This method cannot always correctly determine a text annotation's open state. For the current version of Acrobat, text and other annotations have an associated Popup annotation which maintains the open state of the popup window; the method works correctly when you pass it the popup annotation itself. You can use Cos-level routines to find the Popup entry in the annotation dictionary, which is itself a dictionary containing an Open entry.

**Parameters**

- `aTextAnnot` ([`PDTextAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnot)): The text annotation whose open/closed state is obtained.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the annotation is open, `false` otherwise.

**See also:** [`PDTextAnnotSetOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnotSetOpen)

#### PDTextAnnotSetContents

```cpp
void PDTextAnnotSetContents(PDTextAnnot aTextAnnot, const char *str, ASInt32 nBytes)
```

Header: `PDProcs.h:610`

Sets the text of a text annotation. This method also sets the modification date of the annotation to the current date and time. @note The text must be encoded using `PDFDocEncoding` or Unicode. @notify PDAnnotWillChange @notify PDAnnotDidChange @since

**Parameters**

- `aTextAnnot` ([`PDTextAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnot)): The text annotation whose text is set.
- `str` (`const char *`): A string containing the new text. The string
  must be encoded using `PDFDocEncoding` or Unicode. The strings
  in a platform's native encoding can be converted to `PDFDocEncoding`
  using PDXlateToPDFDocEnc() or PDXlateToPDFDocEncEx().`str`.
- `nBytes` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))

**Returns:** `void`

**See also:** [`PDTextAnnotGetContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnotGetContents), [`PDXlateToPDFDocEnc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEnc), [`PDXlateToPDFDocEncEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXlateToPDFDocEncEx)

#### PDTextAnnotSetContentsASText

```cpp
void PDTextAnnotSetContentsASText(PDTextAnnot aTextAnnot, const ASText contents)
```

Header: `PDProcs.h:11494`

Sets the text of a text annotation. @notify PDAnnotWillChange @notify PDAnnotDidChange

**Parameters**

- `aTextAnnot` ([`PDTextAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnot)): The text annotation whose text is set.
- `contents` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the new text.

**Returns:** `void`

**See also:** [`PDTextAnnotSetContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnotSetContents), [`PDTextAnnotGetContentsASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnotGetContentsASText), [`PDTextAnnotGetContents`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnotGetContents)

#### PDTextAnnotSetOpen

```cpp
void PDTextAnnotSetOpen(PDTextAnnot aTextAnnot, ASBool isOpen)
```

Header: `PDProcs.h:651`

Opens or closes a text annotation. **Note:** This method cannot always correctly set a text annotation's open state. For the current version of Acrobat, text and other annotations have an associated Popup annotation which maintains the open state of the popup window; the method works correctly when you pass it the popup annotation itself. You can use Cos-level routines to find the Popup entry in the annotation dictionary, which is itself a dictionary containing an Open entry.

**Parameters**

- `aTextAnnot` ([`PDTextAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnot)): The annotation to open or close.
- `isOpen` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): `true` if the annotation is opened, `false` if the annotation is closed. @notify PDAnnotWillChange @notify PDAnnotDidChange

**Returns:** `void`

**See also:** [`PDTextAnnotIsOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextAnnotIsOpen)

### Typedefs (1)

#### PDTextAnnot

```cpp
typedef OPAQUE_64_BITS PDTextAnnot
```

Header: `PDExpT.h:345`

A PDF text annotation on a page in a PDF file. You can use any PDAnnot method on a PDTextAnnot. Applications can: Get and set attributes including the rectangle, textual contents, and whether the annotation is open. Create new text annotations, and delete or move existing ones using PDAnnot methods. Manipulate the behavior of text annotations by modifying the Text Annotation Handler. To obtain a PDF text annotation, use any of the PDAnnot calls, followed by CastToPDTextAnnot(). The annotation passed to CastToPDTextAnnot() must be a text annotation; it will not convert other annotation types into text annotations.

**See also:** [`CastToPDTextAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#CastToPDTextAnnot), [`PDPageRemoveAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageRemoveAnnot)

### Definitions (1)

#### CastToPDTextAnnot

Header: `PDExpT.h:440`

Value: `*(PDTextAnnot *)&(a)`

Casts a link annotation or a generic annotation to a text annotation.

**See also:** [`CastToPDAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#CastToPDAnnot), [`CastToPDLinkAnnot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#CastToPDLinkAnnot)

## PDTextSelect

### Functions (14)

#### PDTextSelectCreatePageHilite

```cpp
PDTextSelect PDTextSelectCreatePageHilite(PDPage page, HiliteEntry *hList, ASInt32 listLen)
```

Header: `PDProcs.h:4616`

Creates a text selection from a page and a list of highlights specified as character offsets from the start of the page. Character offsets are a well-defined quantity in the PDF file, and are therefore stable against revisions of the word-finding algorithm, which makes them a good way to isolate yourself from changes in the algorithm. This method does not highlight the text selection. That occurs when you pass the PDTextSelect returned by this method to AVDocSetSelection(). **Note:** As is the case with the Acrobat viewer, the text selection is always of whole words, not part of words.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page on which the highlights appear.
- `hList` (`HiliteEntry *`): A pointer to an array of highlight entries. If the `length` field of a `HiliteEntry` is `0`, the entire word is highlighted. `hList` should not contain multiple instances of the same highlight; the display appearance is undefined when it does.
- `listLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of highlight entries in `hList`.

**Returns:** [`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)

The newly created text selection.

**See also:** `AVDocSetSelection`, [`PDTextSelectCreateWordHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHilite), [`PDTextSelectCreateWordHiliteEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHiliteEx), [`PDTextSelectCreateRanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRanges), [`PDTextSelectCreateRangesEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRangesEx), [`PDTextSelectCreatePageHiliteEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHiliteEx), [`PDDocCreateTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateTextSelect), [`PDTextSelectDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectDestroy)

#### PDTextSelectCreatePageHiliteEx

```cpp
PDTextSelect PDTextSelectCreatePageHiliteEx(PDPage page, HiliteEntry *hList, ASInt32 listLen, ASInt16 WFVersion)
```

Header: `PDProcs.h:8194`

Adds the `WFVersion` parameter to PDTextSelectCreatePageHilite(). It is the same as PDTextSelectCreatePageHilite(), but it creates a WordFinder using the specified version number. It is intended to be used by plug-ins that want to do text highlighting with previous versions of the word finder algorithm. Annotation Use WF_LATEST_VERSION To obtain the latest available version. WF_VERSION_2 Version used for Acrobat 3.x, 4.x. WF_VERSION_3 Available in Acrobat 5.0 without Accessibility enabled. Includes some improved word-piecing algorithms. WF_VERSION_4 For Acrobat 5.0 with Accessibility enabled. Includes advanced word-ordering algorithms in addition to improved word-piecing algorithms.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page on which the highlights appear.
- `hList` (`HiliteEntry *`): A pointer to an array of highlight entries. If the `length` field of a `HiliteEntry` is `0`, the entire word is highlighted. `hList` should not contain multiple instances of the same highlight; the display appearance is undefined when it does.
- `listLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of highlight entries in `hList`.
- `WFVersion` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): The WordFinder version:

**Returns:** [`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)

The newly created text selection.

**See also:** `AVDocSetSelection`, [`PDTextSelectCreateWordHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHilite), [`PDTextSelectCreateWordHiliteEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHiliteEx), [`PDTextSelectCreatePageHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHilite), [`PDTextSelectCreateRanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRanges), [`PDTextSelectCreateRangesEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRangesEx), [`PDDocCreateTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateTextSelect), [`PDTextSelectDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectDestroy)

#### PDTextSelectCreateRanges

```cpp
PDTextSelect PDTextSelectCreateRanges(PDPage page, PDTextSelectRange range, ASInt32 rangeCount)
```

Header: `PDProcs.h:4703`

Creates a text selection from one or more ranges. This method does not highlight the text selection. That occurs when you pass the PDTextSelect returned by this method to AVDocSetSelection().

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page on which the text appears.
- `range` (`PDTextSelectRange`): IN/OUT A pointer to an array of ranges that are used to create a text selection. Each array element is a PDTextSelectRange structure.
- `rangeCount` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The number of ranges in range.

**Returns:** [`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)

A text selection created from the specified ranges.

**See also:** `AVDocSetSelection`, [`PDTextSelectCreateRangesEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRangesEx), [`PDTextSelectCreatePageHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHilite), [`PDTextSelectCreatePageHiliteEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHiliteEx), [`PDTextSelectCreateWordHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHilite), [`PDTextSelectCreateWordHiliteEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHiliteEx), [`PDTextSelectDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectDestroy)

#### PDTextSelectCreateRangesEx

```cpp
PDTextSelect PDTextSelectCreateRangesEx(PDPage page, PDTextSelectRange range, ASInt32 rangeCount, ASInt16 WFVersion)
```

Header: `PDProcs.h:8261`

Adds the `WFVersion` parameter to PDTextSelectCreateRanges(). It is the same as PDTextSelectCreateRanges() but it creates a WordFinder using the specified version number. It is intended to be used by plug-ins that want to do text highlighting with previous versions of the word finder algorithm. Annotation Use WF_LATEST_VERSION To obtain latest the available version. WF_VERSION_2 Version used for Acrobat 3.x, 4.x. WF_VERSION_3 Available in Acrobat 5.0 without Accessibility enabled. Includes some improved word-piecing algorithms. WF_VERSION_4 For Acrobat 5.0 with Accessibility enabled. Includes advanced word-ordering algorithms in addition to improved word-piecing algorithms.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): IN/OUT The page on which the text appears.
- `range` (`PDTextSelectRange`): IN/OUT A pointer to an array of ranges that are used to create a text selection. Each array element is a PDTextSelectRange structure.
- `rangeCount` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The number of ranges in range.
- `WFVersion` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): IN/OUT The WordFinder version:

**Returns:** [`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)

A text selection created from the specified ranges.

**See also:** `AVDocSetSelection`, [`PDTextSelectCreatePageHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHilite), [`PDTextSelectCreatePageHiliteEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHiliteEx), [`PDTextSelectCreateRanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRanges), [`PDTextSelectCreateWordHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHilite), [`PDTextSelectCreateWordHiliteEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHiliteEx), [`PDTextSelectDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectDestroy)

#### PDTextSelectCreateWordHilite

```cpp
PDTextSelect PDTextSelectCreateWordHilite(PDPage page, HiliteEntry *hList, ASInt32 listLen)
```

Header: `PDProcs.h:4647`

Creates a text selection from a list of highlights specified as word offsets from the start of the page. Word offsets are not well-defined in PDF files, but are calculated by the word-finding algorithm. As a result, word offsets will, in general, differ in different versions of the word-finding algorithm. If you choose to store word offsets, you must also store the version of the word-finding algorithm from which they are obtained using PDWordFinderGetLatestAlgVersion(). This method does not highlight the text selection. That occurs when you pass the PDTextSelect returned by this method to AVDocSetSelection().

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page on which the highlights appear.
- `hList` (`HiliteEntry *`): A pointer to an array of highlight entries. `hList` should not contain multiple instances of the same highlight; the display appearance is undefined when it does.
- `listLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of highlight entries in `hList`.

**Returns:** [`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)

The newly created text selection.

**See also:** `AVDocSetSelection`, [`PDTextSelectCreateRanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRanges), [`PDTextSelectCreateRangesEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRangesEx), [`PDTextSelectCreatePageHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHilite), [`PDTextSelectCreatePageHiliteEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHiliteEx), [`PDTextSelectCreateWordHiliteEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHiliteEx), [`PDWordFinderGetLatestAlgVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderGetLatestAlgVersion), [`PDTextSelectDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectDestroy)

#### PDTextSelectCreateWordHiliteEx

```cpp
PDTextSelect PDTextSelectCreateWordHiliteEx(PDPage page, HiliteEntry *hList, ASInt32 listLen, ASInt16 WFVersion)
```

Header: `PDProcs.h:8226`

Adds the `WFVersion` parameter to PDTextSelectCreateWordHilite(). Annotation Use WF_LATEST_VERSION To obtain the latest available version. WF_VERSION_2 Version used for Acrobat 3.x, 4.x. WF_VERSION_3 Available in Acrobat 5.0 without Accessibility enabled. Includes some improved word-piecing algorithms. WF_VERSION_4 For Acrobat 5.0 with Accessibility enabled. Includes advanced word-ordering algorithms in addition to improved word-piecing algorithms.

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page on which the highlights appear.
- `hList` (`HiliteEntry *`): A pointer to an array of highlight entries. `hList` should not contain multiple instances of the same highlight; the display appearance is undefined when it does.
- `listLen` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of highlight entries in `hList`.
- `WFVersion` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): The WordFinder version:

**Returns:** [`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)

The newly created text selection.

**See also:** `AVDocSetSelection`, [`PDTextSelectCreateRanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRanges), [`PDTextSelectCreateRangesEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRangesEx), [`PDTextSelectCreatePageHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHilite), [`PDTextSelectCreatePageHiliteEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHiliteEx), [`PDTextSelectCreateWordHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHilite), [`PDWordFinderGetLatestAlgVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderGetLatestAlgVersion), [`PDTextSelectDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectDestroy)

#### PDTextSelectDestroy

```cpp
void PDTextSelectDestroy(PDTextSelect text)
```

Header: `PDProcs.h:4506`

Deletes a text selection object (the text on the page remains unchanged). Do not use this method to destroy a text selection that was passed to AVDocSetSelection(); such text selections are automatically destroyed when a new selection is made or the selection is cleared.

**Parameters**

- `text` ([`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)): IN/OUT The text selection to destroy.

**Returns:** `void`

**See also:** [`PDDocCreateTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateTextSelect), [`PDTextSelectCreatePageHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHilite), [`PDTextSelectCreateRanges`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateRanges), [`PDTextSelectCreateWordHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreateWordHilite)

#### PDTextSelectEnumQuads

```cpp
void PDTextSelectEnumQuads(PDTextSelect text, PDTextSelectEnumQuadProc proc, void *procObj)
```

Header: `PDProcs.h:4526`

Enumerates the bounding quads in a text selection. `proc` is called for each quad. If a word is on a curve it may have a quad for each character, but it may also have two characters per quad. An upright word will have only one quad for all the characters. An upright hyphenated word will have two quads.

**Parameters**

- `text` ([`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)): IN/OUT The text selection whose bounding quads are enumerated.
- `proc` ([`PDTextSelectEnumQuadProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumQuadProc)): IN/OUT A user-supplied callback to call for each quad. Enumeration halts if `proc` returns `false`.
- `procObj` (`void *`): IN/OUT A user-supplied data to pass to `proc` each time it is called.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`

**See also:** [`PDDocCreateTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateTextSelect)

#### PDTextSelectEnumText

```cpp
void PDTextSelectEnumText(PDTextSelect text, PDTextSelectEnumTextProc proc, void *procObj)
```

Header: `PDProcs.h:4552`

Enumerates the strings of the specified text select object, calling a procedure for each string. A string, in this context, is the set of like-styled characters within a word. It is never larger than a single word. A word containing three styles is enumerated as three strings. There is no guaranteed correspondence between these strings and the actual show strings in the PDF file. Acrobat enumerates text in the order it appears in the PDF file, which is often not the same as the order in which a person would read the text.

**Parameters**

- `text` ([`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)): IN/OUT The text selection whose strings are enumerated.
- `proc` ([`PDTextSelectEnumTextProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumTextProc)): IN/OUT A user-supplied callback to call for each string in the text object. Enumeration ends if `proc` returns `false`.
- `procObj` (`void *`): IN/OUT User-supplied data to pass to `proc` each time it is called.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`
- `pdErrOpNotPermitted`

**See also:** [`PDDocCreateTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateTextSelect)

#### PDTextSelectEnumTextUCS

```cpp
void PDTextSelectEnumTextUCS(PDTextSelect textP, PDTextSelectEnumTextProc proc, void *procData)
```

Header: `PDProcs.h:7998`

Same as PDTextSelectEnumText(), except the output is forced to UCS.

**Parameters**

- `textP` ([`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)): IN/OUT The text selection whose strings are enumerated.
- `proc` ([`PDTextSelectEnumTextProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumTextProc)): IN/OUT A user-supplied callback to call for each string in the text object. Enumeration ends if `proc` returns `false`.
- `procData` (`void *`): IN/OUT User-supplied data to pass to `proc` each time it is called.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`

**See also:** [`PDDocCreateTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateTextSelect), [`PDTextSelectEnumText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumText)

#### PDTextSelectGetBoundingRect

```cpp
void PDTextSelectGetBoundingRect(PDTextSelect text, ASFixedRect *boundRectP)
```

Header: `PDProcs.h:4582`

Gets a text selection's bounding rectangle. This is the smallest rectangle that completely encloses all characters in the selection.

**Parameters**

- `text` ([`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)): IN/OUT The text selection whose bounding rectangle is determined.
- `boundRectP` (`ASFixedRect *`): IN/OUT (Filled by the method) A pointer to the text selection's bounding rectangle, specified in user space coordinates.

**Returns:** `void`

**See also:** [`PDTextSelectGetPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetPage), [`PDTextSelectGetRange`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetRange), [`PDTextSelectGetRangeCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetRangeCount)

#### PDTextSelectGetPage

```cpp
ASInt32 PDTextSelectGetPage(PDTextSelect text)
```

Header: `PDProcs.h:4565`

Gets the page number of a text selection's page.

**Parameters**

- `text` ([`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)): IN/OUT The text selection whose page number is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The page number of the text selection's page.

**See also:** [`PDTextSelectGetBoundingRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetBoundingRect), [`PDTextSelectGetRange`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetRange), [`PDTextSelectGetRangeCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetRangeCount)

#### PDTextSelectGetRange

```cpp
void PDTextSelectGetRange(PDTextSelect textP, ASInt32 index, PDTextSelectRange range)
```

Header: `PDProcs.h:4665`

Extracts the range specified by index from a text selection. Use PDTextSelectGetRangeCount() to determine the number of ranges in a text selection.

**Parameters**

- `textP` ([`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)): IN/OUT The text selection from which a range is extracted.
- `index` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The index of the range to extract from `textP`.
- `range` (`PDTextSelectRange`): IN/OUT (Filled by the method) A pointer to a structure that contains the specified range.

**Returns:** `void`

**See also:** [`PDTextSelectGetBoundingRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetBoundingRect), [`PDTextSelectGetPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetPage), [`PDTextSelectGetRangeCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetRangeCount)

#### PDTextSelectGetRangeCount

```cpp
ASInt32 PDTextSelectGetRangeCount(PDTextSelect textP)
```

Header: `PDProcs.h:4679`

Gets the number of ranges in a text selection. Use PDTextSelectGetRange() to extract a single range from a text selection.

**Parameters**

- `textP` ([`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)): IN/OUT The text selection whose range count is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The number of ranges in the text selection.

**See also:** [`PDTextSelectGetBoundingRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetBoundingRect), [`PDTextSelectGetPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetPage), [`PDTextSelectGetRange`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectGetRange)

### Typedefs (3)

#### PDTextSelectEnumQuadProc

```cpp
typedef ASBool(*) PDTextSelectEnumQuadProc(void *procObj, ASInt32 page, ASFixedQuad *quad)(void *procObj, ASInt32 page, ASFixedQuad *quad)
```

Header: `PDExpT.h:3184`

A callback for PDTextSelectEnumQuads(). It is called once for each quad in a text selection.

**See also:** [`PDTextSelectEnumQuads`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumQuads)

#### PDTextSelectEnumRTFTextProc

```cpp
typedef ASBool(*) PDTextSelectEnumRTFTextProc(void *procObj, PDFont font, ASFixed size, PDColorValue color, char *text, ASUns32 rtfCntFlag, ASInt32 textLen)(void *procObj, PDFont font, ASFixed size, PDColorValue color, char *text, ASUns32 rtfCntFlag, ASInt32 textLen)
```

Header: `PDExpT.h:3209`

#### PDTextSelectEnumTextProc

```cpp
typedef ASBool(*) PDTextSelectEnumTextProc(void *procObj, PDFont font, ASFixed size, PDColorValue color, char *text, ASInt32 textLen)(void *procObj, PDFont font, ASFixed size, PDColorValue color, char *text, ASInt32 textLen)
```

Header: `PDExpT.h:3204`

A callback for PDTextSelectEnumText() and PDTextSelectEnumTextUCS(). It is called once for each text run (which is text in the same font, size, color, and on the same line) in a text selection.

**See also:** [`PDTextSelectEnumText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumText), [`PDTextSelectEnumTextUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumTextUCS)

### Structures (1)

#### PDTextSelect

```cpp
typedef struct _t_PDTextSelect* PDTextSelect
```

Header: `PDBasicExpT.h:131`

A pointer to a PDTextSelect `struct`.

### Definitions (6)

#### PDTextSelectCreatePageHilite

Header: `PDCalls.h:161`

Value: `PDTextSelectCreatePageHiliteHost`

#### PDTextSelectCreateRanges

Header: `PDCalls.h:163`

Value: `PDTextSelectCreateRangesHost`

#### PDTextSelectCreateWordHilite

Header: `PDCalls.h:162`

Value: `PDTextSelectCreateWordHiliteHost`

#### PDTextSelectEnumQuads

Header: `PDCalls.h:158`

Value: `PDTextSelectEnumQuadsHost`

#### PDTextSelectEnumText

Header: `PDCalls.h:159`

Value: `PDTextSelectEnumTextHost`

#### PDTextSelectGetBoundingRect

Header: `PDCalls.h:160`

Value: `PDTextSelectGetBoundingRectHost`

## PDThread

### Functions (11)

#### PDThreadDestroy

```cpp
void PDThreadDestroy(PDThread thread)
```

Header: `PDProcs.h:4077`

Deletes an article thread from its document. You must call PDDocRemoveThread() to remove the thread from the document (if it was added to one using PDDocAddThread()) before calling PDThreadDestroy().

**Parameters**

- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): IN/OUT The thread to destroy.

**Returns:** `void`

**See also:** [`PDThreadNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadNew), [`PDThreadFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadFromCosObj), [`PDDocRemoveThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemoveThread)

#### PDThreadFromCosObj

```cpp
PDThread PDThreadFromCosObj(CosObj obj)
```

Header: `PDProcs.h:4180`

Gets the thread object corresponding to the specified Cos object. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary Cos object for the thread.

**Returns:** [`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)

The PDThread object for the thread.

**Exceptions**

- `pdErrBadThread`: is raised if the thread is not valid as defined by PDThreadIsValid.

**See also:** [`PDThreadGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadGetCosObj)

#### PDThreadGetCosObj

```cpp
CosObj PDThreadGetCosObj(PDThread thread)
```

Header: `PDProcs.h:4167`

Gets the Cos object corresponding to a thread. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): IN/OUT The thread whose Cos object is to obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The dictionary Cos object for the thread. The contents of the dictionary can be enumerated using CosObjEnum(). It returns a `NULL` Cos object if `PDThreadIsValid(thread)` returns `false`.

**See also:** [`CosObjEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEnum), [`PDThreadFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadFromCosObj)

#### PDThreadGetFirstBead

```cpp
PDBead PDThreadGetFirstBead(PDThread thread)
```

Header: `PDProcs.h:4091`

Gets an article thread's first bead.

**Parameters**

- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): IN/OUT The thread whose first bead is obtained.

**Returns:** [`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)

The thread's first bead, or a `NULL` Cos object if the thread has no beads.

**See also:** [`PDThreadSetFirstBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadSetFirstBead), [`PDBeadGetNext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetNext), [`PDBeadGetPrev`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetPrev)

#### PDThreadGetInfo

```cpp
ASInt32 PDThreadGetInfo(PDThread thread, const char *infoKey, char *buffer, ASInt32 bufSize)
```

Header: `PDProcs.h:4123`

Gets the specified article thread's info. @note This text is stored in either PDFDocEncoding or in Unicode. If it is stored in Unicode, a valid Byte Order Mark must be present.

**Parameters**

- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): IN/OUT The thread whose thread info is obtained.
- `infoKey` (`const char *`): IN/OUT The key whose value is obtained.
- `buffer` (`char *`): IN/OUT (Filled by the method) The value associated
  with `infoKey`.`buffer`
  can hold.`buffer`.
- `bufSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32))

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

**See also:** [`PDThreadSetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadSetInfo)

#### PDThreadGetInfoASText

```cpp
void PDThreadGetInfoASText(PDThread thread, const ASText infoKey, ASText value)
```

Header: `PDProcs.h:11685`

Gets the specified article thread's info as an ASText object.

**Parameters**

- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): The thread whose thread info is being obtained.
- `infoKey` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The key whose value is being obtained.
- `value` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The text object containing the value associated with `infoKey` is set. The client must pass a valid ASText object value. The routine does not allocate it.

**Returns:** `void`

**See also:** [`PDThreadGetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadGetInfo), [`PDThreadSetInfoASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadSetInfoASText), [`PDThreadSetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadSetInfo)

#### PDThreadIsValid

```cpp
ASBool PDThreadIsValid(PDThread thread)
```

Header: `PDProcs.h:4150`

Tests whether a thread is valid. This is intended only to ensure that the thread has not been deleted, not to ensure that all necessary information is present and valid.

**Parameters**

- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): The thread whose validity is tested.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the thread is valid, `false` otherwise.

#### PDThreadNew

```cpp
PDThread PDThreadNew(PDDoc aDocP)
```

Header: `PDProcs.h:4063`

Creates a new article thread. Use PDDocAddThread() to add the thread to a document.

**Parameters**

- `aDocP` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the thread is created.

**Returns:** [`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)

The newly created thread.

**See also:** [`PDThreadDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadDestroy), [`PDThreadFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadFromCosObj), [`PDDocAddThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocAddThread)

#### PDThreadSetFirstBead

```cpp
void PDThreadSetFirstBead(PDThread thread, PDBead newFirstBead)
```

Header: `PDProcs.h:4103`

Sets an article thread's first bead.

**Parameters**

- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): IN/OUT The thread whose first bead is set.
- `newFirstBead` ([`PDBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBead)): IN/OUT The bead to use as the first in thread.

**Returns:** `void`

**See also:** [`PDThreadGetFirstBead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadGetFirstBead), [`PDBeadInsert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadInsert)

#### PDThreadSetInfo

```cpp
void PDThreadSetInfo(PDThread thread, const char *infoKey, const char *buffer, ASInt32 bufSize)
```

Header: `PDProcs.h:4140`

Sets the specified article thread's info. @notify PDThreadDidChange @note This text is stored in either PDFDocEncoding or in Unicode. If it is stored in Unicode, a valid Byte Order Mark must be present.

**Parameters**

- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): IN/OUT The thread whose thread info is set.
- `infoKey` (`const char *`): IN/OUT The key whose value is set.
- `buffer` (`const char *`): IN/OUT The value to set.
- `bufSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The number of characters in `buffer`.

**Returns:** `void`

**See also:** [`PDThreadGetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadGetInfo)

#### PDThreadSetInfoASText

```cpp
void PDThreadSetInfoASText(PDThread thread, const ASText infoKey, const ASText value)
```

Header: `PDProcs.h:11700`

Sets the specified article thread's info.

**Parameters**

- `thread` ([`PDThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThread)): The thread whose thread info is being set.
- `infoKey` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The key whose value is being set.
- `value` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the value to set.

**Returns:** `void`

**See also:** [`PDThreadSetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadSetInfo), [`PDThreadGetInfoASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadGetInfoASText), [`PDThreadGetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadGetInfo)

### Typedefs (1)

#### PDThread

```cpp
typedef OPAQUE_64_BITS PDThread
```

Header: `PDExpT.h:3230`

An article in the Acrobat viewer's user interface. It contains an ordered sequence of rectangles that bound the article. Each rectangle is called a bead. Threads can be created either interactively, by the user, or programmatically.

**See also:** [`PDDocGetThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetThread), [`PDThreadNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadNew), [`PDThreadFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadFromCosObj), [`PDBeadGetThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDBeadGetThread), [`PDDocRemoveThread`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocRemoveThread), [`PDThreadDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThreadDestroy)

## PDThumb

### Functions (2)

#### PDThumbGetImageData

```cpp
ASStm PDThumbGetImageData(PDThumb thumb, ASInt32 *height, ASInt32 *width, ASInt32 *bpc, ASAtom *csName)
```

Header: `PDProcs.h:11811`

Gets an ASStm from a thumbnail data.

**Parameters**

- `thumb` ([`PDThumb`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThumb)): The thumb for which image data is to be retrieved.
- `height` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): (Filled by the method) The height of the thumbnail.
- `width` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): (Filled by the method) The width of the thumbnail.
- `bpc` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): (Filled by the method) The number of bits per component in the thumbnail image's data.
- `csName` ([`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): (Filled by the method) The color space in which thumnail data is represented.

**Returns:** [`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)

An ASStm for the thumbnail data.

**See also:** [`PDThumbGetIndexedColorSpace`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThumbGetIndexedColorSpace), [`PDThumbCreationDrawThumbProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThumbCreationDrawThumbProc)

#### PDThumbGetIndexedColorSpace

```cpp
ASStm PDThumbGetIndexedColorSpace(PDThumb thumb, ASInt32 *hival, ASAtom *baseColorSpaceName)
```

Header: `PDProcs.h:11822`

Gets an ASStm from a thumbnail's indexed color space table.

**Parameters**

- `thumb` ([`PDThumb`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThumb)): The thumb for which image data is to be retrieved.
- `hival` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): (Filled by the method) The highest valid index in the lookup table for the Indexed color space.
- `baseColorSpaceName` ([`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): (Filled by the method) The base color space in which the values in the color table are to be interpreted.

**Returns:** [`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)

An ASStm from the thumbnail's indexed color space table.

**See also:** [`PDThumbGetImageData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThumbGetImageData), [`PDThumbCreationDrawThumbProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThumbCreationDrawThumbProc)

### Typedefs (3)

#### PDThumbCreationDrawThumbProc

```cpp
typedef void(*) PDThumbCreationDrawThumbProc(PDThumb thumb, void *clientData)(PDThumb thumb, void *clientData)
```

Header: `PDExpT.h:3316`

(Optional) A callback for PDThumbCreationServer. It is called after PDThumbCreationGetThumbDataProc() and after a PDThumb has been created. It gives the server a chance to draw the thumbnail image in a status window. It may be `NULL`.

**See also:** [`PDThumbCreationGetThumbDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDThumbCreationGetThumbDataProc), [`PDDocCreateThumbs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateThumbs)

#### PDThumbCreationGetThumbDataProc

```cpp
typedef ASBool(*) PDThumbCreationGetThumbDataProc(PDPage page, ASFixed thumbScale, ASInt32 width, ASInt32 height, void *thumbData, void *clientData)(PDPage page, ASFixed thumbScale, ASInt32 width, ASInt32 height, void *thumbData, void *clientData)
```

Header: `PDExpT.h:3301`

(Optional) A callback for PDThumbCreationServer. It is called for each page that does not currently contain a thumbnail image. It may be `NULL`. If it is `NULL`, the thumbnail data is generated by the default thumbnail generator. where `bitsPerPixel` is specified as `numComponents * bitsPerComponent`. `numComponents` is dependent upon the color space. For DeviceRGB, `numComponents` is `3`. For an indexed color space, `numComponents` is `1`.

**See also:** [`PDDocCreateThumbs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateThumbs)

#### PDThumbCreationNotifyPageProc

```cpp
typedef ASBool(*) PDThumbCreationNotifyPageProc(ASInt32 pageNum, void *clientData)(ASInt32 pageNum, void *clientData)
```

Header: `PDExpT.h:3268`

(Optional) A callback for PDThumbCreationServer. It is called before processing each page. It may be `NULL`.

**See also:** [`PDDocCreateThumbs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateThumbs)

### Structures (2)

#### PDThumb

```cpp
typedef struct _t_PDThumb* PDThumb
```

Header: `PDBasicExpT.h:124`

A thumbnail preview image of a page.

**See also:** [`PDDocCreateThumbs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateThumbs), [`PDDocDeleteThumbs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocDeleteThumbs)

#### PDThumbCreationServer

```cpp
typedef struct _t_PDThumbCreationServer* PDThumbCreationServer
```

Header: `PDExpT.h:3318`

## PDTrans

### Functions (9)

#### PDTransEqual

```cpp
ASBool PDTransEqual(PDTrans pdtOne, PDTrans pdtTwo)
```

Header: `PDProcs.h:5814`

Tests two transitions for equality. Two transitions are equal only if their Cos objects are equal (see CosObjEqual()).

**Parameters**

- `pdtOne` ([`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)): A transition to test for equality.
- `pdtTwo` ([`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)): A transition to test for equality.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the transitions are equal, `false` otherwise.

**See also:** [`CosObjEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEqual)

#### PDTransFromCosObj

```cpp
PDTrans PDTransFromCosObj(CosObj coLayer)
```

Header: `PDProcs.h:5785`

Converts the specified dictionary Cos object to a transition and verifies that the transition is valid. This method does not copy the object but is instead the logical equivalent of a type cast.

**Parameters**

- `coLayer` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary Cos object to convert to a transition.

**Returns:** [`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)

The transition corresponding to the given dictionary object, `obj`.

**Exceptions**

- `pdErrBadBaseObj`: is raised if the transition is not valid as determined by PDTransIsValid().

**See also:** [`PDTransGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransGetCosObj), [`PDTransIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransIsValid)

#### PDTransGetCosObj

```cpp
CosObj PDTransGetCosObj(PDTrans pdl)
```

Header: `PDProcs.h:5801`

Gets the dictionary Cos object corresponding to the transition and verifies that the transition is valid. This method does not copy the object but is the logical equivalent of a type cast.

**Parameters**

- `pdl` ([`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)): The transition whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The dictionary Cos object corresponding to the transition. it returns the `NULL` Cos object if the transition is invalid as determined by PDTransIsValid().

**See also:** [`PDTransFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransFromCosObj), [`PDTransIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransIsValid)

#### PDTransGetDuration

```cpp
ASFixed PDTransGetDuration(PDTrans pdt)
```

Header: `PDProcs.h:5959`

Gets the duration for the given transition. **Note:** Standard durations are: Duration Meaning 0 seconds fast 1 second medium 2 seconds slow

**Parameters**

- `pdt` ([`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)): IN/OUT The transition for which the duration is obtained.

**Returns:** [`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)

The transition duration, specified in seconds. If no duration is specified in the transition, the return value is fxDefaultTransDuration (`1` second).

**See also:** [`PDTransGetSubtype`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransGetSubtype)

#### PDTransGetSubtype

```cpp
ASAtom PDTransGetSubtype(PDTrans pdt)
```

Header: `PDProcs.h:5936`

Gets a transition's subtype.

**Parameters**

- `pdt` ([`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)): IN/OUT The transition whose subtype is obtained.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

The ASAtom for the transition's subtype. It can be converted to a string using ASAtomGetString().

**See also:** [`PDTransGetDuration`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransGetDuration)

#### PDTransIsValid

```cpp
ASBool PDTransIsValid(PDTrans pdt)
```

Header: `PDProcs.h:5757`

Tests whether a transition is valid, meaning that the transition has not been deleted.

**Parameters**

- `pdt` ([`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)): The transition dictionary whose validity is tested.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the transition is valid, `false` otherwise.

**See also:** [`PDTransEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransEqual)

#### PDTransNew

```cpp
PDTrans PDTransNew(PDDoc pdd, ASAtom asaSubtype, ASFixed fxDuration)
```

Header: `PDProcs.h:5925`

Creates a new transition of the specified type and duration associated with the CosDoc of the given PDDoc. You can find this document on the web store of the International Standards Organization (ISO). All implementations that support transitions are required to support these transitions at a minimum. Plug-ins can register new types or provide a new handler for an existing type.

**Parameters**

- `pdd` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The PDDoc to whose CosDoc the transition is added.
- `asaSubtype` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The transition subtype to create. It must be one of the transition effects described under "Presentations" in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.4.4, page 377.
- `fxDuration` ([`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): The transition duration, in seconds.

**Returns:** [`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)

The newly created transition.

**Exceptions**

- `pdErrBadBaseObj`: is raised if the transition is not valid as determined by PDTransIsValid().

**See also:** [`PDTransNewFromCosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransNewFromCosDoc)

#### PDTransNewFromCosDoc

```cpp
PDTrans PDTransNewFromCosDoc(CosDoc cd, ASAtom asaSubtype, ASFixed fxDuration)
```

Header: `PDProcs.h:5900`

Creates a new transition of the specified type and duration associated with the given CosDoc.

**Parameters**

- `cd` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The CosDoc to which the transition is added.
- `asaSubtype` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The transition subtype to create. This subtype is returned by the AVTransHandlerGetTypeProc() callback in AVTransHandler.
- `fxDuration` ([`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): The transition duration, in seconds.

**Returns:** [`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)

The newly created transition.

**Exceptions**

- `pdErrBadBaseObj`: is raised if the transition is not valid as determined by PDTransIsValid().

**See also:** [`PDTransNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransNew)

#### PDTransNull

```cpp
PDTrans PDTransNull(void)
```

Header: `PDProcs.h:5768`

Gets a `NULL` transition. This can be used in conjunction with PDTransEqual() to determine whether a transition is `NULL`.

**Parameters**

- (unnamed) (`void`)

**Returns:** [`PDTrans`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTrans)

A `NULL` transition.

**See also:** [`PDTransNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransNew)

### Typedefs (1)

#### PDTrans

```cpp
typedef OPAQUE_64_BITS PDTrans
```

Header: `PDExpT.h:4070`

A transition to a page. The Trans key in a Page dictionary specifies a Transition dictionary, which describes the effect to use when going to a page and the amount of time the transition should take.

**See also:** [`PDPageGetTransition`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPageGetTransition), [`PDTransFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransFromCosObj), [`PDTransNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransNew), [`PDTransNewFromCosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransNewFromCosDoc), [`PDTransNull`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTransNull)

### Definitions (2)

#### fxDefaultPageDuration

Header: `PDExpT.h:4072`

Value: `-fixedOne`

#### fxDefaultTransDuration

Header: `PDExpT.h:4073`

Value: `fixedOne`

## PDViewDest

### Functions (7)

#### PDViewDestCreate

```cpp
PDViewDestination PDViewDestCreate(PDDoc doc, PDPage initialPage, ASAtom initialFitType, const ASFixedRectP initialRect, const ASFixed initialZoom, ASInt32 pageNumber)
```

Header: `PDProcs.h:4407`

Creates a new view destination object. For information about the Zoom Factor see page 365 of the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7. You can find this document on the web store of the International Standards Organization (ISO).

**Parameters**

- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): The document in which the destination is used.
- `initialPage` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The destination page.
- `initialFitType` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The destination fit type. It must be one of the View Destination Fit Types, which must be converted into an ASAtom with ASAtomFromString().
- `initialRect` (`const ASFixedRectP`): A pointer to an `ASFixedRect` specifying the destination rectangle, specified in user space coordinates. The appropriate information will be extracted from `initialRect`, depending on `initialFitType`, to create the destination. All four of the `initialRect` parameter's components should be set; using PDViewDestNULL for any components can result in incorrect results for rotated pages.
- `initialZoom` ([`const ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): The zoom factor to set for the destination. Used only if `initialFitType` is `XYZ`. Use the predefined value PDViewDestNULL (see `PDExpT.h`) to indicate a `NULL` zoom factor, described in Destinations in "Document-Level Navigation," in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.4.4, page 365.
- `pageNumber` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): Currently unused.

**Returns:** [`PDViewDestination`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestination)

The newly created view destination.

**See also:** [`PDViewDestFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestFromCosObj), `PDViewDestDestroy ViewDestinationFitTypes`

#### PDViewDestDestroy

```cpp
void PDViewDestDestroy(PDViewDestination dest)
```

Header: `PDProcs.h:4420`

Deletes a view destination object. Before deleting a view destination, ensure that no link or bookmark refers to it.

**Parameters**

- `dest` ([`PDViewDestination`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestination)): IN/OUT The view destination to destroy.

**Returns:** `void`

**See also:** [`PDViewDestFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestFromCosObj), [`PDViewDestCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestCreate)

#### PDViewDestFromCosObj

```cpp
PDViewDestination PDViewDestFromCosObj(CosObj obj)
```

Header: `PDProcs.h:4490`

Converts the specified Cos object to a view destination and verifies that the view destination is valid. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The dictionary Cos object to convert to a view destination.

**Returns:** [`PDViewDestination`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestination)

An array Cos object for the view destination.

**Exceptions**

- `pdErrBadAction`: is raised if the destination is invalid, as determined by PDViewDestIsValid().

**See also:** [`PDViewDestGetCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestGetCosObj)

#### PDViewDestGetAttr

```cpp
void PDViewDestGetAttr(PDViewDestination dest, ASInt32 *pageNum, ASAtom *fitType, ASFixedRectP destRect, ASFixed *zoom)
```

Header: `PDProcs.h:4456`

Gets a view destination's fit type, destination rectangle, and zoom factor. The destination must be represented by an array, which is the case for a GoToR action.

**Parameters**

- `dest` ([`PDViewDestination`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestination)): IN/OUT The view destination whose attributes are obtained.
- `pageNum` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT (Filled by the method) The page number of the destination's page.
- `fitType` ([`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): IN/OUT (Filled by the method) The destination fit type. One of the values listed in View Destination Fit Types.
- `destRect` (`ASFixedRectP`): IN/OUT (Filled by the method) A pointer to a `ASFixedRect` containing the destination's rectangle, specified in user space coordinates.
- `zoom` ([`ASFixed *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): IN/OUT (Filled by the method) The destination's zoom factor.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if the destination is not represented by an array.

**See also:** `PDViewDestCreate ViewDestinationFitTypes`

#### PDViewDestGetCosObj

```cpp
CosObj PDViewDestGetCosObj(PDViewDestination dest)
```

Header: `PDProcs.h:4474`

Gets the Cos object corresponding to a view destination and verifies that the view destination is valid. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `dest` ([`PDViewDestination`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestination)): IN/OUT The view destination whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

Array Cos object for the view destination. The contents of the array can be enumerated using CosObjEnum(). It returns a `NULL` Cos object if the view destination is invalid, as determined by PDViewDestIsValid().

**See also:** [`PDViewDestFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestFromCosObj), [`PDViewDestIsValid`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestIsValid)

#### PDViewDestIsValid

```cpp
ASBool PDViewDestIsValid(PDViewDestination dest)
```

Header: `PDProcs.h:4432`

Tests whether a view destination is valid. This is intended only to ensure that the view destination has not been deleted, not to ensure that all necessary information is present and valid.

**Parameters**

- `dest` ([`PDViewDestination`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestination)): The view destination whose validity is determined.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the view destination is valid, `false` otherwise.

#### PDViewDestResolve

```cpp
PDViewDestination PDViewDestResolve(PDViewDestination dest, PDDoc doc)
```

Header: `PDProcs.h:5744`

Resolves a destination. `dest` is the value of the D key in an action. It can be a real destination (an array) or a name. If it is a name, look it up in the `doc` parameter's Dests dictionary. The value found there can be a real destination (an array) or a dictionary. If it is a dictionary, look up the D key in that dictionary. This method is useful for getting a PDViewDestination from an action, as provided by PDActionGetDest(), since this method may not return a PDViewDestination. This method can raise memory, I/O, and parsing exceptions.

**Parameters**

- `dest` ([`PDViewDestination`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestination)): IN/OUT The destination to resolve.
- `doc` ([`PDDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDoc)): IN/OUT The PDDoc that contains the destination.

**Returns:** [`PDViewDestination`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestination)

The resolved view destination.

**See also:** [`PDActionGetDest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionGetDest)

### Typedefs (1)

#### PDViewDestination

```cpp
typedef OPAQUE_64_BITS PDViewDestination
```

Header: `PDExpT.h:3360`

A particular view of a page in a document. It contains a reference to a page, a rectangle on that page, and information specifying how to adjust the view to fit the window's size and shape. It corresponds to a PDF Dest array and can be considered a special form of a PDAction.

**See also:** `AVPageViewToViewDest`, [`PDActionGetDest`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDActionGetDest), [`PDViewDestCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestCreate), [`PDViewDestFromCosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestFromCosObj), [`PDViewDestResolve`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestResolve), [`PDViewDestDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDViewDestDestroy)

### Definitions (1)

#### PDViewDestNULL

Header: `PDExpT.h:3365`

Value: `fixedNegativeInfinity`

## PDWord

### Functions (24)

#### PDWordCreateTextSelect

```cpp
PDTextSelect PDWordCreateTextSelect(PDPage page, PDWord *wList, ASUns32 wListLen)
```

Header: `PDProcs.h:8642`

Creates a text selection object for a given page that includes all words in a word list, as returned from a `PDWordFinder` method. The text selection can then be set as the current selection using AVDocSetSelection(). **Note:** For consistent text selection behavior, avoid using other PDTextSelect creation methods which depend on the word finder versions and word offsets. These include PDTextSelectCreatePageHiliteEx(), PDTextSelectCreateRanges(), PDTextSelectCreateRangesEx(), PDTextSelectCreateWordHilite(), and PDTextSelectCreateWordHiliteEx().

**Parameters**

- `page` ([`PDPage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDPage)): The page on which to select the words.
- `wList` ([`PDWord *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word list to be selected.
- `wListLen` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The number of words in the word list.

**Returns:** [`PDTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelect)

The newly created text selection.

**See also:** [`PDDocCreateTextSelect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateTextSelect), [`PDTextSelectDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectDestroy), `AVDocSetSelection`, [`PDTextSelectEnumQuads`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumQuads), [`PDTextSelectEnumText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectEnumText)

#### PDWordFilterString

```cpp
ASBool PDWordFilterString(ASUns16 *infoArray, char *cNewWord, char *cOldWord)
```

Header: `PDProcs.h:5125`

Removes leading and trailing spaces and leading and trailing punctuation (including soft hyphens) from the specified word. It does not remove wildcard characters (`'*'` and `'?'`) or any punctuation surrounded by alphanumeric characters within the word. The determination of which characters are alphanumeric, wildcard, punctuation, and so forth, is made by the values in `infoArray`. Although this method seems very similar to PDWordFilterWord(), the two methods treat letters and digits slightly differently. PDWordFilterWord() uses the encoding info array but also does a straight character code test for any characters that have not been mapped to anything. It does this to catch letters and digits from non-standard character sets, and is necessary to avoid removing words with non-standard character sets. PDWordFilterString(), on the other hand, was designed for known character sets such as WinAnsi and Mac Roman. For non-Roman character set viewers, this method currently supports only SHIFT-JIS encoding on a Japanese system. For descriptions of `WinAnsiEncoding` and `MacRomanEncoding`, see Annex D, "Character Sets and Encodings, in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 651. You can find this document on the web store of the International Standards Organization (ISO). **Note:** In Acrobat 6.0, the method PDWordFinderEnumWordsStr() is preferred to this method, which remains for backward compatability. CharacterTypeCodes

**Parameters**

- `infoArray` ([`ASUns16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)): An array specifying the type of each character in the font. Each entry in this table must be one of the Character Type Codes. If `infoArray` is set to `NULL`, a default table is used. For non-UNIX Roman systems, it is `WinAnsiEncoding` on Windows`and MacRomanEncoding` on Mac OS. On UNIX (except HP-UX) Roman systems, it is `ISO8859-1` (ISO Latin-1); for HP-UX, it is `HP-ROMAN8`.
- `cNewWord` (`char *`): (Filled by the method) The filtered word.
- `cOldWord` (`char *`): The unfiltered word. This value must be passed to the method.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the string required filtering, `false` if the filtered string is the same as the unfiltered string.

**See also:** [`PDWordFilterWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFilterWord)

#### PDWordFilterWord

```cpp
ASBool PDWordFilterWord(PDWord word, char *buffer, ASInt16 bufferLen, ASInt16 *newLen)
```

Header: `PDProcs.h:5161`

Removes leading and trailing spaces and leading and trailing punctuation (including soft hyphens) from the specified word. It does not remove wildcard characters (`'*'` and `'?'`) or any punctuation surrounded by alphanumeric characters within the word. It also converts ligatures to their constituent characters. The determination of which characters to remove is made by examining the flags in the `outEncInfo` array passed to PDDocCreateWordFinder(). As a result, this method is most useful after you have been called with words obtained by calling PDWordFinderGetNthWord(), in the callback for PDWordFinderEnumWords(), and words in the pXYSortTable returned by PDWordFinderAcquireWordList(). See the description of PDWordFilterString() for further information, and for a description of how the two methods differ. The Acrobat Catalog program uses this method to filter words before indexing them. This method works with non-Roman systems. **Note:** In Acrobat 6.0 and later, the method PDWordFinderEnumWords() is preferred to this method, which remains for backward compatability.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The PDWord to filter.
- `buffer` (`char *`): (Filled by the method) The filtered string.
- `bufferLen` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): The maximum number of characters that `buffer` can hold.
- `newLen` ([`ASInt16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): (Filled by the method) The number of characters actually written into `buffer`.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the word required filtering, `false` if the filtered string is the same as the unfiltered string.

**See also:** [`PDWordFilterString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFilterString)

#### PDWordGetASText

```cpp
void PDWordGetASText(PDWord word, ASUns32 filter, ASText str)
```

Header: `PDProcs.h:8559`

Copies the text from a word into an ASText object. It automatically performs the necessary encoding conversions from the specified word (either in Unicode or Host Encoding) to the ASText object. `PDWordGetASText(word, W_SOFT_HYPHEN + W_ACCENT, mystr);`

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word whose text becomes the new ASText.
- `filter` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): Character types to be dropped from the output string. For example, the following returns text without soft hyphens and accent marks:
- `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): An existing ASText object whose content will be replaced by the new text.

**Returns:** `void`

#### PDWordGetAttr

```cpp
ASUns16 PDWordGetAttr(PDWord word)
```

Header: `PDProcs.h:4913`

Gets a bit field containing information on the types of characters in a word. Use PDWordGetCharacterTypes() if you wish to check each character's type individually. **Note:** PDWordGetAttr() may return an attribute value greater than the maximum of all of the public attributes since there can be private attributes added on. It is recommended to `AND` the result with the attribute you are interested in.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): IN/OUT The word whose character types are obtained.

**Returns:** [`ASUns16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)

A bit field containing information on the types of characters in word. The value is a logical `OR` of the Word Attributes.

**See also:** [`PDWordGetCharacterTypes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharacterTypes), [`PDWordGetStyleTransition`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetStyleTransition), [`PDWordGetNthCharStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNthCharStyle)

#### PDWordGetAttrEx

```cpp
ASUns16 PDWordGetAttrEx(PDWord word, ASUns32 groupID)
```

Header: `PDProcs.h:8617`

This is a version 6.0 extension of PDWordGetAttr() that can be used only with a word finder created with algorithm version WF_VERSION_3 or higher. It can get an additional 16-bit flag group defined in Acrobat 6. It gets a bit field containing information on the types of characters in a word. Use PDWordGetCharacterTypes() if you wish to check each character's type individually.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word whose character types are obtained.
- `groupID` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The group number of the Word Attributes
  flags:
  - `0`, the default, is the first 16-bit group, and is the same as
  PDWordGetAttr(). `1` gets the second group defined in Acrobat 6.

  **Note:** PDWordGetAttr() may return an attribute value greater than the maximum of all of the public attributes, since there can be private attributes added on. It is recommended that you `AND` the result with the attribute you are interested in.

**Returns:** [`ASUns16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)

A bit field containing information on the types of characters in `word`. The value is a logical `OR` of the Word Attributes.

**See also:** [`PDWordGetCharacterTypes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharacterTypes), [`PDWordGetStyleTransition`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetStyleTransition), [`PDWordGetNthCharStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNthCharStyle)

#### PDWordGetByteIdxFromHiliteChar

```cpp
ASUns32 PDWordGetByteIdxFromHiliteChar(PDWord word, ASUns32 charIdx)
```

Header: `PDProcs.h:8542`

Returns the byte offset within the specified word of the highlightable character at the specified character offset. The first character of a word is at byte offset `0`. This method can be used only with a word finder created with algorithm version WF_VERSION_3 or higher. The returned byte offset can be passed to PDWordGetCharOffsetEx() and PDWordGetCharQuad() to get additional information. Use PDWordGetNumHiliteChar() to get the number of highlightable characters in a word.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word containing the character.
- `charIdx` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The character index within the word.

**Returns:** [`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)

The byte offset of the specified character within the word, or `0` if the character index is out of range.

**See also:** [`PDWordGetCharOffsetEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharOffsetEx), [`PDWordGetCharQuad`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharQuad), [`PDWordGetNumHiliteChar`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNumHiliteChar)

#### PDWordGetCharDelta

```cpp
ASInt8 PDWordGetCharDelta(PDWord word)
```

Header: `PDProcs.h:4974`

Gets the difference between the word length (the number of printed characters in the word) and the PDF word length (the number of character codes in the word). For instance, if the PDF word is `fi (ligature) sh` the mapped word will be `"fish"`. The ligature occupies only one character code, so in this case the character delta will be `3-4 = -1`. If the PDWord's character set has no ligatures, such as on a non-Roman viewer supporting Japanese, returns `0`.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): IN/OUT The word whose character delta is obtained.

**Returns:** [`ASInt8`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt8)

The character delta for word. Cast the return value to an ASInt8 before using.

**See also:** [`PDWordGetLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetLength), [`PDWordGetCharOffset`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharOffset)

#### PDWordGetCharEncFlags

```cpp
void PDWordGetCharEncFlags(PDWord word, ASUns32 *fList, ASUns32 size)
```

Header: `PDProcs.h:8584`

Gets the WordFinder Character Encoding Flags for each character in a word, which specify how reliably the word finder identified the character encoding. This method can be used only with a word finder created with algorithm version WF_VERSION_3 or higher.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word whose character encoding flags are obtained.
- `fList` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): (Filled by the method) An array of character encoding flags types. This array contains one element for each byte of text in the word. The byte length of the text can be determined with PDWordGetLength(). Each element is the logical `OR` of one or more of the character encoding flags.
- `size` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The maximum number of elements in the array `fList`.

**Returns:** `void`

**See also:** [`PDWordGetAttrEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetAttrEx), `PDWordGetLength WordFinderCharacterEncodingFlags`

#### PDWordGetCharOffset

```cpp
ASUns16 PDWordGetCharOffset(PDWord word)
```

Header: `PDProcs.h:4953`

Returns a word's character offset from the beginning of its page. This information, together with the character delta obtained from PDWordGetCharDelta(), can be used to highlight a range of words on a page, using PDTextSelectCreatePageHilite().

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): IN/OUT The word whose character offset is obtained.

**Returns:** [`ASUns16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)

The word's character offset. On multi-byte systems, it points to the first byte.

**See also:** [`PDWordGetCharDelta`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharDelta), [`PDWordGetLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetLength), [`PDTextSelectCreatePageHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHilite)

#### PDWordGetCharOffsetEx

```cpp
ASUns32 PDWordGetCharOffsetEx(PDWord word, ASUns32 byteIdx, ASUns32 *bytesConsumed, ASUns32 *offsetLen)
```

Header: `PDProcs.h:8468`

This is a version 6.0 extension of PDWordGetCharOffset() that can be used only with a word finder created with algorithm version WF_VERSION_3 or higher. It returns the character offset for a character identified by its index number, and the number of bytes (length) used for that character. The length is usually `1` for single-byte characters and `2` for double-byte characters. If multiple bytes are used to construct one character, only the first byte has valid character offset information and the other bytes have zero offset length with the same character offset of the first byte. If the returned offset length is zero, it means the specified byte in the word is a part (other than the first byte) of a multi-byte character. The character offset is the character position calculated in bytes from the beginning of a page. Because of the encoding conversions and character replacements applied by the word finder, some characters may have different byte lengths from the original PDF content. The character offset itself can locate a character in the PDF content. However, without the offset length (that is the number of bytes in the PDF content), clients cannot tell whether two characters are next to each other in the PDF content. For example, suppose you want to create a Text Select object of two characters at character offset `1` and `3`. You can create an object with two disconnected ranges of `[Offset 1, The length 1]` and `[Offset 3, The length 1]`. However, if you know that the offset length of both characters is `2`, you can create a simpler object with a single range of `[Offset 1, The length 4]`.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word whose character offset is obtained.
- `byteIdx` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The byte index within the word of the character whose offset is obtained. Valid values are `0` to `PDWordGetLength(word)-1`.
- `bytesConsumed` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): (Filled by method) Returns the number of bytes in the word that are occupied by the specified character. It can be `NULL` if it is not needed. Use `(byteIdx + *bytesConsumed)` to get the byte index of the next character in the word.
- `offsetLen` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): (Filled by the method) Returns the number of bytes occupied by the specified character in the original PDF content. This is `0` if the specified byte is not the starting byte of a character in the PDF content. It can be `NULL` if it is not needed.

**Returns:** [`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)

The word's character offset and the number of bytes occupied by the character.

**See also:** [`PDWordGetCharOffset`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharOffset), [`PDWordGetCharDelta`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharDelta), [`PDWordGetLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetLength), [`PDTextSelectCreatePageHilite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDTextSelectCreatePageHilite)

#### PDWordGetCharQuad

```cpp
ASBool PDWordGetCharQuad(PDWord word, ASUns32 byteIdx, ASFixedQuad *quad)
```

Header: `PDProcs.h:8496`

Gets the quadrilateral bounding of the character at a given index position in the word. The `byteIdx` parameter should be a value returned from `PDWordGetByteIdxFromHiliteChar` where the `charIdx` parameter should be between `0` and `PDWordGetNumHiliteChar()-1`. However, if the specified character is constructed with multiple bytes, only the first byte returns a valid quad. Otherwise, this method returns `false`.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word whose character offset is obtained.
- `byteIdx` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The byte index within the word of the character whose quad is obtained. Valid values are `0` to `PDWordGetLength(word)-1`.
- `quad` (`ASFixedQuad *`): (Filled by method) A pointer to an existing quad structure in which to return the character's quad specified in user-space coordinates.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the provided byte index is the beginning byte of a character and a valid quad is returned, `false` otherwise.

**See also:** [`PDWordGetByteIdxFromHiliteChar`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetByteIdxFromHiliteChar), [`PDWordGetNumHiliteChar`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNumHiliteChar), [`PDWordGetCharOffsetEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharOffsetEx), [`PDWordGetNthQuad`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNthQuad), [`PDWordGetNumQuads`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNumQuads)

#### PDWordGetCharacterTypes

```cpp
void PDWordGetCharacterTypes(PDWord word, ASUns16 *cArr, ASInt16 size)
```

Header: `PDProcs.h:4935`

Gets the character type for each character in a word.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word whose character types are obtained.
- `cArr` ([`ASUns16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)): (Filled by the method) An array of character types. This array contains one element for each character in the word. Use PDWordGetLength() to determine the number of elements that must be in the array. Each element is the logical `OR` of one or more of the Character Type Codes. For non-Roman character set viewers, meaningful values are returned only for Roman characters. For non-Roman characters, it returns `0`, which is the same as `W_CNTL`. If the character is 2 bytes, both bytes indicate the same character type.
- `size` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): The number of elements in `cArr`.

**Returns:** `void`

**See also:** [`PDWordGetAttr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetAttr), `PDWordGetLength CharacterTypeCodes`

#### PDWordGetLength

```cpp
ASUns8 PDWordGetLength(PDWord word)
```

Header: `PDProcs.h:4863`

Gets the number of bytes in a word. This method also works on non-Roman systems.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): IN/OUT The word object whose character count is obtained.

**Returns:** [`ASUns8`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)

The number of characters in word.

**See also:** [`PDWordGetCharDelta`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharDelta), [`PDWordGetCharOffset`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharOffset)

#### PDWordGetNthCharStyle

```cpp
PDStyle PDWordGetNthCharStyle(PDWordFinder wObj, PDWord word, ASInt32 dex)
```

Header: `PDProcs.h:5010`

Returns a PDStyle object for the nth style in a word.

**Parameters**

- `wObj` ([`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)): IN/OUT A word finder object.
- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): IN/OUT The word whose nth style is obtained.
- `dex` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The index of the style to obtain. The first
  style in a word has an index of zero.

**Returns:** [`PDStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDStyle)

**Exceptions**

- `genErrBadParm`: is raised if `dex < 0`.

**See also:** [`PDWordGetStyleTransition`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetStyleTransition)

#### PDWordGetNthQuad

```cpp
ASBool PDWordGetNthQuad(PDWord word, ASInt16 nTh, ASFixedQuad *quad)
```

Header: `PDProcs.h:5060`

Gets the specified word's nth quad, specified in user space coordinates. See PDWordGetNumQuads() for a description of a quad. The quad's height is the height of the font's bounding box, not the height of the tallest character used in the word. The font's bounding box is determined by the glyphs in the font that extend farthest above and below the baseline; it often extends somewhat above the top of `'A'` and below the bottom of `'y'`. The quad's width is determined from the characters actually present in the word. For example, the quads for the words `"AWAY"` and `"away"` have the same height, but generally do not have the same width unless the font is a mono-spaced font (a font in which all characters have the same width). Despite the names of the fields in an `ASFixedQuad` (`tl` for top left, `bl` for bottom left, and so forth) the corners of `quad` do not necessarily have these positions.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word whose nth quad is obtained.
- `nTh` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): The quad to obtain. A word's first quad has an index of zero.
- `quad` (`ASFixedQuad *`): (Filled by the method) A pointer to the word's nth quad, specified in user-space coordinates.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the word has an nth quad, `false` otherwise.

**See also:** [`PDWordGetNumQuads`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNumQuads)

#### PDWordGetNumHiliteChar

```cpp
ASUns32 PDWordGetNumHiliteChar(PDWord word)
```

Header: `PDProcs.h:8519`

Gets the number of *highlightable* characters in a word. A highlightable character is the minimum text unit that Acrobat can select and highlight. This method can be used only with a word finder created with algorithm version WF_VERSION_3 or higher. Because of the encoding conversion, the characters in a word finder word list do not have a 1-to-1 correspondence to the characters displayed by Acrobat. For example, if the word is `"fish"` and the text operation in PDF content is `"fi"`(ligature) `+ 's' + 'h'`, this method returns the number of highlightable characters as `3`, counting `"fi"` as one character. For the same word, the PDWordGetLength() method returns the byte-length as `4`.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word whose highlightable character count is obtained.

**Returns:** [`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)

The number of highlightable characters in `word`.

**See also:** [`PDWordGetLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetLength)

#### PDWordGetNumQuads

```cpp
ASInt16 PDWordGetNumQuads(PDWord word)
```

Header: `PDProcs.h:5025`

Gets the number of quads in a word. A quad is a quadrilateral bounding a contiguous piece of a word. Every word has at least one quad. A word has more than one quad, for example, if it is hyphenated and split across multiple lines or if the word is set on a curve rather than on a straight line.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): IN/OUT The word whose quad count is obtained.

**Returns:** [`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)

The number of quads in word.

**See also:** [`PDWordGetNthQuad`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNthQuad)

#### PDWordGetString

```cpp
void PDWordGetString(PDWord word, char *str, ASInt32 len)
```

Header: `PDProcs.h:4892`

This method gets a word's text. The string to return includes any word break characters (such as space characters) that follow the word, but not any that precede the word. The characters that are treated as word breaks are defined in the `outEncInfo` parameter of PDDocCreateWordFinder() method. Use PDWordFilterString() to subsequently remove the word break characters. This method produces a string in whatever encoding the PDWord uses, for both Roman and non-Roman systems.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word whose string is obtained.
- `str` (`char *`): (Filled by the method) The string. The encoding of the string is the encoding used by the `PDWordFinder` that supplied the PDWord. For instance, if PDDocCreateWordFinderUCS() is used to create the word finder, PDWordGetString() returns only Unicode. There is no way to detect Unicode strings returned by PDWordGetString(), since there is no UCS header (`FEFF`) added to each string returned.
- `len` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The length of `str` in bytes. Up to `len` characters of word will be copied into `str`. If `str` is long enough, it will be `NULL`-terminated.

**Returns:** `void`

**Exceptions**

- `genErrBadParm`: is raised if either `word` or `str` is `NULL`.

**See also:** [`PDWordGetLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetLength), [`PDWordGetCharDelta`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetCharDelta), [`PDWordSplitString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordSplitString)

#### PDWordGetStyleTransition

```cpp
ASInt16 PDWordGetStyleTransition(PDWord word, ASInt16 *transTbl, ASInt16 size)
```

Header: `PDProcs.h:4995`

Gets the locations of style transitions in a word. Every word has at least one style transition, at character position zero in the word.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): IN/OUT The word whose style transition list is obtained.
- `transTbl` ([`ASInt16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): IN/OUT (Filled by the method) An array of style transitions. Each element is the character offset in word where the style changes. The offset specifies the first character in the word that has the new style. The first character in a word has an offset of zero.
- `size` ([`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)): IN/OUT The number of entries that `transTbl` can hold. The word is searched only until this number of style transitions have been found.

**Returns:** [`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)

The number of style transition offsets copied to `transTbl`.

**See also:** [`PDWordGetNthCharStyle`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNthCharStyle)

#### PDWordIsCurrentlyVisible

```cpp
ASBool PDWordIsCurrentlyVisible(PDWord word, ASInt32 pageNum, PDOCContext ctx)
```

Header: `PDProcs.h:10668`

Tests whether a word is visible in a given optional-content context on a given page.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word to test.
- `pageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number for which the word is tested.
- `ctx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context in which the word is tested, as returned by `PDDocGetOCContext(pdDoc)`.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the word is visible in the given context, `false` if it is hidden.

**See also:** [`PDWordMakeVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordMakeVisible), [`PDWordFinderAcquireVisibleWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireVisibleWordList), [`PDWordFinderEnumVisibleWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumVisibleWords)

#### PDWordIsRotated

```cpp
ASBool PDWordIsRotated(PDWord word)
```

Header: `PDProcs.h:5069`

Tests whether a word is rotated.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word to test.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the word is rotated, `false` otherwise.

**See also:** [`PDWordGetNthQuad`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordGetNthQuad)

#### PDWordMakeVisible

```cpp
ASBool PDWordMakeVisible(PDWord word, ASInt32 pageNum, PDOCContext ctx)
```

Header: `PDProcs.h:10685`

Makes a word visible in a given optional-content context on a given page.

**Parameters**

- `word` ([`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): The word to test.
- `pageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number for which the word is to be made visible.
- `ctx` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context in which the word is to be made visible, as returned by `PDDocGetOCContext(pdDoc)`.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the word can be made visible in the given context, `false` otherwise.

**See also:** [`PDWordIsCurrentlyVisible`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordIsCurrentlyVisible), [`PDWordFinderAcquireVisibleWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireVisibleWordList), [`PDWordFinderEnumVisibleWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumVisibleWords)

#### PDWordSplitString

```cpp
ASUns16 PDWordSplitString(ASUns16 *infoArray, char *cNewWord, char *cOldWord, ASUns16 nMaxLen)
```

Header: `PDProcs.h:2252`

Splits the specified string into words by substituting spaces for word separator characters. The list of characters considered to be word separators can be specified, or a default list can be used. The characters `','` and `'.'` are context-sensitive word separators. If surrounded by digits (for example, `654,096.345`), they are not considered word separators. For non-Roman character set viewers, this method currently supports only SHIFT-JIS encoding on a Japanese system.

**Parameters**

- `infoArray` ([`ASUns16 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)): A character information table. It specifies each character's type; word separator characters must be marked as `W_WORD_BREAK` (see Character Type Codes). This table can be identical to the table to pass to PDDocCreateWordFinder(). If `infoArray` is `NULL`, a default table is used (see Glyph Names of Word Separators).
- `cNewWord` (`char *`): (Filled by the method) The word that has been split. Word separator characters have been replaced with spaces.
- `cOldWord` (`char *`): The word to split.
- `nMaxLen` ([`ASUns16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)): The number of characters that `cNewWord` can hold. Word splitting stops when `cOldWord` is completely processed or `nMaxLen` characters have been placed in `cNewWord`, whichever occurs first.

**Returns:** [`ASUns16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASUns16)

The number of splits that occurred.

**Exceptions**

- `genErrGeneral`: is raised if `infoArray` is `NULL`, but host encoding cannot be obtained.

**See also:** `PDWordGetString CharacterTypeCodes`

### Typedefs (1)

#### PDWordProc

```cpp
typedef ASBool(*) PDWordProc(PDWordFinder wObj, PDWord wInfo, ASInt32 pgNum, void *clientData)(PDWordFinder wObj, PDWord wInfo, ASInt32 pgNum, void *clientData)
```

Header: `PDExpT.h:3412`

A callback for PDWordFinderEnumWords. It is called once for each word.

**See also:** [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords)

### Structures (1)

#### PDWord

```cpp
typedef struct _t_PDWord* PDWord
```

Header: `PDExpT.h:3391`

A word in a PDF file. Each word contains a sequence of characters in one or more styles (see PDStyle).

**See also:** [`PDWordFinderGetNthWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderGetNthWord), [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords)

### Definitions (45)

#### WXE_ADJACENT_TO_SPACE

Header: `PDExpT.h:3600`

Value: `0x800`

The character following the end of the word is a space (either an explicit space character encoded in a string, or one that appears implicitly because the drawing point was moved).

#### WXE_ENCODING_WARNING

Header: `PDExpT.h:3635`

Value: `0x02`

#### WXE_ENC_MISSING

Header: `PDExpT.h:3517`

Value: `0x02`

#### WXE_ENC_NO_UCS

Header: `PDExpT.h:3521`

Value: `0x04`

#### WXE_ENC_UNMAPPED

Header: `PDExpT.h:3514`

Value: `0x01`

#### WXE_EXT_CHAR_OFFSETS

Header: `PDExpT.h:3642`

Value: `0x10`

#### WXE_FROM_ACTUALT

Header: `PDExpT.h:3523`

Value: `0x08`

#### WXE_FRONT_TAB

Header: `PDExpT.h:3633`

Value: `0x01`

#### WXE_HAS_DIGIT

Header: `PDExpT.h:3546`

Value: `0x8`

One or more characters in the word are digits.

#### WXE_HAS_HYPHEN

Header: `PDExpT.h:3562`

Value: `0x20`

There is a hyphen in the word.

#### WXE_HAS_LEADING_PUNC

Header: `PDExpT.h:3579`

Value: `0x100`

The first character in the word is a punctuation mark. If this bit is set, `WXE_HAS_PUNCTUATION` will also be set.

#### WXE_HAS_LETTER

Header: `PDExpT.h:3536`

Value: `0x2`

The word contains a character between A-Z or a-z.

#### WXE_HAS_LIGATURE

Header: `PDExpT.h:3572`

Value: `0x80`

The word contains a ligature.

#### WXE_HAS_NONALPHANUM

Header: `PDExpT.h:3531`

Value: `0X1`

The word contains a character outside the range of A-Z, a-Z, 0-9.

#### WXE_HAS_PUNCTUATION

Header: `PDExpT.h:3557`

Value: `0x10`

One or more characters in the word are punctuation marks. Other flag bits can be checked to test whether the punctuation was at the beginning of the word (`WXE_HAS_LEADING_PUNC`), the end of the word (`WXE_HAS_TRAILING_PUNC`), or elsewhere in the word.

#### WXE_HAS_SOFT_HYPHEN

Header: `PDExpT.h:3567`

Value: `0x40`

There is a soft hyphen in the word.

#### WXE_HAS_TRAILING_PUNC

Header: `PDExpT.h:3586`

Value: `0x200`

The last character in the word is a punctuation mark. If this bit is set, `WXE_HAS_PUNCTUATION` will also be set.

#### WXE_HAS_UNMAPPED_CHAR

Header: `PDExpT.h:3592`

Value: `0x400`

One or more characters in the word cannot be represented in the output font encoding.

#### WXE_HAS_UPPERCASE

Header: `PDExpT.h:3541`

Value: `0x4`

The word contains a character between A-Z.

#### WXE_LAST_WORD_ON_LINE

Header: `PDExpT.h:3630`

Value: `0x8000`

The word is at the end of the current text line (for example, the word is followed by a line break).

#### WXE_PDF_ORDER

Header: `PDExpT.h:3653`

Value: `0x2`

#### WXE_RD_ORDER_SORT

Header: `PDExpT.h:3661`

Value: `0x8`

#### WXE_REVERSE_DIRECTION

Header: `PDExpT.h:3637`

Value: `0x04`

#### WXE_ROTATED

Header: `PDExpT.h:3610`

Value: `0x1000`

The writing direction of the word is not in a multiple of 90 degrees, or the bounding box of the text is skewed. This flag indicates that the quads of the word should be used to specify the highlight area correctly.

#### WXE_STREAM

Header: `PDExpT.h:3649`

Value: `0x1`

#### WXE_VERTICAL_FLOW

Header: `PDExpT.h:3619`

Value: `0x2000`

The writing direction of the word is either 90 or 180 degrees. This flag ignores the page rotation parameter of the page dictionary. Therefore, if the page is rotated 90 degrees, this flag will be set on each word that appears horizonally on the screen.

#### WXE_WBREAK_WORD

Header: `PDExpT.h:3624`

Value: `0x4000`

#### WXE_WORD_IS_UNICODE

Header: `PDExpT.h:3638`

Value: `0x08`

#### WXE_XY_SORT

Header: `PDExpT.h:3657`

Value: `0x4`

#### W_ACCENT

Header: `PDExpT.h:3484`

Value: `0x800`

An accent mark.

#### W_CNTL

Header: `PDExpT.h:3425`

Value: `0x1`

A control code.

#### W_COMMA

Header: `PDExpT.h:3474`

Value: `0x200`

A comma. Commas and periods are treated separately from other punctuation marks because they are used both as word punctuation marks and as delimiters in numbers, and need to be treated differently in the two cases.

#### W_DIGIT

Header: `PDExpT.h:3440`

Value: `0x8`

A digit.

#### W_END_PHRASE

Header: `PDExpT.h:3494`

Value: `0x2000`

An end-of-phrase glyph (for example, `"."`, `"?"`, `"!"`, `":"`, and `";"`).

#### W_HYPHEN

Header: `PDExpT.h:3450`

Value: `0x20`

A hyphen.

#### W_LETTER

Header: `PDExpT.h:3430`

Value: `0x2`

A lowercase letter.

#### W_LIGATURE

Header: `PDExpT.h:3460`

Value: `0x80`

A ligature.

#### W_PERIOD

Header: `PDExpT.h:3479`

Value: `0x400`

A period.

#### W_PUNCTUATION

Header: `PDExpT.h:3445`

Value: `0x10`

A punctuation mark.

#### W_SOFT_HYPHEN

Header: `PDExpT.h:3455`

Value: `0x40`

A hyphen that is only present because a word is broken across two lines of text.

#### W_UNMAPPED

Header: `PDExpT.h:3489`

Value: `0x1000`

A glyph that cannot be represented in the destination font encoding.

#### W_UPPERCASE

Header: `PDExpT.h:3435`

Value: `0x4`

An uppercase letter.

#### W_WHITE

Header: `PDExpT.h:3465`

Value: `0x100`

A white space glyph.

#### W_WILD_CARD

Header: `PDExpT.h:3499`

Value: `0x4000`

A wildcard glyph (for example, `"*"` and `"?"`) that should not be treated as a normal punctuation mark.

#### W_WORD_BREAK

Header: `PDExpT.h:3505`

Value: `0x8000`

A glyph that acts as a delimiter between words.

**See also:** `GlyphNamesofWordSeparators`

## PDWordFinder

### Functions (9)

#### PDWordFinderAcquireVisibleWordList

```cpp
void PDWordFinderAcquireVisibleWordList(PDWordFinder wObj, ASInt32 pgNum, PDOCContext ocContext, PDWord *wInfoP, PDWord **xySortTable, PDWord **rdOrderTable, ASInt32 *numWords)
```

Header: `PDProcs.h:10650`

Finds all words on the specified page that are visible in the given optional-content context and returns one or more tables containing the words. One table contains the words sorted in the order in which they appear in the PDF file, while the other contains the words sorted by their x- and y-coordinates on the page. The list contains only words that are visible in the given context. If the word states change in the given context, the word list will have to be released and re-acquired to reflect the changed set of visible words. There can be only one word list in existence at a time; clients must release the previous word list, using PDWordFinderReleaseWordList(), before creating a new one. Use PDWordFinderEnumWords() instead of this method if you wish to find one word at a time instead of obtaining a table containing all visible words on a page. This procedure is intended to replace the call to PDWordFinderAcquireWordList() in most cases where you want to work only with the content that is visible on screen (such as a text selection). Change this call to update an application to work with the Optional Content feature. Access the acquired list through PDWordFinderGetNthWord(). The words are ordered in PDF order, which is the order in which they appear in the PDF file's data. This is often, but not always, the order in which a person would read the words. Use PDWordFinderGetNthWord to traverse this array; you cannot access this array directly. This array is always filled, regardless of the flags used in the call to PDDocCreateWordFinder() or PDDocCreateWordFinderUCS().

**Parameters**

- `wObj` ([`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)): The word finder (created using PDDocCreateWordFinder() or PDDocCreateWordFinderUCS()) used to acquire the word list.
- `pgNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number for which words are found. First page is `0`, not `1` as designated in Acrobat.
- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context within which the words are in a visible state. `NULL` is equivalent to passing `PDDocGetOCContext(pdDoc)`.
- `wInfoP` ([`PDWord *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): (Filled by the method) A user-supplied PDWord variable. Acrobat will fill this in to point to an Acrobat-allocated array of PDWord objects, which should *never* be accessed directly.
- `xySortTable` ([`PDWord **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): (Filled by the method) Acrobat fills in this user-supplied pointer to a pointer with the location of an Acrobat-allocated array of PDWords, sorted in x-y order, meaning that all words on the first *line*, from left to right, followed by all words on the next line. This array is only filled if the WXE_XY_SORT flag was set in the call to PDDocCreateWordFinder() or PDDocCreateWordFinderUCS(). PDWordFinderReleaseWordList() *must* be called to release allocated memory for this return or there will be a memory leak. As long as this parameter is non-`NULL`, the array is always filled regardless of the value of the rdFlags parameter in PDDocCreateWordFinder().
- `rdOrderTable` ([`PDWord **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): Currently unused. Pass `NULL` for its value.
- `numWords` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): (Filled by the method) The number of visible words found on the page.

**Returns:** `void`

**Exceptions**

- `pdErrOpNotPermitted`

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDWordFinderAcquireWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireWordList), [`PDWordFinderReleaseWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderReleaseWordList), [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords), [`PDWordFinderGetNthWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderGetNthWord)

#### PDWordFinderAcquireWordList

```cpp
void PDWordFinderAcquireWordList(PDWordFinder wObj, ASInt32 pgNum, PDWord *wInfoP, PDWord **xySortTable, PDWord **rdOrderTable, ASInt32 *numWords)
```

Header: `PDProcs.h:4767`

Finds all words on the specified page and returns one or more tables containing the words. One table contains the words sorted in the order in which they appear in the PDF file, while the other contains the words sorted by their x- and y-coordinates on the page. Only words within or partially within the page's crop box (see PDPageGetCropBox()) are enumerated. Words outside the crop box are skipped. There can be only one word list in existence at a time; clients must release the previous word list, using PDWordFinderReleaseWordList(), before creating a new one. Use PDWordFinderEnumWords() instead of this method, if you wish to find one word at a time instead of obtaining a table containing all words on a page. Access the acquired list through PDWordFinderGetNthWord(). The words are ordered in PDF order, which is the order in which they appear in the PDF file's data. This is often, but not always, the order in which a person would read the words. Use PDWordFinderGetNthWord() to traverse this array; you cannot access this array directly. This array is always filled, regardless of the flags used in the call to PDDocCreateWordFinder() or PDDocCreateWordFinderUCS().

**Parameters**

- `wObj` ([`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)): The word finder (created using PDDocCreateWordFinder() or PDDocCreateWordFinderUCS()) used to acquire the word list.
- `pgNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number for which words are found. The first page is `0`, not `1` as designated in Acrobat.
- `wInfoP` ([`PDWord *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): (Filled by the method) A user-supplied PDWord variable. Acrobat will fill this in to point to an Acrobat-allocated array of PDWord objects, which should *never* be accessed directly.
- `xySortTable` ([`PDWord **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): (Filled by the method) Acrobat fills in this user-supplied pointer to a pointer with the location of an Acrobat-allocated array of PDWords, sorted in x-y order, meaning that all words on the first *line*, from left to right, are followed by all words on the next line. This array is only filled if the `WXE_XY_SORT` flag was set in the call to PDDocCreateWordFinder() or PDDocCreateWordFinderUCS(). PDWordFinderReleaseWordList() must be called to release allocated memory for this return or there will be a memory leak. As long as this parameter is non-`NULL`, the array is always filled regardless of the value of the `rdFlags` parameter in PDDocCreateWordFinder().
- `rdOrderTable` ([`PDWord **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)): Currently unused. Pass `NULL` for this value.
- `numWords` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): (Filled by the method) The number of words found on the page.

**Returns:** `void`

**Exceptions**

- `pdErrOpNotPermitted`

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDWordFinderReleaseWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderReleaseWordList), [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords), [`PDWordFinderGetNthWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderGetNthWord)

#### PDWordFinderDestroy

```cpp
void PDWordFinderDestroy(PDWordFinder wObj)
```

Header: `PDProcs.h:4814`

Destroys a word finder. Use this when you are done extracting text in a file.

**Parameters**

- `wObj` ([`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)): IN/OUT The word finder to destroy.

**Returns:** `void`

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDDocGetWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetWordFinder)

#### PDWordFinderEnumVisibleWords

```cpp
ASBool PDWordFinderEnumVisibleWords(PDWordFinder wObj, ASInt32 PageNum, PDOCContext ocContext, PDWordProc wordProc, void *clientData)
```

Header: `PDProcs.h:10723`

Extracts visible words, one at a time, from the specified page or the entire document. It calls a user-supplied procedure once for each word found. If you wish to extract all text from a page at once, use PDWordFinderAcquireWordList() instead of this method. Only words that are visible in the given optional-content context are enumerated.

**Parameters**

- `wObj` ([`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)): A word finder object.
- `PageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number from which to extract words. Pass PDAllPages (see `PDExpT.h`) to sequentially process all pages in the document.
- `ocContext` ([`PDOCContext`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDOCContext)): The context within which the words are in a visible state. `NULL` is equivalent to passing `PDDocGetOCContext(pdDoc)`.
- `wordProc` ([`PDWordProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordProc)): A user-supplied callback to call once for each word found. Enumeration halts if `wordProc` returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `wordProc` each time it is called.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if enumeration was successfully completed, `false` if enumeration was terminated because `wordProc` returned `false`.

**Exceptions**

- `genErrBadParm`: is raised if `wordProc` is `NULL`, or `pageNum` is less than zero or greater than the total number of pages in the document.
- `pdErrOpNotPermitted`

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDDocGetWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetWordFinder), [`PDWordFinderAcquireWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireWordList), [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords), [`PDWordFinderEnumWordsStr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWordsStr)

#### PDWordFinderEnumWords

```cpp
ASBool PDWordFinderEnumWords(PDWordFinder wObj, ASInt32 PageNum, PDWordProc wordProc, void *clientData)
```

Header: `PDProcs.h:4850`

Extracts words, one at a time, from the specified page or the entire document. It calls a user-supplied procedure once for each word found. If you wish to extract all text from a page at once, use PDWordFinderAcquireWordList() instead of this method. Only words within or partially within the page's crop box (see PDPageGetCropBox()) are enumerated. Words outside the crop box are skipped.

**Parameters**

- `wObj` ([`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)): A word finder object.
- `PageNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The page number from which to extract words.
  Pass PDAllPages (see PDExpT.h) to sequentially process all
  pages in the document.
- `wordProc` ([`PDWordProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordProc)): A user-supplied callback to call once for
  each word found. Enumeration halts if `wordProc` returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass
  to `wordProc` each time it is called.`true` if enumeration was successfully completed,
  `false` if enumeration was terminated because `wordProc` returned
  `false`.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

**Exceptions**

- `pdErrOpNotPermitted`
- `genErrBadParm`: is raised if `wordProc` is `NULL`, or
  `pageNum` is less than zero or greater than the total number of pages in the document.

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDDocGetWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetWordFinder), [`PDWordFinderAcquireWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireWordList), [`PDWordFinderEnumVisibleWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumVisibleWords), [`PDWordFinderEnumWordsStr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWordsStr)

#### PDWordFinderEnumWordsStr

```cpp
ASBool PDWordFinderEnumWordsStr(PDWordFinder wObj, const ASUTF16Val *ucsStr, ASUns32 strLen, ASUns32 charOffsetAdj, PDWordProc wordProc, void *clientData)
```

Header: `PDProcs.h:8689`

Constructs a PDWord list from a Unicode string, and calls a user-supplied procedure once for each word found. The words extracted by this method do not have quads, text style, or text selection information. The character offset is calculated from the beginning of the input string, and is increased by `2` on every 16 bits of data (the character offset of a character in a PDWord is the byte offset of the character in the source Unicode string). For example: `PDWordFinderEnumWordsStr(wf, str1, stelen(str1), 0, wp, d);` `PDWordFinderEnumWordsStr(wf, str2, stelen(str2), stelen(str1), wp, d);`

**Parameters**

- `wObj` ([`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)): A word finder object.
- `ucsStr` ([`const ASUTF16Val *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUTF16Val)): A pointer to the Unicode string.
- `strLen` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The length of the string in bytes.
- `charOffsetAdj` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The character offset value of the first character in the input Unicode string. This value is added to the word character offsets, and is used to maintain contiguous word character offsets when multiple strings (and multiple calls to this method) are combined into one word list.
- `wordProc` ([`PDWordProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordProc)): A user-supplied callback to call once for each word found. Enumeration halts if `wordProc` returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `wordProc` each time it is called.

**Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)

`true` if the enumeration was successfully completed, `false` if the enumeration was terminated because `wordProc` returned `false`.

**Exceptions**

- `genErrBadParm`: is raised if `wordProc` is `NULL`.
- `pdErrOpNotPermitted`

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDDocGetWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetWordFinder), [`PDWordFinderAcquireWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireWordList), [`PDWordFinderEnumVisibleWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumVisibleWords), [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords)

#### PDWordFinderGetLatestAlgVersion

```cpp
ASInt16 PDWordFinderGetLatestAlgVersion(PDWordFinder wObj)
```

Header: `PDProcs.h:4785`

Gets the version number of the specified word finder, or the version number of the latest word finder algorithm.

**Parameters**

- `wObj` ([`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)): IN/OUT The word finder whose algorithm's version is obtained. Pass `NULL` to obtain the latest word finding algorithm version number.

**Returns:** [`ASInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16)

The algorithm version associated with `wObj`, or the version of the latest word finder algorithm if `wObj` is `NULL`.

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDDocGetWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetWordFinder)

#### PDWordFinderGetNthWord

```cpp
PDWord PDWordFinderGetNthWord(PDWordFinder wObj, ASInt32 nTh)
```

Header: `PDProcs.h:2217`

Gets the nth word in the word list obtained using PDWordFinderAcquireWordList().

**Parameters**

- `wObj` ([`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)): IN/OUT The word finder whose nth word is obtained.
- `nTh` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The index of the word to obtain. The first word on a page has an index of zero. Words are counted in PDF order. See the description of the `wInfoP` parameter in PDWordFinderAcquireWordList().

**Returns:** [`PDWord`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWord)

The nth word. It returns `NULL` when the end of the list is reached.

**See also:** [`PDWordFinderAcquireWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireWordList), [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords)

#### PDWordFinderReleaseWordList

```cpp
void PDWordFinderReleaseWordList(PDWordFinder wObj, ASInt32 pgNum)
```

Header: `PDProcs.h:4802`

Releases the word list for a given page. Use this to release a list created by PDWordFinderAcquireWordList() when you are done using this list.

**Parameters**

- `wObj` ([`PDWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinder)): A word finder object.
- `pgNum` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of pages for which a word list is released.

**Returns:** `void`

**Exceptions**

- `genErrBadUnlock`: is raised if the list has already been released.

**See also:** [`PDWordFinderAcquireWordList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderAcquireWordList), [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDDocGetWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetWordFinder)

### Typedefs (1)

#### PDWordFinderCtrlProc

```cpp
typedef ASBool(*) PDWordFinderCtrlProc(ASUns32 startTime, void *clientData)(ASUns32 startTime, void *clientData)
```

Header: `PDExpT.h:3937`

This is passed to PDWordFinderSetCtrlProc(). This is the callback function called by Word Finder when its page enumeration process takes longer than the specified time (in seconds). Return `true` to continue the enumeration process, or `false` to stop. `startTime` is the value that was set by ASGetSecs() when the Word Finder started processing the current page.

### Structures (1)

#### PDWordFinder

```cpp
typedef struct _t_PDWordFinder* PDWordFinder
```

Header: `PDExpT.h:3382`

Extracts words from a PDF file, and enumerates the words on a single page or on all pages in a document.

**See also:** [`PDDocCreateWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinder), [`PDDocCreateWordFinderUCS`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateWordFinderUCS), [`PDDocGetWordFinder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetWordFinder), [`PDWordFinderDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderDestroy), [`PDWordFinderEnumWords`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDWordFinderEnumWords)

### Definitions (4)

#### WF_LATEST_VERSION

Header: `PDExpT.h:3665`

Value: `0`

Used to obtain the latest available version.

#### WF_VERSION_2

Header: `PDExpT.h:3669`

Value: `2`

The version used for Acrobat 3.x, 4.x.

#### WF_VERSION_3

Header: `PDExpT.h:3673`

Value: `3`

For Acrobat 5.0 without accessibility enabled.

#### WF_VERSION_4

Header: `PDExpT.h:3677`

Value: `4`

For Acrobat 5.0 with accessibility enabled.

## PDXObject

### Functions (5)

#### PDXObjectEnumFilters

```cpp
void PDXObjectEnumFilters(PDXObject obj, PDXObjectFilterEnumProc proc, void *clientData)
```

Header: `PDProcs.h:3866`

(Obsolete, provided only for backwards compatibility) Enumerates the filters attached to an XObject, calling a user-supplied procedure for each filter.

**Parameters**

- `obj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The XObject whose filters are enumerated.
- `proc` ([`PDXObjectFilterEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObjectFilterEnumProc)): A user-supplied callback to call for each filter attached to the XObject. Enumeration ends if `proc` returns `false`. `proc` will not be called if there are no filters attached to the XObject.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `proc` each time it is called.

**Returns:** `void`

#### PDXObjectGetCosObj

```cpp
CosObj PDXObjectGetCosObj(PDXObject xObj)
```

Header: `PDProcs.h:3825`

(Obsolete, provided only for backwards compatibility) Gets the Cos object associated with an XObject. This method does not copy the object, but is instead the logical equivalent of a type cast.

**Parameters**

- `xObj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The XObject whose Cos object is obtained.

**Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)

The dictionary Cos object for the XObject.

#### PDXObjectGetData

```cpp
void PDXObjectGetData(PDXObject obj, PDGetDataProc getDataProc, void *clientData)
```

Header: `PDProcs.h:3851`

(Obsolete, provided only for backwards compatibility) Passes the data from an XObject to a user-supplied procedure.

**Parameters**

- `obj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The XObject whose data is read.
- `getDataProc` ([`PDGetDataProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetDataProc)): A user-supplied callback to call with the XObject's data. Enumeration ends if `getDataProc` returns `false`.
- `clientData` (`void *`): A pointer to user-supplied data to pass to `getDataProc`.

**Returns:** `void`

**See also:** [`PDXObjectGetDataLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObjectGetDataLength)

#### PDXObjectGetDataLength

```cpp
ASInt32 PDXObjectGetDataLength(PDXObject xObj)
```

Header: `PDProcs.h:3837`

(Obsolete, provided only for backwards compatibility) Gets the value of the XObject stream's `length` key, which specifies the amount of data in the PDF file (that is, after all compression/encoding filters have been applied).

**Parameters**

- `xObj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The XObject whose data length is obtained.

**Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)

The XObject's data length.

**See also:** [`PDXObjectGetData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObjectGetData)

#### PDXObjectGetSubtype

```cpp
ASAtom PDXObjectGetSubtype(PDXObject xObj)
```

Header: `PDProcs.h:3814`

(Obsolete, provided only for backwards compatibility) Gets the subtype of an XObject. Examples of a subtype are Image and Form.

**Parameters**

- `xObj` ([`PDXObject`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObject)): The XObject whose subtype is obtained.

**Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)

The ASAtom corresponding to the XObject's subtype. It can be converted into a string using ASAtomGetString().

**See also:** [`PDXObjectGetData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObjectGetData)

### Typedefs (2)

#### PDGetDataProc

```cpp
typedef ASBool(*) PDGetDataProc(char *data, ASUns32 lenData, void *clientData)(char *data, ASUns32 lenData, void *clientData)
```

Header: `PDExpT.h:3122`

A callback for PDXObjectGetData(). It is passed the XObject's data. Currently, the XObject's data is read 1 kB at a time and passed to this callback.

**See also:** [`PDXObjectGetData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObjectGetData)

#### PDXObjectFilterEnumProc

```cpp
typedef ASBool(*) PDXObjectFilterEnumProc(char *filter, CosObj decodeParms, void *clientData)(char *filter, CosObj decodeParms, void *clientData)
```

Header: `PDExpT.h:3094`

A callback for PDXObjectEnumFilters(). It is called once for each filter that has been applied to an XObject's data.

**See also:** [`PDXObjectEnumFilters`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObjectEnumFilters)

### Structures (1)

#### PDXObject

```cpp
typedef struct _t_PDXObject* PDXObject
```

Header: `PDExpT.h:2506`

A superclass used for PDF XObjects. Acrobat currently uses two XObject subclasses: PDImage and PDForm. You can use any PDXObject method on these three objects.

**See also:** [`PDXObjectEnumFilters`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObjectEnumFilters), [`PDXObjectGetData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDXObjectGetData)