The Pajdeg pipe. More...

Files
file	PDPipe.h

Data Structures
struct	PDPipe

Typedefs
typedef struct PDPipe *	PDPipeRef

Functions
PDPipeRef	PDPipeCreateWithFilePaths (const char inputFilePath, const char outputFilePath)

void	PDPipeAddTask (PDPipeRef pipe, PDTaskRef task)

PDBool	PDPipePrepare (PDPipeRef pipe)

PDParserRef	PDPipeGetParser (PDPipeRef pipe)

PDObjectRef	PDPipeGetRootObject (PDPipeRef pipe)

PDInteger	PDPipeExecute (PDPipeRef pipe)

const char *	PDPipeGetInputFilePath (PDPipeRef pipe)

const char *	PDPipeGetOutputFilePath (PDPipeRef pipe)

PDParserAttachmentRef	PDPipeConnectForeignParser (PDPipeRef pipe, PDParserRef foreignParser)

Detailed Description

The Pajdeg pipe.

Pipes provide functionality to define input and output files, add tasks, and start the streaming process.

Pipes contain a PDParser instance, accessible through the PDPipeGetParser() function, and any number of PDTask instances. It also maintains a PDTwinStream instance, along with file pointers for the input and output files.

The life cycle of a pipe that does not encounter any errors is made up of these 6 steps:

define in/out files (on creation)
add tasks/filters
prepare pipe
add tasks/filters
execute
destroy

It is perfectly acceptable to add tasks from within a task, i.e. in the middle of an execution call, although be warned that the mutability of objects is subject to their location within the PDF file. The following sequence is fine:

...
Object #1 > initial task object > creation of task for Object #2
...
Object #2 > task for Object #2
...

whereas this sequence will trigger an assertion:

...
Object #2
...
Object #1 > initial task object > creation of task for Object #2

To resolve this, there are a number of options:

Object #1 can be fetched directly, rather than have a filtered task attacked to it, before the execute call. Object #2's identity can then be resolved without waiting for Object #1 in the stream, and a task can be made for Object #2 directly.
If the Object #2 task is optional, it can be wrapped in a conditional based on PDParserIsObjectStillMutable().

Prepared pipes

A pipe that has opened the in- and output file handlers, configured a stream, and configured a parser, is considered "prepared". Pipes are not prepared by default, but many operations indirectly result in PDPipePrepare being called.

Data Structure Documentation

struct PDPipe

Internal structure.

Data Fields
PDBool	opened
	Whether pipe has been opened or not.

PDBool	dynamicFiltering
	Whether dynamic filtering is necessary; if set, the static hash filtering of filters is skipped and filters are checked for all objects.

PDBool	typedTasks
	Whether type tasks (excluding unfiltered tasks) are activated; activation results in a slight decrease in performance due to all dictionary objects needing to be resolved in order to check their Type dictionary key.

char *	pi
	The path of the input file.

char *	po
	The path of the output file.

FILE *	fi
	Reader.

FILE *	fo
	Writer.

PDInteger	filterCount
	Number of filters in the pipe.

PDTwinStreamRef	stream
	The pipe stream.

PDParserRef	parser
	The parser.

PDSplayTreeRef	filter
	The filters, in a tree with the object ID as key.

pd_stack	typeTasks [_PDFTypeCount]
	Tasks which run depending on all objects of the given type; the 0'th element (type NULL) is triggered for all objects, and not just objects without a /Type dictionary key.

PDSplayTreeRef	attachments
	PDParserAttachment entries.

Typedef Documentation

typedef struct PDPipe* PDPipeRef

A pipe.

Function Documentation

void PDPipeAddTask	(	PDPipeRef	pipe,
		PDTaskRef	task
	)

Attach a task to a pipe.

The task is attached to the end. This was not the case up until Pajdeg 0.0.7.

Parameters

pipe	The pipe. If the pipe is not prepared, and the task is a filter on the root or info object, this will trigger PDPipePrepare().
task	The task to add.

Note: In the current implementation, non-filter tasks which are added directly to the pipe will be triggered once when PDPipePrepare() is called, not once per object iteration.

PDParserAttachmentRef PDPipeConnectForeignParser	(	PDPipeRef	pipe,
		PDParserRef	foreignParser
	)

Connect a foreign parser into pipe, making it possible to import objects from the foreign parser throughout the pipe's existence.

This sets up a permanent parser attachment to the foreign parser. Some operations, such as PDPageInsertIntoPipe, will do this automatically.

Multiple calls to connecting the same pipe/parser pair are ignored.

Parameters

pipe	The native pipe into which importing of objects will be possible
foreignParser	The foreign parser from which imports should be possible

Returns: Parser attachment associated with the connection

PDPipeRef PDPipeCreateWithFilePaths	(	const char *	inputFilePath,
		const char *	outputFilePath
	)

Create a pipe with an input PDF file and an output PDF file.

Parameters

inputFilePath	The input PDF file (must be readable and exist).
outputFilePath	The output PDF file (must be readwritable). If the file exists, it is overwritten. The file may not be the same as inputFilePath. On most operating systems, "/dev/null" can be passed to provide a readonly session (not MS Windows), but this must be explicitly passed, and NULL will result in failure.

Returns: The PDPipeRef instance, or NULL if the pipe cannot be set up.

PDInteger PDPipeExecute ( PDPipeRef pipe )

Perform the pipe operation, reading input file, performing all defined tasks, and writing the results to the output file.

Parameters

pipe	The pipe. If the pipe is not prepared, PDPipePrepare() will be called.

Returns: Returns # of objects seen on success, -1 on failure.

Note: After executing a pipe, it can in theory be reused, but this is currently experimental. Recreating a pipe is recommended for multi-pass operations.

check filtered tasks;

Todo:: : CLANG: does not recognize that dynamicFiltering is always true if sht is nil.

const char* PDPipeGetInputFilePath ( PDPipeRef pipe )

Get pipe input file path.

Parameters

pipe The pipe.

Returns: The input file path, as provided when the pipe was created.

const char* PDPipeGetOutputFilePath ( PDPipeRef pipe )

Get pipe output file path.

Parameters

pipe The pipe.

Returns: The output file path, as provided when the pipe was created.

PDParserRef PDPipeGetParser ( PDPipeRef pipe )

Get parser instance for pipe.

Parameters

pipe	The pipe. If the pipe is not prepared, PDPipePrepare() will be called.

Returns: The parser associated with the pipe.

PDObjectRef PDPipeGetRootObject ( PDPipeRef pipe )

Get the root object.

Parameters

pipe	The pipe. If the pipe is not prepared, PDPipePrepare() will be called.

Returns: The PDObjectRef instance of the root object.

Warning: The returned object is silently immutable. To perform mutations on the root object, add an object mutator to the pipe using the ID of the root object.

PDBool PDPipePrepare ( PDPipeRef pipe )

Prepares the pipe for execution, by setting up the streams and parser.

The parser will at this point open the input stream and fetch the XREF table and trailer data, which includes key refererences such as Info and Root. After this and before Execute, definitions for objects may be obtained as stack refs via the parser object's PDParserLocateAndCreateDefinitionForObject.

Parameters

pipe	The pipe to prepare. If the pipe is already prepared, this does nothing.

Returns: true if the pipe was prepared already, or if preparations were successful; false if an error occurred.

Files

Data Structures

Typedefs

Functions

Detailed Description

Prepared pipes

Data Structure Documentation

Data Fields

Typedef Documentation

Function Documentation