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 Systems.

ACGetOption

(AC_OptionCode code, ASUns32 *value)
Return Value: AC_Error
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.
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)
Return Value AC_Error
Exceptions
Header DLExtrasCalls.h
Related Methods ACSetOption

ACSetOption

(AC_OptionCode code, ASUns32 value)
Return Value: AC_Error
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.
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
Return Value AC_Error
Exceptions
Header DLExtrasCalls.h
Related Methods ACGetOption

ASSetDefaultFileSys

(ASFileSys fileSys) Return Value: void
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.
Parameters ASFileSys fileSys: Alternate file system to be used
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods

CosStreamSetData

(CosObj stream, ASStm sourceP, ASInt32 sourceStart, ASBool encodeTheSourceData, CosObj attributes, CosObj encodeParms, ASInt32 sourceLength)
Return Value: void
Description The interface is essentially identical to the Adobe PDF Library method CosNewStream, except that the result is a modification of an existing stream.
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 encodeTheSourceData: 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
Return Value void
Exceptions
Header DLExtraProcs.h
Related Methods CosStreamNew

DLEnableLicensedBehavior

(const char * keyVal, const char * additionalInfo)
Return Value: void
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 in the Print Routines section.
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.
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods
Technical Notes
1 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.

PDDocAddJobID

(PDDoc doc, ASUns32 jobId)
Return Value: void
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.
Parameters PDDoc doc: the document whose jobId is being set
ASUns32 jobId: the Print Job ID being added to the document’s list of Job IDs
Return Value void
Exceptions
Header PDProcs.h
Related Methods
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

(PDDoc doc, ASUns32 flags, ASStatusMonitorProcs  statusMon)
Return Value: void
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.
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.
Return Value void
Exceptions
Header DLExtrasCalls.h
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

(PDDoc doc, const PDFont* fonts, ASUns32 nFonts, ASUns32 flags, ASStatusMonitorProcs  statusMon)
Return Value: void
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.
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.
Return Value void
Exceptions
Header DLExtrasCalls.h
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

(PDDoc doc, ASBool enableCompactRDF)
Return Value: ASText
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.
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.
Return Value ASText: The XMP metadata associated with the document pdDoc.
Exceptions pdMetadataErrCouldntCreateMetaXAP
Header PDMetadataProcs.h
Related Methods

PDEContentGetElemsStatus

(PDEContent pdeContent)
Return Value: ASUns32
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.
Parameters PDEContent pdeContent: The PDEContent examined by PDEContentGetNumElems
Return Value ASUns32: Return status:
0: No errors detected
1: Unpaired Marked Content operators (unbalanced MC/EC operators)
Exceptions
Header PERProcs.h
Related Methods PDEContentGetNumElems

PDEFontCheckASTextIsRepresentable

(const  PDEFont font, const ASText text, ASUns32 *index)
Return Value: ASBool
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.
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.
Return Value ASBool
Exceptions
Header DLExtrasCalls.h
Related Methods

PDEFormGetTextState

(PDEForm form, PDETextState *tState)
Return Value: void
Description This API provides access to the Text State in the PDEForm object, returning the PDETextState for the indicated form.
Parameters PDEForm form: The form whose COS object is obtained
PDETextState *tState: The text state associated with this form (Filled by the method)
Return Value void
Exceptions peErrWrongPDEObjectType
Header PERProcs.h
Related Methods PDEFormSetTextState

PDEFormSetTextState

(PDEForm form, PDETextState *tState)
Return Value: void
Description This API provides access to the Text State in the PDEForm object, letting you specify the PDETextState for the indicated form.
Parameters PDEForm form: The form whose COS object is to be set
PDETextState *tState: The text state to be associated with this form
Return Value void
Exceptions  peErrWrongPDEObjectType
Header PERProcs.h
Related Methods PDEFormGetTextState

PDEImageGetColorValue

(PDEImage image, PDEColorValueP color)
Return Value: void
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.
Parameters PDEImage image: The image whose data is retrieved
PDEColorValueP color: The image color data
Return Value void
Exceptions peErrWrongPDEObjectType
Header PERProcs.h
Related Methods PDEImageSetColorValue

PDEImageSetColorValue

(PDEImage image, PDEColorValueP color)
Return Value: void
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.
Parameters PDEImage image: The image whose data is set
PDEColorValueP color: The image color data
Return Value void
Exceptions peErrWrongPDEObjectType
Header PERProcs.h
Related Methods PDEImageGetColorValue
Technical Notes
1 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.
2 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

(PDEPath path, ASFloat *data, ASUns32 dataSize)
Return Value: ASUns32
Description This API will get the size of the path data and, optionally, the path data itself. See Technical Notes below.
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
Return Value ASUns32: The length of the data of path
Exceptions  peErrWrongPDEObjectType
Header PERProcs.h
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

(PDEPath path, ASFloat *data, ASUns32 dataSize)
Return Value: void
Description This API will set new path data for a path element. See Technical Notes below.
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
Return Value void
Exceptions genErrBadParm, peErrWrongPDEObjectType
Header PEWProcs.h
Related Methods PDEPathSetData, PDEPathGetDataFloat
Technical Notes
1 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.

PDETextAddASText

(PDEText pdeText, ASUns32 flags,
ASInt32 index, ASText text, PDEFont font,
PDEGraphicStateP gstateP, ASUns32 gstateLen,
PDETextStateP tstateP, ASUns32 tstateLen,
ASFixedMatrixP textMatrixP)
Return Value: void
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.
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
Return Value void
Exceptions
Header DLExtrasCalls.h
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

(PDEText pdeText, ASUns32 flags, ASInt32 index, ASText text)
Return Value: void
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.
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
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods PDETextAddASText

PDETextItemCopyASText

(PDETextItem textItem, ASText text)
Return Value: void
Description This API will copy the text from a text item. The PDEFont associated with the PDEText must contain a ToUnicode table.
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
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods PDETextItemCreateASText

PDETextItemCreateASText

(ASText text, PDEFont font, PDEGraphicStateP gStateP, ASUns32 gStateLen, PDETextStateP textStateP, ASUns32 textStateLen, ASFixedMatrixP textMatrixP)
Return Value: PDETextItem
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.
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
Return Value PDETextItem
Exceptions genErrBadParm
Header DLExtrasCalls.h
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.

PDFLAddFontDirectories

(ASInt32 pathCount, ASPathName *paths)
Return Value: ASBool
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.
Parameters ASInt32 pathCount: Number of new paths to be addedASPathName *paths: Paths to new resource locations to be added
Return Value ASBool
Exceptions
Header DLExtrasCalls.h
Related Methods PDFLRescanFontDirectories

PDFLReinit (void)

Return Value: ASInt32
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.
Parameters
Return Value ASInt32 (Always 0)
Exceptions
Header PDFLProcs.h
Related Methods
Technical Notes
1 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

(FontRescanFlags  flags)
Return Value: ASBool
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 PDFLAddFontDi- rectories call. Technical Notes below.
Parameters FontRescanFlags flags: Flags controlling rescan process. See Technical Notes below.
Return Value ASBool
Exceptions
Header DLExtrasCalls.h
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.

PDPageDrawContentsToMemoryWithParams

(PDPage page, PDPageDrawMParams drawParams)
Return Value: ASSize_t
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.

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.
Return Value ASSize_t
Exceptions
Header DLExtrasCalls.h
Related Methods PDPageDrawContentsToMemory, PDPageDrawContentsToWindowWithParams
 Technical Notes
1 The default assumed color profile for uncalibrated RGB input/output is Adobe sRGB.
2 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

(PDPage page, PDPageDrawWParams drawParams)
Return Value: void
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.
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
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods PDPageDrawContentsToMemoryWithParams

PDPageSetBlendingProfile

(PDPage page,  AC_Profile profile)
Return Value: void
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.
Parameters PDPage page: The PDPage to be rendered
AC_Profile profile: Color blending profile to be used
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods

PDPrefGetAllowOpeningXFA  (void)

Return Value: ASBool
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.
Parameters
Return Value ASBool
Exceptions
Header DLExtrasCalls.h
Related Methods PDPrefSetAllowOpeningXFA

PDPrefGetAllowRelaxedSyntax (void)

Return Value: ASBool
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).
Parameters
Return Value ASBool
Exceptions
Header DLExtrasCalls.h
Related Methods PDPrefSetAllowRelaxedSyntax

PDPrefGetDefaultIntentToProfile (void)

Return Value: ASBool
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.
Parameters void
Return Value ASBool
Exceptions
Header DLExtrasCalls.h
Related Methods PDPrefSetDefaultIntentToProfile

PDPrefSetAllowOpeningXFA (ASBool flag)

Return Value: void
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.
Parameters ASBool flag: When true, this will allow Adobe PDF Library to open XFA PDF documents
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods PDPrefGetAllowOpeningXFA
 Technical Notes
1 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 (ASBool flag)

Return Value: void
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).
Parameters ASBool flag: When true, this will allow Adobe PDF Library to attempt to resolve or ignore minor PDF document errors
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods PDPrefGetAllowRelaxedSyntax

PDPrefSetDefaultIntentToProfile (ASBool flag)

Return Value: void
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.
Parameters ASBool flag: If true, use intent specified in the profile. (Default false)
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods PDPrefGetDefaultIntentToProfile

PDPrefSuppressDefaultCMYKCalibration (ASBool flag)

Return Value: void
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.
Parameters ASBool flag: Setting this flag to true will suppress the Adobe-defined Default color profile.
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods PDPrefSuppressDefaultGrayCalibration, PDPrefSuppressDefaultRGBCalibration

PDPrefSuppressDefaultGrayCalibration (ASBool flag)

Return Value: void
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.
Parameters ASBool flag: Setting this flag to true will suppress the Adobe-defined Default color profile.
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods PDPrefSuppressDefaultCMYKCalibration, PDPrefSuppressDefaultRGBCalibration

PDPrefSuppressDefaultRGBCalibration (ASBool flag)

Return Value: void
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.
Parameters ASBool flag: Setting this flag to true will suppress the Adobe-defined Default color profile.
Return Value void
Exceptions
Header DLExtrasCalls.h
Related Methods PDPrefSuppressDefaultCMYKCalibration, PDPrefSuppressDefaultGrayCalibration

PDWordGetCharPoint

(PDWord word, ASInt16 byteIdx, ASFixedPoint *point)
Return Value: ASBool
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.
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
Return Value 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.
Exceptions
Header DLExtrasCalls.h
Related Methods PDWordGetNthQuadPoint, PDWordIsLastWordInRegion
Technical Notes
1 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.
2 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).
3 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

(PDWord word, ASInt16 nTh, ASFixedPoint *point)
Return Value: ASBool
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.
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.
Return Value ASBool
Exceptions
Header DLExtrasCalls.h
Related Methods PDWordGetCharPoint, PDWordIsLastWordInRegion

PDWordIsLastWordInRegion

(PDWord word)
Return Value: ASBool
Description This routine will check whether a word is the last one in a region, as determined by the WordFinder.
Parameters PDWord word: The word whose position is to be examined
Return Value AsBool
Exceptions
Header DLExtrasCalls.h
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:

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

  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.