Adobe® PDF Library

Additional APIs from Datalogics

This appendix defines Adobe PDF Library methods that were created by Datalogics to supplement the functions provided by Adobe, Inc.

ACGetOption Header: DLExtrasCalls.h

Description

The ACGetOption function call returns the current value for the option specified by the supplied AC_OptionCode. This call controls the behavior of colorspace conversions and manipulations carried out via AC-layer calls; it does not impact other Adobe PDF Library color behaviors.

Syntax

AC_Error ACGetOption(AC_OptionCode code, ASUns32 *value)

Parameters

AC_OptionCode code AC_Option_BlackPointCompensation indicates whether the Acrobat Color Engine will carry out black point compensation when converting between colorspaces with different black points.
ASUns32 *value AC_Option_BlackPointCompensation flag value to be retrieved (Filled by the method)

Exceptions

  None

Returns

  AC_Error

Related Methods

  ACSetOption

ACSetOption Header:  DLExtrasCalls.h

Description

The ACSetOption function call sets the current value for the option specified by the supplied AC_OptionCode.

This call controls the behavior of colorspace conversions and manipulations carried out via AC-layer calls; it does not impact other Adobe PDF Library color behaviors.

Syntax

AC_Error ACSetOption(AC_OptionCode code, ASUns32 value)

Parameters

AC_OptionCode code AC_Option_BlackPointCompensation indicates whether the Acrobat Color Engine will carry out black point compensation when converting between colorspaces with different black points.
ASUns32 value AC_Option_BlackPointCompensation flag value to be set

Exceptions

  None

Returns

  AC_Error

Related Methods

   ACGetOption

ASSetDefaultFileSys Header: DLExtrasCalls.h

Description

This call accepts a declaration for an alternate file system to be used by the Adobe PDF Library. If called, all Library file operations (such as open, read, write) will be directed through the set of callback functions that define the ASFileSys. This is typically used to enable reading and writing PDF documents to and from memory buffers.

Syntax

void ASSetDefaultFileSys(ASFileSys fileSys)

Parameters

ASFileSys fileSys Alternate file system to be used

Exceptions

  None

Returns

  None

Related Methods

  None

CosStreamSetData Header: DLExtrasProcs.h

Description

The interface is essentially identical to the Adobe PDF Library method CosNewStream, except that the result is a modification of an existing stream.

Syntax

void CosStreamSetData(CosObj stream, ASStm sourceP, ASInt32 sourceStart, ASBool encodeTheSourceData, CosObj attributes, CosObj encodeParms, ASInt32 sourceLength)

Parameters

CosObj stream Stream to be modified
ASStm sourceP Source stream to be added
ASInt32 sourceStart The byte offset to the starting point of the stream to be added
ASBool encode TheSourceData Flag indicating whether the source data is to encoded via filters specified in the attributes
CosObj attributes Dictionary containing string data attributes, including its length and encoding parameters
CosObj encodeParms Parameters to be used for encoding (if any)
ASInt32 sourceLength Length of data to be read from the source, or -1 to read to EOF

Exceptions

  None

Returns

  None

Related Methods

  CosStreamNew

DLEnableLicensedBehavior Header: DLExtrasCalls.h

Description

This call accepts a key supplied to Adobe PDF Library customers who sign a separate license agreement with Datalogics. This license agreement covers (and the accepted key enables) Copy permission override capability, bypassing the document’s "No Content Copying or Extraction" setting, and enabling the application to rasterize PDF pages where content copying or extraction is normally not allowed. See the Technical Notes below, and Bypassing the No-Copy Restriction below.

Syntax

ASBool DLEnableLicensedBehavior(const char * keyVal, const char * additionalInfo)

Parameters

const char * keyVal Key for unlocking functionality, supplied to you by Datalogics at delivery time when this call is licensed.
const char * additionalInfo Reserved for future use; use NULL here.

Exceptions

  None

Returns

  None

Related Methods

  None

Technical Notes

DLEnableLicensedBehavior is intended for use in creating PDF page viewing applications where rendering is required; it is not intended as a bypass for actual extraction of the content.

JPXColorSpaceGetApprox Header: DLExtrasProcs.h

Description

JPX is compression format used with JPEG 2000 image files, considered an improvement over the standard JPEG format.

Syntax

ASInt32 JPXColorSpaceGetApprox(JPXColorSpace jpxColorSpace);

Parameters

jpxColorSpace A JPX color space object (IN/OUT).

Exceptions

  None

Returns

  None

Related Methods

  PDEImageJPXAcquireJPXColorSpace

PDDocAddJobID Header: PDProcs.h

Description

This assists Adobe PDF Library users in deleting temporary font files prior to Library termination if needed. (A deletion call for temporary font files is always made at Library termination time.) This adds a Print Job Identifier, or JobID, from the print job to the PDDoc’s list of associated JobIDs.

There are two points in time when Adobe PDF Library is free to delete temporary font files if desired: just after PDDoc destruction, and at PDFLTerm when the library terminates. Prior to this release, font files were deleted only at termination time, but this method provides a means of deleting them as soon as the associated PDDoc is destroyed, to avoid long-term buildup in long-running applications. See Technical Notes below.

Syntax

void PDDocAddJobID(PDDoc doc, ASUns32 jobId)

Parameters

PDDoc doc The document whose Job ID is being set
ASUns32 jobId The Print Job ID being added to the document's list of Job IDs

Exceptions

  None

Returns

  None

Related Methods

  None

Technical Notes

1 This function is for use when calling PDPageDrawContentsToWindow or PDPageDrawContentsToWindowEx to draw to a printer device context via a StartDoc call, such as can be seen in the PrintDCWin sample (available for download from the Knowledgebase on the Datalogics website).
Using this method, the print routine deletes the associated temporary font files as soon as the specified job has completed spooling to the print queue and the associated PDDoc is destroyed, rather than simply waiting to clean up everything at Library termination time. You can add as many JobIDs to the PDDoc as desired, calling PDDocAddJobID each time, and giving it the appropriate pdDoc and JobID values.
2 Modify the StartDoc call as follows:

int jobId =0;
if ((jobId = StartDoc(printDialog.hDC, &docInfo)) > 0)
{
PDDocAddJobID(pdDoc, jobId); [etc.]
}

If PDDocAddJobID is not used to create an associated JobID list for the PDDoc, then the temporary font files will be held until Library termination before being deleted, as before. If PDDocAddJobID is used and a JobID list is present, then the temporary font files associated with the appropriate Process ID and Thread ID will be flagged for deletion when the PDDoc is destroyed. They will be actually removed as soon as the spooling process is complete.

3 The statusMon value should be a pointer to a record containing a Progress Monitor, Cancel Procedure, and Report Procedure:
Progress Monitor Procedures in the progress monitor are called to indicate the progress of the routine.
Cancel Procedure The cancel procedure is called periodically to allow the client to cancel the routine. If the cancel procedure returns false then the routine is canceled.
Report Procedure This will be called to report errors or warnings while embedding the fonts.Each font that cannot be embedded will result in a call to the report procedure.

 

PDDocEmbedFonts Header: DLExtrasCalls.h

Description

The PDDocEmbedFonts API allows PDF document creators who have created fonts to embed and/or subset their created PDE fonts without needing to call PDEFontEmbedNow or PDE- FontSubsetNow prior to their document save.

Syntax

void PDDocEmbedFonts(PDDoc doc, ASUns32 flags, ASStatusMonitorProcs statusMon)

Parameters

PDDoc doc The PDdoc on which to operate
ASUns32 flags Embedding flags
ASStatusMonitorProcs statusMon Pointer to a record containing a Progress Monitor, Cancel Procedure, and Report Procedure. See Technical Notes below.

Exceptions

  None

Returns

  None

Related Methods

PDDocEmbedFontsFromFontArray

Technical Notes

1 The doc value indicates the PDdoc on which to operate. The fonts will be embedded in this document. To keep the changes, the document must be saved. Fonts on the user's system that match the original font definition will be embedded. For the Times-Roman and Helvetica and corresponding styles, if displayed with a font alias, then the font alias will be embedded in the file.
NOTE: If the font has information indicating that it cannot be embedded for print and preview, then the font will not be embedded in the document.
2 The flags value should be one of the following:
kDocEmbedSubset
If set, fonts will be subset when embedded. Otherwise the entire font will be embedded. A full font should only be embedded if the information in the font indicates that it can be used for editable embedding. Fonts that have more than 2048 characters will be subset-embedded regardless of the setting of this flag.
kDocEmbedSubsetOfEmbeddedFont
If set, fonts that have already been embedded, but are not subset fonts, will be re-embedded in subset form.
3 The statusMon value should be a pointer to a record containing a Progress Monitor, Cancel Procedure, and Report Procedure:
Progress Monitor Procedures in the progress monitor are called to indicate the progress of the routine.
Cancel Procedure The cancel procedure is called periodically to allow the client to cancel the routine. If the cancel procedure returns false then the routine is canceled.
Report Procedure This will be called to report errors or warnings while embedding the fonts.Each font that cannot be embedded will result in a call to the report procedure.

 

PDDocEmbedFontsFromFontArray Header: DLExtrasCalls.h

Description

As with the PDDocEmbedFonts API, this call allows PDF document creators who have created fonts to embed and/or subset their created PDE fonts without needing to call PDEFontEmbedNow or PDEFontSubsetNow prior to their document save.

This will embed only those fonts listed in an array. The parameters to this routine are the same as described for PDDocEmbedFonts, but also including the additional fonts and nFonts parameters described below.

Syntax

void PDDocEmbedFontsFromFontArray(PDDoc doc, const PDFont* fonts, ASUns32 nFonts, ASUns32 flags, ASStatusMonitorProcs  statusMon)

Parameters

PDDoc doc The PDdoc on which to operate
const PDFont* fonts An array of PDFont elements, containing fonts to be embedded.
ASUns32 nFonts The number of fonts in the Fonts array.
ASUns32 flags Embedding flags. See Technical Notes below.
ASStatusMonitorProcs statusMon Pointer to a record containing a Progress Monitor, Cancel Procedure, and Report Procedure. See Technical Notes below.

Exceptions

  None

Returns

  None

Related Methods

  PDDocEmbedFonts

Technical Notes

1 The doc value indicates the PDdoc on which to operate. The fonts will be embedded in this document. To keep the changes, the document must be saved. Fonts on the user's system that match the original font definition will be embedded. For the Times-Roman and Helvetica and corresponding styles, if displayed with a font alias, then the font alias will be embedded in the file.
NOTE: If the font has information indicating that it cannot be embedded for print and preview, then the font will not be embedded in the document.
2 The flags value should be one of the following:
kDocEmbedSubset
If set, fonts will be subset when embedded. Otherwise the entire font will be embedded. A full font should only be embedded if the information in the font indicates that it can be used for editable embedding. Fonts that have more than 2048 characters will be subset-embedded regardless of the setting of this flag.
kDocEmbedSubsetOfEmbeddedFont
If set, fonts that have already been embedded, but are not subset fonts, will be re-embedded in subset form.
3 The statusMon value should be a pointer to a record containing a Progress Monitor, Cancel Procedure, and Report Procedure:
Progress Monitor Procedures in the progress monitor are called to indicate the progress of the routine.
Cancel Procedure The cancel procedure is called periodically to allow the client to cancel the routine. If the cancel procedure returns false then the routine is canceled.
Report Procedure This will be called to report errors or warnings while embedding the fonts.Each font that cannot be embedded will result in a call to the report procedure.

 

PDDocGetXAPMetadataCompactOptional Header: PDMetadataProcs.h

Description

A call to PDDocGetXAPMetadata to retrieve embedded XML document metadata will by default return it in compact Resource Description Framework (RDF) format, translating it to RDF format during extraction if it is not already in that format. This PDDocGetXAPMetadataCompactOptional API has been added to make the compact RDF conversion a user-controllable option, giving you the choice of whether to have XMP metadata returned in compact RDF format, which will otherwise occur by default.

Calling this with a FALSE value for enableCompactRDF will return XMP metadata without translation into RDF format. If TRUE, this will behave like PDDocGetXAPMetadata, to compact the format of returned XMP metadata by translating subtags to attributes whenever possible.

Syntax

ASText PDDocGetXAPMetadataCompactOptional(PDDoc doc, ASBool enableCompactRDF)

Parameters

PDDoc doc The PDdoc on which to operate
ASBool enableCompactRDF Flag determining whether returned XML metadata should be translated to compact RDF format. TRUE will translate to compact RDF; FALSE makes no translation.

Exceptions

  pdMetadataErrCouldntCreateMetaXAP

Returns

  ASText:The XMP metadata associated with the document PDDoc.

Related Methods

  None

PDDocHasSignature Header: DLExtrasProcs.h

Description

Determines if a PDF document has a digital signature.

Syntax

ASBool PDDocHasSignature(PDDoc pdDoc)

Parameters

pdDoc The document.

Exceptions

  None

Returns

  True if the document has a digital signature, false if it does not.

Related Methods

  None

PDDocOptimizeGetImageRecompress Header: DLExtrasProcs.h

Description

Returns the values set for one of the three cases of image recompression and downsampling. These values are used in deciding which class of images from the set of all images in the document will be modified by the optimizer.

Syntax

void PDDocOptimizeGetImageRecompress(PDFOptimizationParams params, PDFOptimizerCompressImageType imageType, \ ASInt16 *recompressIfAbove, ASInt16 *recompressTo, PDFOptimizerCompressionType *compressType, \ PDFOptimizationCompressQuality *compressQuality)

Parameters

params Set of parameters for objects
imageType The class of images these parameters are to refer to--Color, Gray, or Monochrome (B/W)
recompressifAbove The lower limit of resolution (In DPI) of an image to be resampled. Only images with resolutions greater than this setting will be considered for resampling.
recompressTo The target DPI for resampling. If an image is resampled, it will be resampled to this resolution.
compressType A member of the PDFOptimizerCompressionType enumeration. If an image is resampled or recompressed, it will be written in this compression type. If the value of this enumeration is either the specifier for "Same" or for "None" it does not recompress images which do not require downsampling.
compressQuality A member of the PDFOptimizationCompressQuality enumeration. This enumeration is only meaningful for lossy compression techniques. Note that it is an error to specify "Lossless" for techniques that cannot support lossless compression.

Exceptions

  None

Returns

  None

Related Methods

  PDDocOptimizeSetImageRecompress

PDDocOptimizeGetOption Header: DLExtrasProcs.h

Description

Reports on the optimization option being set to on or off.

Syntax

ASBool PDDocOptimizeGetOption(PDFOptimizationParams params, PDFOptimizerOption option)

Parameters

params A PDFOptimizationParams object to be checked
option A member of the enumerations PDFOptimizerOption, selecting which option to affect

Exceptions

  None

Returns

"On" for the associated option if the value is set to true. "Off" if the option is  false.

Related Methods

  PDDocOptimizeSetOption

PDDocOptimizeGetPDFOutputLevel Header: DLExtrasProcs.h

Description

Gets the output level for the optimized PDF document.

Syntax

void PDDocOptimizeGetPDFOutputLevel(PDFOptimizationParams params, ASInt16* majorP, ASInt16* minorP)

Parameters

params Set of parameters for objects
majorP Major version number
minorP Minor version number

Exceptions

  None

Returns

  None

Related Methods

  None

PDDocOptimizeReleaseParams Header: DLExtrasProcs.h

Description

This will free the resources used by a PDFOptimizationParams structure.

Syntax

void PDDocOptimizeReleaseParams(PDFOptimizationParams params)

Parameters

params Set of parameters to release

Exceptions

  None

Returns

  None

Related Methods

  None

PDDocOptimizeSetImageRecompress Header: DLExtrasProcs.h

Description

This sets the value for one of the three cases of image recompression and downsampling. These values are used in deciding which class of images from the set of all images in the document will be modified by the optimizer.

Syntax

void PDDocOptimizeSetImageRecompress(PDFOptimizationParams params, PDFOptimizerCompressImageType imageType, \ ASInt16 recompressIfAbove, ASInt16 recompressTo, PDFOptimizerCompressionType compressType, \ PDFOptimizationCompressQuality compressQuality)

Parameters

params Set of parameters for objects
imageType The class of images these parameters are to refer to. This is a member of the Enumeration PDFOptimizerCompressImageType, and is one of three values--Color, Gray, or Monochrome (B/W).
recompressifAbove The lower limit of resolution (In DPI) of an image to be resampled. Only images with resolutions greater than this setting will be considered for resampling.
recompressTo The target DPI for resampling. If an image is resampled, it will be resampled to this resolution.
compressType A member of the PDFOptimizerCompressionType enumeration. If an image is resampled or recompressed, it will be written in this compression type. If the value of this enumeration is either the specifier for "Same" or for "None" it does not recompress images which do not require downsampling.
compressQuality A member of the PDFOptimizationCompressQuality enumeration. This enumeration is only meaningful for lossy compression techniques. Note that it is an error to specify "Lossless" for techniques that cannot support lossless compression.

Exceptions

  None

Returns

  None

Related Methods

  PDDocOptimizeGetImageRecompress

PDDocOptimizeSetObjectCompression Header: DLExtrasProcs.h

Description

Sets the type of compression used for objects.

Syntax

void PDDocOptimizeSetObjectCompression(PDFOptimizationParams params, PDFOptimizerObjectCompressionType compressionType)

Parameters

params a set of parameters for objects
compressionType compression method to use

Exceptions

  None

Returns

  None

Related Methods

  None

PDDocOptimizeSetOption Header: DLExtrasProcs.h

Description

Sets the optimization option to either on or off.

Syntax

void PDDocOptimizeSetOption(PDFOptimizationParams params, PDFOptimizerOption option, ASBool onOff)

Parameters

params A PDFOptimizationParams object to be modified
option A member of the enumerations PDFOptimizerOption, selecting which option to affect
onOff Set to "on" if true, "off" if false

Exceptions

  None

Returns

  None

Related Methods

  PDDocOptimizeGetOption

PDDocOptimizeSetPDFOutputLevel Header: DLExtrasProcs.h

Description

Sets the output level for the optimized PDF document. This refers to the version of the PDF document itself, as in PDF 1.7 or PDF 2.0.

Syntax

void PDDocOptimizeSetPDFOutputLevel(PDFOptimizationParams params, ASInt16 majorP, ASInt16 minorP)

Parameters

params set of parameters for objects
majorP Major version number
minorP Minor version number

Exceptions

  None

Returns

  None

Related Methods

  None

PDDocWillNeedIncrementalSave Header: DLExtrasProcs.h

Description

Determines if the document must be saved incrementally.

Syntax

ASBool PDDocWillNeedIncrementalSave(PDDoc pdDoc)

Parameters

pdDoc The document

Exceptions

  None

Returns

  True if the document requires an incremental save, false if it does not.

Related Methods

  None

PDDocumentOptimize Header: DLExtrasProcs.h

Description

Used to create an optimized copy of the original PDF document.  The optimization process can take many specific forms, and the result is saved to a new PDF version of the original file.

Syntax

ASBool PDDocumentOptimize(PDDoc InputDoc, ASPathName OutputPath, ASFileSys fileSys, PDFOptimizationParams params, ProgressMonitor progMon, void *progMonClientData, ASCancelProc cancelProc, void *cancelProcClientData)

Parameters

InputDoc Input document object
OutputPath Where the optimized document is to be written
fileSys File system used to write the document
params Used to control optimization
progMon Progress monitor
progMonClientData Pointer to client data used by progress monitor
cancelProc Pointer to cancel procedure
cancelProcClientData Pointer to cancel proc client data

Exceptions

  None

Returns

  None

Related Methods

  None

PDDocumentOptimizeWithReport Header: DLExtrasProcs.h

Description

This facility is used to create an optimized copy of the original document. Optimization can be in many specific forms, controlled by control records input to the optimizer. The result of optimization is always a new document, saved to a file. This is because some of the optimizations are done at Document save time.

Syntax

ASBool PDDocumentOptimizeWithReport(PDDoc InputDoc, ASPathName OutputPath, ASFileSys fileSys, PDFOptimizationParams params, ProgressMonitor progMon, void * progMonClientData, ASCancelProc cancelProc, void *cancelProcClientData, PDFOptimizerReport report);

Parameters

InputDoc a PDDoc object
OutputPath An ASFilePath where the optimized document is to be written.
OutputFileSys A FileSys to write the document to. May be NULL, in which case default file sys will be used.
OptimizationParams A reference to a OptimizationParamsRec structure, used to control optimization.
ProgMon An optional progress monitor.
progMonClientData An optional pointer to client data used by the progress monitor.
cancelProc An optional pointer to a cancel procedure
cancelProcClientData An optional pointer to cancel proc client data
report An PDFOptimizerReport that will be filled by the method.

Exceptions

  None

Returns

  True if an optimized document is created, false if a document is not created.

Related Methods

  None

PDDocReplaceUnembeddedSimpleFonts Header: DLExtrasProcs.h

Description

This method replaces simple, unembedded, non-subset fonts in a PDF document with a different font. This does not include Type 0 or composite fonts. For fonts that lack required dictionary entries, such as /FontDescriptor, the method will create default entries.

Syntax

void PDDocReplaceUnembeddedSimpleFonts(PDDoc doc, ASAtom *currentFontNames, ASAtom * newFontNames, ASUns32 fontNamesLength);

Parameters

doc a PDDoc object
currentFontNames The names of the fonts to be replaced
newFontNames The names of the new fonts
fontNamesLength The number of current font names and the number of new font names. These two values must match.

Exceptions

  None

Returns

  None

Related Methods

  None

Technical Notes

This method should only be used by advanced users.  It is useful for applications that need to define precise font substitutions for unembedded fonts rather than relying on the PDF viewing tool (such as Adobe Acrobat) to select a suitable font based on the fonts available on the local system. If you choose a new font replacement that is not similar to the font being replaced in terms of encoding, metrics, and glyphs then your result may appear distorted or incorrect in a variety of ways. Be careful when selecting a replacement font.

PDDocTextFinderAcquireMatchList Header: DLExtrasProcs.h

Description

Finds all regular expression (regex) matches for the given page range.

PDDocTextFinderAcquireMatchList is the API call.

This API is only available with Windows, Linux, and macOS.

Syntax

PDDocTextFinderMatchList PDDocTextFinderAcquireMatchList(PDDocTextFinder mObj, PDDoc pdDoc, ASInt32 beginPageNumber, ASInt32 endPageNumber, const char *regexstr)

Parameters

mObj The document text finder used to acquire the match list.
pdDoc The document to search for matches.
beginPageNumber Beginning page number in the PDF document to start the search. The first page in the document is page 0, not page 1 as found in Adobe Acrobat. Pass PDAllPages (see PDExpT.h) to process all of the pages in the document.
endPageNumber The final page number in the PDF document, where the search will stop. If beginPageNumber is set to PDAllPages, this parameter will be ignored.
regexstr Regular expression to use for text or pattern search in the PDF document.

Exceptions

  PDErrBadRegex

Returns

PDDocTextFinderMatchList: Structure that contains information about matching phrases and their associated quads.

Related Methods

PDDocTextFinderCreate: Creates a document text finder that is used to extract words or phrases that match regular expressions from a PDF file, based on words extracted using a given word finder configuration.

PDDocTextFinderReleaseMatchList: Releases the match list.

PDDocTextFinderDestroy: Destroys a document text finder when the process is complete to extract phrases from a file.

PDDocTextFinderCreate Header: DLExtrasProcs.h

Description

Creates a document text finder used to extract words or phrases that match regular expressions from a PDF file based on words extracted using a given word finder configuration.

This API is only available with Windows, Linux, and macOS.

Syntax

PDDocTextFinder PDDocTextFinderCreate(PDWordFinderConfig wfConfig)

Parameters

wfConfig The word finder configuration to be used to extract the words.

Exceptions

  None

Returns

PDDocTextFinder: Newly created document text finder object that will be used to find matches.

Related Methods

PDDocTextFinderAcquireMatchList: Finds all regular expression (regex) matches for the given page range. Returns the PDDocTextFinderMatchList structure that contains the match information for the document.

PDDocTextFinderReleaseMatchList: Releases the match list.

PDDocTextFinderDestroy: Destroys a document text finder when the process is complete to extract phrases from a file.

PDDocTextFinderDestroy Header: DLExtrasProcs.h

Description

Destroys a document text finder when the process is complete to extract phrases from a file.

This API is only available with Windows, Linux, and macOS.

Syntax

void PDDocTextFinderDestroy(PDDocTextFinder mObj)

Parameters

mObj The document text finder to destroy.

Exceptions

  None

Returns

  None

Related Methods

PDDocTextFinderCreate: Creates a document text finder that is used to extract words or phrases that match regular expressions from a PDF file, based on words extracted using a given word finder configuration.

PDDocTextFinderAcquireMatchList: Finds all regular expression (regex) matches for the given page range. Returns the PDDocTextFinderMatchList structure that contains the match information for the document.

PDDocTextFinderReleaseMatchList: Releases the match list.

PDDocTextFinderReleaseMatchList Header: DLExtrasProcs.h

Description

Releases the match list created by  PDDocTextFinderAcquireMatchList.

This API is only available with Windows, Linux, and macOS.

Syntax

void PDDocTextFinderReleaseMatchList(PDDocTextFinder mObj)

Parameters

mObj A document text finder object.

Exceptions

  None

Returns

  None

Related Methods

PDDocTextFinderCreate: Creates a document text finder that is used to extract words or phrases that match regular expressions from a PDF file, based on words extracted using a given word finder configuration.

PDDocTextFinderAcquireMatchList: Finds all regular expression (regex) matches for the given page range. Returns the PDDocTextFinderMatchList structure that contains the match information for the document.

PDDocTextFinderDestroy: Destroys a document text finder when the process is complete to extract phrases from a file.

PDFOptimizationParams Header: DLExtrasProcs.h

Description

Creates a set of parameters for optimizing a document, set to the default values. These values can be examined with “get” methods and changed using the “set” methods. When these parameters are no longer needed, they should be freed by a call to PDDocOptimizeReleaseParams.

Syntax

PDFOptimizationParams(PDDocOptimizeDefaultParams)

Parameters

none

Exceptions

  None

Returns

  Initialized optimization parameters that can be further modified.

Related Methods

  PDDocOptimizeReleaseParams

PDFOptimizeObjectCompressionType

PDDocOptimizeGetObjectCompresson

Header: DLExtrasProcs.h

Description

Obtains the compression type used for objects

Syntax

PDFOptimizerObjectCompressionType PDDocOptimizeGetObjectCompression(PDFOptimizationParams params)

Parameters

params Set of parameters for objects

Exceptions

  None

Returns

  PDFOptimizerObjectCompressionType

Related Methods

  None

PDEContentGetElemsStatus Header: PERProcs.h

Description

This call lets the application determine whether the value returned from a PDEContentGetNumElems call is correct, especially if that API has returned a zero. It is possible for the PDEContentGetNumElems call to return a zero count under two conditions, normal and abnormal: when there is in fact no PDEContent to be examined, or when there is poorly  formed content which cannot be examined.

Calling PDEContentGetElemsStatus following a PDE- ContentGetNumElems call will return an unsigned (ASUns32) integer value, to be interpreted as a set of bit flags. Only 0 and 1 are defined as return values.

The returned value from PDEContentGetElemsStatus will either confirm that the returned PDEContentGetNumElems count is correct or flag that a problem has occurred. Future bit flags to be added (as needed) will enable multiple error conditions to be reported.

Syntax

ASUns32 PDEContentGetElemsStatus(PDEContent pdeContent)

Parameters

PDEContent pdeContent The PDEContent examined by PDEContentGetNumElems

Exceptions

  None

Returns

ASUns32. Return status 0, no errors detected, or 1, Unpaired Marked Content operators (unbalanced MC/EC operators)

Related Methods

  PDEContentGetNumElems

PDEFontCheckASTextIsRepresentable Header: DLExtrasCalls.h

Description

This API allows callers to determine if a given PDEFont contains the necessary glyphs for the string given in the supplied ASText object, by checking to ensure that the entire contents of an ASText are representable in the font. If the index parameter is not NULL and this function returns false, the *index value will indicate the first character not representable in the font.

Syntax

ASBool PDEFontCheckASTextIsRepresentable(const  PDEFont font, const ASText text, ASUns32 *index)

Parameters

const PDEFont font The font to check against
const ASText text  An ASText containing the text to check
ASUns32 *index The index of the first character in the Unicode representation of the string that could not be represented in the font. May be NULL if the user wants to ignore this information.

Exceptions

  None

Returns

  ASBool

Related Methods

  None

PDEFormCalcBBox Header: DLExtrasProcs.h

Description

The bounding box of a form is set in the COS form, and is usually not changed by any event in the conversions between PDE and COS content. This is done so that the user may set the bounding box of a form so as to specifically clip its contents to a given path (the bounding box).

If the content of a form is changed, the user may want to reset the form's bounding box to the size of the current content. This interface is provided to do that.

Syntax

void PDEFormCalcBBox(PDEForm form);

Parameters

form The PDEForm whose BBox should be recalculated.

Exceptions

  None

Returns

  None

Related Methods

  None

Technical Notes

1 This interface with change the COS bounding box of the form referenced in a PDEForm. As such, it will change the effective bounding box of all references to that form. However, this change will not be noted in existing PDEForms references. So it is a good idea after using this call to do a PDERelease and PDEAcquire, before trusting such references.
2 This function allows the BBox stored in a form's XObject to be recalculated after its contents have been modified.

 

PDEFormGetFont Header: DLExtrasProcs.h

Description

This retrieves the PDEFont referenced in a PDEForm.

Syntax

PDEFont PDEFormGetFont(PDEForm form);

Parameters

form The PDEForm of interest.

Exceptions

  None

Returns

  None

Related Methods

  PDEFormSetFont

Technical Notes

  1. These functions allow the user to access and set the PDEFont object, which may be stored in a PDEForm object.  When the form is required to inherit a font from the referencing environment, the font is stored in the form reference and the specification of the font occurs after the last preceding mark is made. In this event, if the font is not stored in the PDEForm and restored to the COS content, the page may render differently following a PDE "round trip."
  2. Most of the time the font referenced will be a NULL pointer. Applications which use these interfaces must be aware that an invalid font pointer is possible. Generally, if this font reference is incorrect it will not cause an issue in document handling unless the font is not NULL and the referenced form inherits (uses before setting) the font value.
  3. If a font is a reference to a font being replaced, but that font is not in fact replaced itself, a reference to the original font remains in the document. It will not be garbage collected. The replacement of the font with a null pointer is valid, but this may cause a form which inherits this font to render improperly.
PDEFormSetFont Header: DLExtrasProcs.h

Description

This sets the PDEFont referenced in a PDEForm.

Syntax

void PDEFormSetFont(PDEForm form, PDEFont font);

Parameters

form The PDEForm of interest.
font The PDEFont to be set.

Exceptions

  None

Returns

  None

Related Methods

  PDEFormGetFont

PDEFormGetTextState Header: PerProcs.h

Description

This API provides access to the Text State in the PDEForm object, returning the PDETextState for the indicated form.

Syntax

void PDEFormGetTextState(PDEForm form, PDETextState *tState)

Parameters

PDEForm form The form whose COS object is obtained
PDETextState *tState The text state associated with this form (Filled by the method)

Exceptions

  peErrWrongPDEObjectType

Returns

  None

Related Methods

  PDEFormSetTextState

PDEFormSetTextState Header: PerProcs.h

Description

This API provides access to the Text State in the PDEForm object, letting you specify the PDETextState for the indicated form.

Syntax

void PDEFormSetTextState(PDEForm form, PDETextState *tState)

Parameters

PDEForm form The form whose COS object is to be set
PDETextState *tState The text state to be associated with this form

Exceptions

  peErrWrongPDEObjectType

Returns

  None

Related Methods

  PDEFormGetTextState

PDEImageGetColorValue Header: PERProcs.h

Description

This API will get the current color value (PDEColorValueP) for an imagemask in a PDE content stream,, complementing the PDEImageGetColorSpace API.

This API is only valid for PDEImage objects that are image masks.  It will create a PDFL exception if given non-mask PDE- Image inputs.

Syntax

void PDEImageGetColorValue(PDEImage image, PDEColorValueP color)

Parameters

PDEImage image The image whose data is retrieved
PDEColorValueP color The image color data

Exceptions

  peErrWrongPDEObjectType

Returns

  None

Related Methods

  PDEImageSetColorValue

PDEImageRemoveIndexedColor Header: DLExtrasProcs.h

Description

If the image input uses an indexed color space, a new image will be created from it. The new image will use the base color space. If the image is not using an indexed color model, the original image will be incremented and returned. The image returned must be released when no longer needed.

Syntax

PDEImage PDEImageRemoveIndexedColor(PDEImage image);

Parameters

image The Indexed image inP.

Exceptions

  None

Returns

  The new or original image.

Related Methods

  None

PDEImageSetColorValue Header: PERProcs.h

Description

This API will set the current color value (PDEColorValueP) for an imagemask in a PDE content stream, and complement the PDEImageGetColorSpace and PDEImageSetColor- Space APIs. See Technical Notes below.

Syntax

void PDEImageSetColorValue(PDEImage image, PDEColorValueP color)

Parameters

PDEImage image The image whose data is set
PDEColorValueP color The image color data

Exceptions

  peErrWrongPDEObjectType

Returns

  None

Related Methods

  PDEImageGetColorValue

Technical Notes

The Adobe PDF Library did not allow a means of accessing the color value embedded in a PDEImage object that represented an imagemask. While it could be set when the object was first created (as the PDEImageCreate API always requires a color value when creating an imagemask), there was no means of reading an existing value later on, and thus there was no way to change the color of any existing PDEImage which was a mask.

The PDEImageGetColorValue API call will fill a color value object from the PDEImage internal value. This interface will raise peErrWrongPDEObjectType if it is called with an image that is not an imagemask.

PDEPathGetDataFloat Header: PERProcs.h

Description

This API will get the size of the path data and, optionally, the path data itself. See Technical Notes below.

Syntax

ASUns32 PDEPathGetDataFloat(PDEPath path, ASFloat *data, ASUns32 dataSize)

Parameters

PDEPath path The path whose data is obtained
ASFloat *data A pointer to the path data (Filled by the method)
ASUns32 dataSize Specifies the size of the buffer provided in data. If it is less than the length of the path data, the method copies dataSize bytes.

Exceptions

  peErrWrongPDEObjectType

Returns

  ASUns32: The length of the data path

Related Methods

  PDEPathGetData

  PDEPathSetDataFloat

Technical Notes

1 If data is NULL, the number of bytes required for data is returned by the method.
If data is not NULL, it contains a variable-sized array of path operators (opcodes) and operands. The format is a 32-bit operator followed by 0 to 3 ASFloat values, depending on the operator. Opcodes are codes for moveto, lineto, curveto, rect or closepath, and must be of PDEPathElementType. Operands are ASFixedPoint values.
2 Note that this returns raw path data. If you want the points in page coordinates, concatenate the path data points with the PDEElement matrix obtained from the PDEElementGetMatrix method.

 

PDEPathSetDataFloat Header: PEWProcs.h

Description

This API will set new path data for a path element. See Technical Notes below.

Syntax

void PDEPathSetDataFloat(PDEPath path, ASFloat *data, ASUns32 dataSize)

Parameters

PDEPath path The path whose data is set
ASFloat *data A pointer to the path data
ASUns32 dataSize The size of the new path data in bytes

Exceptions

  genErrBadParm

  peErrWrongPDEObjectType

Returns

  None

Related Methods

  PDEPathSetData

  PDEPathGetDataFloat

Technical Notes

The data value is a variable-sized array of path operators (opcodes) and operands. The format is a 32-bit operator followed by 0 to 3 ASFloat values, depending on the operator. Opcodes are codes for moveto, lineto, curveto, rect or closepath, and must be of PDEPathElementType. Operands are ASFixedPoint values.

PDEPSGetCosObj Header: DLExtrasProcs.h

Description

Get the CosObj for a Postscript pass through.

Syntax

void PDEPSGetCosObj(IN PDEPS ps, OUT CosObj *cosObjP)

Parameters

ps The PostScript XObject whose Cos object is obtained (IN)
cosObjP The Cos object of the PostScript XObject (OUT)

Exceptions

  None

Returns

  None

Related Methods

  None

PDETextAddASText Header: DLExtrasCalls.h

Description

This API will add the text for a text run or character. The PDE- Font associated with the PDEText must contain a ToUnicode table.

This call adds a character or a text run to a PDEText object, taking them from the ASText, and thus Unicode characters can be placed in the PDEText. This function will accept characters that are not representable in the given font; such characters will be replaced with the .notdef glyph.

Syntax

void PDETextAddASText(PDEText pdeText, ASUns32 flags, ASInt32 index, ASText text, PDEFont font, PDEGraphicStateP gstateP, ASUns32 gstateLen, PDETextStateP tstateP, ASUns32 tstateLen, ASFixedMatrixP textMatrixP)

Parameters

PDEText pdeText The text object to which a character or text run is added
ASUns32 flags A PDETextFlags that specifies what kind of text to add
ASInt32 index The index after which to add the character or text run
ASText text An ASText containing the text to add
PDEFont font The font for the element
PDEGraphicStateP gstateP A pointer to a PDEGraphicState structure with the graphics state for the element
ASUns32 gstateLen The length of the graphics state for the element
PDETextStateP tstateP A pointer to a PDETextState structure with the text state for the element
ASUns32 tstateLen The length of the text state for the element
ASFixedMatrixP textMatrixP A pointer to an ASFixedMatrix that holds the matrix for the element

Exceptions

  None

Returns

  None

Related Methods

  PDEFontCheckASTextIsRepresentable, PDETextGetASText

Technical Notes

  1. Text strings handled via this API should be properly-formatted Unicode. You should be aware of compiler-sensitive issues such as byte-ordering and string termination.
  2. Created fonts must have a PDSysEncoding value of Identity-H or Identity-V, and should be created via the PDEFontCreateFromSysFontAndEncoding API.
  3. Fonts should be created with the kPDEFontCreateEmbedded, kPDEFontCreateSubset, kPDEFontCreateToUnicode and kPDEFontEncodeByGID flags in effect.
  4. PDEFontCheckASTextIsRepresentable can be used to verify that valid glyphs are available for a Unicode string.
  5. PDEFontEmbedNow and PDEFontSubsetNow will return an exception if no text is actually placed prior to their call.
PDETextGetASText Header: DLExtrasCalls.h

Description

This API will get the text for a text run or character. The PDE- Font associated with the PDEText must contain a ToUnicode table.

Syntax

void PDETextGetASText(PDEText pdeText, ASUns32 flags, ASInt32 index, ASText text)

Parameters

PDEText pdeText A text object containing a character or text run whose text is found
ASUns32 flags A PDETextFlags value that specifies whether index (below) refers to a character or a text run
ASInt32 index The index of the character or text run inpdeText
ASText text An ASText that is filled with the text from the text item

Exceptions

  None

Returns

  None

Related Methods

  PDETextAddASText

PDETextItemCopyASText Header: DLExtrasCalls.h

Description

This API will copy the text from a text item. The PDEFont associated with the PDEText must contain a ToUnicode table.

Syntax

void PDETextItemCopyASText(PDETextItem textItem, ASText text)

Parameters

PDETextItem textItem The text item from which the text will be copied
ASText text An ASText object that is filled with the text from the text item

Exceptions

  None

Returns

  None

Related Methods

  PDETextItemCreateASText

PDETextItemCreateASText Header: DLExtrasCalls.h

Description

This call creates a text element containing a character or run which can be added to a PDEText object. This function will accept characters that are not representable in the given font; such characters will be replaced with the .notdef glyph.

Syntax

PDETextItem PDETextItemCreateASText(ASText text, PDEFont font, PDEGraphicStateP gStateP, ASUns32 gStateLen, PDETextStateP textStateP, ASUns32 textStateLen, ASFixedMatrixP textMatrixP)

Parameters

ASText text An ASText containing the text to add
PDEFont font The PDEFont for the element.  Its type must be Type0 or TrueType.
PDEGraphicStateP gstateP A pointer to a PDEGraphicStateP structure with the graphics state for the element.
ASUns32 gstateLen The length of the graphics state for the element.
PDETextStateP tstateP A pointer to a PDETextState structure with the text state for the element.
ASUns32 textstateLen The length of the text state for the element.
ASFixedMatrixP textMatrixP A pointer to an ASFixedMatrix that holds the matrix for the element.

Exceptions

  genErrBadParm

Returns

  PDETextItem

Related Methods

  PDETextItemCopyASText

Technical Notes

  1. Passing an ASText containing an empty string will return a genErrBadParm exception.
  2. PDFEdit ignores the wasSetFlags flag of the PDETextState structure, so you must initialize the PDETextState fields.
  3. An exception will be raised if the supplied font is incompatible with the API. This could if the font is a Type 1 font, for example,  or if the font is retrieved from an existing PDF document.
PDFLAddFontDirectories Header: DLExtrasCalls.h

Description

This API was introduced as part of an enhancement to allow Adobe PDF Library to rescan for fonts without re-initializing. This will allow an operating Library process to detect and update new font directories and resources after startup, without requiring a restart and re-initialization.

PDFLAddFontDirectories will add one or more directories, and the fonts within them, to the set of all directories containing fonts (those specified in the DirList string arrays of resource locations). This should be followed by a call to PDFL- RescanFontDirectories after all new font directories have been loaded.

Syntax

ASBool PDFLAddFontDirectories(ASInt32 pathCount, ASPathName *paths)

Parameters

ASInt32 pathCount Number of new paths to be addedASPathName *paths: Paths to new resource locations to be added

Exceptions

  None

Returns

  ASBool

Related Methods

  PDFLRescanFontDirectories

PDFLReinit Header: PDFLProcs.h

Description

In some circumstances, a CosDoc object within Adobe PDF Library functions as an internal cache, a thread-local object that is created at the outset of the process and released by a PDFL- Term call, but which grows continuously for the duration of the application.

For applications where this behavior causes problems, the PDFLReinit call can be made, to act as a sort of "Warm Reboot" for the already-initialized Adobe PDF Library. For applications which process a queue of PDF documents and do not attempt to return to any files processed earlier, this function can improve memory usage by clearing the gPDEScratchCosDoc object cache, which is normally done only at termination. See Technical Notes below.

Syntax

ASInt32 PDFLReinit(void)

Parameters

None

Exceptions

  None

Returns

  ASInt32 (Always 0)

Related Methods

  None

Technical Notes

Calling this method will destroy the gPDEScratchCosDoc at that time, instead of waiting for PDFLTerm. This occurs immediately upon calling; it is assumed that the gPDEScratchCosDoc is no longer needed.

CAUTION:  This should be used with great care. It is assumed that all documents referenced by the gPDEScratchCosDoc are already closed or otherwise no longer needed. No internal checking is performed prior to executing the cleanup and deleting the cache.

PDFLRescanFontDirectories Header: DLExtrasCalls.h

Description

This API was introduced as part of an enhancement to allow Adobe PDF Library to rescan for fonts without re-initializing. This will allow an operating Library process to detect and update new font directories and resources after startup, without requiring a restart and re-initialization.

This call can, depending on flag settings, force a rescan of font resource areas defined in your dirList array, a rescan of those residing in the System folder, or both. (To add new font resources to your dirList array, use the PDFLAddFontDirectories call. Technical Notes below.

Syntax

ASBool PDFLRescanFontDirectories(FontRescanFlags flags)

Parameters

FontRescanFlags flags Flags controlling rescan process. See Technical Notes below.

Exceptions

  None

Returns

  ASBool

Related Methods

  PDFLAddFontDirectories

Technical Notes

1 The FontRescanFlags value (defined in DLExtrasExpT.h) specifies the extent of the font resource rescanning to perform:
  • FontRescan_Files = 1: Rescan only the resource locations defined in dirList, plus those added via PDFLAddFontDirectories
  • FontRescan_System = 2: Rescan only the system directories
  • FontRescan_All = 3: Rescan both areas above
2 Using the FontRescan_All flag value is functionally equivalent to an OR of the preceding two values.
3 This call (as well as the PDFLAddFontDirectories call) will act upon all PDSysFont structures referenced by the font cache that have a reference count of zero. Any pointers to such structures will become invalid after a rescan call has occurred.
By default, all referenced PDSysFont structures will be affected, as their reference counts are always zero. To preserve a PDSysFont reference across a rescan call, use PDEAcquire and PDERelease calls to increment and decrement usage counts of a PDSysFont object as like other PDE Object.
For example, use “PDEAcquire ((PDEObject)PDEFontGetSysFont(font));” to increment, and later “PDERelease((PDEObject)PDEFontGetSysFont(font));" to decrement again.

 

PDFontXlateToUCSCanRaise Header: DLExtrasProcs.h

Description

Translates a string from whatever encoding the PDFont uses to Unicode encoding. This may raise an error.

Syntax

ASInt32 PDFontXlateToUCSCanRaise(PDFont fontP, ASUns8 *inP, ASInt32 inLen, ASUns8 * outP, ASInt32 outLen);

Parameters

fontP The font of the input string inP.
inP A pointer to the string to translate.
inLen The length of the inP buffer in bytes.
outP Filled by the method. A pointer to the translated.
string If it is NULL, the method returns the size of the translated string.
outLen The length of the outP buffer in bytes. If it is 0, the method returns the size of the translated string.

Exceptions

  genErrBadParm

Returns

  The number of bytes in the translated string in outP.

Related Methods

  PDFontXlateToUCS

PDPageDrawContentsToMemoryWithParams Header: DLExtrasCalls.h

Description

The  PDPageDrawContentsToMemoryWithParams API call supports the same rasterization parameters as those of the PDPageDrawContentsToMemory call, and also allows users to specify these additional arguments:

  • The destination rectangle (in ASFixed or ASReal notation)
  • The update rectangle (in ASFixed notation)
  • The transformation matrix (in ASFixed or ASRealnotation)
  • The colorspace to use, as a named colorspace or as a color profile
  • The rendering intent to use for rendering
  • A request to ignore restrictions on content copying & page extraction
  • Default profile for Uncalibrated RGB

If the buffer is not supplied and the length of the buffer is specified as 0, this API call returns the size of the buffer required to rasterize the PDPage.

Syntax

ASSize_t, PDPageDrawContentsToMemoryWithParams(PDPage page, PDPageDrawMParams drawParams)

Parameters

PDPage page The PDPage to be rendered.
PDPageDrawMParams drawParams Set of parameters (of type PDPageDrawMParams) describing how to rasterize the supplied PDPage, rasterizing the PDPage into a memory buffer supplied in the parameter set.

Exceptions

  None

Returns

  ASSize_t

Related Methods

   PDPageDrawContentsToMemory

   PDPageDrawContentsToWindowWithParams

Technical Notes

The default assumed color profile for uncalibrated RGB input/output is Adobe sRGB.

The use of sRGB as the default means that PDPageDrawContentsToMemory and PDPageDrawContentsToMemoryWithParams draws to an assumed sRGB condition if no ICC color profile is specified for output. You may change the profile used for uncalibrated RGB input/ output via the PDPrefSetWorkingRGB API.

PDPageDrawContentsToWindowWithParams Header: DLExtrasCalls.h

Description

This API accepts a structure of type PDPageDrawWParams, which includes a set of ASReal - based values in the same manner as  PDPageDrawContentsToMemoryWith- Params, and is intended to address overflow or underflow issues with the ASFixed-based drawing APIs when rendering a page to a window object.

Syntax

void PDPageDrawContentsToWindowWithParams(PDPage page, PDPageDrawWParams drawParams)

Parameters

PDPage page The PDPage to be rendered.
PDPageDrawWParams drawParams Set of parameters (of type PDPageDrawWParams) describing how to rasterize the supplied PDPage to a platform-dependent window object.

Exceptions

  None

Returns

  None

Related Methods

  PDPageDrawContentsToMemoryWithParams

PDPageEnumInksWithParams Header: DLExtrasProcs.h

Description

Enumerates the inks for a page, using the supplied options specified in the parameters.

Syntax

void PDPageEnumInksWithParams(PDPage Page, PDPageEnumInksParam Params)

Parameters

Page The page of interest.
Params The parameters describing options for enumerating inks.

Exceptions

  None

Returns

  None

Related Methods

  None

PDPageSetBlendingProfile Header: DLExtrasCalls.h

Description

This API enables direct specification of an overlay blending profile to be used, and to override any profiles that may be chosen in code or encoded in the document. It sets the blending profile for a PDPage throughout its duration, effectively creating a page-level isolated, non-knockout transparency group with the specified profile for the page. This appearance group will be used in rendering the page, in order to ensure consistency in color and shade regardless of other page content. It will directly set the overlay blending profile to be used, unaffected by any profiles that may be chosen in code or encoded in the document.

Syntax

void PDPageSetBlendingProfile(PDPage page,  AC_Profile profile)

Parameters

PDPage page The PDPage to be rendered.
AC_Profile profile Color blending profile to be used.

Exceptions

  None

Returns

  None

Related Methods

  None

PDPrefGetAllowOpeningXFA Header: DLExtrasCalls.h

Description

This function will return the current status of the default (as of v9.1.0PlusP2f) XFA file opening exception routine.

As of the v9.1.0PlusP2f release, the default Adobe PDF Library behavior will be to return an exception in cases where the PDF document being opened is found to contain an XFA form. This call will indicate whether PDPrefSetAllowOpeningXFA has been called to override that behavior. If true is returned here, the PDF document will be opened without an exception reporting the presence of XFA forms.

Syntax

ASBool PDPrefGetAllowOpeningXFA(void)

Parameters

None

Exceptions

  None

Returns

  ASBool

Related Methods

  PDPrefSetAllowOpeningXFA

PDPrefGetAllowRelaxedSyntax Header: DLExtrasCalls.h

Description

This call will return the current value of the AllowRelaxedSyntax flag setting, to indicate whether the Library will attempt to resolve or ignore minor PDF syntax errors (if True), or return an exception (if False, as before).

Syntax

ASBool PDPrefGetAllowRelaxedSyntax(void)

Parameters

None

Exceptions

  None

Returns

  ASBool

Related Methods

  PDPrefSetAllowRelaxedSyntax

PDPrefGetDefaultIntentToProfile Header: DLExtrasCalls.h

Description

This function returns the current status of the default source intent used in a color profile. If true is returned here, the intent to be used shall be the intent specified in the profile; otherwise AC_RelColorimetric will be assumed.

Syntax

ASBool PDPrefGetDefaultIntentToProfile(void)

Parameters

None

Exceptions

  None

Returns

  ASBool

Related Methods

  PDPrefSetDefaultIntentToProfile

PDPrefGetNeverUseOutputIntent Header: DLExtrasProcs.h

Description

This function returns whether that the output intent should be completely ignored when rendering a document. This setting defaults to false.

Syntax

ASBool PDPrefGetNeverUseOutputIntent(void)

Parameters

None

Exceptions

  None

Returns

If true, the OutputIntent will not be used when rendering even for PDF/A, PDF/E, or PDF/X documents.

Related Methods

PDPrefGetUseProfileIntent

PDPrefSetPrintUsingWorkingSpaces

Technical Notes

  1. UseProfileIntent is a true/false global preference. When UseProfileIntent is true, we always consider the output intent of a document when rendering. We may not always use it, depending on the color model specified, but we always consider it. When it is false, we do not consider the output intent unless the document claims compliance with PDF/A, PDF/E, or PDF/X. If the document claims compliance with one of these formats, we use the output intent regardless of the UseProfileIntent setting.
  2. To allow the user to say, "Never consider the output intent when rendering a document," we added this preference. It defaults to false.
PDPrefGetPrintUsingWorkingSpaces Header: DLExtrasProcs.h

Description

This function returns whether the device spaces are treated as calibrated when rendering.

Syntax

ASBool PDPrefGetPrintUsingWorkingSpaces(void)

Parameters

None

Exceptions

  None

Returns

If true, treats device spaces as calibrated to the associated working space profile. Otherwise, treats device spaces as uncalibrated.

Related Methods

  PDPrefSetPrintUsingWorkingSpaces

Technical Notes

This setting is only effective when the document is being rendered to memory, or a window, and kPDPageIsPrinting is true.

PDPrefSetAllowOpeningXFA Header: DLExtrasCalls.h

Description

This function overrides the default Adobe PDF Library behavior of returning an exception in cases where the PDF document being opened is found to contain an XFA form. If you want to suppress the new returned exception and open the PDF document (with its XFA form) anyway, this function should be called with a true argument. See Technical Notes below.

Syntax

void PDPrefSetAllowOpeningXFA(ASBool flag)

Parameters

ASBool flag When true, this will allow Adobe PDF Library to open XFA PDF documents

Exceptions

  None

Returns

  None

Related Methods

  PDPrefGetAllowOpeningXFA

Technical Notes

PDF documents containing XFA forms primarily use the PDF file as a "wrapper," and are properly interpreted by XFA-aware applications, but not necessarily an Adobe PDF Library application. XFA form documents are really XML-based documents that use the PDF file mechanism for convenience of transport only. So the Adobe PDF Library by default warns the user (via a returned exception) if a document is (or contains) an XFA form rather than PDF content.

These API methods, PDPrefGetAllowOpeningXFA and PDPrefSetAllowOpeningXFA, are provided if the application needs to override and ignore that exception.

PDPrefSetAllowRelaxedSyntax Header: DLExtrasCalls.h

Description

This call, with a True flag value, will allow callers to ask Adobe PDF Library to attempt to resolve or ignore minor PDF syntax errors. For example, the Library may fix up FontDescriptor entries with certain missing values by adding defaults, add a missing Supplement for Adobe Identity, or add a missing / FirstChar or /LastChar entry (if the other of the pair is present, along with a valid Widths table).

Syntax

void PDPrefSetAllowRelaxedSyntax(ASBool flag)

Parameters

ASBool flag When true, this will allow Adobe PDF Library to attempt to resolve or ignore minor PDF document errors

Exceptions

  None

Returns

  None

Related Methods

  PDPrefGetAllowRelaxedSyntax

PDPrefSetDefaultIntentToProfile Header: DLExtrasCalls.h

Description

Normally, if a source intent is not specified, it is assumed to be the intent AC_RelColorimetric. However, this leaves no way for a user to specify the profile intent if desired.

When this preference is set to true, the intent used (when no other intent is explicitly specified) will be the intent specified in the profile; otherwise AC_RelColorimetric will be assumed.

Syntax

void PDPrefSetDefaultIntentToProfile(ASBool flag)

Parameters

ASBool flag If true, use intent specified in the profile. (Default false)

Exceptions

  None

Returns

  None

Related Methods

  PDPrefGetDefaultIntentToProfile

PDPrefSetNeverUseOutputIntent Header: DLExtrasProcs.h

Description

This function sets a flag to specify that the output intent should not be considered when rendering a document.

This overrides the default behavior of the preference set with PDPrefSetUseProfileIntent. The PDPrefSetUseProfileIntent may still use the OutputIntent in spite of being set to false, if the document claims compliance with PDF/A, PDF/E, or PDF/X.

Syntax

void PDPrefSetNeverUseOutputIntent(ASBool value)

Parameters

flag If true, the OutputIntent will not be used when rendering even for PDF/A, PDF/E, or PDF/X documents.

Exceptions

  None

Returns

  None

Related Methods

  PDPrefGetPrintUsingWorkingSpaces

  PDPrefSetUseProfileIntent

Technical Notes

This setting defaults to false.

PDPrefSetPrintUsingWorkingSpaces Header: DLExtrasProcs.h

Description

This function sets a flag to treat the device spaces as calibrated when rendering. This setting is only effective when the document is being rendered to memory, or a window, and kPDPageIsPrinting is true.

Syntax

void PDPrefSetPrintUsingWorkingSpaces(ASBool flag)

Parameters

flag If true, treats device spaces as calibrated to the associated working space profile. Otherwise, treats device spaces as uncalibrated

Exceptions

  None

Returns

  None

Related Methods

  PDPrefGetPrintUsingWorkingSpaces

Technical Notes

These functions set and obtain a bool value. The value is interrogated internally during the rendering process, and chooses between (false) treating device spaces as uncalibrated, and (true) treated device spaces as calibrated to the associated working space profile.

PDPrefSuppressDefaultCMYKCalibration Header: DLExtrasCalls.h

Description

This call will suppress the Adobe-defined Default color profile used for a DeviceCMYK-specified object. If a Default color space is defined in the document resources or via PDEContentSetDefault, it will still be used.

Syntax

void PDPrefSuppressDefaultCMYKCalibration(ASBool flag)

Parameters

ASBool flag Setting this flag to true will suppress the Adobe-defined Default color profile.

Exceptions

  None

Returns

  None

Related Methods

  PDPrefSuppressDefaultGrayCalibration

  PDPrefSuppressDefaultRGBCalibration

PDPrefSuppressDefaultGrayCalibration Header: DLExtrasCalls.h

Description

This call will suppress the Adobe-defined Default color profile used for a DeviceGray-specified object. If a Default color space is defined in the document resources or via PDEContentSetDefault, it will still be used.

Syntax

void PDPrefSuppressDefaultGrayCalibration(ASBool flag)

Parameters

ASBool flag Setting this flag to true will suppress the Adobe-defined Default color profile.

Exceptions

  None

Returns

  None

Related Methods

  PDPrefSuppressDefaultCMYKCalibration

  PDPrefSuppressDefaultRGBCalibration

PDPrefSuppressDefaultRGBCalibration Header: DLExtrasCalls.h

Description

This call will suppress the Adobe-defined Default color profile used for a DeviceRGB-specified object. If a Default color space is defined in the document resources or via PDEContentSetDefault, it will still be used.

Syntax

void PDPrefSuppressDefaultRGBCalibration(ASBool flag)

Parameters

ASBool flag Setting this flag to true will suppress the Adobe-defined Default color profile.

Exceptions

  None

Returns

  None

Related Methods

  PDPrefSuppressDefaultCMYKCalibration

  PDPrefSuppressDefaultGrayCalibration

PDSysFontGetFullName Header: DLExtrasProcs.h

Description

This method retrieves the full font name of a system font. This method only returns a meaningful result for TrueType-based technology fonts.

Syntax

ASText PDSysFontGetFullName(PDSysFont sysFont)

Parameters

None

Exceptions

  None

Returns

  Font name

Related Methods

  None

PDWordGetCharPoint Header: DLExtrasCalls.h

Description

This method gets the placement point of the character at a given index position in the word. If the specified character is constructed with multiple bytes, only the first byte returns a valid quad. Otherwise, this method returns false. The placement point is specified in user space coordinates.

This method is intended to enhance the WordFinder feature in Adobe PDF Library, to provide additional information about the typesetting characteristics of the text that forms a word, specifically the baseline shift used for superscripts and subscripts.

For example, if someone is describing a temperature measurement of "78°" (78 degrees) using a superscript ‘o’ (Latin small letter O), the current implementation of WordFinder returns "78o," which may be confused with a mistyped 780 (seven hundred eighty), with no way to understand the semantic meaning of this character sequence.

PDWordGetCharPoint provides a means of detecting that the Degree symbol is not on the same baseline as the rest of the word.

See Technical Notes below.

Syntax

ASBool PDWordGetCharPoint(PDWord word, ASInt16 byteIdx, ASFixedPoint *point)

Parameters

PDWord word The word whose placement point is obtained
ASInt16 byteIdx The byte index within the word of the character whose placement point is obtained. Valid values are 0 to PDWordGetLength(word)-1
ASFixedPoint *point (Filled by the method) Pointer to the character's placement point, specified in user-space coordinates

Exceptions

  None

Returns

ASBool: Returns a false if the specified character is constructed with multiple bytes and the byteIdx value is not pointing to a byte with a valid quad; true otherwise.

Related Methods

  PDWordGetNthQuadPoint

  PDWordIsLastWordInRegion

Technical Notes

The returned placement point represents the position at which the specified character is placed, taking into account the current transform matrix, the current text matrix, text rise, and other parameters affecting the character’s position. The placement point is specified in user space coordinates, and is the location on the PDF page where the word is drawn. Typically this would be the leftmost point of the word's baseline, although this is not always true.

The values returned from PDWordGetCharPoint may be used to calculate the vector representing the PDWord.  Obtain each character’s font size. Calculate the font size used most often, and collect the list of characters with this font size. If there is no majority font size, use the largest font size in the PDWord. The baseline is a vector extending from the placement position of the first character in the list that you created above, through the placement position of the last character. Superscript and subscript characters will have placement positions which do not lie on the calculated baseline vector. Other normally-placed characters will lie on the baseline, unless the word is not typeset in a straight line (but that situation is currently not supported by this method).

For a PDWord where there is no one font size used most often, the baseline may be calculated as the vector extending from the placement position of the largest letter, through the placement position of the largest character in the next word on the line, and defining the baseline of the last word on a line to be a vector with the same direction as the baseline of the previous word on the line.

PDWordGetNthQuadPoint Header: DLExtrasCalls.h

Description

Gets the specified word's nth quad placement point, specified in user space coordinates.

PDWordGetNthQuadPoint returns true if the word has an nth quad, false otherwise.

Syntax

ASBool PDWordGetNthQuadPoint(PDWord word, ASInt16 nTh, ASFixedPoint *point)

Parameters

PDWord word The word whose nth quad is obtained
ASInt16 nTh The quad placement point to obtain. A word's first quad has an index of zero.
ASFixedPoint *point (Filled by the method) Pointer to the word's nth quad placement point, specified in user-space coordinates.

Exceptions

  None

Returns

  ASBool

Related Methods

   PDWordGetCharPoint

   PDWordIsLastWordInRegion

PDWordIsLastWordInRegion Header: DLExtrasCalls.h

Description

This routine will check whether a word is the last one in a region, as determined by the WordFinder.

Syntax

ASBool PDWordIsLastWordInRegion(PDWord word)

Parameters

PDWord word The word whose position is to be examined

Exceptions

  None

Returns

  ASBool

Related Methods

  PDWordGetCharPoint

  PDWordGetNthQuadPoint

Bypassing the No-Copy Restriction

The DLEnableLicensedBehavior call accepts a key supplied to Adobe PDF Library customers who sign a separate license agreement with Datalogics. This license agreement covers, and the accepted key enables, Copy permission override capability (bypassing the document’s "No Content Copying or Extraction" setting), allowing the application to rasterize PDF pages where content copying or extraction is not allowed.

Implementing this bypass requires several steps to be performed in sequence, after which the application can proceed with its rendering:

  1. Call DLEnableLicensedBehavior with the correct key (provided to you by Datalogics).
  2. Set the Boolean indicator PDPageDrawMParams.bypassCopyPerm to true.
  3. Call PDPageDrawContentsToMemoryWithParams to continue with content rendering.

The important point here is that you should only set DPageDrawMParams.bypassCopyPerm to true if the call to DLEnableLicensedBehavior succeeds.

NOTE: DLEnableLicensedBehavior is intended for use in creating PDF page viewing applications where rendering is required; it is not intended as a bypass for actual extraction of the content.