Layer

PD Layer

47 components1090 items
671 Functions 170 Definitions 174 Typedefs 39 Structures 36 Enums

ASFileAttachment

3 items

Functions(3)

ASFileAttachmentCreatePathName

void ASFileAttachmentCreatePathName(PDDoc pdDoc, ASText pathText, ASFileSys *fileSys, ASPathName *pathName)
PDProcs.h:12667

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

Parameters
pdDoc: PDDoc

The document containing the specified file or folder.

pathText: 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 *

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 *

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

PDProcs.h:12678

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

The ASFileSys for file attachments.

pathName: ASPathName

The ASPathName identifying the file attachment of interest.

attachment: PDFileAttachment *

A pointer that will be receive the file attachment.

Returns
ASBool

true if the file attachment was found, false otherwise.

ASFileAttachmentGetPDFolder

PDProcs.h:12689

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

The ASFileSys for file attachments

pathName: ASPathName

The ASPathName identifying the folder of interest.

folder: PDFolder *
Returns
ASBool

true if the folder was found, false otherwise.

General

65 items

Functions(18)

PDApplyFunction

void PDApplyFunction(CosObj funcDict, const float inVals[], float outVals[])
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. Deprecated use PDApplyFunctionEx instead

Parameters
funcDict: CosObj

The CosObj representing a function.

inVals: const float

Input values.

outVals: float

Output values.

Returns
void

PDApplyFunctionEx

void PDApplyFunctionEx(CosObj funcDict, const float inVals[], const ASArraySize nInput, float outVals[], const ASArraySize nOutput)
PDProcs.h:12707

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

The CosObj representing a function.

inVals: const float

Input values.

nInput: const ASArraySize

Number of input values.

outVals: float

Output values.

nOutput: const ASArraySize

Number of output values.

Returns
void

PDDrawCosObjToWindow

void PDDrawCosObjToWindow(CosObj cosObj, void *window, void *displayContext, ASBool isDPS, ASFixedMatrix *matrix, ASFixedRect *updateRect, CancelProc cancelProc, void *cancelProcClientData)
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 Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

Parameters
cosObj: 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

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

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

PDDrawCosObjWithParams

void PDDrawCosObjWithParams(CosObj cosObj, PDDrawParams params)
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. Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

Parameters
cosObj: 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

PDFormEnumPaintProc

void PDFormEnumPaintProc(PDXObject obj, PDGraphicEnumMonitor mon, void *clientData)
PDProcs.h:3994

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

Parameters
obj: PDXObject

The form whose drawing operations are enumerated.

mon: 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

PDFormEnumPaintProcWithParams

void PDFormEnumPaintProcWithParams(PDXObject obj, PDGraphicEnumParams params)
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

The form whose drawing operations are enumerated.

params: PDGraphicEnumParams

The parameters, including the optional-content context to use for content visibility.

Returns
void

PDFormEnumResources

void PDFormEnumResources(PDXObject obj, PDResourceEnumMonitor mon, void *clientData)
PDProcs.h:3977

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

Parameters
obj: PDXObject

The form whose resources are enumerated.

mon: 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

PDFormGetBBox

void PDFormGetBBox(PDXObject obj, ASFixedRect *bboxP)
PDProcs.h:3938

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

Parameters
obj: 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

PDProcs.h:3927

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

Parameters
obj: PDXObject

The form whose type is obtained.

Returns
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

void PDFormGetMatrix(PDXObject obj, ASFixedMatrix *matrixP)
PDProcs.h:3951

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

Parameters
obj: 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

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

The form whose XUID is obtained.

Returns
CosObj

The array Cos object for the form's XUID.

PDImageColorSpaceGetIndexLookup

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

Parameters
xobj: PDXObject

The image whose lookup table is obtained.

data: ASUns8 *

(Filled by the method) An array for the returned color space information.

dataLen: ASInt32

The length of data in bytes.

Returns
void

PDImageGetAttrs

void PDImageGetAttrs(PDXObject obj, PDImageAttrsP attrsP, ASInt32 attrsLen)
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

The image whose attributes are obtained.

attrsP: PDImageAttrsP

(Filled by the method) A pointer to a PDImageAttrs structure containing the image attributes.

attrsLen: ASInt32

It must be sizeof(PDImageAttrs) .

Returns
void

PDImageSelAdjustMatrix

void PDImageSelAdjustMatrix(void *callData, ASFixedMatrix newUserMatrix)
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 *
newUserMatrix: ASFixedMatrix
Returns
void

PDImageSelGetDeviceAttr

void PDImageSelGetDeviceAttr(void *callData, PDColorSpace *colorSpaceP, ASUns32 *bitsPerPixelP, ASAtom *deviceTypeP)
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:

<ul> <li>8-bit gray scale monitor </li> <li>4-bit RGB color monitor </li> </ul>

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.

Value Description Display A display device such as a monitor PostScript A PostScript printer or PostScript file nonPostScriptPrinter A non-PostScript printer

Parameters
callData: void *
colorSpaceP: PDColorSpace *
bitsPerPixelP: ASUns32 *
deviceTypeP: ASAtom *

(Filled by the method) The output device type. It will be one of the following:

Returns
void

PDImageSelGetGeoAttr

void PDImageSelGetGeoAttr(void *callData, ASFixedRect *updateBBoxP, ASFixedMatrix *imageToDefaultMatrixP, ASFixedMatrix *imageToDevMatrixP)
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

PDImageSelectAlternate

CosObj PDImageSelectAlternate(CosObj image, ASBool print, ASUns32 tickLimit, ASBool *cacheImageP, void *callData)
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

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

true if printing, false if displaying.

tickLimit: 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 *

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

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

Typedefs(22)

PDLaunchActionProc

typedef ASBool(* PDLaunchActionProc) (void *fileSpecHandlerObj, PDDoc pdDoc, PDAction pdAction))(void *fileSpecHandlerObj, PDDoc pdDoc, PDAction pdAction)
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.

Structures(5)

PDContent

typedef struct _t_PDContent* PDContent
PDBasicExpT.h:114

A pointer to a PDContent struct .

PDResourceEnumMonitor

typedef struct _t_PDResourceEnumMonitor* PDResourceEnumMonitor
PDExpT.h:2722

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

Enums(15)

GCHTextType

PDExpT.h:4366
Values
kGCHTTipText
—
kGCHTMiniText
—
kGCHTLargeText
—

HSEmitFonts

PDExpT.h:5873
Values
kHSEmitFontNoFonts
—

Embed no fonts.

kHSEmitFontEmbeddedFonts
—

Emit all embedded fonts.

kHSEmitFontAllFonts
—

Emit all fonts.

InkTypes

PDExpT.h:5908

Ink types.

Values
kNormal
—
kTransparent
—
kOpaqueInk
—
kOpaqueIgnore
—

PDCharSets

PDExpT.h:2306

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

Values
PDUnknownCharSet
—

The font does not use Adobe standard encoding.

PDStandardRomanCharSet
—

The font uses Adobe standard encoding. This is determined by the "Uses Adobe Standard Encoding" bit in the font descriptor.

PDAdobeExpertCharSet
—

Currently unused.

PDLastCharSet
—

PDColorSpaces

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
—

Grayscale. It requires one value entry to specify the color.

PDDeviceRGB
—

Red-Green-Blue color specification. It requires three value entries to specify the color.

PDDeviceCMYK
—

Cyan-Magenta-Yellow-Black color specification. It requires four value entries to specify the color.

Values
kAnnotAll
—

Copy all annotations; do not consult annotation type list

kDoNotMergeFonts
—

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

PDExpT.h:5836
Values
kPDEndMiter
—
kPDEndOverlap
—

PDFindFlagTypes

PDExpT.h:2171

Passed to PDFindText().

Values
PDFindWholeWords
—

Find whole words only.

PDFindCaseSens
—

Perform a case-sensitive search.

PDFindReverse
—

Perform a reverse order search.

PDFindAllOnPage
—

Return a PDTextSelect with all found words on the page.

PDFindIgnoreFH
—

Do not perform a match of full-width/half-width Kana characters.

PDFindIgnoreDiacritics
—

Ignore diacritics.

PDFindReset
—

Reset to the beginning of the document.

PDHorizAlignments

PDExpT.h:6533
Values
kPDHorizLeft
—
kPDHorizCenter
—
kPDHorizRight
—

PDInsertFlags

PDExpT.h:2115

Used by PDDocInsertPages().

Values
PDInsertBookmarks
—

Insert bookmarks as well as pages.

PDInsertAll
—

Insert all Catalog and Info dictionary values as well as pages.

PDInsertThreads
—

Insert articles as well.

PDDoNotInsertOutputIntent
—

Do not merge output Intents

PDInsertDoNotMergeFonts
—

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
—

This is not necessary in most cases but it can show performance benefits for a document with a complicated Structure Tree.

PDInsertDoNotRemovePageInheritance
—

This can slow down the performance when document has a very large page tree

PDInsertNamedDestinations
—

Copy named destinations to maintain link annotations

PDJoinStyles

PDExpT.h:5824
Values
kPDJoinMiter
—
kPDJoinRound
—
kPDJoinBevel
—

PDLayoutModes

PDExpT.h:2015

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
—

(Default) Use the user preference when opening the file, as specified in the avpPageViewLayoutMode preference, set by AVAppSetPreference().

PDLayoutSinglePage
—

Use single-page mode.

PDLayoutOneColumn
—

Use one-column continuous mode.

PDLayoutTwoColumnLeft
—

Use two-column continuous mode with the first page on the left.

PDLayoutTwoColumnRight
—

Use two-column continuous mode with the first page on the right.

PDLayoutTwoPageLeft
—
PDLayoutTwoPageRight
—

PDVertAlignments

PDExpT.h:6537
Values
kPDVertTop
—
kPDVertCenter
—
kPDVertBottom
—
Values
kEmitPlate
—
kDontEmitPlate
—
kConvertToProcess
—

Represents an ink used on a page.

kConvertToAltSpace
—

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

PDExpT.h:5919
Values
kPDDefaultMarkType
—

No flags means InDesign style printer marks.

kPDInDesignJ1MarkType
—
kPDInDesignJ2MarkType
—
kPDIllustratorMarkType
—
kPDIllustratorJ
—
kPDQuarkXPress
—

Definitions(5)

kPDEmitSlug

PDExpT.h:6278
Value:0x0004

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

Metadata

4 items

Functions(4)

PDDocGetInfo

ASInt32 PDDocGetInfo(PDDoc doc, const char *infoKey, char *buffer, ASInt32 bufSize)
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.

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
infoKey: const char *
buffer: char *
bufSize: ASInt32

The maximum number of bytes that can be written into buffer .

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

PDDocGetInfoASText

void PDDocGetInfoASText(PDDoc doc, const ASText key, ASText value)
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

The document whose Info dictionary key is obtained.

key: const ASText

The name of the Info dictionary key whose value is obtained.

value: 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

PDDocSetInfo

void PDDocSetInfo(PDDoc doc, const char *infoKey, const char *buffer, ASInt32 nBytes)
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

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

The number of bytes in buffer .

Returns
void

PDAction

18 items

Functions(16)

PDActionCanCopy

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

The action to test.

Returns
ASBool

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

PDActionGetCosObj

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

IN/OUT The action whose Cos object is obtained.

Returns
CosObj

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

PDActionGetDest

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). Since this method may not return a PDViewDestination, use the PDViewDestResolve() method on the returned value to obtain a PDViewDestination.

Parameters
action: PDAction

The action whose destination is obtained.

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

PDActionGetFileSpec

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

The action whose file specification is obtained.

Returns
PDFileSpec

The action's file specification.

See Also

PDActionIsValid

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

The action whose validity is determined.

Returns
ASBool

true if the action is valid, false otherwise.

See Also

PDActionNewFromDest

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

The document in which the action is created and used.

dest: PDViewDestination

The destination view.

destDoc: PDDoc

The destination document. destDoc must be the same as doc .

Returns
PDAction

The newly created action.

PDActionNewFromFileSpec

PDAction PDActionNewFromFileSpec(PDDoc containingDoc, ASAtom type, PDFileSpec fileSpec)
PDProcs.h:111

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

Parameters
containingDoc: PDDoc

The document in which the action is created and used.

type: ASAtom

The type of action to create.

fileSpec: PDFileSpec

The file specification that is made part of an action.

Returns
PDAction

The newly created PDAction.

PDActionPaste

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

The destination document for the paste operation.

data: PDActionClipboardData

The clipboard structure holding the copied action data.

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

Typedefs(1)

Structures(1)

PDActionHandler

10 items

Functions(1)

Typedefs(8)

PDActionHandlerCanCopyProc

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. The handler is not expected to test other actions (if any) in the action chain.

PDActionHandlerCanPasteProc

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. The handler is not expect to test other actions (if any) in the action chain.

PDActionHandlerCopyProc

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.

PDActionHandlerPasteProc

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.

Structures(1)

PDAnnot

53 items

Functions(28)

PDAnnotCanCopy

ASBool PDAnnotCanCopy(PDPage sourcePage, PDAnnot annot)
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

The page containing the annotation to test. It can be NULL (as when copying annotations while spawning a hidden template).

annot: PDAnnot

The annotation to test.

Returns
ASBool

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

PDAnnotCanPaste

ASBool PDAnnotCanPaste(PDPage destPage, const ASFixedPoint *center, PDAnnotClipboardData data)
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

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

The copied annotation data to test.

Returns
ASBool

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

PDAnnotCopy

PDProcs.h:10916

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

Parameters
sourcePage: PDPage

The page containing the annotation to copy. It can be NULL (as when copying annotations while spawning a hidden template).

annot: PDAnnot

The annotation to copy.

Returns
PDAnnotClipboardData

The annotation clipboard data object.

PDAnnotEqual

PDProcs.h:393

Tests whether two annotations are identical.

Parameters
anAnnot: PDAnnot

The first annotation to compare.

annot2: PDAnnot

The second annotation to compare.

Returns
ASBool

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

See Also

PDAnnotGetColor

ASBool PDAnnotGetColor(PDAnnot anAnnot, PDColorValue color)
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

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

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

PDAnnotGetCosObj

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

IN/OUT The annotation whose Cos object is obtained.

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

PDAnnotGetSubtype

PDProcs.h:343

Gets an annotation's subtype.

Parameters
anAnnot: PDAnnot

The annotation whose subtype is obtained.

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

PDAnnotGetTitleASText

void PDAnnotGetTitleASText(PDAnnot anAnnot, ASText title)
PDProcs.h:11445

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

Parameters
anAnnot: PDAnnot

The annotation whose label is obtained.

title: 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

PDAnnotIsCurrentlyVisible

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

The annotation to test.

ocContext: PDOCContext

The optional-content context in which the visibility is tested.

Returns
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

PDAnnotIsValid

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

The annotation whose validity is tested.

Returns
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

PDAnnotNotifyDidChange

PDProcs.h:274

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

Parameters
annot: PDAnnot

The annotation that has changed.

key: ASAtom

The ASAtom corresponding to the name of the key in the annotation's Cos dictionary that is changing.

err: 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

PDAnnotPaste

PDAnnot PDAnnotPaste(PDPage destPage, const ASFixedPoint *center, PDAnnotClipboardData data)
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

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

The copied annotation data to paste.

Returns
PDAnnot

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

PDAnnotSetColor

void PDAnnotSetColor(PDAnnot anAnnot, const PDColorValue color)
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

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

PDAnnotSetRect

void PDAnnotSetRect(PDAnnot anAnnot, const ASFixedRect *newBox)
PDProcs.h:380

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

Parameters
anAnnot: 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

Typedefs(3)

Structures(1)

Enums(1)

PDAnnotPrintOps

PDExpT.h:556

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

Values
kPDAnnotPrintStandard
—

A standard print operation.

kPDAnnotPrintVariableData
—

The user selected Form Fields Only.

Definitions(20)

PDAnnotIgnorePerms

PDExpT.h:469
Value:0x0008

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

pdAnnotHidden

PDExpT.h:376
Value:0x02

The annotation is not visible and does not print.

pdAnnotInvisible

PDExpT.h:371
Value:0x01

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

pdAnnotLock

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

PDExpT.h:417
Value:0x200

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

pdAnnotNoRotate

PDExpT.h:391
Value:0x10

The annotation does not rotate with the page.

pdAnnotNoView

PDExpT.h:396
Value:0x20

The annotation does not view but can print.

pdAnnotNoZoom

PDExpT.h:386
Value:0x08

The annotation does not zoom with the view.

pdAnnotReadOnly

PDExpT.h:401
Value:0x40

The annotation does not interact with the user.

pdAnnotSequenceAdjust

PDExpT.h:422
Value:0x80000000

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

pdAnnotToggleNoView

PDExpT.h:412
Value:0x100

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

PDAnnotHandler

16 items

Functions(2)

PDGetAnnotHandlerByName

PDProcs.h:6905

Gets the annotation handler that handles the specified annotation type.

Parameters
name: 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

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

PDRegisterAnnotHandler

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

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

Typedefs(13)

PDAnnotHandlerCanCopyProc

typedef ASBool(* PDAnnotHandlerCanCopyProc) (PDAnnotHandler pdanh, PDPage sourcePage, PDAnnot pdan))(PDAnnotHandler pdanh, PDPage sourcePage, PDAnnot pdan)
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.

PDAnnotHandlerCanPasteProc

typedef ASBool(* PDAnnotHandlerCanPasteProc) (PDAnnotHandler pdanh, PDPage destPage, const ASFixedPoint *center, PDAnnotHandlerClipboardData data))(PDAnnotHandler pdanh, PDPage destPage, const ASFixedPoint *center, PDAnnotHandlerClipboardData data)
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.

PDAnnotHandlerCopyProc

typedef PDAnnotHandlerClipboardData(* PDAnnotHandlerCopyProc) (PDAnnotHandler pdanh, PDPage sourcePage, PDAnnot pdan))(PDAnnotHandler pdanh, PDPage sourcePage, PDAnnot pdan)
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.

PDAnnotHandlerDestroyDataProc

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.

PDAnnotHandlerGetAnnotInfoFlagsProc

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.

PDAnnotHandlerPasteProc

typedef PDAnnot(* PDAnnotHandlerPasteProc) (PDAnnotHandler pdanh, PDPage destPage, const ASFixedPoint *center, PDAnnotHandlerClipboardData data))(PDAnnotHandler pdanh, PDPage destPage, const ASFixedPoint *center, PDAnnotHandlerClipboardData data)
PDExpT.h:775

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

Structures(1)

PDAnnotHandler

typedef struct _t_PDAnnotHandler* PDAnnotHandler
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.

PDBead

16 items

Functions(15)

PDBeadEqual

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

The first bead to compare.

bead2: PDBead

The second bead to compare.

Returns
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

PDBeadFromCosObj

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

The dictionary Cos object whose bead is obtained.

Returns
PDBead

The PDBead object for the bead.

See Also

PDBeadGetCosObj

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

IN/OUT The bead whose Cos object is obtained.

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

PDBeadGetRect

void PDBeadGetRect(PDBead bead, ASFixedRectP rectP)
PDProcs.h:4286

Gets a bead's bounding rectangle.

Parameters
bead: 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

PDBeadIsValid

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

The bead whose validity is tested.

Returns
ASBool

true if the bead is valid, false otherwise.

See Also

PDBeadNew

PDBead PDBeadNew(PDPage page, const ASFixedRectP destRect)
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

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

The newly created bead.

PDBeadSetRect

void PDBeadSetRect(PDBead bead, const ASFixedRectP newDestRect)
PDProcs.h:4299

Sets a bead's bounding rectangle.

Parameters
bead: 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

Typedefs(1)

PDBookmark

40 items

Functions(38)

PDBookmarkAddChild

void PDBookmarkAddChild(PDBookmark parent, PDBookmark aBookmark)
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

The parent of the bookmark being added.

aBookmark: PDBookmark

The bookmark that will become the last child of aBookmark . aBookmark must have been previously unlinked. @notify PDBookmarkDidChangePosition

Returns
void

PDBookmarkAddNewChild

PDBookmark PDBookmarkAddNewChild(PDBookmark aBookmark, const char *initialText)
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

The bookmark to which a new last child is added.

initialText: const char *

The new bookmark's title.

Returns
PDBookmark

The newly created bookmark. @notify PDBookmarkDidChangePosition @notify PDBookmarkWasCreated

PDBookmarkAddNewChildASText

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

The bookmark to which a new last child is added.

initialText: const ASText

The text object containing the new bookmark's title.

Returns
PDBookmark

The newly created bookmark.

PDBookmarkAddNewSibling

PDBookmark PDBookmarkAddNewSibling(PDBookmark aBookmark, char *initialText)
PDProcs.h:752

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

Parameters
aBookmark: PDBookmark

The bookmark that will be the left sibling of the new bookmark.

initialText: char *

The new bookmark's title.

Returns
PDBookmark

The newly created bookmark. @notify PDBookmarkDidChangePosition @notify PDBookmarkWasCreated

PDBookmarkAddNewSiblingASText

PDProcs.h:11590

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

Parameters
aBookmark: PDBookmark

The bookmark that will be the left sibling of the new bookmark.

initialText: const ASText

The text object containing the new bookmark's title.

Returns
PDBookmark

The newly created bookmark.

PDBookmarkAddNext

void PDBookmarkAddNext(PDBookmark aBookmark, PDBookmark newNext)
PDProcs.h:885

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

Parameters
aBookmark: PDBookmark

IN/OUT The bookmark that will receive a new right sibling.

newNext: PDBookmark

IN/OUT The bookmark to become the new right sibling of aBookmark . newNext must have been previously unlinked.

Returns
void

PDBookmarkAddPrev

void PDBookmarkAddPrev(PDBookmark aBookmark, PDBookmark newPrev)
PDProcs.h:867

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

Parameters
aBookmark: PDBookmark

The bookmark that will receive a new left sibling newPrev .

newPrev: PDBookmark

The bookmark to become the new left sibling of aBookmark . newPrev must have been previously unlinked. @notify PDBookmarkDidChangePosition

Returns
void

PDBookmarkAddSubtree

void PDBookmarkAddSubtree(PDBookmark aBookmark, PDBookmark source, char *sourceTitle)
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

IN/OUT The bookmark to which the subtree source will be added as a new last child.

source: 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

PDBookmarkAddSubtreeASText

void PDBookmarkAddSubtreeASText(PDBookmark aBookmark, PDBookmark source, const ASText sourceTitle)
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.

Parameters
aBookmark: PDBookmark
source: PDBookmark
sourceTitle: const ASText
Returns
void

PDBookmarkGetByTitle

PDBookmark PDBookmarkGetByTitle(PDBookmark aBookmark, const char *aname, ASInt32 nameLen, ASInt32 maxdepth)
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. 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

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

IN/OUT The length of aName .

maxdepth: ASInt32

IN/OUT The number of subtree levels to search, not counting the root level:

Returns
PDBookmark

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

PDBookmarkGetColor

ASBool PDBookmarkGetColor(PDBookmark bm, PDColorValue pdcvOut)
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

The bookmark in question.

pdcvOut: PDColorValue

(Filled by the method) The color of the bookmark in PDColorValue format.

Returns
ASBool

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

PDBookmarkGetIndent

PDProcs.h:1009

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

Parameters
aBookmark: PDBookmark

IN/OUT The bookmark whose indentation level is obtained.

Returns
ASInt32

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

PDBookmarkIsValid

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

The bookmark whose validity is tested.

Returns
ASBool

true if the bookmark is valid, false otherwise.

See Also

PDBookmarkSetFlags

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

The bookmark whose flags are set.

nFlags: 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

PDBookmarkSetOpen

void PDBookmarkSetOpen(PDBookmark aBookmark, ASBool isOpen)
PDProcs.h:1091

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

Parameters
aBookmark: PDBookmark

IN/OUT The bookmark to open or close.

isOpen: ASBool

IN/OUT true if the bookmark is opened, false if the bookmark is closed. @notify PDBookmarkWillChange @notify PDBookmarkDidChange

Returns
void

Typedefs(2)

PDBookmark

typedef OPAQUE_64_BITS PDBookmark
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.

PDCharProc

2 items

Functions(2)

PDCharProcEnum

void PDCharProcEnum(PDCharProc obj, PDGraphicEnumMonitor mon, void *clientData)
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

The character procedure whose graphic description is enumerated.

mon: 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

PDCollection

22 items

Functions(16)

PDCollectionCreateFolder

PDProcs.h:12430

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

The collection that will be associated with the new folder.

path: 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

The new folder object.

PDCollectionGetFolder

PDProcs.h:12448

Gets an existing folder.

Parameters
collection: PDCollection

The collection associated with the folder to be obtained.

path: 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

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

PDCollectionGetSortOrder

ASArraySize PDCollectionGetSortOrder(PDCollection collection, PDCollectionSchemaSortPairRec *pairs, ASArraySize arrayLen)
PDProcs.h:12341

Gets the contents of the collection sort dictionary.

Parameters
collection: PDCollection

The collection object.

pairs: PDCollectionSchemaSortPairRec *

The array of pairs. It may be NULL .

arrayLen: ASArraySize

The length of the pairs array.

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

PDCollectionSchemaGetField

ASBool PDCollectionSchemaGetField(PDCollectionSchema schema, PDCollectionFieldRec *field)
PDProcs.h:12390

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

The collection schema object.

field: PDCollectionFieldRec *

The field to be obtained.

Returns
ASBool

true if the field was found, false otherwise.

PDCollectionSchemaSetField

void PDCollectionSchemaSetField(PDCollectionSchema schema, const PDCollectionFieldRec *field)
PDProcs.h:12402

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

The collection schema object.

field: const PDCollectionFieldRec *

The field to add or modify in the collection schema.

Returns
void

Typedefs(4)

PDCollection

typedef OPAQUE_64_BITS PDCollection
PDExpT.h:6987

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.

PDNavigator

typedef OPAQUE_64_BITS PDNavigator
PDExpT.h:6996

Opaque object representing a collection navigator dictionary.

Enums(2)

PDCollectionSplitTypes

PDExpT.h:7010

Collection split types.

Values
kCollectionSplitDefault
—

Default split based on view.

kCollectionSplitHorizontal
—

Split vertical.

kCollectionSplitVertical
—

Split horizontal.

kCollectionSplitNone
—

No split; show the navigator.

kCollectionSplitPreview
—

No split; show the preview.

PDCollectionViewTypes

PDExpT.h:6999

Collection view types.

Values
kCollectionViewTile
—

Tile navigator.

kCollectionViewDetails
—

Details navigator.

kCollectionViewCustom
—

Custom navigator.

PDCollectionSchema

2 items

Functions(1)

Structures(1)

PDCollectionSchema

typedef struct CPDCollectionSchema* PDCollectionSchema
PDExpT.h:7052

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

41 items

Functions(3)

PDCryptAuthorizeFilterAccess

ASBool PDCryptAuthorizeFilterAccess(PDDoc doc, ASAtom handlerName, ASAtom filterName, ASBool bEncrypt)
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

The document containing the embedded file whose filter access is requested.

handlerName: ASAtom

The security handler containing the Authorize() callback procedure to run.

filterName: ASAtom

The ASAtom corresponding to the name of the security filter used by the embedded file.

bEncrypt: ASBool

When true , the access is required for an encryption operation. When false , it is a decryption operation.

Returns
ASBool

true if the authorization succeeds, false otherwise.

PDRegisterCryptHandler

void PDRegisterCryptHandler(PDCryptHandler handler, const char *pdfName, const char *userName)
PDProcs.h:2594

Registers a new security handler with the Acrobat viewer.

Parameters
handler: 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

PDRegisterCryptHandlerEx

void PDRegisterCryptHandlerEx(PDCryptHandler handler, const char *pdfName, const char *userName, void *clientData)
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

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

Typedefs(34)

PDCryptAuthorizeProc

typedef PDPerms(* PDCryptAuthorizeProc) (PDDoc pdDoc, void *authData, PDPerms permWanted))(PDDoc pdDoc, void *authData, PDPerms permWanted)
PDExpT.h:4425

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.

PDCryptBatchAuthorizeProc

typedef PDPermReqStatus(* PDCryptBatchAuthorizeProc) (PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void *authData))(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void *authData)
PDExpT.h:4975

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

typedef void(* PDCryptBatchFreeAuthDataProc) (void *authData))(void *authData)
PDExpT.h:4987

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

typedef void *(* PDCryptBatchNewAuthDataProc) (void))(void)
PDExpT.h:4953

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

typedef void(* PDCryptBatchParamDescProc) (const ASCab settings, ASCab paramDesc))(const ASCab settings, ASCab paramDesc)
PDExpT.h:4934

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

typedef void(* PDCryptBatchPostSequenceProc) (ASCab settings))(ASCab settings)
PDExpT.h:5015

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

typedef ASBool(* PDCryptBatchPreSequenceProc) (ASCab settings))(ASCab settings)
PDExpT.h:5006

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

typedef ASBool(* PDCryptBatchShowDialogProc) (ASCab settings))(ASCab settings)
PDExpT.h:4919

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

typedef ASBool(* PDCryptBatchUpdateSecurityDataProc) (PDDoc pdDoc, ASCab settings, ASAtom *cryptHandler, void **secDataP))(PDDoc pdDoc, ASCab settings, ASAtom *cryptHandler, void **secDataP)
PDExpT.h:5033

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(). This function is called a batch operation and therefore should not display any user interface.

PDCryptCanParseEncryptDictProc

typedef ASBool(* PDCryptCanParseEncryptDictProc) (PDDoc pdDoc, CosObj encryptDict))(PDDoc pdDoc, CosObj encryptDict)
PDExpT.h:4834

(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

typedef ASBool(* PDCryptDisplaySecurityDataProc) (PDDoc pdDoc, ASAtom cryptHandler))(PDDoc pdDoc, ASAtom cryptHandler)
PDExpT.h:4814

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

typedef ASBool(* PDCryptEncryptDocMetadata) (PDDoc pdDoc))(PDDoc pdDoc)
PDExpT.h:4878

(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

typedef void(* PDCryptFillEncryptDictProc) (PDDoc pdDoc, CosObj encryptDict))(PDDoc pdDoc, CosObj encryptDict)
PDExpT.h:4637

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

PDCryptFilterAuthorizeProc

typedef ASBool(* PDCryptFilterAuthorizeProc) (CosDoc dP, ASAtom filterName, CosObj encryptDict, ASBool bEncrypt, ASBool bUIAllowed))(CosDoc dP, ASAtom filterName, CosObj encryptDict, ASBool bEncrypt, ASBool bUIAllowed)
PDExpT.h:5093

(Optional) A callback for PDCryptFilterHandler. Acrobat's security mechanism calls this method to determine whether the user should have access to this filter.

PDCryptFilterGetDataProc

typedef ASInt32(* PDCryptFilterGetDataProc) (CosDoc dP, ASAtom filterName, char **key, ASBool bNewKey, ASBool bUIAllowed))(CosDoc dP, ASAtom filterName, char **key, ASBool bNewKey, ASBool bUIAllowed)
PDExpT.h:5116

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

PDCryptFilterStreamProc

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)
PDExpT.h:5068

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

PDCryptGetAuthDataExProc

typedef ASBool(* PDCryptGetAuthDataExProc) (PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void **authDataP))(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void **authDataP)
PDExpT.h:4770

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.

PDCryptGetAuthDataProc

typedef ASBool(* PDCryptGetAuthDataProc) (PDDoc pdDoc, PDPerms permWanted, void **authDataP))(PDDoc pdDoc, PDPerms permWanted, void **authDataP)
PDExpT.h:4479

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

PDCryptGetDocPermsProc

typedef void(* PDCryptGetDocPermsProc) (PDDoc pdDoc, ASBool perms[PDPermReqObjLast][PDPermReqOprLast], ASInt16 *version))(PDDoc pdDoc, ASBool perms[PDPermReqObjLast][PDPermReqOprLast], ASInt16 *version)
PDExpT.h:4863

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.

PDCryptGetInfoTextProc

typedef ASText(* PDCryptGetInfoTextProc) (PDDoc pdDoc, GCHTextType textType))(PDDoc pdDoc, GCHTextType textType)
PDExpT.h:4898

(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

typedef void(* PDCryptGetSecurityInfoProc) (PDDoc pdDoc, ASUns32 *secInfo))(PDDoc pdDoc, ASUns32 *secInfo)
PDExpT.h:4660

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

PDCryptNewAuthDataProc

typedef void *(* PDCryptNewAuthDataProc) (PDDoc pdDoc))(PDDoc pdDoc)
PDExpT.h:4442

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

PDCryptNewCryptDataExProc

typedef void(* PDCryptNewCryptDataExProc) (PDDoc pdDoc, char **cryptData, ASInt32 *cryptDataLen, ASInt32 *cryptVersion))(PDDoc pdDoc, char **cryptData, ASInt32 *cryptDataLen, ASInt32 *cryptVersion)
PDExpT.h:4725

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.

PDCryptNewSecurityDataFromOriginalDocProc

typedef ASBool(* PDCryptNewSecurityDataFromOriginalDocProc) (PDDoc pdDoc, CosObj encryptDict, PDDoc alreadyOpenedDoc, CosObj openedEncryptDict, void **authDataP))(PDDoc pdDoc, CosObj encryptDict, PDDoc alreadyOpenedDoc, CosObj openedEncryptDict, void **authDataP)
PDExpT.h:4798

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

typedef void *(* PDCryptNewSecurityDataProc) (PDDoc pdDoc, CosObj encryptDict))(PDDoc pdDoc, CosObj encryptDict)
PDExpT.h:4522

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

PDCryptReservedProc

typedef void *(* PDCryptReservedProc) (void))(void)
PDExpT.h:4820

(Optional) A callback for PDCryptHandler. It is used by the Acrobat WebBuy proprietary method of passing crypt data.

PDCryptUpdateSecurityDataProc

typedef ASBool(* PDCryptUpdateSecurityDataProc) (PDDoc pdDoc, ASAtom *cryptHandler, void **secDataP))(PDDoc pdDoc, ASAtom *cryptHandler, void **secDataP)
PDExpT.h:4583

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.

PDCryptValidateSecurityDataProc

typedef void(* PDCryptValidateSecurityDataProc) (PDDoc pdDoc, void *secData))(PDDoc pdDoc, void *secData)
PDExpT.h:4546

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

Structures(3)

Definitions(1)

PDDoc

211 items

Functions(121)

PDDocAcquire

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

IN/OUT The document whose reference count is incremented.

Returns
void
See Also

PDDocAcquirePage

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

The document containing the page to acquire.

pageNum: ASInt32

The page number of the page to acquire. The first page is 0 .

Returns
PDPage

The acquired page.

PDDocAddJobID

void PDDocAddJobID(PDDoc doc, ASInt32 jobId)
PDProcs.h:12837

Adds a print job identifier, or JobId, from the print job to the PDDoc's list of associated jobIds.

Parameters
doc: PDDoc

The document whose jobId is being set.

jobId: ASInt32

The job Id being added to the document's list of job ids.

Returns
void

PDDocAddThread

void PDDocAddThread(PDDoc doc, ASInt32 addAfterIndex, PDThread thread)
PDProcs.h:1865

Adds an article thread to a document after the specified thread index.

Parameters
doc: 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

IN/OUT The index of the thread after which thread is added.

thread: PDThread

IN/OUT The thread to add. @notify PDDocDidAddThread

Returns
void

PDDocAddWatermarkFromPDPage

void PDDocAddWatermarkFromPDPage(PDDoc pdDoc, PDPage pdPage, PDDocAddWatermarkParamsRec *pParams)
PDProcs.h:11313

Adds a PDPage as a watermark to a page range in the given document.

Parameters
pdDoc: PDDoc

The document onto which the watermark will be added.

pdPage: 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

void PDDocAddWatermarkFromText(PDDoc pdDoc, PDDocWatermarkTextParamsRec *pTextParams, PDDocAddWatermarkParamsRec *pParams)
PDProcs.h:11321

Adds a text-based watermark to a page range in the given document.

Parameters
pdDoc: 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

ASBool PDDocApplyRedactions(PDDoc pdDoc, PDApplyRedactionParams applyParams)
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

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

true if the document's content was changed, false otherwise.

PDDocAuthorize

PDPerms PDDocAuthorize(PDDoc pdDoc, PDPerms permsWanted, void *authData)
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
permsWanted: PDPerms
authData: void *
Returns

PDDocClearErrors

PDProcs.h:12730

Clears all the non-fatal errors encountered since the document was opened, or PDDocClearErrors was called.

Parameters
doc: PDDoc

The document in which the non-fatal errors have occurred.

Returns
void

PDDocClearFlags

void PDDocClearFlags(PDDoc doc, ASInt32 flags)
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

IN/OUT The document whose flags are cleared.

flags: ASInt32

IN/OUT The flags to clear. It must be an OR of the PDDocFlags values.

Returns
void

PDDocClose

void PDDocClose(PDDoc doc)
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

The document to close.

Returns
void

PDDocCopyToFile

void PDDocCopyToFile(PDDoc pdDoc, PDDocCopyParams params)
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

The document to copy.

params: PDDocCopyParams

A structure that defines how the PDF file is copied.

Returns
void

PDDocCreate

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
: void
Returns
PDDoc

The newly created document.

PDDocCreateNameTree

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

The document in which the name tree is created.

theTree: ASAtom

The name of the name tree to create. A string can be converted to an ASAtom using ASAtomFromString().

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

PDDocCreatePage

PDPage PDDocCreatePage(PDDoc doc, ASInt32 afterPageNum, ASFixedRect mediaBox)
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

The document in which the page is created.

afterPageNum: 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

The newly created page. @notify PDDocWillInsertPages @notify PDDocDidInsertPages @notify PDDocDidChangePages @notify PDDocDidChangeThumbs

PDDocCreateRedaction

PDAnnot PDDocCreateRedaction(PDDoc pdDoc, PDRedactParams redactionProps)
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

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

The new annotation representing the redaction mark.

PDDocCreateTextSelect

PDTextSelect PDDocCreateTextSelect(PDDoc doc, ASInt32 pageNum, ASFixedRect *boundingRect)
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(). When this method is used to create a text selection on a rotated page, you must pass in a rotated boundingRect .

Parameters
doc: PDDoc

The document in which a text selection is created.

pageNum: 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

The newly created text selection.

PDDocCreateTextSelectUCS

PDTextSelect PDDocCreateTextSelectUCS(PDDoc doc, ASInt32 pageNum, ASFixedRect *fxBoundingRectP)
PDProcs.h:12896

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(). When this method is used to create a text selection on a rotated page, you must pass in a rotated boundingRect .

Parameters
doc: PDDoc

The document in which a text selection is created.

pageNum: ASInt32

The page number on which the text selection is created.

fxBoundingRectP: ASFixedRect *
Returns
PDTextSelect

The newly created text selection.

PDDocCreateThumbs

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

IN/OUT The document for which thumbnail images are created.

firstPage: ASInt32

IN/OUT The page number of the first page for which thumbnails are created. The first page is 0 .

lastPage: 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

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

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

IN/OUT The number of bits per color component in the thumbnail image's data. 8 is the only valid value.

hiVal: 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

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

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

PDDocCreateWordFinder

PDWordFinder PDDocCreateWordFinder(PDDoc doc, ASUns16 *outEncInfo, char **outEncVec, char **ligatureTbl, ASInt16 algVersion, ASUns16 rdFlags, void *clientData)
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 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/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.

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

Parameters
doc: PDDoc

The document on which the word finder is used.

outEncInfo: 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 **
algVersion: ASInt16
rdFlags: 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

The newly created word finder.

PDDocCreateWordFinderEx

PDWordFinder PDDocCreateWordFinderEx(PDDoc doc, ASInt16 algVersion, ASBool outUnicode, PDWordFinderConfig wbConfig)
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. 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

The document on which the word finder is used.

algVersion: 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

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

The newly created word finder object.

PDDocCreateWordFinderUCS

PDWordFinder PDDocCreateWordFinderUCS(PDDoc doc, ASInt16 algVersion, ASUns16 rdFlags, void *clientData)
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 Technical Note #5014, Adobe CMap and CIDFont Files Specification https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf 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). 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

The document on which the word finder is used.

algVersion: 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

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

The newly created word finder.

PDDocDeletePages

void PDDocDeletePages(PDDoc doc, ASInt32 firstPage, ASInt32 lastPage, ProgressMonitor progMon, void *progMonClientData)
PDProcs.h:1615

Deletes the specified pages.

Parameters
doc: PDDoc

The document from which pages are deleted.

firstPage: ASInt32

The page number of the first page to delete. The first page is 0 .

lastPage: ASInt32

The page number of the last page to delete.

progMon: 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

PDDocDeleteThumbs

void PDDocDeleteThumbs(PDDoc doc, ASInt32 firstPage, ASInt32 lastPage, ProgressMonitor progMon, void *progMonClientData)
PDProcs.h:2028

Deletes thumbnail images for a range of pages in a document.

Parameters
doc: PDDoc

IN/OUT The document from which thumbnail images are deleted.

firstPage: ASInt32

IN/OUT The page number of the first page in doc whose thumbnail image is deleted. The first page is 0 .

lastPage: ASInt32

IN/OUT The page number of the last page in doc whose thumbnail image is deleted.

progMon: 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

PDDocEnumFonts

void PDDocEnumFonts(PDDoc doc, ASInt32 firstPage, ASInt32 lastPage, PDFontEnumProc eproc, void *clientData, ProgressMonitor progMon, void *progMonClientData)
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

The document whose fonts are enumerated.

firstPage: ASInt32

The page number of the first page for which fonts are enumerated. The first page is 0 .

lastPage: ASInt32

The page number of the last page for which fonts are enumerated.

eproc: 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

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

PDDocEnumLoadedFonts

void PDDocEnumLoadedFonts(PDDoc doc, PDFontEnumProc proc, void *clientData)
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

IN/OUT The document whose loaded fonts are enumerated.

proc: 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

PDDocEnumOCConfigs

void PDDocEnumOCConfigs(PDDoc pdDoc, PDOCConfigEnumProc enumProc, void *clientData)
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

The document whose configurations are enumerated.

enumProc: 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

PDDocEnumOCGs

void PDDocEnumOCGs(PDDoc pdDoc, PDOCGEnumProc enumProc, void *clientData)
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

The document whose groups are enumerated.

enumProc: 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

PDDocEnumResources

void PDDocEnumResources(PDDoc pdDoc, ASInt32 startPage, ASInt32 endPage, ASAtom resourceType, CosObjEnumProc enumProc, void *clientData)
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

IN/OUT The document whose resources are enumerated.

startPage: ASInt32

IN/OUT The first page whose resources are enumerated. The first page in a document is 0 .

endPage: ASInt32

IN/OUT The last page whose resources are enumerated.

resourceType: 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

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

PDDocExportNotes

CosDoc PDDocExportNotes(PDDoc doc, ASFileSys unused1, ASPathName unused2, void *unused3, void *unused4, PDDocWillExportAnnotCallback exportFilter, ASInt32 *numNotesP)
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

The document from which notes are exported.

unused1: ASFileSys

Currently unused.

unused2: ASPathName

Currently unused.

unused3: void *

Currently unused.

unused4: void *

Currently unused.

exportFilter: PDDocWillExportAnnotCallback

A user-supplied routine that selects which notes to export.

numNotesP: ASInt32 *

If non- NULL , the number of notes exported.

Returns
CosDoc

The CosDoc of the document created to hold the exported notes. @notify PDDocWillExportAnnots @notify PDDocDidExportAnnots

PDDocExportSomeNotes

CosDoc PDDocExportSomeNotes(PDDoc doc, ASFileSys unused1, ASPathName unused2, void *unused3, void *unused4, PDDocWillExportAnnotCallback exportFilter, PDAnnotArray pdanArray, ASInt32 *numNotesP)
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. Make sure to explicitly include popups.

Parameters
doc: PDDoc

The document from which notes are exported.

unused1: ASFileSys

Currently unused.

unused2: ASPathName

Currently unused.

unused3: void *

Currently unused.

unused4: void *

Currently unused.

exportFilter: 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 *

(Filled by the method) If non- NULL , the number of notes exported.

Returns
CosDoc

The CosDoc of the document created to hold the exported notes. @notify PDDocWillExportAnnots @notify PDDocDidExportAnnots

PDDocFindPageNumForLabel

ASInt32 PDDocFindPageNumForLabel(PDDoc pdDoc, const char *labelStr, ASInt32 labelLen)
PDProcs.h:7387

Superseded by PDDocFindPageNumForLabelEx() in Acrobat 6.0. Finds the first page in the document with a specified label.

Parameters
pdDoc: PDDoc

The document to search for the page named in labelStr .

labelStr: const char *

The label of the page to find.

labelLen: ASInt32

The length of labelStr .

Returns
ASInt32

The page number of the first page with the specified label, or -1 if no such page exists.

PDDocFindPageNumForLabelEx

PDProcs.h:11099

Supersedes PDDocFindPageNumForLabel in Acrobat 6.0. Finds the first page in the document with a specified label.

Parameters
pdDoc: PDDoc

The document to search for the page named in labelStr .

labelText: ASConstText

The label of the page to find.

Returns
ASInt32

The page number of the first page with the specified label, or -1 if no such page exists.

PDDocFlattenOC

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

The document to be modified.

context: PDOCContext

The optional-content context in which content is checked for visibility.

Returns
ASBool

true if the operation is successful, false otherwise.

PDDocGetBookmarkRoot

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

IN/OUT Document whose root bookmark is obtained.

Returns
PDBookmark

The document's root bookmark.

PDDocGetCryptHandler

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

The document whose new security handler is obtained.

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

PDDocGetCryptHandlerClientData

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

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.

PDDocGetCryptRevision

PDProcs.h:12723

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

The document.

Returns
ASInt32

The Crypt Revision retreived from the Security handler or encrypt dict or 0 if not found or not encrypted

PDDocGetCryptVersion

PDProcs.h:12715

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

The document.

Returns
ASInt32

The Crypt Version retreived from the Security handler or encrypt dict or 0 if not found or not encrypted

PDDocGetID

ASInt32 PDDocGetID(PDDoc doc, ASInt32 nElemNum, ASUns8 *buffer, ASInt32 bufferSize)
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

The document whose file ID is obtained.

nElemNum: ASInt32

The element number to get from the document's file ID. It must be one of the following:

buffer: 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

The length of buffer in bytes.

Returns
ASInt32

The number of bytes in the ID element.

PDDocGetLabelForPageNum

ASInt32 PDDocGetLabelForPageNum(PDDoc pdDoc, ASInt32 pageNum, char *buffer, ASInt32 bufferLen)
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

The document containing the page for which a label is requested.

pageNum: 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

The length of the label ( NULL -terminated).

Returns
ASInt32

The length of the resulting label. If no such page number exists, the resulting string will be the ASCII representation of pageNum + 1 .

PDDocGetLabelForPageNumEx

void PDDocGetLabelForPageNumEx(PDDoc pdDoc, ASInt32 pageNum, ASText text)
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

The document containing the page for which a label is requested.

pageNum: ASInt32

The number of the page whose label is requested.

text: ASText

If a label exists for pageNum , it is returned in this object.

Returns
void

PDDocGetNameTree

PDProcs.h:7063

Retrieves a name tree, with the key name specified in theTree , from the Names dictionary of thePDDoc .

Parameters
thePDDoc: PDDoc

IN/OUT The document containing the name tree desired.

theTree: ASAtom

IN/OUT The name of the tree requested. This can be created by passing a string to the ASAtomFromString() method.

Returns
PDNameTree

The PDNameTree requested.

PDDocGetNewCryptHandler

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

The document whose new security handler is obtained.

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

PDDocGetNewSecurityData

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

The document whose new security data structure is obtained.

Returns
void *

The security data structure for the document's new security handler.

PDDocGetNewSecurityInfo

void PDDocGetNewSecurityInfo(PDDoc pdDoc, ASUns32 *secInfo)
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

IN/OUT The document whose new security information is obtained.

secInfo: 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

PDDocGetNthError

ASInt32 PDDocGetNthError(PDDoc doc, ASInt32 errNumber, ASInt32 *errorP, char *buffer, ASInt32 bufSize)
PDProcs.h:12005

Returns the error code and string for the nth non-fatal error encountered since the document was opened, or PDDocClearErrors was called.

Parameters
doc: PDDoc

The document in which the error has occurred.

errNumber: ASInt32

This is the serial number of the non-fatal error to be returned.

errorP: ASInt32 *

The error code. Use ASGetErrorString() to get the error message.

buffer: char *

If there is a string associated with this error, the string is copied to this buffer if it is non- NULL and is NULL -terminated.

bufSize: ASInt32

The maximum number of bytes that will be written to the buffer.

Returns
ASInt32

If there is a string associated with this error, the length of that string is returned. If there is no string, the return value is zero.

PDDocGetNumPages

PDProcs.h:1546

Gets the number of pages in a document.

Parameters
doc: PDDoc

IN/OUT The document for which the number of pages is obtained.

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

PDDocGetOCGs

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

The document whose OCGs are obtained.

Returns
PDOCG *

A NULL -terminated array of PDOCG objects. The client is responsible for freeing the array using ASfree().

PDDocGetOpenAction

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

IN/OUT The document whose open action is obtained.

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

PDDocGetPageLabel

PDPageLabel PDDocGetPageLabel(PDDoc pdDoc, ASInt32 pageNum, ASInt32 *firstPage, ASInt32 *lastPage)
PDProcs.h:7230

Returns the label that is in effect for the given page.

Parameters
pdDoc: PDDoc

The document for which a page label is desired.

pageNum: ASInt32

The page number of the page for which a label is requested.

firstPage: 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 *

(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

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 .

PDDocGetSecurityData

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

The document whose security data structure is obtained.

Returns
void *

A pointer to the document's current security data structure.

PDDocGetTrapped

PDProcs.h:11039

Gets the value of the Trapped key in the Info dictionary.

Parameters
pdDoc: PDDoc

The document whose Trapped key value is obtained.

Returns
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

PDDocGetVersion

void PDDocGetVersion(PDDoc doc, ASInt16 *majorP, ASInt16 *minorP)
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-1.2" . 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

IN/OUT The document whose version is obtained.

majorP: ASInt16 *

IN/OUT (Filled by the method) The major version number.

minorP: ASInt16 *

IN/OUT (Filled by the method) The minor version number.

Returns
void

PDDocGetVersionEx

void PDDocGetVersionEx(PDDoc doc, ASUns32 *majorP, ASUns32 *minorP, CosObj *adbeExtensionBaseP, ASUns32 *adbeExtensionLevelP)
PDProcs.h:12037

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
majorP: ASUns32 *
minorP: ASUns32 *
adbeExtensionBaseP: CosObj *
adbeExtensionLevelP: 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

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

The document whose word finder is obtained.

WXEVersion: ASInt16

The version of the word finder to get.

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

PDDocHasISOExtensions

PDProcs.h:12056

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

Parameters
doc: PDDoc
Returns

PDDocHasOC

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

The document whose OC status is obtained.

Returns
ASBool

true if the document has optional content, false otherwise.

PDDocImportCosDocNotes

ASInt32 PDDocImportCosDocNotes(PDDoc doc, CosDoc src, const char *noteTitle, ASInt32 noteTitleLen, PDColorValue color, void *progMon, void *monClientData, PDDocWillImportAnnotCallback importFilter)
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

The document that will receive the imported annotations.

src: CosDoc

The document from which the annotations will be imported.

noteTitle: const char *

Not currently used.

noteTitleLen: 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

A user-supplied procedure that will be called to provide a filtering process, allowing only desired annotations to import.

Returns
ASInt32

The number of notes imported. @notify PDDocDidImportAnnots @notify PDDocWillImportAnnots

PDDocImportNotes

ASInt32 PDDocImportNotes(PDDoc doc, PDDoc sourceDoc, void *progMon, void *monClientData, PDDocWillImportAnnotCallback importFilter)
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

The document to which the notes are exported.

sourceDoc: 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

A user-supplied filter which determines what type of notes will be exported.

Returns
ASInt32

The number of notes imported. @notify PDDocDidImportAnnots @notify PDDocWillImportAnnots

PDDocInsertPages

void PDDocInsertPages(PDDoc doc, ASInt32 mergeAfterThisPage, PDDoc doc2, ASInt32 startPage, ASInt32 numPages, ASUns16 insertFlags, ProgressMonitor progMon, void *progMonClientData, CancelProc cancelProc, void *cancelProcClientData)
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:

<ul> <li>The parameters indicating which pages to insert are ignored: all the pages of doc2 are inserted.</li> <li>

In addition to inserting the pages themselves, it also merges other document data from doc2 into doc:

<ul> <li>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.</li> <li>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.</li> </ul> </li> </ul>

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

The document into which pages are inserted. This document must have at least one page.

mergeAfterThisPage: 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

The document containing the pages that are inserted into doc .

startPage: 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

The number of pages in doc2 to insert into doc . Use PDAllPages to insert all pages from startPage of doc2 into doc .

insertFlags: 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

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

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

PDDocNewSecurityData

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

The document for which a security data structure is created.

Returns
void *

The newly created security data structure.

PDDocOpen

PDDoc PDDocOpen(ASPathName fileName, ASFileSys fileSys, PDAuthProc authProc, ASBool doRepair)
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

A path name to the file, specified in whatever format is correct for fileSys .

fileSys: 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

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

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

The newly-opened document.

PDDocOpenEx

PDDoc PDDocOpenEx(ASPathName fileName, ASFileSys fileSys, PDAuthProcEx authProcEx, void *authProcClientData, ASBool doRepair)
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

A path name to the file, specified in whatever format is correct for fileSys .

fileSys: ASFileSys

A pointer to an ASFileSysRec containing the file system in which the file resides.

authProcEx: 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

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

The newly-opened document.

PDDocOpenFromASFile

PDDoc PDDocOpenFromASFile(ASFile aFile, PDAuthProc authProc, ASBool doRepair)
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

The ASFile to open. The ASFile should be released after the PDDoc is closed.

authProc: 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

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

A valid PDDoc if successfully opened.

PDDocOpenFromASFileEx

PDDoc PDDocOpenFromASFileEx(ASFile aFile, PDAuthProcEx authProcEx, void *authProcClientData, ASBool doRepair)
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

The ASFile to open. The ASFile should be released after the PDDoc is closed.

authProcEx: 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

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

A valid PDDoc if successfully opened.

PDDocOpenWithParams

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

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

The PDDoc for the PDF document described by the structure passed in openParams .

PDDocPermRequest

PDPermReqStatus PDDocPermRequest(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void *authData)
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.

Parameters
pdDoc: PDDoc
reqObj: PDPermReqObj
reqOpr: PDPermReqOpr
authData: void *

PDDocPermRequestNoUB

PDPermReqStatus PDDocPermRequestNoUB(PDDoc pdDoc, PDPermReqObj reqObj, PDPermReqOpr reqOpr, void *authData)
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

The PDDoc whose permissions are being requested.

reqObj: PDPermReqObj

The target object of the permissions request.

reqOpr: PDPermReqOpr

The target operation of the permissions request.

authData: void *

A pointer to an authorization data structure.

Returns
PDPermReqStatus

The request status constant: 0 if the requested operation is allowed, a non-zero status code otherwise.

PDDocReadAhead

void PDDocReadAhead(PDDoc doc, ASUns32 flags, void *clientData)
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

IN/OUT The document being read.

flags: 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

void PDDocReadAheadEmbeddedFile(PDDoc doc, CosObj embeddedFileObj)
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

The document being read.

embeddedFileObj: CosObj

The Cos object of the embedded file stream (the stream referenced by entries in the EF dictionary).

Returns
void

PDDocReadAheadPages

void PDDocReadAheadPages(PDDoc doc, ASInt32 startPage, ASInt32 nPages)
PDProcs.h:7337

Reads ahead nPages starting at startPage (if the file is linearized).

Parameters
doc: PDDoc

IN/OUT The document for which pages are read ahead.

startPage: ASInt32

IN/OUT The page for which read ahead is initiated.

nPages: ASInt32

IN/OUT The number of pages to read ahead.

Returns
void

PDDocRelease

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

IN/OUT The document whose reference count is decremented.

Returns
void
See Also

PDDocReplacePages

void PDDocReplacePages(PDDoc doc, ASInt32 startPage, PDDoc doc2, ASInt32 startPageDoc2, ASInt32 numPages, ASBool mergeTextAnnots, ProgressMonitor progMon, void *progMonClientData, CancelProc cancelProc, void *cancelProcClientData)
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. Annotations in the replaced pages are not replaced and remain with the page. Use PDDocDeletePages() to remove annotations.

Parameters
doc: PDDoc

The document in which pages are replaced.

startPage: ASInt32

The first page number in doc to replace. The first page is 0 .

doc2: PDDoc

The document from which pages are copied into doc .

startPageDoc2: ASInt32

The page number of the first page in doc2 to copy. The first page is 0 .

numPages: ASInt32

The number of pages to replace.

mergeTextAnnots: 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

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

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

PDDocRequestPages

void PDDocRequestPages(PDDoc doc, ASInt32 startPage, ASInt32 nPages, PDDocRequestPagesProc requestProc, void *clientData)
PDProcs.h:10860

Requests nPages starting at startPage , and performs a specified procedure on them.

Parameters
doc: PDDoc

The document for which pages are read ahead.

startPage: ASInt32

The first page requested.

nPages: ASInt32

The number of pages requested.

requestProc: 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

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

IN The document on which to reset set the ink usage.

Returns
void

PDDocSave

void PDDocSave(PDDoc doc, PDSaveFlags saveFlags, ASPathName newPath, ASFileSys fileSys, ProgressMonitor progMon, void *progMonClientData)
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 Not replaceable in Adobe Reader.

Parameters
doc: PDDoc
saveFlags: PDSaveFlags
newPath: ASPathName
fileSys: ASFileSys
progMonClientData: void *
Returns
void

PDDocSaveWithParams

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(). 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. Not replaceable in Adobe Reader.

Parameters
doc: PDDoc

The document to save.

inParams: PDDocSaveParams

A PDDocSaveParams structure specifying how the document should be saved.

Returns
void
See Also

PDDocSetFlags

void PDDocSetFlags(PDDoc doc, ASInt32 flags)
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

IN/OUT The document whose flags are set.

flags: ASInt32

IN/OUT A bit field composed of an OR of the PDDocFlags values.

Returns
void

PDDocSetMinorVersion

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

The document.

minor: ASInt16

The minimum required minor version

Returns
void

PDDocSetNewCryptFilterData

void PDDocSetNewCryptFilterData(PDDoc doc, ASAtom filterName, char *cryptData, ASInt32 cryptDataLen)
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

The document whose new encrypted data is set.

filterName: 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

The length of cryptData in bytes.

Returns
void

PDDocSetNewCryptFilterMethod

void PDDocSetNewCryptFilterMethod(PDDoc doc, ASAtom filterName, ASAtom method)
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

The document whose new security filter method is set.

filterName: ASAtom

The ASAtom corresponding to the name of the security filter to use.

method: ASAtom

One of five supported security methods:

None (default)

V2 (RC4)

V3 (RC4)

AESV1

AESV2 (128 bit)

AESV3 (256 bit)

Returns
void

PDDocSetNewCryptHandler

void PDDocSetNewCryptHandler(PDDoc pdDoc, ASAtom newCryptHandler)
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

The document whose new security handler is set.

newCryptHandler: 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

PDDocSetNewCryptHandlerEx

void PDDocSetNewCryptHandlerEx(PDDoc pdDoc, ASAtom newCryptHandler, void *currentAuthData)
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

The document whose new security handler is set.

newCryptHandler: 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

PDDocSetNewDefaultFilters

void PDDocSetNewDefaultFilters(PDDoc doc, ASAtom defaultStmFilterName, ASAtom defaultStrFilterName)
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

The document whose new security filter is set.

defaultStmFilterName: 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

The ASAtom corresponding to the name of the default security filter to use for strings. The filter must exist and be registered.

Returns
void

PDDocSetNewSecurityData

void PDDocSetNewSecurityData(PDDoc pdDoc, void *secData)
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

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

PDDocSetPageLabel

void PDDocSetPageLabel(PDDoc pdDoc, ASInt32 pageNum, PDPageLabel pgLabel)
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

The document containing the page to label.

pageNum: ASInt32

The number of the page to label.

pgLabel: PDPageLabel

The label for the page specified by pageNum .

Returns
void

PDDocSetTrapped

void PDDocSetTrapped(PDDoc pdDoc, ASAtom newValue)
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

The document whose Trapped key value to set.

newValue: 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

PDEnumDocs

void PDEnumDocs(PDDocEnumProc proc, void *clientData)
PDProcs.h:1171

Enumerates the PDDoc objects that are currently open, calling a user-supplied procedure for each open document.

Parameters
proc: 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

Typedefs(22)

PDAuthProc

typedef ASBool(* PDAuthProc) (PDDoc pdDoc))(PDDoc pdDoc)
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().

PDAuthProcEx

typedef ASBool(* PDAuthProcEx) (PDDoc pdDoc, void *clientData))(PDDoc pdDoc, void *clientData)
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.

PDDocPreSaveProc

typedef void(* PDDocPreSaveProc) (PDDoc pdDoc, PDDocPreSaveInfo preSaveInfo, void *clientData))(PDDoc pdDoc, PDDocPreSaveInfo preSaveInfo, void *clientData)
PDExpT.h:1661

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.

Structures(4)

PDDoc

typedef struct _t_PDDoc* PDDoc
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 .

PDDocOpenParams

typedef struct _t_PDDocOpenParams* PDDocOpenParams
PDExpT.h:1923

A structure used by PDDocOpenWithParams() to specify file open information. The parameters are very similar to those in PDDocOpenEx() and PDDocOpenFromASFileEx().

Enums(5)

PDDocOCChangeTypes

PDExpT.h:5759

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
—

Optional Content Groups (OCGs) created.

kPDOCGProperties
—

OCG properties changed.

kPDOCGReplace
—

An OCG was replaced by another.

kPDOCGDestroy
—

An OCG was destroyed.

kPDOCMDAttach
—

Content was made optional.

kPDOCMDRemove
—

Content was made optional.

kPDOCConfigCreate
—

An OC config was created.

kPDOCConfigChange
—

An OC config was changed.

kPDOCConfigDestroy
—

An OC config was destroyed.

kPDDocRemoveOC
—

OC was removed from document.

kPDOC_LastDocChangeType
—

PDDocRequestReasons

PDExpT.h:6483

This tells the callback why it is being called.

Values
kPDDocRequestUnderway
—

The request is still being processed.

kPDDocRequestComplete
—

The requested data has arrived.

kPDDocRequestCancelled
—

The request is cancelled because the file is being closed.

kPDDocRequestError
—

An error occurred.

PDDocSaveFlags

PDExpT.h:1449

Flags for the PDDocSave saveFlags parameter. All undefined flags should be set to zero.

Values
PDSaveIncremental
—

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
—

Save the entire document. Plug-ins that set PDSaveFull are also encouraged to set PDSaveCollectGarbage .

PDSaveCopy
—

Save a copy of the document (the PDDoc continues to use the old file). This flag is ignored if PDSaveFull is off.

PDSaveLinearized
—

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
—

(Obsolete. In effect, it is always off). Write a PostScript header as part of the saved file.

PDSaveBinaryOK
—

(Obsolete. In effect, it is always on). It is okay to store binary data in the PDF file.

PDSaveCollectGarbage
—

Remove unreferenced objects, often reducing file size. Plug-ins are encouraged to use this flag. This flag is ignored if PDSaveFull is off.

PDSaveForceIncremental
—

Perform an incremental save even if the save is to a different file or the document's version number has changed.

PDSaveKeepModDate
—

Do not update ModDate in InfoDict.

PDSaveLeaveOpen
—

Leave the file open after the save (do not Close the file)

PDSaveLinearizedNoOptimizeFonts
—

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.

PDDocSaveFlags2

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
—

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
—

Compress objects, without restrictions about which objects to compress. This flag is ignored if PDSaveFull is off.

PDSaveCompressStructureOnly
—

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
—

Remove ASCII85 filters from all streams. This flag is ignored if PDSaveFull is off.

PDSaveAddFlate
—

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.

PDSaveReplaceLZW
—

Replace all LZW filters with FlateEncode filters. This flag is ignored if PDSaveFull is off.

PDSaveOptimizeXObjects
—

Merge identical forms and images, as determined by an MD5 hash of their contents (it causes OptimizeXObjects() to be called).

PDSaveOptimizeContentStreams
—

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
—

Merge identical font descriptors and encodings. Does not merge the top-level font dictionary (it causes OptimizeFonts() to be called).

PDSaveOptimizeMarkedJBIG2Dictionaries
—

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
—

(Obsolete. In effect, it is always off).

PDSaveAutoSave
—

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
—

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
—

Do not save the new file output with the file attributes of the original

PDSaveOriginalMetaData
—

Save the new file Metadata stream with the Metadata stream of the original

PDSaveOptimizeObjects
—

Merge identical objects, as determined by an MD5 hash of their contents.

PDOperations

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
—

Page insertion.

pdOpDeletePages
—

Page deletion.

pdOpReplacePages
—

Page replacement.

pdOpMovePages
—

Page rearrangment.

pdOpRotatePages
—

Page rotation.

pdOpCropPages
—

Page cropping.

pdOpAddResources
—

Only PDDocDidChangePages() exists, not PDDocWillChangePages().

pdOpRemoveResources
—

Only PDDocDidChangePages() exists, not PDDocWillChangePages().

pdOpAddContents
—

Only PDDocDidChangePages() exists, not PDDocWillChangePages().

pdOpRemoveContents
—

Only PDDocDidChangePages() exists, not PDDocWillChangePages().

pdOpSetMediaBox
—

Page media box modification.

pdOpSetBleedBox
—

Page bleed box modification.

pdOpSetTrimBox
—

Page trim box modification.

pdOpSetArtBox
—

Page art box modification.

pdOpSetTabOrder
—

Page tab order modification.

Definitions(59)

PDPermReqDenied

PDExpT.h:4108
Value:(PDPermReqStatus)(-1)

-1 The request was denied.

PDPermReqGranted

PDExpT.h:4110
Value:(PDPermReqStatus)(0)

0 The request was granted.

PDPermReqOperationNA

PDExpT.h:4116
Value:(PDPermReqStatus)(3) /* Not applicable operation for specified object */

3 The operation is not applicable for the specified object.

PDPermReqPending

PDExpT.h:4120
Value:(PDPermReqStatus)(4)

The handler does not have enough information to determine an answer at this point. Try again later.

STDSEC_METHOD_AES_V3

PDExpT.h:4345
Value:7 /* CF_METHOD_AES_V3 (AES256) */

New encryption method for Acrobat 9.0

kPDDocReadAheadAcroForms

PDExpT.h:4066
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

PDExpT.h:4082
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.

kPDDocReadAheadStructure

PDExpT.h:4089
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

PDExpT.h:4074
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

PDExpT.h:4278
Value:pdPermCopy

The document text and graphics can be copied to the clipboard.

pdInfoCanPrint

PDExpT.h:4267
Value:pdPermPrint

The document can be printed.

pdInfoHasOwnerPW

PDExpT.h:4262
Value:pdPermSecure

The document has an owner password.

pdInfoHasUserPW

PDExpT.h:4257
Value:pdPermOpen

The document has a user password.

pdPermCopy

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

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

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.

pdPermOpen

PDExpT.h:1304
Value:0x01

The user can open and decrypt the document.

pdPermOwner

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

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

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.... This cannot be set by clients.

pdPermSecure

PDExpT.h:1309
Value:0x02

The user can change the document's security settings.

pdPermSettable

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

PDExpT.h:1426
Value:(pdPermAll - pdPermOpen - pdPermSecure)

All permissions.

pdPrivPermAccessible

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

PDExpT.h:1378
Value:0x400

Overrides various pdPermEdit bits and allows the following operations: page insert/delete/rotate and create bookmark and thumbnail.

pdPrivPermFillandSign

PDExpT.h:1365
Value:0x100

Overrides other PDPerm bits. It allows the user to fill in or sign existing form or signature fields.

pdPrivPermFormSpawnTempl

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

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

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

1 items

Structures(1)

PDEObject

1 items

Enums(1)

PDFLPrint

1 items

Structures(1)

PDFileAttachment

24 items

Functions(23)

PDFileAttachmentGetCreationDate

PDProcs.h:12187

Gets the creation date of the file attachment.

Parameters
attachment: PDFileAttachment

The file attachment object.

date: ASTimeRec *

A pointer to a date that will receive the creation date.

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

PDFileAttachmentNewFromFile

PDFileAttachment PDFileAttachmentNewFromFile(CosDoc parentDoc, ASFile sourceFile, const ASAtom *filterNames, const ASArraySize numFilters, CosObj filterParams, ASProgressMonitor monitor, ASConstText monitorText, void *monitorData)
PDProcs.h:12113

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

The CosDoc in which the file attachment dictionary will be created.

sourceFile: ASFile

The ASFile from which to create the file attachment.

filterNames: const 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

The number of elements in filterNames .

filterParams: 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

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

The new file attachment.

PDFileAttachmentSaveToFile

PDProcs.h:12147

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

The file attachment.

destFile: ASFile

The file that will be written with the file attachment data.

Returns
void

PDFileAttachmentSetFieldPrefix

PDProcs.h:12295

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

The file attachment.

fieldName: ASAtom

The field identifier.

text: 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

PDFileAttachmentUpdateFromFile

void PDFileAttachmentUpdateFromFile(PDFileAttachment attachment, ASFile sourceFile, ASProgressMonitor monitor, ASConstText monitorText, void *monitorData)
PDProcs.h:12133

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

The file attachment.

sourceFile: 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

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)

PDFileSpec

17 items

Functions(14)

PDFileSpecAcquireASPathEx

ASPathName PDFileSpecAcquireASPathEx(PDFileSpec fileSpec, ASFileSys relPathFileSys, ASPathName relativeToThisPath, ASFileSys *retFileSys, ASBool pathMustExist)
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

IN/OUT The file specification for which an ASPathName is acquired.

relPathFileSys: ASFileSys

The file system that owns relativeToThisPath .

relativeToThisPath: 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 *

IN/OUT The file system that owns the returned ASPathName.

pathMustExist: ASBool

IN/OUT If it is true and the result ASPathName does not exist, then the return value is NULL .

Returns
ASPathName

The ASPathName corresponding to fileSpec .

PDFileSpecGetDIPath

ASInt32 PDFileSpecGetDIPath(PDFileSpec fileSpec, char *buffer, ASInt32 bufLen)
PDProcs.h:5336

Gets the device-independent path name from a file specification.

Parameters
fileSpec: 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

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

The number of characters (excluding the NULL ) copied into buffer .

PDFileSpecGetDIPathEx

void PDFileSpecGetDIPathEx(PDFileSpec fileSpec, ASText diPath)
PDProcs.h:11425

Gets the device-independent path name from a file specification.

Parameters
fileSpec: PDFileSpec

IN The file specification whose device-independent path name is obtained.

diPath: ASText

IN/OUT An existing ASText object whose content is set to the path name obtained from from fileSpec .

Returns
void

PDFileSpecGetFileSysName

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

A PDFileSpec.

Returns
ASAtom

An ASAtom representing the file system of fileSpec .

PDFileSpecIsValid

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

The file specification whose validity is tested.

Returns
ASBool

true if fileSpec is valid, false otherwise.

PDFileSpecNewFromASPath

PDFileSpec PDFileSpecNewFromASPath(PDDoc pdDoc, ASFileSys fileSys, ASPathName path, ASPathName relativeToThisPath)
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

The document in which the new file specification will be used.

fileSys: ASFileSys

A pointer to an ASFileSysRec specifying the file system responsible for the newly created file specification.

path: ASPathName

The path to convert into a file specification.

relativeToThisPath: 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

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

PDFileSpecNewFromASPathEx

PDFileSpec PDFileSpecNewFromASPathEx(PDDoc pdDoc, ASFileSys fileSys, ASPathName path, ASFileSys relPathFileSys, ASPathName relativeToThisPath)
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

The document in which the new file specification will be used.

fileSys: ASFileSys

A pointer to an ASFileSysRec specifying the file system responsible for the newly created file specification.

path: ASPathName

The path to convert into a file specification.

relPathFileSys: ASFileSys

The file system that owns relativeToThisPath .

relativeToThisPath: 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

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

PDRegisterFileSpecHandler

void PDRegisterFileSpecHandler(ASFileSys contextFileSys, PDFileSpecHandler fileSpecHandler, void *fileSpecHandlerObj)
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

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

PDRegisterFileSpecHandlerByName

void PDRegisterFileSpecHandlerByName(ASAtom specSysName, ASFileSys contextFileSys, PDFileSpecHandler fileSpecHandler, void *fileSpecHandlerObj)
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

The name (as an ASAtom) of a file system with which this file specification works.

contextFileSys: 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

Typedefs(3)

PDFileSpec

typedef OPAQUE_64_BITS PDFileSpec
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.

PDFolder

28 items

Functions(27)

PDFolderGetModDate

ASBool PDFolderGetModDate(PDFolder folder, ASTimeRec *date)
PDProcs.h:12521

Gets the modification date of the folder.

Parameters
folder: PDFolder

The folder.

date: ASTimeRec *

A pointer to an that will be filled with the folder modification date.

Returns
ASBool

true if the folder has a modification date, false otherwise.

PDFolderSetModDate

void PDFolderSetModDate(PDFolder folder, const ASTimeRec *date)
PDProcs.h:12527

Sets the modification date of the folder.

Parameters
folder: PDFolder

The folder.

date: const ASTimeRec *

A pointer to an that will be used to set the modification date.

Returns
void

Typedefs(1)

PDFolder

typedef OPAQUE_64_BITS PDFolder
PDExpT.h:7075

An opaque object representing a collection folder dictionary. Folders are used to provide grouping for files in a portable collection.

PDFont

61 items

Functions(36)

PDCharProcEnumWithParams

void PDCharProcEnumWithParams(PDCharProc obj, PDGraphicEnumParams params)
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

The character procedure whose graphic descriptions are enumerated.

params: PDGraphicEnumParams

The parameters, including the optional-content context to use for content visibility.

Returns
void

PDFontAcquireEncodingArray

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

The font whose encoding array is obtained.

Returns
ASUns8 **

The font's encoding array. It returns NULL if there is no encoding array associated with the font.

PDFontAcquireEncodingArrayFull

PDProcs.h:12868

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

The font whose encoding array is obtained.

Returns
ASUns8 **

The font's encoding array. It returns NULL if there is no encoding array associated with the font.

PDFontAcquireXlateTable

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

IN/OUT The font whose XlateTable is obtained.

Returns
ASInt16 *

A pointer to the font's XlateTable, if any. Otherwise it returns NULL .

PDFontEnumCharProcs

void PDFontEnumCharProcs(PDFont font, PDCharProcEnumProc proc, void *clientData)
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

IN/OUT The Type 3 font's character drawing procedures are being enumerated.

proc: 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

PDFontGetASTextName

void PDFontGetASTextName(PDFont font, ASBool removePrefix, ASText nameToFill)
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

The font whose name is obtained.

removePrefix: ASBool

Whether to remove the subset prefix, if present. For example, when true , the name "ABCDEF+Myriad" is returned as "Myriad" .

nameToFill: ASText

(Filled by the method) The ASText object for the font's name.

Returns
void

PDFontGetBBox

void PDFontGetBBox(PDFont font, ASFixedRect *bboxP)
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

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

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 Technical Note #5014, Adobe CMap and CIDFont Files Specification https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf

Parameters
font: PDFont

IN/OUT The font whose Registry and Ordering information is obtained.

Returns
ASAtom

The ASAtom representing the CIDFont's Registry and Ordering information (for example, "Adobe-Japan1" ).

PDFontGetCIDSystemSupplement

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 Technical Note #5014, Adobe CMap and CIDFont Files Specification https://www.adobe.com/content/dam/acom/en/devnet/font/pdfs/5014.CIDFont_Spec.pdf

Parameters
font: PDFont

IN/OUT The font whose SystemSupplement field is obtained.

Returns
ASInt32

The SystemSupplement field from the CIDFont.

PDFontGetCharSet

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

IN/OUT The font whose character set is obtained.

Returns
PDCharSet

The font's character set. For non-Roman character set viewers, it returns PDUnknownCharSet.

PDFontGetCosObj

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

IN/OUT The font whose Cos object is obtained.

Returns
CosObj

The dictionary Cos object for the font. The dictionary's contents may be enumerated with CosObjEnum().

See Also

PDFontGetDescendant

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

IN/OUT The font whose descendant is obtained.

Returns
PDFont

The font's descendant font.

PDFontGetEncodingIndex

PDProcs.h:2769

Gets a font's encoding index. For non-Roman character set viewers, call PDFontGetEncodingName() instead.

Parameters
font: PDFont

IN/OUT The font whose encoding index is obtained.

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

PDFontGetEncodingName

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

Parameters
font: PDFont

PDFontGetFontMatrix

void PDFontGetFontMatrix(PDFont fontP, ASFixedMatrix *matrixP)
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

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

PDFontGetMetrics

void PDFontGetMetrics(PDFont font, PDFontMetricsP metricsP, ASSize_t sizeMetrics)
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

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

IN/OUT It must be sizeof(PDFontMetrics) .

Returns
void

PDFontGetName

ASInt32 PDFontGetName(PDFont font, char *buffer, ASInt32 bufSize)
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

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

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

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.

PDFontGetWidths

void PDFontGetWidths(PDFont font, ASInt16 *widths)
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

IN/OUT The font whose glyph advance widths are obtained.

widths: 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

PDFontIsEmbedded

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

The font to test.

Returns
ASBool

true if the font is embedded in the file, false otherwise.

See Also

PDFontSetMetrics

void PDFontSetMetrics(PDFont font, PDFontMetricsP metricsP, ASSize_t sizeMetrics)
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

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

IN/OUT It must be sizeof(PDFontMetrics) .

Returns
void

PDFontXlateString

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

The font (and hence, the encoding) that inP uses.

inP: ASUns8 *

The string to translate.

outP: ASUns8 *

(Filled by the method) The translated string. outP may point to the same buffer as inP , to allow in-place translation.

len: ASInt32

The length of inP and outP .

Returns
ASBool

true if an XlateTable exists in the font, false otherwise. If no XlateTable exists in the font, outP is not written.

PDFontXlateToHost

ASInt32 PDFontXlateToHost(PDFont fontP, ASUns8 *inP, ASInt32 inLen, ASUns8 *outP, ASInt32 outLen)
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.

Parameters
fontP: PDFont
inLen: ASInt32
outP: ASUns8 *
outLen: ASInt32
Returns

PDFontXlateToUCS

ASInt32 PDFontXlateToUCS(PDFont fontP, ASUns8 *inP, ASInt32 inLen, ASUns8 *outP, ASInt32 outLen)
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.

Parameters
fontP: PDFont
inLen: ASInt32
outP: ASUns8 *
outLen: ASInt32
Returns

PDFontXlateWidths

void PDFontXlateWidths(PDFont font, ASInt16 *inP, ASInt16 *outP)
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

IN/OUT The font whose glyph widths are translated.

inP: ASInt16 *

IN/OUT The array of glyph advance widths to rearrange.

outP: ASInt16 *

IN/OUT (Filled by the method) The rearranged array of glyph advance widths.

Returns
void
See Also

PDGetHostEncoding

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.

Parameters
: void

PDGetPDFDocEncoding

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
: void
Returns
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.

PDHostMBLen

ASInt32 PDHostMBLen(const char *cp)
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

The number of bytes in the multi-byte character.

PDXlateToASText

void PDXlateToASText(const char *inHostString, ASInt32 inHostStringSize, ASText outPDFString)
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

The number of bytes in the string to translate.

outPDFString: 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 .

PDXlateToHost

void PDXlateToHost(char *in, char *out, ASInt32 numBytes)
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

The number of bytes in the string to translate.

Returns
void

PDXlateToHostASText

ASInt32 PDXlateToHostASText(const ASText inPdfString, char *outHostString, ASInt32 outHostStringSize)
PDProcs.h:11721

Returns a host encoded string corresponding to an ASText object.

Parameters
inPdfString: const ASText

The text object.

outHostString: char *

(Filled by the method) A pointer to the translated string.

outHostStringSize: ASInt32

The length of the outHostString buffer, in bytes.

Returns
ASInt32

The number of bytes in the translated string outHostString .

PDXlateToHostEx

ASInt32 PDXlateToHostEx(const char *inPdfStr, ASInt32 inPdfStrSize, char *outHostStr, ASInt32 outHostStrSize)
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.

Parameters
inPdfStr: const char *
inPdfStrSize: ASInt32
outHostStr: char *
outHostStrSize: ASInt32
Returns

PDXlateToPDFDocEnc

void PDXlateToPDFDocEnc(char *in, char *out, ASInt32 numBytes)
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.

Parameters
in: char *
out: char *
numBytes: ASInt32
Returns
void

PDXlateToPDFDocEncEx

ASInt32 PDXlateToPDFDocEncEx(ASBool bUseUnicode, const char *inHostStr, ASInt32 inHostStrSize, char *outPDFStr, ASInt32 outPDFStrSize)
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.

Parameters
bUseUnicode: ASBool
inHostStr: const char *
inHostStrSize: ASInt32
outPDFStr: char *
outPDFStrSize: ASInt32
Returns

Typedefs(6)

Structures(2)

PDFont

typedef struct _t_PDFont* PDFont
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.

Definitions(17)

PD_PI

PDExpT.h:2246
Value:0x00000004

PDFontEncoding

3 items

Functions(1)

Typedefs(1)

Enums(1)

PDFontEncodings

PDExpT.h:2259

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
—

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
—

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
—

MacExpertEncoding, see Annex D, "Character Sets and Encodings," page 651.

PDWinAnsiEncoding
—

WinAnsiEncoding, see Annex D, "Character Sets and Encodings," page 651.

PDStdEncoding
—

StandardEncoding, see Annex D, "Character Sets and Encodings," page 651.

PDFDocEncoding
—

PDFDocEncoding, see Annex D, "Character Sets and Encodings," page 651. This will never be returned for a font; it is used internally.

PDLastKnownEncoding
—

PDGraphic

14 items

Functions(3)

PDGraphicGetBBox

void PDGraphicGetBBox(PDGraphic obj, ASFixedRect *bboxP)
PDProcs.h:3633

Gets a bounding box for the specified graphic object.

Parameters
obj: 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

PDGraphicGetCurrentMatrix

void PDGraphicGetCurrentMatrix(PDGraphic obj, ASFixedMatrix *matrix)
PDProcs.h:3645

Gets the current transformation matrix in effect for a graphic object; the matrix is relative to user space.

Parameters
obj: 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

void PDGraphicGetState(PDGraphic obj, PDGraphicStateP stateP, ASInt32 stateLen)
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

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

IN/OUT It must be sizeof(PDGraphicsState) .

Returns
void

Typedefs(9)

Structures(2)

PDInlineImage

4 items

Functions(3)

PDInlineImageColorSpaceGetIndexLookup

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

Parameters
image: PDInlineImage

IN/OUT The inline image whose lookup table is obtained.

data: ASUns8 *

IN/OUT (Filled by the method) The lookup table for image.

dataLen: ASInt32

IN/OUT The length of data in bytes.

Returns
void

PDInlineImageGetAttrs

void PDInlineImageGetAttrs(PDInlineImage obj, PDImageAttrsP attrsP, ASInt32 attrsLen)
PDProcs.h:3751

Gets an inline image's attributes. 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. 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

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

IN/OUT It must be sizeof(PDImageAttrs) .

Returns
void

PDInlineImageGetData

PDProcs.h:3766

Gets the image data for an inline image.

Parameters
obj: PDInlineImage

IN/OUT The inline image whose data is obtained.

data: ASUns8 *

IN/OUT (Filled by the method) A buffer into which the image data will be placed.

dataLen: 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

Structures(1)

PDLinkAnnot

7 items

Functions(5)

PDLinkAnnotGetBorder

void PDLinkAnnotGetBorder(PDLinkAnnot aLinkAnnot, PDLinkAnnotBorder *border)
PDProcs.h:663

Gets the border of a link annotation.

Parameters
aLinkAnnot: 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

PDLinkAnnotSetBorder

void PDLinkAnnotSetBorder(PDLinkAnnot aLinkAnnot, const PDLinkAnnotBorder *border)
PDProcs.h:679

Sets a link annotation's border.

Parameters
aLinkAnnot: 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

Typedefs(1)

PDLinkAnnot

typedef OPAQUE_64_BITS PDLinkAnnot
PDExpT.h:366

A link annotation on a page in a PDF file. You can use any PDAnnot method on a PDLinkAnnot.

Applications can:

<ul> <li>Get and set the bounding rectangle and color using PDAnnot methods.</li> <li>Get and set the action that occurs when the link is activated, and the link's border, using PDLinkAnnot methods.</li> <li>Create new link annotations and delete existing ones using the PDPage methods.</li> </ul>

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.

Definitions(1)

PDNameTree

13 items

Functions(12)

PDNameTreeEnum

void PDNameTreeEnum(PDNameTree theTree, CosObjEnumProc proc, void *clientData)
PDProcs.h:7046

Enumerates the entries in the tree.

Parameters
theTree: PDNameTree

IN/OUT A name tree.

proc: 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

PDNameTreeGet

ASBool PDNameTreeGet(PDNameTree theTree, const char *name, ASInt32 nameLen, CosObj *value)
PDProcs.h:7011

Retrieves an object from the name tree.

Parameters
theTree: 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

The length of name .

value: CosObj *

(Filled by the method) The Cos object corresponding to name within theTree .

Returns
ASBool

true if the object was retrieved, false if no object with this name exists.

PDNameTreeLookup

CosObj PDNameTreeLookup(CosObj nameTree, char *string, ASInt32 stringLen)
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

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

The length of name in bytes.

Returns
CosObj

The Cos object associated with the specified name, which is the array element following the name.

PDNameTreeNew

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

The document for which a new name tree is desired.

Returns
PDNameTree

The newly created name tree or a NULL CosObj if Acrobat is unable to create a PDNameTree for the document specified by pdDoc .

PDNameTreeNotifyNameAdded

PDProcs.h:7956

Sends a PDNameTreeNameAdded() notification.

Parameters
theTree: PDNameTree

The PDNameTree to which a name had been added.

key: CosObj

The name of the object within theTree that was added. This is a Cos string, not a C string.

value: CosObj

(Filled by the method) The Cos object corresponding to the object name that was added to theTree . @notify PDNameTreeNameAdded

Returns
void

PDNameTreePut

void PDNameTreePut(PDNameTree theTree, CosObj key, CosObj value)
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

IN/OUT The name tree for which a new entry is added.

key: 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

IN/OUT The Cos object to be associated with key .

Returns
void
See Also

PDNameTreeRemove

void PDNameTreeRemove(PDNameTree theTree, const char *key, ASInt32 keyLen)
PDProcs.h:7027

Removes the specified object from the tree. It does nothing if no object with that name exists.

Parameters
theTree: 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

IN/OUT The length of key in bytes. @notify PDNameTreeNameRemoved

Returns
void

Typedefs(1)

PDNameTree

typedef OPAQUE_64_BITS PDNameTree
PDExpT.h:5503

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

PDNumTree

10 items

Functions(9)

PDNumTreeEnum

void PDNumTreeEnum(PDNumTree theTree, CosObjEnumProc proc, void *clientData)
PDProcs.h:7778

Enumerates the entries in the tree.

Parameters
theTree: PDNumTree

IN/OUT A number tree.

proc: 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

Typedefs(1)

PDNumTree

typedef OPAQUE_64_BITS PDNumTree
PDExpT.h:5518

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.

PDOCConfig

23 items

Functions(19)

PDOCConfigDestroy

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

The configuration to destroy.

Returns
void

PDOCConfigGetAllRadioButtonGroups

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

The configuration.

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

PDOCConfigGetCreator

PDProcs.h:10229

Gets the creator property for an optional-content configuration.

Parameters
pdOCCfg: PDOCConfig

The configuration for which a creator is desired.

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

PDOCConfigGetInitState

void PDOCConfigGetInitState(PDOCConfig pdOCCfg, PDOCConfigBaseState *bs, PDOCG **onOCGs, PDOCG **offOCGs)
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

The configuration for which the initial state is desired.

bs: PDOCConfigBaseState *

(Filled by the method) An existing PDOCConfigBaseState structure in which to store the initialization information.

onOCGs: 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 **

(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

PDOCConfigGetIntent

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

The configuration for which an intent list is desired.

Returns
ASAtom *

The ASAtomNull-terminated intent array. The client is responsible for freeing it using ASfree().

PDOCConfigGetLockedArray

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

The optional-content configuration.

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

PDOCConfigGetOCGOrder

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

The configuration for which an OCG display order is desired.

orderObj: 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

true if the order belongs directly to this configuration, false if it is inherited from the document's default configuration.

PDOCConfigGetRadioButtonGroupForOCG

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

The optional-content configuration.

ocg: PDOCG

The optional-content group for which to obtain the radio-button group.

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

PDOCConfigMakeRadioButtonGroup

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

The optional-content configuration.

ocgs: PDOCG *

A NULL -terminated array of optional-content groups to be included in the group.

Returns
void

PDOCConfigSetInitState

void PDOCConfigSetInitState(PDOCConfig pdOCCfg, PDOCConfigBaseState bs, PDOCG *onOCGs, PDOCG *offOCGs)
PDProcs.h:10152

Sets the initial ON-OFF states of optional-content groups to be saved in an optional-content configuration.

Parameters
pdOCCfg: PDOCConfig

The configuration for which to set the initial state.

bs: PDOCConfigBaseState

An existing PDOCConfigBaseState structure containing the initialization information.

onOCGs: 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 *

A NULL -terminated array of OCGs that have an initial state of OFF when that is not the base state, or NULL .

Returns
void

PDOCConfigSetIntent

void PDOCConfigSetIntent(PDOCConfig pdOCCfg, ASAtom *intent)
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

The configuration for which to set an intent.

intent: 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

PDOCConfigSetLockedArray

void PDOCConfigSetLockedArray(PDOCConfig pdOCCfg, PDOCG *lockedOCGs)
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

The optional-content configuration.

lockedOCGs: 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

PDOCConfigSetOCGOrder

void PDOCConfigSetOCGOrder(PDOCConfig pdOCCfg, CosObj orderArray)
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

The configuration for which a OCG is desired.

orderArray: 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

Typedefs(2)

Structures(1)

PDOCConfig

typedef struct _t_PDOCConfig* PDOCConfig
PDExpT.h:5645

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

PDExpT.h:5685

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
—
kPDOCBaseState_ON
—
kPDOCBaseState_Unchanged
—

PDOCContext

31 items

Functions(24)

PDOCContextApplyAutoStateChanges

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

The context for which the visibility state is changed.

cfg: PDOCConfig

The configuration whose usage directives are used.

event: ASAtom

The event for which an ON-OFF state is automatically changed. Events are View , Export , and Print .

Returns
ASBool

true if successful, false otherwise.

PDOCContextClearAllUserOverrides

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

The context for which the user override marks are removed.

Returns
void

PDOCContextContentIsVisible

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

The context for which the visibility state is desired.

Returns
ASBool

true if the content is visible, false otherwise.

PDOCContextFindAutoStateChanges

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

The context for which the visibility state should be changed.

cfg: PDOCConfig

The configuration whose usage directives are used.

event: ASAtom

The event for which an ON-OFF state is automatically changed. Events are View , Export , and Print .

Returns
PDOCG *

A NULL -terminated array of optional-content group objects. The client is responsible for freeing it using ASfree().

PDOCContextGetIntent

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

The context for which an intent is desired.

Returns
ASAtom *

An array containing intent entries (ASAtom objects) terminated by ASAtomNull. The client is responsible for freeing it using ASfree().

PDOCContextGetNonOCDrawing

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
Returns

PDOCContextGetOCDrawEnumType

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

Parameters
ocContext: PDOCContext

PDOCContextGetOCGStates

void PDOCContextGetOCGStates(PDOCContext ocContext, PDOCG *pdocgs, ASBool *states)
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

The context for which the OCG states are desired.

pdocgs: PDOCG *

A NULL -terminated array of optional-content groups whose states are obtained.

states: 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

PDOCContextInit

void PDOCContextInit(PDOCContext ocContext, PDOCContextInitPolicy policy, PDOCContext otherCtx, PDOCConfig pdOCCfg)
PDProcs.h:9524

Initializes the ON-OFF states of all optional-content groups (OCGs) within an existing context.

Parameters
ocContext: PDOCContext

The context to initialize.

policy: PDOCContextInitPolicy

The initialization policy for the context. This value determines whether optional-content groups are initially ON or OFF .

otherCtx: PDOCContext

Another context from which to take initial OCG states when the policy is kOCCInit_FromOtherContext. It is ignored for other policies.

pdOCCfg: PDOCConfig

A configuration from which to take initial OCG states when the policy is kOCCInit_FromConfig. It is ignored for other policies.

Returns
void

PDOCContextMakeCopy

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,

Parameters
ocContext: PDOCContext

The context to copy.

Returns
PDOCContext

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

PDOCContextMakeCopyWithAutoStateChanges

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.

Parameters
event: ASAtom
Returns

PDOCContextNew

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

The initialization policy for the new context. This value determines whether optional-content groups (OCGs) are initially ON or OFF .

otherCtx: PDOCContext

Another context from which to take initial OCG states when the policy is kOCCInit_FromOtherContext. It is ignored for other policies.

pdOCCfg: PDOCConfig

A configuration from which to take initial OCG states when the policy is kOCCInit_FromConfig. It is ignored for other policies.

pdDoc: PDDoc

The document for which to create a context.

Returns
PDOCContext

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

PDOCContextNewWithInitialState

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

The document for which to create a context.

Returns
PDOCContext

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

PDOCContextNewWithOCDisabled

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

The document for which to create a context.

Returns
PDOCContext

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

PDOCContextPopOCMD

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

The context for which to pop the OCMD stack.

Returns
void

PDOCContextPushOCMD

void PDOCContextPushOCMD(PDOCContext pdOCContext, PDOCMD pdOCMD)
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

The context containing the OCMD stack.

pdOCMD: PDOCMD

The OCMD to push onto the stack.

Returns
void

PDOCContextResetOCMDStack

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

Parameters
pdOCContext: PDOCContext
Returns
void

PDOCContextSetIntent

void PDOCContextSetIntent(PDOCContext ocContext, ASAtom *intent)
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

The context for which to set the intent.

intent: ASAtom *

The new Intent entry value, an array of atoms terminated with ASAtomNull.

Returns
void

PDOCContextSetNonOCDrawing

void PDOCContextSetNonOCDrawing(PDOCContext ocContext, ASBool drawNonOC)
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

The context for which to set the non-OC drawing status.

drawNonOC: ASBool

The new value for the non-OC drawing status, true or false .

Returns
void

PDOCContextSetOCDrawEnumType

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

The context for which the drawing and enumeration type is desired.

dt: PDOCDrawEnumType

The new drawing and enumeration type.

Returns
void

PDOCContextSetOCGStates

void PDOCContextSetOCGStates(PDOCContext ocContext, PDOCG *pdocgs, ASBool *newStates)
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

The context for which the OCG states are set.

pdocgs: PDOCG *

A NULL -terminated array of optional-content groups.

newStates: 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

PDOCContextXObjectIsVisible

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

The context for which to test visibility.

obj: CosObj

The external object.

Returns
ASBool

true if the external object is visible, false otherwise.

Structures(1)

PDOCContext

typedef struct _t_PDOCContext* PDOCContext
PDExpT.h:5636

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

PDExpT.h:5737

The optional-content group (OCG) state is changing.

Values
kPDOCGState
—

The OCGs' states are changing.

kPDOCContextDrawEnumType
—

The PDOCContext object's PDDrawEnumType is changing.

kPDOCContextNonOCDrawing
—

The PDOCContext object's non-optional content drawing is changing.

kPDOCContextIntent
—

The PDOCContext object's intent is changing.

kPDOCContextInit
—

The PDOCContext is being reset using PDOCContextInit().

kPDOC_LastContextChangeType
—

PDOCContextInitPolicies

PDExpT.h:5666

PDOCContextInitPolicy is used to specify how to initialize the states of Optional Content Groups (OCGs) when calling PDOCContextNew() or PDOCContextInit().

Values
kOCCInit_OFF
—
kOCCInit_ON
—
kOCCInit_FromOtherContext
—
kOCCInit_FromConfig
—

PDOCDrawEnumTypes

PDExpT.h:5714

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
—

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
—

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
—

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
—

PDOCG

26 items

Functions(24)

PDOCGCreate

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

The document in which the group is used.

name: ASConstText

The name of the optional-content group.

Returns
PDOCG

The newly created group object.

PDOCGDestroy

void PDOCGDestroy(PDOCG pdocg)
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

The optional-content group object.

Returns
void

PDOCGGetInitialState

ASBool PDOCGGetInitialState(PDOCG pdocg, PDOCConfig pdOCCfg, ASBool *initState)
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

The optional-content group object.

pdOCCfg: PDOCConfig

The configuration for which to get the group's initial state.

initState: ASBool *

(Filled by the method) The initial state, true if the state is ON , false if it is OFF .

Returns
ASBool

true if the initial state is unambiguously defined in the configuration, false otherwise.

PDOCGGetIntent

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

The optional-content group object for which the intent is desired.

Returns
ASAtom *

An array containing intent entries (ASAtom objects) terminated by ASAtomNull. The client is responsible for freeing it using ASfree().

PDOCGGetLocked

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

IN The PDOCG whose locked state is requested.

pdOCCfg: PDOCConfig

IN The optional-content configuration.

Returns
ASBool

An ASBool that is true if the OCG is locked, and false if it is unlocked.

PDOCGGetName

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

The optional-content group object for which the name is desired.

Returns
ASText

The name string.

See Also

PDOCGGetUsageEntry

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: <ul> CreatorInfo Language Export Zoom Print View User PageElement

Parameters
pdocg: PDOCG

The optional-content group object.

entry: ASAtom

The usage key in the usage dictionary entry.

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

PDOCGGetUserOverride

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.

Parameters
ocg: PDOCG
Returns

PDOCGRemoveInitialState

PDProcs.h:8945

Removes the initial ON-OFF state information for the optional-content group (OCG) object in a given configuration.

Parameters
pdocg: PDOCG

The optional-content group object.

pdOCCfg: PDOCConfig

The configuration for which to remove the group's initial state.

Returns
void

PDOCGSetCurrentState

void PDOCGSetCurrentState(PDOCG pdocg, PDOCContext ocContext, ASBool newState)
PDProcs.h:9111

Sets the current ON-OFF state of the optional-content group (OCG) object in a given context.

Parameters
pdocg: PDOCG

The optional-content group object.

ocContext: PDOCContext

The context for which to set the group's state.

newState: ASBool

The new state.

Returns
void

PDOCGSetInitialState

void PDOCGSetInitialState(PDOCG pdocg, PDOCConfig pdOCCfg, ASBool onOff)
PDProcs.h:8904

Sets the initial state ( ON or OFF ) of the optional-content group (OCG) object in a given configuration.

Parameters
pdocg: PDOCG

The optional-content group object.

pdOCCfg: PDOCConfig

The configuration for which to set the group's initial state.

onOff: ASBool

The new initial state, true if the state is ON , false if it is OFF .

Returns
void

PDOCGSetIntent

void PDOCGSetIntent(PDOCG pdocg, ASAtom *intent)
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

The optional-content group object for which the intent is desired.

intent: ASAtom *

The new Intent entry value, an array of atoms terminated with ASAtomNull.

Returns
void

PDOCGSetLocked

void PDOCGSetLocked(PDOCG ocg, PDOCConfig pdOCCfg, ASBool locked)
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

IN The PDOCG whose locked state is to be set.

pdOCCfg: PDOCConfig

IN/OUT The optional-content configuration.

locked: ASBool

IN An ASBool that is true if the OCG should be locked, and false if it should be unlocked.

Returns
void

PDOCGSetUsageDictEntry

void PDOCGSetUsageDictEntry(PDOCG pdocg, ASAtom usagekey, CosObj usageinfo)
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

The optional-content group object.

usagekey: ASAtom

The usage entry key.

usageinfo: CosObj

The usage information to associate with the key.

Returns
void

PDOCGSetUserOverride

void PDOCGSetUserOverride(PDOCG ocg, PDOCContext ctx, ASBool overridden)
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.

Parameters
ocg: PDOCG
overridden: ASBool
Returns
void

PDOCGUsedInOCConfig

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

The optional-content group object.

pdoccfg: PDOCConfig

The optional-content configuration.

Returns
ASBool

true if the group is taken into consideration when determining the visibility of content, false otherwise.

PDOCGUsedInOCContext

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

The optional-content group object.

pdocctx: PDOCContext

The optional-content context.

Returns
ASBool

true if the group is taken into consideration when determining the visibility of content, false otherwise.

Typedefs(1)

Structures(1)

PDOCG

typedef struct _t_PDOCG* PDOCG
PDExpT.h:5618

A PDOCG represents a named object whose state can be toggled in a user interface to affect changes in visibility of content.

PDOCMD

15 items

Functions(12)

PDOCMDCreate

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

The document in which the dictionary is used.

ocgs: PDOCG *

A NULL -terminated array of optional-content groups (OCGs) to be members of the dictionary.

policy: 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

The newly created dictionary object, or NULL if no groups are supplied.

PDOCMDFindOrCreate

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

The document in which the dictionary is used.

ocgs: PDOCG *

A NULL -terminated array of optional-content groups (OCGs) to be members of the dictionary.

policy: 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

The newly created or existing dictionary object, or NULL if no groups are supplied.

PDOCMDFindOrCreateEx

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

The PDDoc in which to create the PDOCMD.

ocgs: PDOCG *

A list of OCGs, or NULL if only a visibility expression is to be used.

policy: PDOCMDVisPolicy

The visibility policy to use. unused if ocgs is NULL .

veObj: CosObj

A CosObj containing a visibility expression.

Returns

PDOCMDGetOCGs

PDProcs.h:9309

Gets the optional-content groups listed in a membership dictionary.

Parameters
pdocmd: PDOCMD

The membership dictionary whose OCGs are obtained.

Returns
PDOCG *

A NULL -terminated array of the document's optional-content groups. The client is responsible for freeing the array using ASfree().

PDOCMDGetVisibilityExpression

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

The PDOCMD in which to check for a visibility expression.

veObj: CosObj *

The cos object in which to return the visibility expression.

Returns
ASBool

true if there is a visibility expression, false otherwise.

PDOCMDIsCurrentlyVisible

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

The dictionary.

ocContext: PDOCContext

The context in which the visibility of content is tested.

Returns
ASBool

true if content tagged with this dictionary is visible in the given context, false if it is hidden.

PDOCMDsAreCurrentlyVisible

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 *

A NULL -terminated array of dictionaries to test.

ocContext: PDOCContext

The context in which visibility is tested.

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

PDOCMDsMakeContentVisible

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 *

A NULL -terminated array of dictionaries to act upon.

ocContext: PDOCContext

The context in which the contents are made visible.

Returns
ASBool

true if successful or if the OCMD list is empty, false otherwise.

Typedefs(1)

Structures(1)

PDOCMD

typedef struct _t_PDOCMD* PDOCMD
PDExpT.h:5623

A PDOCMD is an object that is attached to content to indicate membership in an OCG or group of OCGs.

Enums(1)

PDOCMDVisPolicies

PDExpT.h:5651

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
—
kOCMDVisibility_AnyOn
—
kOCMDVisibility_AnyOff
—
kOCMDVisibility_AllOff
—

PDPage

93 items

Functions(72)

PDPageAcquirePDEContent

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

A PDEContent representing the page's contents.

PDPageAcquirePage

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

Parameters
pdPage: PDPage

IN The page whose reference count is to be incremented.

Returns
void
Since
0 .

PDPageAddAnnot

void PDPageAddAnnot(PDPage aPage, ASInt32 addAfter, PDAnnot annot)
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

The page to which the annotation is added.

addAfter: 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

The annotation to add.

Returns
void

PDPageAddCosContents

void PDPageAddCosContents(PDPage page, CosObj newContents)
PDProcs.h:3541

Completely replaces the contents of the specified page with newContents .

Parameters
page: PDPage

IN/OUT The page whose Cos contents are replaced.

newContents: 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

PDPageAddCosResource

void PDPageAddCosResource(PDPage page, const char *resType, const char *resName, CosObj resObj)
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

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

The Cos object being added as a resource to page. @notify PDDocDidChangePages

Returns
void

PDPageAddNewAnnot

PDAnnot PDPageAddNewAnnot(PDPage aPage, ASInt32 addAfter, ASAtom subType, const ASFixedRect *initialRect)
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

The page to which the annotation is added.

addAfter: 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

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

The newly created annotation.

PDPageCreateAnnot

PDAnnot PDPageCreateAnnot(PDPage aPage, ASAtom subType, const ASFixedRect *initialLocation)
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

The page to whose PDDoc the annotation is added.

subType: 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

The newly created annotation.

PDPageDrawContentsToWindow

void PDPageDrawContentsToWindow(PDPage page, void *window, void *displayContext, ASBool isDPS, ASFixedMatrix *matrix, ASFixedRect *updateRect, CancelProc cancelProc, void *cancelProcClientData)
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. This method cannot be reliably used to print to a device. Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

Parameters
page: 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

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

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

PDPageDrawContentsToWindowEx

void PDPageDrawContentsToWindowEx(PDPage page, void *window, void *displayContext, ASBool isDPS, ASFixedMatrix *matrix, ASUns32 flags, ASFixedRect *updateRect, CancelProc cancelProc, void *cancelProcClientData)
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. 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. Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

Parameters
page: 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

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

See PDPageDrawFlagsPI for possible values.

updateRect: ASFixedRect *

A rectangle represented by the coordinates of its four sides.

cancelProc: 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

PDPageDrawContentsToWindowEx2

void PDPageDrawContentsToWindowEx2(PDPage page, void *window, void *displayContext, ASBool isDPS, ASDoubleMatrix *matrix, ASCab flags, ASDoubleRect *updateRect, ASCancelProc cancelProc, void *cancelProcClientData)
PDProcs.h:12778

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. This method cannot be reliably used to print to a device. Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

Parameters
page: 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

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

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

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

PDPageDrawContentsWithParams

void PDPageDrawContentsWithParams(PDPage page, PDDrawParams params)
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. Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

Parameters
page: 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

PDPageEnumContents

void PDPageEnumContents(PDPage page, PDGraphicEnumMonitor mon, void *clientData)
PDProcs.h:3619

Enumerates the contents of a page, calling a procedure for each drawing object in the page description. 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

IN/OUT The page whose contents are enumerated.

mon: 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

void PDPageEnumInks(PDPage pdPage, PDPageEnumInksCallback proc, void *clientData, ASBool includeOPI)
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

The page whose contents are enumerated.

proc: 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

If true , enumerate inks contained in OPI dictionaries.

Returns
void

PDPageEnumInksEx

void PDPageEnumInksEx(PDPage pdPage, PDPageEnumInksCallback proc, void *clientData, ASBool includeOPI, ASAtom colorModel)
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

The page whose contents are enumerated.

proc: 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

If true , enumerate inks contained in OPI dictionaries.

colorModel: ASAtom

CMYK_K , RGB_K , or Gray_K .

Returns
void

PDPageEnumOCGs

void PDPageEnumOCGs(PDPage pdPage, PDOCGEnumProc enumProc, void *clientData)
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

The page whose groups are enumerated.

enumProc: 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

PDPageEnumResources

void PDPageEnumResources(PDPage page, PDResourceEnumMonitor mon, void *clientData)
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(). 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

The page whose Cos resources are enumerated.

mon: 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

PDPageGetAnnotSequence

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. The sequence number is one-based, while the index returned by PDPageGetAnnotIndex() is zero-based.

Parameters
page: PDPage

The page on which the annotation exists.

annot: PDAnnot

The annotation for which the sequence number is desired.

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

PDPageGetBBox

void PDPageGetBBox(PDPage page, ASFixedRect *bboxP)
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

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

PDPageGetBox

ASBool PDPageGetBox(PDPage page, ASAtom boxName, ASFixedRect *box)
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

The page whose box is obtained.

boxName: 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

true if the requested box was specified for the page, false otherwise.

See Also

PDPageGetCosObj

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

IN/OUT The page whose Cos object is obtained.

Returns
CosObj

The dictionary Cos object associated with page.

PDPageGetCosResources

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

IN/OUT The page whose Cos resources are obtained.

Returns
CosObj

The dictionary Cos object associated with the page's resource.

PDPageGetDefaultMatrix

void PDPageGetDefaultMatrix(PDPage pdPage, ASFixedMatrix *defaultMatrix)
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

The page whose default transformation matrix is obtained.

defaultMatrix: ASFixedMatrix *

(Filled by the method) A pointer to the default transformation matrix.

Returns
void

PDPageGetDuration

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

The page whose timing value is obtained.

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

PDPageGetFlippedMatrix

void PDPageGetFlippedMatrix(PDPage pdPage, ASFixedMatrix *flipped)
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

The page whose flipped transformation matrix is obtained.

flipped: ASFixedMatrix *

(Filled by the method) A pointer to the flipped transformation matrix.

Returns
void

PDPageGetMediaBox

void PDPageGetMediaBox(PDPage page, ASFixedRect *mediaBoxP)
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

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

PDPageGetNumAnnots

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

The page for which the number of annotations is obtained.

Returns
ASInt32

The number of annotations on aPage .

See Also

PDPageGetPDEContentFilters

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
numFilters: OUT ASInt32 *
filters: OUT ASAtom **
Returns
ASBool

true if filters are obtained, false if the page's contents are not cached.

PDPageGetPalette

ASBool PDPageGetPalette(PDPage page, void *displayContext, char *table)
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. Platform: ((!MAC_PLATFORM || (MAC_PLATFORM && !AS_ARCH_64BIT))) && ((!MAC_PLATFORM))

Parameters
page: PDPage

The page whose palette is obtained.

displayContext: void *

The bitmap.

table: char *

(Filled by the method) The palette.

Returns
ASBool

true if the palette was returned, false otherwise.

PDPageGetUserUnitSize

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

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

void PDPageGetVisibleBBox(PDPage page, PDOCContext ocContext, ASBool includeAnnots, ASFixedRect *fr)
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

The page whose visible-content bounding box is obtained.

ocContext: PDOCContext

The context within which the contents are visible.

includeAnnots: 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

PDPageHasTransparency

ASBool PDPageHasTransparency(PDPage pdPage, ASBool includeAnnotAppearances)
PDProcs.h:8157

Checks whether a page uses any transparency features. 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

The page to check.

includeAnnotAppearances: ASBool

If true , annotation appearances are included in the check; if false annotation appearances will be ignored.

Returns
ASBool

true only if the page uses any transparency features.

PDPageMakeSeparations

void PDPageMakeSeparations(PDPage pdPage, PDHostSepsSpec spec)
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

The page.

spec: PDHostSepsSpec

The separation specification structure containing parameters for the generation.

Returns
void

PDPageNotifyContentsDidChange

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

IN/OUT The page that changed. @notify PDPageContentsDidChange @notify PDPageContentsDidChangeEx (in version 2.1 and later)

Returns
void

PDPageNotifyContentsDidChangeEx

void PDPageNotifyContentsDidChangeEx(PDPage page, ASBool invalidateViews)
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

The page that changed.

invalidateViews: 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

PDPageNumFromCosObj

PDProcs.h:3135

Gets the page number of the page specified by a Cos object. Do not call this method with a NULL Cos object.

Parameters
pageObj: CosObj

IN/OUT The dictionary Cos object for the page whose number is obtained.

Returns
ASInt32

The page within the document (the first page in a document is page number zero).

See Also

PDPagePDEContentWasChanged

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

PDPageRegisterForPDEContentChanged

void PDPageRegisterForPDEContentChanged(IN PagePDEContentDidChangeNPROTO proc, IN ASExtension self)
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

PDPageRegisterForPDEContentNotCached

void PDPageRegisterForPDEContentNotCached(IN PagePDEContentNotCachedNPROTO proc, IN ASExtension self)
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

PDPageReleasePDEContent

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

The updated reference count.

PDPageRemoveAnnot

void PDPageRemoveAnnot(PDPage aPage, ASInt32 annotIndex)
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

The page from which the annotation is removed.

annotIndex: ASInt32

The index (into the page's annotation array) of the annotation to remove.

Returns
void

PDPageRemoveCosResource

void PDPageRemoveCosResource(PDPage page, const char *resType, const char *resName)
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

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

PDPageSetBox

void PDPageSetBox(PDPage page, ASAtom boxName, ASFixedRect box)
PDProcs.h:7905

Sets the box specified by boxName for the page. This method may throw exceptions.

Parameters
page: PDPage

IN/OUT The page for which the box is to be set.

boxName: 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

PDPageSetCropBox

void PDPageSetCropBox(PDPage page, ASFixedRect cropBox)
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

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

PDPageSetDuration

void PDPageSetDuration(PDPage pdp, ASFixed fxDuration)
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

The page whose timing is set.

fxDuration: ASFixed

The auto-advance timing, in seconds. If no advance timing is desired, fxDuration should be set to fxDefaultPageDuration.

Returns
void

PDPageSetMediaBox

void PDPageSetMediaBox(PDPage page, ASFixedRect mediaBox)
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

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

PDPageSetPDEContent

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

true if PDEContent successfully set, false otherwise.

PDPageSetPDEContentCanRaise

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

PDPageSetPDEContentFilters

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

true if filters were set, false if the page's contents are not cached (meaning that nothing was done).

PDPageSetUserUnitSize

void PDPageSetUserUnitSize(PDPage page, float unitSize)
PDProcs.h:11246

Set the UserUnit value for a page.

Parameters
page: 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

PDPageStmGetInlineImage

ASUns32 PDPageStmGetInlineImage(ASStm stm, ASUns32 flags, CosDoc cosDoc, CosObj resDict, PDPageStmImageDataProc proc, void *procClientData, ASUns32 *imageRawDataStmOffsetP, ASUns32 *imageRawDataLenP, CosObj *imageDict)
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 <i>filtered</i> 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.

Parameters
stm: ASStm
flags: ASUns32
cosDoc: CosDoc
resDict: CosObj
procClientData: void *
imageRawDataStmOffsetP: ASUns32 *
imageRawDataLenP: ASUns32 *
imageDict: CosObj *
Returns

PDPageStmGetToken

ASUns32 PDPageStmGetToken(ASStm stm, ASUns32 flags, PDPageStmStringOverflowProc proc, void *procClientData, PDPageStmToken pageStmToken)
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 <i>filtered</i> 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:

<ul> <li>A NULL object is returned (an object of type CosNull). </li> <li>The number of bytes read (return value) is 1. </li> </ul>

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.

Parameters
stm: ASStm
flags: ASUns32
procClientData: void *
pageStmToken: PDPageStmToken
Returns

PDPageSuspendPDEContentChanged

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

PDPageUnRegisterForPDEContentChanged

void PDPageUnRegisterForPDEContentChanged(IN PagePDEContentDidChangeNPROTO proc, IN ASExtension self)
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

PDPageUnRegisterForPDEContentNotCached

void PDPageUnRegisterForPDEContentNotCached(IN PagePDEContentNotCachedNPROTO proc, IN ASExtension self)
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

Typedefs(8)

Structures(1)

PDPage

typedef struct _t_PDPage* PDPage
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 .

Enums(4)

PDPageAreas

PDExpT.h:6327

Different logical areas on a page.

Values
kPDPageArea
—
kPDClipArea
—
kPDNumAreas
—

PDPageDrawFlagsPIs

PDExpT.h:6726
Values
kPDPageDoLazyErasePI
—

Erase the page while rendering only as needed.

kPDPageIgnoreIsolatedAndKnockoutTransparencyGroupPI
—

Ignore Isolated and Knockout transparency at page boundary.

kPDPageUseAnnotFacesPI
—

Draw annotation appearances.

kPDPageIsPrintingPI
—

The page is being printed.

kPDPageDisplayOverPrintPreviewPI
—

Display overprint preview.

kPDPageUseTrapAnnotsPI
—

Use trap network annotations.

kPDPageDirectlyImposedPI
—

Directly imposed page.

kPDPageIsPSPrintingPI
—

PostScript printing.

kPDPageEmitPageGroupPI
—

Emit a page group.

kPDPageUsePrinterMarkAnnotsPI
—

User printer's mark annotations.

kPDPagePassOPItoAGMPortPI
—

Pass open prepress interface (OPI) to AGM port.

kPDPagePassMetadatatoAGMPortPI
—

Pass metadata to AGM port.

kPDPagePassOCtoAGMPortPI
—

Pass optional content to AGM port.

kPDPageDoNotSubstituteWorkingSpacesPI
—

Do not substitute working spaces.

kPDPageSwapComponentsPI
—

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
—

Suppress raster alpha.

kPDPageWorkingSpacesOnlyForChangePI
—

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
—

If set, only consider Stamp annotations. This overrides kPDPageUseAnnotFaces.

PDPageModes

PDExpT.h:1975

An enumerated data type that specifies whether thumbnail images or bookmarks are shown.

Values
PDDontCare
—

Leaves the view mode as is.

PDUseNone
—

Displays the document, but displays neither thumbnails nor bookmarks.

PDUseThumbs
—

Displays the document plus thumbnails.

PDUseBookmarks
—

Displays the document plus bookmarks.

PDFullScreen
—

Displays the document in full-screen viewing mode. This is equivalent to AVAppBeginFullScreen().

PDContents
—
PDUseOC
—

Displays the document plus layers.

PDUseAttachments
—

Displays the document plus attachments.

PDPageRotation

PDExpT.h:2456

Specifies page rotation, in degrees. It is used for routines that set or get the value of a page's Rotate key.

Values
pdRotate0
—
pdRotate90
—
pdRotate180
—
pdRotate270
—

Definitions(8)

PDPageLabel

11 items

Functions(10)

PDPageLabelEqual

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

A page label.

pdlTwo: PDPageLabel

Another page label.

Returns
ASBool

true if the two labels are valid and equivalent, false otherwise.

PDPageLabelGetPrefix

const char * PDPageLabelGetPrefix(PDPageLabel pgLabel, ASInt32 *prefixLen)
PDProcs.h:7189

Returns the prefix string for the label. The prefix string is transitory and should be copied immediately.

Parameters
pgLabel: PDPageLabel

The label for the page whose prefix is desired.

prefixLen: 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.

PDPageLabelGetPrefixASText

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

The label for the page whose prefix is desired.

prefix: 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

PDPageLabelIsValid

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

The page label whose validity is determined.

Returns
ASBool

true if the label is valid, false otherwise.

PDPageLabelNew

PDPageLabel PDPageLabelNew(PDDoc pdDoc, ASAtom style, const char *prefix, ASInt32 prefixLen, ASInt32 startAt)
PDProcs.h:7262

Constructs a new label object in the document with the specified style, prefix, and starting page number.

Parameters
pdDoc: PDDoc

The document that contains the new page label.

style: 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

The length in bytes of the prefix string.

startAt: 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

The newly created page label.

Typedefs(1)

PDPageLabel

typedef OPAQUE_64_BITS PDPageLabel
PDExpT.h:5538

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

PDPath

15 items

Functions(2)

PDPathEnum

void PDPathEnum(PDPath obj, PDPathEnumMonitor mon, void *clientData)
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

IN/OUT The path whose operators are enumerated.

mon: 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

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

IN/OUT The path whose painting operators are obtained.

Returns
ASInt32

A bit-wise OR of the PDPathPaintOp flags.

Typedefs(9)

PDPathCurveToProc

typedef ASBool(* PDPathCurveToProc) (ASFixedPoint *p1, ASFixedPoint *p2, ASFixedPoint *p3, void *clientData))(ASFixedPoint *p1, ASFixedPoint *p2, ASFixedPoint *p3, void *clientData)
PDExpT.h:2951

A callback for PDPathEnumMonitor. It is called for every c operator.

See Also

PDPathRectProc

typedef ASBool(* PDPathRectProc) (ASFixedPoint *p1, ASFixedPoint *p2, void *clientData))(ASFixedPoint *p1, ASFixedPoint *p2, void *clientData)
PDExpT.h:2991

A callback for PDPathEnumMonitor. It is called for every re operator.

See Also

PDPathVCurveToProc

typedef ASBool(* PDPathVCurveToProc) (ASFixedPoint *p1, ASFixedPoint *p2, void *clientData))(ASFixedPoint *p1, ASFixedPoint *p2, void *clientData)
PDExpT.h:2965

A callback for PDPathEnumMonitor. It is called for every v operator.

See Also

PDPathYCurveToProc

typedef ASBool(* PDPathYCurveToProc) (ASFixedPoint *p1, ASFixedPoint *p2, void *clientData))(ASFixedPoint *p1, ASFixedPoint *p2, void *clientData)
PDExpT.h:2978

A callback for PDPathEnumMonitor. It is called for every y operator.

See Also

Structures(2)

Enums(2)

PDPathPaintOps

PDExpT.h:2521

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
—

The path is not painted.

pdPathOpClose
—

The path contains a closepath operator.

pdPathStroke
—

The path contains a stroke operator.

pdPathFill
—

The path contains a fill operator.

pdPathEOFill
—

The path contains an eofill operator.

pdPathClip
—

The path contains a clip operator.

pdPathEOClip
—

The path contains an eoclip operator.

PDPathSegmentOps

PDExpT.h:2495

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
—
pdSegLineTo
—
pdSegCurveTo
—
pdSegVCurveTo
—
pdSegYCurveTo
—
pdSegRect
—
pdSegClosePath
—
See Also

PDPref

13 items

Functions(13)

PDPrefGetColorCal

ASBool PDPrefGetColorCal(PDColorCalP colorCal)
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

Always returns true .

PDPrefGetInstallPatternParentGState

PDProcs.h:12825

Get the preference whether to install the graphics state that was in effect at the beginning of the pattern's parent content stream

Parameters
: void
Returns
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.

PDPrefSetBlackPointCompensation

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

true to enable black-point compensation, false otherwise.

Returns
void

PDPrefSetColorCal

ASBool PDPrefSetColorCal(PDColorCalP colorCal)
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

true if the values were successfully set and installed for the currently active display device, false otherwise.

PDPrefSetInstallPatternParentGState

void PDPrefSetInstallPatternParentGState(ASBool bInstallPatternParentGStateFlag)
PDProcs.h:12819

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

Pass 1 to install GState was in effect at the beginning of the pattern's parent content stream

Returns
void

PDPrefSetWorkingGray

void PDPrefSetWorkingGray(void *profile, ASUns32 profileLength)
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

The length in bytes of the profile.

Returns
void

PDRedaction

2 items

Functions(2)

PDRedactionSetProps

ASBool PDRedactionSetProps(PDAnnot redactionAnnot, PDRedactParams redactionProps)
PDProcs.h:11976

Assigns a set of properties to a given redaction mark.

Parameters
redactionAnnot: 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

true if the properties were successfully assigned, false otherwise.

PDStyle

4 items

Functions(3)

Structures(1)

PDText

4 items

Functions(2)

PDTextEnum

void PDTextEnum(PDText text, PDStringEnumProc enumProc, void *clientData)
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

IN/OUT The text object whose strings are enumerated.

enumProc: 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

void PDTextGetState(PDText obj, PDTextStateP stateP, ASInt32 stateLen)
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

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

IN/OUT It must be sizeof(PDTextState) .

Returns
void

Typedefs(1)

Structures(1)

PDTextAnnot

8 items

Functions(6)

PDTextAnnotGetContentsASText

PDProcs.h:11479

Gets the text of a text annotation as an ASText object.

Parameters
aTextAnnot: PDTextAnnot

The text annotation whose text is obtained.

contents: 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

PDTextAnnotIsOpen

PDProcs.h:630

Tests whether a text annotation is open. 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

The text annotation whose open/closed state is obtained.

Returns
ASBool

true if the annotation is open, false otherwise.

PDTextAnnotSetOpen

void PDTextAnnotSetOpen(PDTextAnnot aTextAnnot, ASBool isOpen)
PDProcs.h:651

Opens or closes a text annotation. 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

The annotation to open or close.

isOpen: ASBool

true if the annotation is opened, false if the annotation is closed. @notify PDAnnotWillChange @notify PDAnnotDidChange

Returns
void

Typedefs(1)

PDTextAnnot

typedef OPAQUE_64_BITS PDTextAnnot
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:

<ul> <li>Get and set attributes including the rectangle, textual contents, and whether the annotation is open.</li> <li>Create new text annotations, and delete or move existing ones using PDAnnot methods.</li> <li>Manipulate the behavior of text annotations by modifying the Text Annotation Handler.</li> </ul>

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.

Definitions(1)

PDTextSelect

24 items

Functions(14)

PDTextSelectCreatePageHilite

PDTextSelect PDTextSelectCreatePageHilite(PDPage page, HiliteEntry *hList, ASInt32 listLen)
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(). As is the case with the Acrobat viewer, the text selection is always of whole words, not part of words.

Parameters
page: 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

The number of highlight entries in hList .

Returns
PDTextSelect

The newly created text selection.

PDTextSelectCreatePageHiliteEx

PDTextSelect PDTextSelectCreatePageHiliteEx(PDPage page, HiliteEntry *hList, ASInt32 listLen, ASInt16 WFVersion)
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

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

The number of highlight entries in hList .

WFVersion: ASInt16

The WordFinder version:

Returns
PDTextSelect

The newly created text selection.

PDTextSelectCreateRanges

PDTextSelect PDTextSelectCreateRanges(PDPage page, PDTextSelectRange range, ASInt32 rangeCount)
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

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

IN/OUT The number of ranges in range.

Returns
PDTextSelect

A text selection created from the specified ranges.

PDTextSelectCreateRangesEx

PDTextSelect PDTextSelectCreateRangesEx(PDPage page, PDTextSelectRange range, ASInt32 rangeCount, ASInt16 WFVersion)
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

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

IN/OUT The number of ranges in range.

WFVersion: ASInt16

IN/OUT The WordFinder version:

Returns
PDTextSelect

A text selection created from the specified ranges.

PDTextSelectCreateWordHilite

PDTextSelect PDTextSelectCreateWordHilite(PDPage page, HiliteEntry *hList, ASInt32 listLen)
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

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

The number of highlight entries in hList .

Returns
PDTextSelect

The newly created text selection.

PDTextSelectCreateWordHiliteEx

PDTextSelect PDTextSelectCreateWordHiliteEx(PDPage page, HiliteEntry *hList, ASInt32 listLen, ASInt16 WFVersion)
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

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

The number of highlight entries in hList .

WFVersion: ASInt16

The WordFinder version:

Returns
PDTextSelect

The newly created text selection.

PDTextSelectDestroy

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

IN/OUT The text selection to destroy.

Returns
void

PDTextSelectEnumQuads

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

IN/OUT The text selection whose bounding quads are enumerated.

proc: 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

PDTextSelectEnumText

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

IN/OUT The text selection whose strings are enumerated.

proc: 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

PDTextSelectEnumTextUCS

PDProcs.h:7998

Same as PDTextSelectEnumText(), except the output is forced to UCS.

Parameters
textP: PDTextSelect

IN/OUT The text selection whose strings are enumerated.

proc: 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

PDTextSelectGetBoundingRect

void PDTextSelectGetBoundingRect(PDTextSelect text, ASFixedRect *boundRectP)
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

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

PDTextSelectGetRange

void PDTextSelectGetRange(PDTextSelect textP, ASInt32 index, PDTextSelectRange range)
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

IN/OUT The text selection from which a range is extracted.

index: 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

Typedefs(3)

PDTextSelectEnumTextProc

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)
PDExpT.h:3181

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.

Structures(1)

Definitions(6)

PDThread

12 items

Functions(11)

PDThreadGetCosObj

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

IN/OUT The thread whose Cos object is to obtained.

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

PDThreadGetInfoASText

void PDThreadGetInfoASText(PDThread thread, const ASText infoKey, ASText value)
PDProcs.h:11685

Gets the specified article thread's info as an ASText object.

Parameters
thread: PDThread

The thread whose thread info is being obtained.

infoKey: const ASText

The key whose value is being obtained.

value: 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

PDThreadIsValid

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

The thread whose validity is tested.

Returns
ASBool

true if the thread is valid, false otherwise.

Typedefs(1)

PDThumb

7 items

Functions(2)

PDThumbGetImageData

ASStm PDThumbGetImageData(PDThumb thumb, ASInt32 *height, ASInt32 *width, ASInt32 *bpc, ASAtom *csName)
PDProcs.h:11811

Gets an ASStm from a thumbnail data.

Parameters
thumb: PDThumb

The thumb for which image data is to be retrieved.

height: ASInt32 *

(Filled by the method) The height of the thumbnail.

width: ASInt32 *

(Filled by the method) The width of the thumbnail.

bpc: ASInt32 *

(Filled by the method) The number of bits per component in the thumbnail image's data.

csName: ASAtom *

(Filled by the method) The color space in which thumnail data is represented.

Returns
ASStm

An ASStm for the thumbnail data.

PDThumbGetIndexedColorSpace

ASStm PDThumbGetIndexedColorSpace(PDThumb thumb, ASInt32 *hival, ASAtom *baseColorSpaceName)
PDProcs.h:11822

Gets an ASStm from a thumbnail's indexed color space table.

Parameters
thumb: PDThumb

The thumb for which image data is to be retrieved.

hival: ASInt32 *

(Filled by the method) The highest valid index in the lookup table for the Indexed color space.

baseColorSpaceName: ASAtom *

(Filled by the method) The base color space in which the values in the color table are to be interpreted.

Returns
ASStm

An ASStm from the thumbnail's indexed color space table.

Typedefs(3)

PDThumbCreationGetThumbDataProc

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)
PDExpT.h:3278

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

Structures(2)

PDTrans

12 items

Functions(9)

PDTransEqual

PDProcs.h:5814

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

Parameters
pdtOne: PDTrans

A transition to test for equality.

pdtTwo: PDTrans

A transition to test for equality.

Returns
ASBool

true if the transitions are equal, false otherwise.

See Also

PDTransFromCosObj

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

The dictionary Cos object to convert to a transition.

Returns
PDTrans

The transition corresponding to the given dictionary object, obj .

PDTransGetCosObj

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

The transition whose Cos object is obtained.

Returns
CosObj

The dictionary Cos object corresponding to the transition. it returns the NULL Cos object if the transition is invalid as determined by PDTransIsValid().

PDTransGetDuration

PDProcs.h:5959

Gets the duration for the given transition. Standard durations are: Duration Meaning 0 seconds fast 1 second medium 2 seconds slow

Parameters
pdt: PDTrans

IN/OUT The transition for which the duration is obtained.

Returns
ASFixed

The transition duration, specified in seconds. If no duration is specified in the transition, the return value is fxDefaultTransDuration ( 1 second).

PDTransNew

PDTrans PDTransNew(PDDoc pdd, ASAtom asaSubtype, ASFixed fxDuration)
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

The PDDoc to whose CosDoc the transition is added.

asaSubtype: 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

The transition duration, in seconds.

Returns
PDTrans

The newly created transition.

PDTransNewFromCosDoc

PDTrans PDTransNewFromCosDoc(CosDoc cd, ASAtom asaSubtype, ASFixed fxDuration)
PDProcs.h:5900

Creates a new transition of the specified type and duration associated with the given CosDoc.

Parameters
cd: CosDoc

The CosDoc to which the transition is added.

asaSubtype: ASAtom

The transition subtype to create. This subtype is returned by the AVTransHandlerGetTypeProc() callback in AVTransHandler.

fxDuration: ASFixed

The transition duration, in seconds.

Returns
PDTrans

The newly created transition.

See Also

PDTransNull

PDProcs.h:5768

Gets a NULL transition. This can be used in conjunction with PDTransEqual() to determine whether a transition is NULL .

Parameters
: void
Returns
PDTrans

A NULL transition.

See Also

Typedefs(1)

Definitions(2)

PDViewDest

9 items

Functions(7)

PDViewDestCreate

PDViewDestination PDViewDestCreate(PDDoc doc, PDPage initialPage, ASAtom initialFitType, const ASFixedRectP initialRect, const ASFixed initialZoom, ASInt32 pageNumber)
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

The document in which the destination is used.

initialPage: PDPage

The destination page.

initialFitType: 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

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

Currently unused.

Returns
PDViewDestination

The newly created view destination.

PDViewDestGetAttr

void PDViewDestGetAttr(PDViewDestination dest, ASInt32 *pageNum, ASAtom *fitType, ASFixedRectP destRect, ASFixed *zoom)
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

IN/OUT The view destination whose attributes are obtained.

pageNum: ASInt32 *

IN/OUT (Filled by the method) The page number of the destination's page.

fitType: 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 *

IN/OUT (Filled by the method) The destination's zoom factor.

Returns
void

PDViewDestGetCosObj

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

IN/OUT The view destination whose Cos object is obtained.

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

PDViewDestIsValid

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

The view destination whose validity is determined.

Returns
ASBool

true if the view destination is valid, false otherwise.

PDViewDestResolve

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

IN/OUT The destination to resolve.

doc: PDDoc

IN/OUT The PDDoc that contains the destination.

Returns
PDViewDestination

The resolved view destination.

See Also

Typedefs(1)

Definitions(1)

PDWord

71 items

Functions(24)

PDWordCreateTextSelect

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

The page on which to select the words.

wList: PDWord *

The word list to be selected.

wListLen: ASUns32

The number of words in the word list.

Returns
PDTextSelect

The newly created text selection.

PDWordFilterString

ASBool PDWordFilterString(ASUns16 *infoArray, char *cNewWord, char *cOldWord)
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). In Acrobat 6.0, the method PDWordFinderEnumWordsStr() is preferred to this method, which remains for backward compatability. CharacterTypeCodes

Parameters
infoArray: 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

true if the string required filtering, false if the filtered string is the same as the unfiltered string.

PDWordFilterWord

ASBool PDWordFilterWord(PDWord word, char *buffer, ASInt16 bufferLen, ASInt16 *newLen)
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. In Acrobat 6.0 and later, the method PDWordFinderEnumWords() is preferred to this method, which remains for backward compatability.

Parameters
word: PDWord

The PDWord to filter.

buffer: char *

(Filled by the method) The filtered string.

bufferLen: ASInt16

The maximum number of characters that buffer can hold.

newLen: ASInt16 *

(Filled by the method) The number of characters actually written into buffer .

Returns
ASBool

true if the word required filtering, false if the filtered string is the same as the unfiltered string.

PDWordGetASText

void PDWordGetASText(PDWord word, ASUns32 filter, ASText str)
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

The word whose text becomes the new ASText.

filter: ASUns32

Character types to be dropped from the output string. For example, the following returns text without soft hyphens and accent marks:

str: ASText

An existing ASText object whose content will be replaced by the new text.

Returns
void

PDWordGetAttr

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

IN/OUT The word whose character types are obtained.

Returns
ASUns16

A bit field containing information on the types of characters in word. The value is a logical OR of the Word Attributes.

PDWordGetAttrEx

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.

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.

Parameters
word: PDWord
groupID: ASUns32
Returns
ASUns16

A bit field containing information on the types of characters in word . The value is a logical OR of the Word Attributes.

PDWordGetByteIdxFromHiliteChar

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

The word containing the character.

charIdx: ASUns32

The character index within the word.

Returns
ASUns32

The byte offset of the specified character within the word, or 0 if the character index is out of range.

PDWordGetCharDelta

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

IN/OUT The word whose character delta is obtained.

Returns
ASInt8

The character delta for word. Cast the return value to an ASInt8 before using.

PDWordGetCharEncFlags

void PDWordGetCharEncFlags(PDWord word, ASUns32 *fList, ASUns32 size)
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

The word whose character encoding flags are obtained.

fList: 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

The maximum number of elements in the array fList .

Returns
void

PDWordGetCharOffset

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

IN/OUT The word whose character offset is obtained.

Returns
ASUns16

The word's character offset. On multi-byte systems, it points to the first byte.

PDWordGetCharOffsetEx

ASUns32 PDWordGetCharOffsetEx(PDWord word, ASUns32 byteIdx, ASUns32 *bytesConsumed, ASUns32 *offsetLen)
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

The word whose character offset is obtained.

byteIdx: ASUns32

The byte index within the word of the character whose offset is obtained. Valid values are 0 to PDWordGetLength(word)-1 .

bytesConsumed: 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 *

(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

The word's character offset and the number of bytes occupied by the character.

PDWordGetCharQuad

ASBool PDWordGetCharQuad(PDWord word, ASUns32 byteIdx, ASFixedQuad *quad)
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

The word whose character offset is obtained.

byteIdx: 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

true if the provided byte index is the beginning byte of a character and a valid quad is returned, false otherwise.

PDWordGetCharacterTypes

PDProcs.h:4935

Gets the character type for each character in a word.

Parameters
word: PDWord

The word whose character types are obtained.

cArr: 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

The number of elements in cArr .

Returns
void

PDWordGetNthQuad

ASBool PDWordGetNthQuad(PDWord word, ASInt16 nTh, ASFixedQuad *quad)
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

The word whose nth quad is obtained.

nTh: 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

true if the word has an nth quad, false otherwise.

PDWordGetNumHiliteChar

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

The word whose highlightable character count is obtained.

Returns
ASUns32

The number of highlightable characters in word .

See Also

PDWordGetNumQuads

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

IN/OUT The word whose quad count is obtained.

Returns
ASInt16

The number of quads in word.

PDWordGetString

void PDWordGetString(PDWord word, char *str, ASInt32 len)
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

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

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

PDWordGetStyleTransition

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

IN/OUT The word whose style transition list is obtained.

transTbl: 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

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

The number of style transition offsets copied to transTbl .

PDWordIsCurrentlyVisible

PDProcs.h:10668

Tests whether a word is visible in a given optional-content context on a given page.

Parameters
word: PDWord

The word to test.

pageNum: ASInt32

The page number for which the word is tested.

ctx: PDOCContext

The context in which the word is tested, as returned by PDDocGetOCContext(pdDoc) .

Returns
ASBool

true if the word is visible in the given context, false if it is hidden.

PDWordMakeVisible

PDProcs.h:10685

Makes a word visible in a given optional-content context on a given page.

Parameters
word: PDWord

The word to test.

pageNum: ASInt32

The page number for which the word is to be made visible.

ctx: PDOCContext

The context in which the word is to be made visible, as returned by PDDocGetOCContext(pdDoc) .

Returns
ASBool

true if the word can be made visible in the given context, false otherwise.

PDWordSplitString

ASUns16 PDWordSplitString(ASUns16 *infoArray, char *cNewWord, char *cOldWord, ASUns16 nMaxLen)
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 *

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

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

The number of splits that occurred.

Typedefs(1)

Structures(1)

Definitions(45)

WXE_ADJACENT_TO_SPACE

PDExpT.h:3577
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

PDExpT.h:3611
Value:0x02 /* Unreliable encoding conversion happened in this word. \&#10; Check the encoding flags of each character for detail. */

WXE_ENC_MISSING

PDExpT.h:3493
Value:0x02 /* The character code is not available in the output encoding space. \&#10; This character is replaced by a space character. */

WXE_ENC_NO_UCS

PDExpT.h:3496
Value:0x04 /* Word Finder is not able to find a reliable Unicode value \&#10;from the character. The character encoding is determined by "guessing" due to insufficient \&#10;encoding information available in the PDF file. */

WXE_ENC_UNMAPPED

PDExpT.h:3485
Value:0x01 /* The font has no useful encoding information. Word Finder copied \&#10;the original character string from the PDF content. In this case, Word Finder always assumes \&#10;the original string is single-byte characters. If the Word Finder is extracting the text in \&#10;Unicode, it inserts additional bytes, 0x00s, to form 16-bit characters. (i.e. "0x41, 0x42" a \&#10;"0x00, 0x41, 0x00, 0x42") A common example of this case is a Symbol font without ToUnicode \&#10;table.Since there is no valid Unicode values are available, during the word-finding process, these \&#10;characters are treated as symbolic characters and each character becomes a word. */

WXE_EXT_CHAR_OFFSETS

PDExpT.h:3616
Value:0x10 /* The word has extened character offset information and \&#10; can be used for character based PDWord methods like \&#10; PDWordGetCharOffsetEx(), PDWordGetCharQuad(), \&#10; PDWordGetNumHiliteChar(), and PDWordGetByteIdxFromHiliteChar(). */

WXE_FROM_ACTUALT

PDExpT.h:3500
Value:0x08 /* The character comes from an ActualText, rather than the page content. */

WXE_FRONT_TAB

PDExpT.h:3610
Value:0x01 /* Insert a tab character before this word */

WXE_HAS_DIGIT

PDExpT.h:3523
Value:0x8

One or more characters in the word are digits.

WXE_HAS_LEADING_PUNC

PDExpT.h:3556
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

PDExpT.h:3513
Value:0x2

The word contains a character between A-Z or a-z.

WXE_HAS_NONALPHANUM

PDExpT.h:3508
Value:0X1

The word contains a character outside the range of A-Z, a-Z, 0-9.

WXE_HAS_PUNCTUATION

PDExpT.h:3534
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_TRAILING_PUNC

PDExpT.h:3563
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

PDExpT.h:3569
Value:0x400

One or more characters in the word cannot be represented in the output font encoding.

WXE_LAST_WORD_ON_LINE

PDExpT.h:3607
Value:0x8000

The word is at the end of the current text line (for example, the word is followed by a line break).

WXE_ROTATED

PDExpT.h:3587
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_VERTICAL_FLOW

PDExpT.h:3596
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.

W_ACCENT

PDExpT.h:3461
Value:0x800

An accent mark.

W_CNTL

PDExpT.h:3402
Value:0x1

A control code.

W_COMMA

PDExpT.h:3451
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

PDExpT.h:3417
Value:0x8

A digit.

W_END_PHRASE

PDExpT.h:3471
Value:0x2000

An end-of-phrase glyph (for example, "." , "?" , "!" , ":" , and ";" ).

W_HYPHEN

PDExpT.h:3427
Value:0x20

A hyphen.

W_LETTER

PDExpT.h:3407
Value:0x2

A lowercase letter.

W_PERIOD

PDExpT.h:3456
Value:0x400

A period.

W_SOFT_HYPHEN

PDExpT.h:3432
Value:0x40

A hyphen that is only present because a word is broken across two lines of text.

W_UNMAPPED

PDExpT.h:3466
Value:0x1000

A glyph that cannot be represented in the destination font encoding.

W_WHITE

PDExpT.h:3442
Value:0x100

A white space glyph.

W_WILD_CARD

PDExpT.h:3476
Value:0x4000

A wildcard glyph (for example, "*" and "?" ) that should not be treated as a normal punctuation mark.

PDWordFinder

15 items

Functions(9)

PDWordFinderAcquireVisibleWordList

void PDWordFinderAcquireVisibleWordList(PDWordFinder wObj, ASInt32 pgNum, PDOCContext ocContext, PDWord *wInfoP, PDWord **xySortTable, PDWord **rdOrderTable, ASInt32 *numWords)
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

The word finder (created using PDDocCreateWordFinder() or PDDocCreateWordFinderUCS()) used to acquire the word list.

pgNum: ASInt32

The page number for which words are found. First page is 0 , not 1 as designated in Acrobat.

ocContext: PDOCContext

The context within which the words are in a visible state. NULL is equivalent to passing PDDocGetOCContext(pdDoc) .

wInfoP: 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 **

(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 **

Currently unused. Pass NULL for its value.

numWords: ASInt32 *

(Filled by the method) The number of visible words found on the page.

Returns
void

PDWordFinderAcquireWordList

void PDWordFinderAcquireWordList(PDWordFinder wObj, ASInt32 pgNum, PDWord *wInfoP, PDWord **xySortTable, PDWord **rdOrderTable, ASInt32 *numWords)
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

The word finder (created using PDDocCreateWordFinder() or PDDocCreateWordFinderUCS()) used to acquire the word list.

pgNum: ASInt32

The page number for which words are found. The first page is 0 , not 1 as designated in Acrobat.

wInfoP: 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 **

(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 **

Currently unused. Pass NULL for this value.

numWords: ASInt32 *

(Filled by the method) The number of words found on the page.

Returns
void

PDWordFinderEnumVisibleWords

ASBool PDWordFinderEnumVisibleWords(PDWordFinder wObj, ASInt32 PageNum, PDOCContext ocContext, PDWordProc wordProc, void *clientData)
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

A word finder object.

PageNum: ASInt32

The page number from which to extract words. Pass PDAllPages (see PDExpT.h ) to sequentially process all pages in the document.

ocContext: PDOCContext

The context within which the words are in a visible state. NULL is equivalent to passing PDDocGetOCContext(pdDoc) .

wordProc: 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

true if enumeration was successfully completed, false if enumeration was terminated because wordProc returned false .

PDWordFinderEnumWords

ASBool PDWordFinderEnumWords(PDWordFinder wObj, ASInt32 PageNum, PDWordProc wordProc, void *clientData)
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
PageNum: ASInt32
wordProc: PDWordProc
clientData: void *
Returns

PDWordFinderEnumWordsStr

ASBool PDWordFinderEnumWordsStr(PDWordFinder wObj, const ASUTF16Val *ucsStr, ASUns32 strLen, ASUns32 charOffsetAdj, PDWordProc wordProc, void *clientData)
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), PDWordFinderEnumWordsStr(wf, str2, stelen(str2), stelen(str1), wp, d);

Parameters
wObj: PDWordFinder

A word finder object.

ucsStr: const ASUTF16Val *

A pointer to the Unicode string.

strLen: ASUns32

The length of the string in bytes.

charOffsetAdj: 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

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

true if the enumeration was successfully completed, false if the enumeration was terminated because wordProc returned false .

PDWordFinderGetLatestAlgVersion

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

IN/OUT The word finder whose algorithm's version is obtained. Pass NULL to obtain the latest word finding algorithm version number.

Returns
ASInt16

The algorithm version associated with wObj , or the version of the latest word finder algorithm if wObj is NULL .

PDWordFinderGetNthWord

PDProcs.h:2217

Gets the nth word in the word list obtained using PDWordFinderAcquireWordList().

Parameters
wObj: PDWordFinder

IN/OUT The word finder whose nth word is obtained.

nTh: 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

The nth word. It returns NULL when the end of the list is reached.

Typedefs(1)

PDWordFinderCtrlProc

typedef ASBool(* PDWordFinderCtrlProc) (ASUns32 startTime, void *clientData))(ASUns32 startTime, void *clientData)
PDExpT.h:3901

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)

Definitions(4)

WF_VERSION_2

PDExpT.h:3646
Value:2

The version used for Acrobat 3.x, 4.x.

WF_VERSION_3

PDExpT.h:3650
Value:3

For Acrobat 5.0 without accessibility enabled.

WF_VERSION_4

PDExpT.h:3654
Value:4

For Acrobat 5.0 with accessibility enabled.

PDXObject

8 items

Functions(5)

PDXObjectEnumFilters

void PDXObjectEnumFilters(PDXObject obj, PDXObjectFilterEnumProc proc, void *clientData)
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

The XObject whose filters are enumerated.

proc: 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

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

The XObject whose Cos object is obtained.

Returns
CosObj

The dictionary Cos object for the XObject.

PDXObjectGetData

void PDXObjectGetData(PDXObject obj, PDGetDataProc getDataProc, void *clientData)
PDProcs.h:3851

(Obsolete, provided only for backwards compatibility) Passes the data from an XObject to a user-supplied procedure.

Parameters
obj: PDXObject

The XObject whose data is read.

getDataProc: 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

Typedefs(2)

PDGetDataProc

typedef ASBool(* PDGetDataProc) (char *data, ASUns32 lenData, void *clientData))(char *data, ASUns32 lenData, void *clientData)
PDExpT.h:3099

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.

Structures(1)