Acrobat comes with a plug-in called the PDF Consultant and Accessibility Checker. This plug-in walks through PDF documents, visiting each object and determining its type and other statistics. It can make certain modifications or repairs to the PDF document. The objects that the Consultant visits can range from simple, primitive types such as CosString objects to higher-level objects such as Images. Users call the Consultant to run on a particular PDF document, choose which tests or repairs to run, then view the results and/or select repair options.

The Consultant visits the objects in a PDF document according to instructional flags you pass to it. After the Consultant has visited an object, the object may be different. The Consultant reclassifies modified objects before moving on to the next object.

As the Consultant traverses a PDF document, gathering objects of interest, it can perform the following functions:

• 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 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 object's visitation status.

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 Developing Plug-ins and Applications for more detailed information on this point.

If an Agent or the Consultant itself modifies an object, the Consultant reclassifies that object, possibly changing its type.

Agents also pass to the Consultant the visitation flags that determine how object types should be visited. Limiting the traversal is important, as PDF documents are graphs, arbitrarily complex, and there are often many ways to visit a single object. If the Consultant has reclassified an object, it may also change the way that object is revisited. You must keep this in mind as you develop your Agents.

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 Developing Plug-ins and Applications for an example agent from which you can generalize.

How the Consultant Works

The Consultant completes a full, non-recursive traversal of the Cos graph that comprises a PDF document, keeping track of cycles as it goes. Note that there is no guarantee that objects will be visited in any particular order, only that the Consultant will visit all objects (except isolated objects such as the DocInfo object or previously orphaned objects) at least once, provided no Agents modify the graph such that graph paths are removed or redirected.

Removing or modifying objects

If an Agent removes, replaces or modifies an object, the Consultant will pass to other Agents the modified objects (if they are encountered). For example, Dict A refers to Dict B. The first Agent replaces all references to Dict B with references to Dict C,so when later agents receive Dict A from the Consultant, they will see the references to Dict C.

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 object type identification

One of the main features the PDF Consultant and Accessibility Checker framework gives you is the use of its identification engine. This engine can look at Cos objects in a PDF file and, based on properties of the objects and of the objects' parents, assign PDF object type identifiers to them. Though on a very basic level each Cos object has a simple Cos type and attributes, in the scheme of the document as a whole, each object serves a particular purpose. The PDF Object Type assigned to each object represents that object's role in the PDF document. Some PDF object types represent higher-level, conceptually-familiar objects like PT_PAGE (which indicates that the object is a page in the document), while others (like PT_AADICTIONARY) are a bit more obscure, particularly to those who are not familiar with the PDF structure. PDF object types are represented using the enumerated type PDFObjType, which is defined in ConsObTp.h. A good way to see all of the various PDF object types that the Consultant can identify is to look at the constants defined in that file.

Some object types (in particular many simpler objects such as strings and numbers) are not assigned a particular type. In general the Consultant can identify those objects that are of most use to you. If the Consultant cannot identify a particular object, for one reason or another, it assigns the identity of PT_UNKNOWN to the object. Just because the Consultant assigns this value to an object, does not mean the object is foreign or malformed (although it can potentially mean that); it may simply mean that the object type is not particularly significant in the realm of PDF, and thus the Consultant does not know about it.

Object type subclassing

To allow for greater Agent flexibility, the Consultant understands PDF object type subclasses and superclasses. Certain PDF object types are members of more generic classes of PDF object type. Agents can often make use of this information, so the Consultant assigns object types that are actually arrays of types.

The Consultant assigns to an object the most specific classification as well as the more generic classes of which the object is a member. Agent structures include a field called WantSubclasses that indicates whether or not the Agent wants be called for all the interesting object's subclasses as well as their directly interesting types.

For example, the PDF object type PT_ANNOTATION has a number of more specific subclasses such as PT_LINKANNOTATION, PT_LINEANNOTATION, and so on. If an Agent requests only objects of type PT_ANNOTATION, and its WantSubclasses member is false, it may not be called back for very many objects. If the WantSubclasses member is true, then the Consultant will call the Agent back for objects of all specific types of annotations as well as those classified only as PT_ANNOTATION. This also means that when an Agent retrieves the type of an object, it must specify which type it wants. The types in the array that is the classification of the object always go from the most specific (at index 0) to the least specific (the last index in the array).