Documente Academic
Documente Profesional
Documente Cultură
Corporate Headquarters 345 Park Avenue San Jose, CA 95110-2704 (408) 536-6000 http://partners.adobe.com
May 2003
Copyright 2003 Adobe Systems Incorporated. All rights reserved. NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in hardcopy or electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of the Adobe Systems Incorporated. PostScript is a registered trademark of Adobe Systems Incorporated. All instances of the name PostScript in the text are references to the PostScript language as defined by Adobe Systems Incorporated unless otherwise stated. The name PostScript also is used as a product trademark for Adobe Systems implementation of the PostScript language interpreter. Except as otherwise stated, any reference to a PostScript printing device,PostScript display device, or similar item refers to a printing device, display device or item (respectively) that contains PostScript technology created or licensed by Adobe Systems Incorporated and not to devices or items that purport to be merely compatible with the PostScript language. Adobe, the Adobe logo, Acrobat, the Acrobat logo, Acrobat Capture, Distiller, PostScript, the PostScript logo and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Apple, Macintosh, and Power Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries. PowerPC is a registered trademark of IBM Corporation in the United States. ActiveX, Microsoft, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. UNIX is a registered trademark of The Open Group. All other trademarks are the property of their respective owners. This publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies, makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and all warranties of merchantability, fitness for particular purposes, and noninfringement of third party rights.
Acrobat Core API Acrobat Core API Overview Acrobat Core API Reference
PDF Creation APIs and Specifications Acrobat Distiller Parameters Acrobat Distiller API Reference pdfmark Reference
JavaScript Acrobat JavaScript Scripting Reference Acrobat JavaScript Scripting Guide Programming Acrobat JavaScript Using Visual Basic
Acrobat Interapplication Communication (IAC) Acrobat IAC Overview Acrobat IAC Reference
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
What Is In This Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Who Should Read This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Other Useful Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Conventions Used in This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
The PDF Consultant and Accessibility Checker Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Acrobat Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Reclassifying and Revisiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Agent Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 How the Consultant Works . . . . . . . Removing or Modifying Objects Reclassifying Objects. . . . . . . . Consultant Itinerary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 12 13 13 14 14 14 15 15
Important Issues For Consultant Development . Maintaining the Traversal Stack . . . . . . . . Deciding Who Does The Work . . . . . . . . . Avoiding Agent Collisions. . . . . . . . . . . . Avoiding Visitation Collisions . . . . . . . . .
Chapter 2
Importing the Consultant HFTs Into a Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 HFT Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Creating and Destroying Consultants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Registering Agents With The Consultant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Starting The Consultant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Using the Traversal Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Consultant Object Type Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Object Type Subclassing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Creating Your Agent Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Contents
Chapter 3
Consultant Management Methods. . ConsultantCreate . . . . . . . ConsultantDestroy . . . . . . ConsultantRegisterAgent . . ConsultantResume . . . . . . ConsultantSetStart . . . . . . ConsultantSuspend. . . . . . ConsultantTraverseFrom . . PDFObjTypeGetSuperclass .
Consultant Traversal Stack Methods . . . . . . . . . . . ConsStackGetCount . . . . . . . . . . . . . . . ConsStackIndexGetArrayIndex. . . . . . . . . ConsStackIndexGetDictKey . . . . . . . . . . . ConsStackIndexGetObj . . . . . . . . . . . . . ConsStackIndexGetTypeAt . . . . . . . . . . . ConsStackIndexGetTypeCount . . . . . . . . ConsStackIndexIsArray. . . . . . . . . . . . . . ConsStackIndexIsDict . . . . . . . . . . . . . . ConsultantGetNumDirectVisited . . . . . . . ConsultantGetNumIndirectVisited . . . . . . ConsultantGetNumUniqueIndirectsVisited . ConsultantGetPercentDone . . . . . . . . . . ConsultantNextObj . . . . . . . . . . . . . . . .
Chapter 4
Preface
The PDF Consultant and Accessibility Checker is a plug-in that walks through a PDF document, checking for items and/or making modifications. The Consultant achieves this through the use of Agents. You will write Agents to perform your specific actions on PDF documents.
Chapter 1, Overview, provides a general description of the PDF Consultant and Accessibility Checker, and presents development issues to keep in mind. Chapter 2, Using the Consultant, descibes how to use the PDF Consultant and Accessibility Checker, and provides examples. Chapter 3, Consultant API Reference, provides a complete reference for the PDF Consultant and Accessibility Checker methods. Chapter 4, Declarations and Callbacks, provides a complete reference for the data declarations and callbacks used by the PDF Consultant and Accessibility Checker methods.
Prerequisites
This document assumes that you are familiar with:
the Acrobat product and the provided API how to write an Acrobat plug-in PDF format
Preface
Other Useful Documentation
The GetExtensionID method ... The enumeration terminates if proc returns false.
ACCB1 void ACCB2 ExeProc(void) { do something } AFSimple_Calculate(cFunction, cFields)
Preface
Conventions Used in This Book
Font blue
Used for Live links to Web pages Live links to sections within this document
Examples The Acrobat Solutions Network URL is: http://partners/adobe.com/asn See Using the SDK.
Live links to other See the Acrobat Core API Overview. Acrobat SDK documents Live links to code items within this document bold PostScript language and PDF operators, keywords, dictionary key names User interface names italic Document titles that are not live links New terms PostScript variables Test whether an ASAtom exists. The setpagedevice operator
The File menu Acrobat Core API Overview User space specifies coordinates for... filename deletefile
Preface
Conventions Used in This Book
10
Overview
walk a given hierarchy keep track of cycles ensure that objects are only visited once, if desired recognize object types keep a traversal stack list
Acrobat Agents
The Consultant accomplishes its task by using Agents, which are pieces of code you design to gather the statistics and recommend to the Consultant the necessary repairs of the document. Separate Agents handle each area of analysis and repair. The Agents inform the Consultant of the particular types of objects in which they are interested by registering with the Consultant. When the Consultant has one or more Agents registered, it hands each object of the requested type(s) in the current document to each of the Agents that requested that type. The Consultant gives objects to each Agent in turn, depending on the order in which they registered. The Consultant must intelligently determine the type of each object it comes across (both direct and indirect), so it can pass appropriate objects to the Agents, or replace or remove ones that it has been instructed to handle itself. The Consultant communicates directly with Agents, keeping lists of which Agents are interested in which objects, and obtaining instructions from the Agent as to an objects visitation status.
11
Overview
How the Consultant Works
Agents can perform their own repairs and modifications to the PDF document, and can return a corrected object to serve as a replacement for the object the Consultant originally passed to it. Agents can also modify the Cos graph themselves (including adding or removing Cos objects or modifiying the contents such as keys or array elements). The Consultant keeps a list of each object (starting with the object which began the traversal) that it visits on its way to any given object. Agents must be careful not to make any modifications that would affect any of the objects in this list, which is referred to as the traversal stack. For this reason, Agents can specify a post-processing callback that the Consultant calls once it has finished traversing the entire document. See Important Issues For Consultant Development for more detailed information on this point.
Agent Architecture
Your Agent code will primarily consist of a structure, as defined in the ConsExpt.h header file. Acrobat provides a C++ wrapper class to facilitate writing agents; you can derive an agent class from this base class. See Creating Your Agent Class for an example agent from which you can generalize.
12
Overview
How the Consultant Works
Reclassifying Objects
In general, the Consultant reclassifies an object after an Agent is finished performing operations on it. It is possible that, in the process of modifying the object, the Agent may actually have changed the type of the object. This could mean that Agents originally interested in the object might no longer wish to see it. So the Consultant must reclassify an object after each Agent has finished with it. Since the default behavior in "revisit upon reclassification" mode is to revisit objects when they are reclassified, new objects added in this mode will actually be visited again if they are reclassified as the traversal continues. Determining the higher-level type (the PDFObjType, as the Consultant code calls it) of a given Cos object is not always easy. The Consultant not only looks at construction of objects (what keys are present in the object) but also at how the object was reached (through what particular object type and via what keys). Objects that are interpreted differently depending on how they are traversed can be properly identified. For example, if the Consultant is looking at an object containing "/Type /Annot" and "/Subtype /Widget" it is clear that the object is a Widget Annotation; however, when traversed via the AcroForms section, that same object is actually a form field. It is because of such possible dualities that the Consultant can operate in a "revisit upon reclassify" mode that would visit the above object twice: once as a Widget Annotation and again as a form field.
Consultant Itinerary
The Consultant process works like this (See Consultant API Reference for details on how to write the actual code to do these steps.): 1. You create a Consultant. 2. You create an Agent. 3. Register your Agent with the Consultant, with information as to which object types are of interest. 4. The user calls the Consultant to work on a particular PDF document. 5. The Consultant creates a traversal stack to keep track of where it is in walking through the PDF document. 6. The Consultant begins traversing the PDF document. If Agents have instructed the Consultant to modify or remove the object, it does so, returning the appropriate replacement. 7. The Consultant pushes the object onto the traversal stack and sends a message to the Agent that the object was found. 8. The Agent sends messages to the Consultant about what to do to objects: replace them, remove them, revisit them later or not. 9. When the entire PDF document has been traversed, the Consultant calls the Agent back to perform any postprocessing repairs it might want to do.
13
Overview
Important Issues For Consultant Development
10.Consultant unregisters all Agents. 11.Remove the Agent object. 12.Remove the Consultant object.
Agents must not modify objects on the traversal stack while the Consultant is still walking through the document, otherwise infinite loops and other problems can occur. Decide which piece of code is actually going to do the workthe Consultant or the Agentin order to optimize your plug-in. The order in which Agents interact with the Consultant is very important, as Agents can modify objects that other Agents want to see.
14
Overview
Important Issues For Consultant Development
For instance, suppose an Agent wants to remove annotations while there are form widgets present in the document. There are a few ways the Agent can remove the annotions while the Consultant is working, but they all have problems:
Calling the Agent for all annotations and removing them at the Cos level does not clean up the forms tree if there are Widget Annots in the document. Calling the Agent for all Annots and using PDPageAnnotRemove modifies the page object, which might still be in the traversal stack.
The best solution in this case is to enumerate all of the Annot objects by having the Consultant look for Annot objects and keep a list of them, then let the Agent call PDPageAnnotRemove on them in the postprocessing step.
15
Overview
Important Issues For Consultant Development
16
};
17
HFT Functions
The Consultant defines the following functions for HFT usage:
ConsultantCreate ConsultantDestroy ConsultantTraverseFrom ConsultantRegisterAgent ConsultantSetStart ConsultantNextObj ConsultantGetPercentDone ConsultantGetNumDirectVisited ConsultantGetNumIndirectVisited ConsultantSuspend ConsultantResume ConsStackGetCount ConsStackIndexGetObj ConsStackIndexGetTypeCount ConsStackIndexGetTypeAt ConsStackIndexIsDict ConsStackIndexIsArray ConsStackIndexGetDictKey ConsStackIndexGetArrayIndex PDFObjTypeGetSuperclass ConsultantGetNumUniqueIndirectsVisited
18
may want to destroy it after each execution of the menu item that launches it, or you may wish to keep it running. See Example: Registering An Agent With A Consultant for an illustration of creating and destroying a Consultant object.
19
gDumpAllObjectsAgent = new DumpAllObjectsAgent( hPDDoc ); if((gDumpAllObjectsAgent == (DumpAllObjectsAgent*)NULL) || (gDumpAllObjectsAgent->IsValid() == false)) { ASRaise( GenError( genErrNoMemory ) ); } else { ConsultantRegisterAgent(hConsultant, *gDumpAllObjectsAgent, REG_REVISITRECLASS_ALL ); /* Start the Consultant */ ConsultantTraverseFrom(hConsultant, CosDocGetRoot(PDDocGetCosDoc(hPDDoc)),PT_CATALOG); } } } HANDLER ... Destroy Consultant...Free Memory... END_HANDLER if( hConsultant != ( Consultant )NULL ) ConsultantDestroy( hConsultant ); if( gDumpAllObjectsAgent != ( DumpAllObjectsAgent* )NULL ) { delete gDumpAllObjectsAgent; gDumpAllObjectsAgent = ( DumpAllObjectsAgent* )NULL; } AVSysSetCursor( hCurrentCursor );
20
21
22
Agent Constructors
In order to write an Agent class derived from the ConsultantAgentObj baseclass, you must call the base constructor in the derived class construction list. The base constructor requires a constant array of so-called objects of interest (of type PDFObjType) as well as the length of the array (as ASUns32) to be passed as parameters. It is up to you as to where and how the array of types is stored; however the storage must persist, as the base class saves only a pointer to the data. This has important implications for authoring agents; the derived class cannot initialize the data in its own constructor since the base constructor will be called first. The following example shows an example constructor. In the example Agent the array of types and array length are static data members of the Agent class. In larger-scale systems it is better to create a host object for the Agent that will be responsible for determining the proper objects to include in the array and passing them on to the Agent constructor. The list of object types is passed on to the Consultant when ConsultantRegisterAgent is called.
23
The parameters the Consultant passes to this function allow the function to set up a return value with information about the current object, its parents, and the state of the Consultant traversal stack. The return value from the callback is an OR of bit flags that instruct the Consultant as to handling the current object.
See ConsAgentObjFoundCallback for details of the syntax. The Agent in Example: An Agent Constructor simply gathers information about each object encountered and outputs it to a file. It does not need to have the Consultant make any modifications to the document. Therefore, in the definition of the ObjFound callback function, the return value is always OD_NOCHANGE and the object returned in pObjToReturn is simply the same object that was found. In many cases it makes the most sense for an Agent to make all document modifications itself, without the Consultants replace and remove facilities. In these cases you must take special care not to modify objects that are currently on the Consultants traversal stack. The DumpAllObjects plug-in demonstrates that PDFConsultant agents can access any Cos object from any point in the document. The plug-in writes information about certain Cos objects to an output file, called AllObjects.txt. The ObjFound callback function of the DumpAllObjects agent writes to a file the Cos object traversal path that it took to reach a specific Cos object. The function calls GetTraversalString, which describes, with respect to other objects, where a given object lives in the document. For example, the following shows the format of a traversal path of a text annotation:
18 0 obj PT_TEXTANNOTATION | PT_ANNOTATION | ->AcroForm->Fields->[0]-> P->Annots->[1]
24
The traversal path illustrates the "hierarchy" of types that the PDF Consultant and Accessibility Checker assigns to some objects (for example, a PT_TEXTANNOTATION is also listed as PT_ANNOTATION). The Consultant will look at all Cos objects. To simplify the output, the DumpAllObjects agent only involves the most useful Cos objectsCosString, CosDict, CosArray, and CosStream.
25
26
This chapter is a complete reference for the methods specific to the Consultant. The methods are organized alphabetically within logical groupings: Consultant Management Methods Consultant Traversal Stack Methods
ConsultantCreate
Consultant ConsultantCreate (ConsPercentDoneCallback cb);
Description Allocates and intializes a new Consultant object. Use the returned object to call the other Consultant API functions. When you are finished with this object, you must destroy it using the ConsultantDestroy function. Parameters
cb
Return Value
The Consultant object that was created. Exceptions Raises an Acrobat exception on failure. Header File
ConsHFT.h
Related Methods
ConsultantDestroy
27
ConsultantDestroy
void ConsultantDestroy(Consultant hConsultantToDestroy);
Description Detaches all Agents and destroys the given Consultant object, invalidating its handle. You must never call this on a Consultant that is currently running. Parameters
hConsultantToDestroy
A valid Consultant object handle as returned by ConsultantCreate. Handle is invalid after the call returns.
Return Value None. Exceptions Raises an Acrobat exception on failure. Header File
ConsHFT.h
Related Method
ConsultantCreate
28
ConsultantRegisterAgent
void ConsultantRegisterAgent (Consultant s, const ConsultantAgent *tagConsultantAgent, RegAgentFlag kFlag);
Description Registers the given agent with the given consultant, so that the agent is called when the consultant encounters objects of interest. Parameters
A valid Consultant object handle as returned by ConsultantCreate. The Consultant with which the Agent will be registered. The Agent to register, of a type derived from the ConsultantAgentObj base class. Flag indicating the mode that the Consultant should operate in.
tagConsultantAgent kFlag
Return Value None. Exceptions Raises an Acrobat exception if the Consultant has been started and is not in a suspended state. Header File
ConsHFT.h
Related Method None.
29
ConsultantResume
void ConsultantResume(Consultant s);
Description Resumes a previously suspended Consultant at the point in the traversal where it stopped. This function does not return from traversing and notifying Agents until the traversal is complete or ConsultantSuspend is called. The function does nothing if the Consultant object is already running or has not been started. Parameters
s
Return Value None. Header File
ConsultantSuspend ConsultantSetStart
30
ConsultantSetStart
void ConsultantSetStart (Consultant s, CosObj objstart, PDFObjType InitType);
Description Resets the suspended Consultant and starts a new traversal from the given starting object. If you do not know the type of the object, the Consultant will attempt to determine it. This function does not return until the entire path beneath the starting object has been traversed. The Consultant passes to the registered Agents all objects it encounters that have been registered as interesting. Parameters
A valid Consultant object handle as returned by ConsultantCreate. The Consultant with which the Agent will be registered. document, this is the Catalog.
objstart Object at which to restart traversal. Usually, for traversing an entire InitType The object type of the specified start object. May be PT_NULL, in which
case the Consultant attempts to determine the type of the object itself. You should specify a value other than PT_NULL whenever possible In most cases, for traversing the entire document, the starting object is the Catalog so the type is PT_CATALOG. Return Value None. Exceptions Raises an Acrobat exception if the Consultant has been started and is not in a suspended state. Header File
ConsHFT.h
Related Method
31
ConsultantSuspend
void ConsultantSuspend(Consultant s);
Description Suspends the Consultant, even if it is currently executing a call to ConsultantCreate or ConsultantResume. This function causes currently executing calls to ConsultantTraverseFrom to return. It is legal to call this function from within the ScrubPercentDoneCallback passed to the Consultant on ConsultantCreate. Calls to ConsultantTraverseFrom that are currently in progress will return when ConsultantSuspend is called. To resume, call ConsultantResume. You can call ConsultantNextObj on a suspended Consultant, which removes the suspension and causes the Consultant to process the next object.
You can destroy a Consultant that has been suspended. If you call ConsultantTraverseFrom on a suspended Consultant it will reset the operation of the Consultant, but the Consultant will remain in a suspended state and will not process the document further.
This function does nothing if you call it on a Consultant object that is already suspended, or was never started. Parameters
s
Return Value None. Header File
ConsultantResume ConsultantSetStart
32
ConsultantTraverseFrom
void ConsultantTraverseFrom(Consultant s, CosObj obj, PDFObjType ObjType;
Description Starts the given Consultant object traversing at the given Cos object. It traverses and processes all objects beneath obj, classifying the type of objects based on the fact that obj is of the given ObjType. It is never legal to destroy a Consultant object that is currently executing a call to
ConsultantTraverseFrom. To properly destroy a running Consultant, you must call ConsultantSuspend first. ConsultantTraverseFrom raises an exception under any other conditions, and may also raise an exception as the result of a registered Agents
raising an exception during the operation. Parameters
s obj ObjType
A valid Consultant object handle as returned by ConsultantCreate. The Consultant with which the Agent will be registered. Object at which to start traversal. The object type of the specified start object. May be PT_NULL, in which case the Consultant attempts to determine the type of the object itself. You should specify a value other than PT_NULL whenever possible.
Return Value None. Exceptions Raises an Acrobat exception if the Consultant has been started and is not in a suspended state. Header File
ConsHFT.h
Related Method None.
33
PDFObjTypeGetSuperclass
PDFObjType PDFObjTypeGetSuperclass (PDFObjType Type);
Description Gets the superclass, if any, of the given PDFObjType. Parameters
Type
Return Value
The superclass of the given type or DT_NULL if no superclass exists. Header File
ConsHFT.h
34
Con s ul ta nt Trave r s a l St a c k M et ho ds
The Consultant uses a traversal stack to maintain knowledge of which objects it has visited. These methods allow you to manipulate the traversal stack and track the consultants progress through the traversal.
ConsStackGetCount
ASUns32 ConsStackGetCount(ConsStack s);
Description Returns the number of objects currently on Consultants traversal stack. The stack includes the objects that the Consultant has visited on its path to the current object, or, in other words, all parents of the current object, but not the object itself. Parameters
s
Return Value
The number of objects on the Consultant.s traversal stack. Exceptions Raises an Acrobat exception on error.
***** An error like not a valid stack argument? What other errors might occur?
Header File
ConsHFT.h
Related Method
ConsultantGetNumDirectVisited
35
ConsStackIndexGetArrayIndex
ASUns32 ConsStackIndexGetArrayIndex(ConsStack s, ASUns32 Index)
Description Get the array index of the object at the given index into the stack (that is, the index that led from the given object to the next object in the traversal). It is only valid to call this function on an index if ConsStackIndexIsArray returns true for that index. Parameters
s Index
Return Value
The Consultants traversal stack. Index in the stack where the object in question is located.
The array index that led from the object at the given index in the stack to the next object in the Consultants traversal path. Header File
ConsHFT.h
Related Method
ConsStackIndexIsArray
36
ConsStackIndexGetDictKey
ASAtom ConsStackIndexGetDictKey(ConsStack s, ASUns32 Index);
Description Gets the key string atom of the object at the given index into the stack (that is, the key that led from the given object to the next object in the traversal). It is only valid to call this function on an index if ConsStackIndexIsDict returns true for that index. Parameters
s Index
Return Value
The Consultants traversal stack. Index in the stack where the object in question is located.
The key that led from the object at the given index in the stack to the next object in the Consultants traversal path. Exceptions Raises an Acrobat exception on error. Header File
ConsHFT.h
Related Method
ConsStackIndexIsDict
37
ConsStackIndexGetObj
CosObj ConsStackIndexGetObj(ConsStack s, ASUns32 Index);
Description Gets the the Cos object at the given index into the stack. Parameters
s Index
Return Value
The object at the specified point in the Consultants traversal stack. Header File
ConsHFT.h
Related Method
ConsStackIndexGetTypeAt
38
ConsStackIndexGetTypeAt
PDFObjType ConsStackIndexGetTypeAt(ConsStack s, ASUns32 Index, ASUns32 TypeIndex);
Description Gets a type from the type array at each index in the stack. Since there are potentially multiple types for each object, you can access the type classifications one at a time. Parameters
s Index TypeIndex
The Consultants traversal stack. The position in the stack of the object in question. The type classification of the object. 0 is the most specific type classification. The higher the number, the more general the type classification.
Return Value One type of an object at a particular location in the traversal stack. Header File
ConsHFT.h
Related Method
ConsStackIndexGetObj ConsStackIndexGetTypeCount
39
ConsStackIndexGetTypeCount
ASUns32 ConsStackIndexGetTypeCount (ConsStack s, ASUns32 Index);
Description Gets the size of the type hierarchy at the given index into the stack. Parameters
s Index
Return Value
ConsHFT.h
Related Method
ConsStackIndexGetObj ConsStackIndexGetTypeAt
40
ConsStackIndexIsArray
ASBool ConsStackIndexisArray(ConsStack s, ASUns32 Index);
Description Tests whether the given index into the stack is a CosArray. Parameters
s Index
Return Value
The Consultants traversal stack. Index in the stack where the object in question is located.
true if the object found at the index point is an array, false otherwise.
Header File
ConsHFT.h
Related Method
ConsStackIndexGetArrayIndex
41
ConsStackIndexIsDict
ASBool ConsStackIndexisDict(ConsStack s, ASUns32 Index);
Description Tests whether the object at the given index into the stack is a CosDict object. Parameters
s Index
Return Value
The Consultants traversal stack. Index in the stack where the object in question is located.
true if the object found at the index point is a dictionary, false otherwise.
Header File
ConsHFT.h
Related Method
ConsStackIndexGetDictKey
42
ConsultantGetNumDirectVisited
ASUns32 ConsultantGetNumDirectVisited(Consultant s);
Description Returns the number of direct objects that the Consultant has processed so far. This count may include some objects twice, depending on revisitation of objects.This count is reset on calls to ConsultantTraverseFrom and ConsultantSetStart. Parameters
s
Return Value
The number of direct objects the Consultant has visited so far. Header File
ConsHFT.h
Related Method
43
ConsultantGetNumIndirectVisited
ASUns32 ConsultantGetNumIndirectVisited(Consultant s);
Description Returns the number of indirect objects that the Consultant has processed so far. This count may include some objects twice, depending on revisitation of objects.This count is reset on calls to ConsultantTraverseFrom and ConsultantSetStart. Parameters
s
Return Value
The number of indirect objects the Consultant has visited so far. Header File
ConsHFT.h
Related Method
ConsultantGetNumDirectVisited
ConsultantGetNumUniqueIndirectsVisited
44
ConsultantGetNumUniqueIndirectsVisited
ASUns32 ConsultantGetNumUniqueIndirectsVisited(Consultant s);
Description Returns the number of unique indirect objects that the Consultant has processed so far. This count is reset on calls to ConsultantTraverseFrom and ConsultantSetStart. Visited objects are not counted more than once; if an object is revisited, the count is not incremented. Parameters
s
Return Value
The number of unique indirect objects the Consultant has visited so far. Header File
ConsHFT.h
Related Method
ConsultantGetNumDirectVisited ConsultantGetNumIndirectVisited
45
ConsultantGetPercentDone
ASReal ConsultantGetPercentDone(Consultant s);
Description Returns an estimate (from 0 - 100) of what percentage of the current document has been processed by the Consultant. You can call this function at any time. Parameters
s
Return Value
ConsHFT.h
Related Method None.
46
ConsultantNextObj
ASBool ConsultantNextObj(Consultant s);
Description Instructs the Consultant to process the next object in the current traversal. Assumes that the Consultant has been suspended and reset with calls to ConsultantSuspend and ConsultantSetStart. This function does not unsuspend a Consultant, so you can call it repeatedly. It returns after all registered Agents have processed the object. Parameters
s
Return Value
true if the process is done or there has been a problem, false otherwise.
Exceptions Raises an Acrobat exception if you call it on a running Consultant. Header File
ConsHFT.h
Related Method
ConsultantSuspend ConsultantSetStart
47
48
This chapter provides a reference for the data declarations and callback functions used by the Consultant methods and to construct Agents. Data Declarations Callbacks
ConsAgentObjFoundCallback
49
Consultant
typedef struct tagConsultant* Consultant;
Description The opaque type to allow programs to retain handles to created PDF Consultant and Accessibility Checker objects. Related Methods numerous
50
ConsultantAgent tagConsultantAgent
typedef struct tagConsultantAgent { ASSize_t Size; const PDFObjType* pFindObjects; ASUns32 NumFindObjects;
Description During traversal, the Consultant checks the Agents list of object types of interest to see if the Agent is interested in the current object, and it calls the callback function pointers when objects of interest are found and when traversal is complete. All Agents should be C++ classes derived from the ConsultantAgentObj class (found in agentobj.h) which can be converted (via a C++ cast operator) to a pointer to this structure type. Wherever the Consultant HFT calls for a (struct Agent*), you can pass the class with no conversion. Members
Size of the data structure. Set to sizeof(Agent). An array of object types of interest. The number of object types in the pFindObjects array. A callback procedure for post-processing. A callback procedure for when an object is found.
Related Methods
ConsultantRegisterAgent
Related Callbacks
ConsAgentObjFoundCallback
51
ConsultantAgentAction
Description Bit flags that instruct the Consultant about how to handle a found object. A logical OR of these values should be returned by the ObjFound callback. Values Flag Description The Consultant makes no changes to the current object. Use this if the Agent is only gathering information of if the Agent is in charge ofmaking all the modifications itself. Instructs the Consultant to replace this occurence of the current object in the document with the one retured via the pObjToReturn parameter to the ObjFound callback. You can optionally combine this with OD_REVISIT or OD_CHANGEALL. Instructs the Consultant to remove this occurence of the current object in the document. You can optionally combine this with OD_REVISIT or OD_CHANGEALL. Instructs the Consultant to visit this object again if it is encountered again. You can combine this with any flag except OD_NEVERREVISIT or OD_CHANGEALL. You must use this in conjunction with either OD_REPLACE or OD_REMOVE. It instructs the Consultant to silently perform the desired operation on all instances of the current object, without calling the ObjFound callback again for this object. Instruct the Consultant that under no circumstances should the object be revisited, regardless of whether it is reclassified when encountered again. Only applicable in the mode in which the Consultant pays attention to object classification when determining whether or not an obect has been visited already.
OD_NOCHANGE
OD_REPLACE
OD_REMOVE
OD_REVISIT
OD_CHANGEALL
OD_NEVERREVISIT
Related Callbacks
ConsAgentObjFoundCallback
52
PDFObjType
typedef ASUns32 PDFObjType;
Description Type corresponding to the enum defined in ConsObTp.h. This type is used to refer to specific object types in the Adobe PDF Document format. Specifically used by Agents to make object requests of the framework, and used by the framework to report the types of objects found. Related Methods
PDFObjTypeGetSuperclass
Related Callbacks
ConsAgentObjFoundCallback
53
RegAgentFlag
Description Constants that specify an operation mode for the Consultant. This value determines whether and how often the Consultant should revisit objects that have been previously encountered. Values Mode Flag Description Revisit objects of an unknown type always, unless an Agent returns AC_NEVERREVISIT for the object. Visit known types only once, unless an Agent returns AC_REVISIT for the object. Visit all objects once unless an Agent returns AC_REVISIT for the object. Revisit objects of an unknown type when encountered again as a known type that the object has not previously been encountered as, unless an Agent returns AC_NEVERREVISIT for the object. Revisit known types when encountered again as a new known type or as unknown, unless an Agent returns AC_NEVERREVISIT for the object. If an agent returns OD_REVISIT, revisit the object (of any known or unknown classification) the next time its encountered. Revisit an object whenever it is encountered again with a new classification; but always revisit objects classified as unknown (even if the object has previously been encountered and classified as unknown)
REG_ONLYREVISITUNKNOWN
REG_REVISITNONE REG_REVISITRECLASS_ALL
REG_REVISITRECLASS_ALWAYSUNKNOWN
Related Methods
ConsultantRegisterAgent
54
Ca l l ba c k s ConsAgentObjFoundCallback
ConsultantAgentAction ConsAgentObjFoundCallback (struct tagConsultantAgent* agent, CosObj hObj, const PDFObjType* objTypeHierarchy, ASUns32 iSizeObjHierarchy ConsStack Stack, CosObj* pObjToReturn);
Description Returns a set of flags instructing the Consultant as to how to handle the current object. The Consultant calls this method when it recognizes the current object as a type which an Agent has declared interesting. Parameters
agent hObj
The agent containing the callback. The object the Consultant has just encountered, which has matched on of the types in any of the registered Agents array of interesting types. A list of the object type classifications this object met. the array runs from index 0, most specific object classification, to index iSizeObjHierarchy, the most general. The size of the type array. A reference to the Consultants traversal stack, which allows read-only access to parents of the current object as well as their respective types. If present, an object the Consultant uses to replace the current object in the document.
pObjTypeHierarchy
iSizeObjHierarchy Stack
pObjToReturn
Return Value
A logical OR of bit flags that instruct the Consultant how to handle the current object (remove it, replace it, ignore it, and so on.) Header File
ConsExpT.h
Related Method None.
55
ConsAgentPostProcessCallback
void ConsAgentPostProcess (void)
Description The Consultant calls this method when it is ready to finish a cycle. You should perform any document modifications assigned to your Agent at this point. Parameters None. Return Value None. Header File
ConsExpT.h
56
ConsPercentDoneCallback
void ConsAgentPercentDoneCallback (ASReal fPercentDone);
Description The Consultant calls this method with progress updates. It can display a progress bar. Parameters
fPercentDone
A number between 0 and 100, indicating the percent of the current document that the Consultant has processed so far.
ConsExpT.h
57
58