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
- 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."
- 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.
- 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
- 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.
- Created fonts must have a PDSysEncoding value of Identity-H or Identity-V, and should be created via the PDEFontCreateFromSysFontAndEncoding API.
- Fonts should be created with the kPDEFontCreateEmbedded, kPDEFontCreateSubset, kPDEFontCreateToUnicode and kPDEFontEncodeByGID flags in effect.
- PDEFontCheckASTextIsRepresentable can be used to verify that valid glyphs are available for a Unicode string.
- 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
- Passing an ASText containing an empty string will return a genErrBadParm exception.
- PDFEdit ignores the wasSetFlags flag of the PDETextState structure, so you must initialize the PDETextState fields.
- 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: | |
|
||
| 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
- 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.
- 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:
- Call DLEnableLicensedBehavior with the correct key (provided to you by Datalogics).
- Set the Boolean indicator PDPageDrawMParams.bypassCopyPerm to true.
- 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.