spdf routines

May 1, 2001

1 of 27

SPDF API Support (Build 1037)

Roger Dunn

The SPDF library supports a number of the routines defined in the Core API Reference to Adobe’s Acrobat Software Development Kit. This document provides a complete list of the supported routines.

Notes:

(1) A level of implementation support is given for each routine listed below. The level of support is color-coded, with the following legend:

(2) New routines are added with each SPDF successive release. Also, routines with par-tial or no implementation are moved to full implementation. Licensees are encouraged to review this document and the SPDF “read me” document for details related to ongo-ing SPDF development.

■ Full implementation

■ Partial implementation, may throw an exception under cer-tain conditions; any limitations noted

■ Defined in the interface and available for linkage, but not yet implemented. Will throw an exception if called.

AS Layer

2 of 27 SPDF API Support (Build 1037)

1.0 AS Layer

1.1 Fixed Math Routines

1.2 Memory Management Routines

1.3 Configuration Routines

1.4 ASPathName Routines

1.5 ASAtom Routines

FixedRoundToInt16 ■

FixedRoundToInt32 ■

FixedToFloat ■

FixedTruncToInt32 ■

FloatToFixed ■

Int16ToFixed ■

Int32ToFixed ■

ASCStringToFixed ■

ASFixedDiv ■

ASFixedMul ■

ASFixedMatrixConcat ■

ASFixedMatrixTransform ■

ASFixedMatrixTransformRect ■

ASFixedToCString ■

ASmalloc ■

ASrealloc ■

ASfree ■

ASGetConfiguration ■ Note: Product key returns “SPDF” and Version key returns current build number

ASPathFromPlatformPath ■

ASAtomExistsForString ■

ASAtomFromString ■

ASAtomGetString ■

AS Layer

SPDF API Support (Build 1037) 3 of 27

1.6 ASFile Routines

1.7 SPDF-specific addition to ASFile Routines

The following routines is an SPDF-specific addition to the Adobe Core API Reference. This additions facilitates searching an ASFile for a given pattern. Note: because this API is an extensions, and does not exist in Adobe’s plug-in SDK, application code using this routine will not be portable back to the Acrobat plug-in SDK unless you provide your own implementation of this routine for the plug-in environment.

ASFileAcquirePathName ■

ASFileClose ■

ASFileFlush ■

ASFileFromMDFile ■

ASFileGetEOF ■

ASFileGetFileSys ■

ASFileGetMDFile ■

ASFileGetPos ■

ASFileIsBusy ■

ASFileRead ■

ASFileSetEOF ■

ASFileSetPos ■

ASFileWrite ■

ASFileFindPattern ■

AS Layer

4 of 27 SPDF API Support (Build 1037)

1.8 ASFileSys Routines

1.9 ASStm Routines

1.10 Error Handling Routines and Macros

ASFileGetFileSysByName ■

ASFileRegisterFileSys ■

ASFileUnregisterFileSys ■

ASFileSysCopyPath ■

ASFileSysCreatePathName ■

ASFileSysDIPathFromPath ■

ASFileSysOpenFile ■

ASFileSysPathFromDIPath ■

ASFileSysReleasePath ■

ASGetDefaultFileSys ■

ASFileStmRdOpen ■

ASMemStmRdOpen ■

ASProcStmRdOpen ■

ASStmRead ■

ASStmClose ■

ACROsetjmp ■

ACROlongjmp ■

ACROjmp_buf ■

DURING ■

HANDLER ■

END_HANDLER ■

E_RETURN ■

E_RTRN_VOID ■

ASRaise ■

ASGetErrorString ■

ASPushExceptionFrame ■

ASPopExceptionFrame ■

ASGetErrorCode ■

ASGetExceptionErrorCode ■

AS Layer

SPDF API Support (Build 1037) 5 of 27

1.11 Callback Routines and Macros

ASCallbackCreateProto ■

ASCallbackDestroy ■

ASCallbackCreateNotification ■

Cos Layer

6 of 27 SPDF API Support (Build 1037)

2.0 Cos Layer

2.1 Basic CosObj Routines

2.2 CosDoc Routines

2.3 CosDict(ionary) Routines

CosNewNull ■

CosObjCopy ■

CosObjCopyShallow ■ (this routine is exclusive to SPDF)

CosObjDestroy ■

CosObjEnum ■

CosObjEqual ■

CosObjGetDoc ■

CosObjGetGeneration ■

CosObjGetID ■

CosObjGetType ■

CosObjIsIndirect ■

CosDecryptData ■

CosEncryptData ■

CosDocClose ■

CosDocCreate ■

CosDocEnumIndirect ■

CosDocGetInfoDict ■

CosDocGetObjByID ■

CosDocGetRoot ■

CosDocOpenWithParams ■

CosDocSaveToFile ■

CosNewDict ■

CosDictGet ■

CosDictKnown ■

CosDictPut ■

CosDictRemove ■

Cos Layer

SPDF API Support (Build 1037) 7 of 27

2.4 SPDF-specific additions to CosDict(ionary) Routines

The following routines are SPDF-specific additions to the Adobe Core API Reference. These additions facilitate type-safe use of CosObjects held within dictionaries. Note: because these APIs are extensions, and do not exist in Adobe’s plug-in SDK, applica-tion code using these routines will not be portable back to the Acrobat plug-in SDK unless you provide your own implementations of these routines for the plug-in environ-ment. However, for stand-alone executables, the runtime validation provided by these routines can help to take a lot of the guesswork out of using CosDictionary values.

CosDictGetArray ■

CosDictGetBoolean ■

CosDictGetDict ■

CosDictGetName ■

CosDictGetNumber ■

CosDictGetStream ■

CosDictGetString ■

CosDictGetBooleanValue ■

CosDictGetNameValue ■

CosDictGetFixedValue ■

CosDictGetIntegerValue ■

CosDictGetIntegerValueNullAllowed ■

CosDictGetStringValue ■

CosDictGetRectFromArray ■

CosDictPutNewArray ■

CosDictPutNewArrayFromRect ■

CosDictPutNewBoolean ■

CosDictPutNewDict ■

CosDictPutNewName ■

CosDictPutNewFixed ■

CosDictPutNewInteger ■

CosDictPutNewStream ■

CosDictPutNewString ■

Cos Layer

8 of 27 SPDF API Support (Build 1037)

2.5 CosArray Routines

2.6 SPDF-specific additions to CosArray Routines

The following routines are SPDF-specific additions to the Adobe Core API Reference. These additions facilitate type-safe use of CosObjects held within arrays. Note: because these APIs are extensions, and do not exist in Adobe’s plug-in SDK, application code using these routines will not be portable back to the Acrobat plug-in SDK unless you provide your own implementations of these routines for the plug-in environment. How-ever, for stand-alone executables, the runtime validation provided by these routines can help to take a lot of the guesswork out of using CosArray values.

CosNewArray ■

CosArrayLength ■

CosArrayGet ■

CosArrayInsert ■

CosArrayPut ■

CosArrayRemove ■

CosArrayRemoveNth ■

CosArrayGetArray ■

CosArrayGetBoolean ■

CosArrayGetDict ■

CosArrayGetName ■

CosArrayGetNumber ■

CosArrayGetStream ■

CosArrayGetString ■

CosArrayGetBooleanValue ■

CosArrayGetNameValue ■

CosArrayGetFixedValue ■

CosArrayGetIntegerValue ■

CosArrayGetIntegerValueNullAllowed ■

CosArrayGetStringValue ■

Cos Layer

SPDF API Support (Build 1037) 9 of 27

2.7 CosString Routines

2.8 CosName Routines

2.9 CosBoolean Routines

2.10 CosInteger Routines

2.11 CosFixed Routines

2.12 CosStream Routines

CosNewString ■

CosStringGetHexFlag ■

CosStringSetHexFlag ■

CosStringValue ■

CosNewName ■

CosNameValue ■

CosBooleanValue ■

CosNewBoolean ■

CosIntegerValue ■

CosNewInteger ■

CosFixedValue ■

CosNewFixed ■

CosNewStream ■

CosStreamDict ■

CosStreamLength ■

Cos Layer

10 of 27 SPDF API Support (Build 1037)

CosStreamOpenStm ■ implemented for cosOpenRaw; cos-OpenUnfiltered decrypts if RC4 is pro-vided via SPDF_RC4Linkage.cpp; cosOpenFiltered is available for ASCII-HexEncode, ASCII85Encode, Run-

LengthEncode and FlateEncodea, can be made available for LZWEncode via SPDF_LZWLinkage.cpp, but not yet available for CCITTFaxEncode or DCTEncode.

CosStreamPos ■

a. Thank you to Jean-loup Gailly and Mark Adler for permission to include and redistribute zlib compression/decompression.

PD Layer

SPDF API Support (Build 1037) 11 of 27

3.0 PD Layer

3.1 PD General Routines

3.2 PDAction Routines

3.3 PDAnnot Routines

PDRegisterCryptHandler ■

PDRegisterCryptHandlerEx ■

PDActionDestroy ■

PDActionEqual ■

PDActionFromCosObj ■

PDActionGetCosObj ■

PDActionGetDest ■

PDActionGetFileSpec ■

PDActionGetSubtype ■

PDActionIsValid ■

PDActionNew ■

PDActionNewFromDest ■

PDActionNewFromFileSpec ■

PDAnnotEqual ■

PDAnnotFromCosObj ■

PDAnnotGetColor ■

PDAnnotGetCosObj ■

PDAnnotGetDate ■

PDAnnotGetFlags ■

PDAnnotGetRect ■

PDAnnotGetSubtype ■

PDAnnotGetTitle ■

PDAnnotIsValid ■

PDAnnotSetColor ■

PDAnnotSetDate ■

PDAnnotSetFlags ■

PD Layer

12 of 27 SPDF API Support (Build 1037)

PDAnnotSetRect ■

PDAnnotSetTitle ■

PD Layer

SPDF API Support (Build 1037) 13 of 27

3.4 PDBead Routines

3.5 PDBookmark Routines

PDBeadAcquirePage ■

PDBeadDestroy ■

PDBeadEqual ■

PDBeadFromCosObj ■

PDBeadGetCosObj ■

PDBeadGetIndex ■

PDBeadGetNext ■

PDBeadGetPrev ■

PDBeadGetRect ■

PDBeadGetThread ■

PDBeadInsert ■

PDBeadIsValid ■

PDBeadNew ■

PDBeadSetPage ■

PDBeadSetRect ■

PDBookmarkAddChild ■

PDBookmarkAddNewChild ■

PDBookmarkAddNewSibling ■

PDBookmarkAddNext ■

PDBookmarkAddPrev ■

PDBookmarkAddSubtree ■

PDBookmarkDestroy ■

PDBookmarkEqual ■

PDBookmarkFromCosObj ■

PDBookmarkGetAction ■

PDBookmarkGetByTitle ■

PDBookmarkGetCosObj ■

PDBookmarkGetCount ■

PDBookmarkGetFirstChild ■

PDBookmarkGetIndent ■

PDBookmarkGetLastChild ■

PD Layer

14 of 27 SPDF API Support (Build 1037)

PDBookmarkGetNext ■

PDBookmarkGetParent ■

PDBookmarkGetPrev ■

PDBookmarkGetTitle ■

PDBookmarkHasChildren ■

PDBookmarkIsOpen ■

PDBookmarkIsValid ■

PDBookmarkSetAction ■

PDBookmarkSetOpen ■

PDBookmarkSetTitle ■

PDBookmarkUnlink ■

PD Layer

SPDF API Support (Build 1037) 15 of 27

3.6 PDDoc Routines

PDDocAcquire ■

PDDocAcquirePage ■

PDDocAuthorize ■

PDDocClearFlags ■

PDDocClose ■

PDDocCreate ■

PDDocCreatePage ■

PDDocCreateWordFinder ■ implemented in SPDF_CP

PDDocDeletePages ■

PDDocEnumFonts ■

PDDocFindPageNumForLabel ■

PDDocFromCosDoc ■

PDDocGetBookmarkRoot ■

PDDocGetCosDoc ■

PDDocGetFile ■

PDDocGetFlags ■

PDDocGetID ■

PDDocGetInfo ■

PDDocGetLabelForPageNum ■

PDDocGetNewCryptHandler ■

PDDocGetNewSecurityData ■

PDDocGetNewSecurityInfo ■

PDDocGetNumPages ■

PDDocGetNumThreads ■

PDDocGetPageMode ■

PDDocGetPermissions ■

PDDocGetSecurityData ■

PDDocGetThread ■

PDDocGetThreadIndex ■

PDDocGetVersion ■

PDDocInsertPages ■ fully implemented except for copying threads (which are very rare)

PDDocNewSecurityData ■

PDDocOpen ■

PD Layer

16 of 27 SPDF API Support (Build 1037)

PDDocOpenEx ■

PDDocRelease ■

PDDocSave ■

PDDocSetFlags ■

PDDocSetInfo ■

PDDocSetNewCryptHandler ■

PDDocSetNewSecurityData ■

PDDocSetPageMode ■

PD Layer

SPDF API Support (Build 1037) 17 of 27

3.7 PDFont Routines

3.8 PDInlineImage Routines

3.9 PDLinkAnnot Routines

3.10 PDPage Routines

PDFontFromCosObj ■

PDFontGetCosObj ■

PDFontGetWidths ■

PDFontGetMetrics ■

PDFontGetName ■

PDFontGetSubtype ■

PDInlineImageGetAttrs ■

PDInlineImageGetData ■

CastToPDLinkAnnot ■

PDLinkAnnotGetAction ■

PDLinkAnnotSetAction ■

PDLinkAnnotSetBorder ■

PDPageAddAnnot ■

PDPageAddCosContents ■

PDPageAddCosResource ■

PDPageAddNewAnnot ■

PDPageCreateAnnot ■

PDPageEnumResources ■

PDPageGetAnnot ■

PDPageGetAnnotIndex ■

PDPageGetBBox ■

PDPageGetCosObj ■

PDPageGetCosResources ■

PDPageGetCropBox ■

PDPageGetDefaultMatrix ■

PDPageGetDoc ■

PDPageGetMediaBox ■

PD Layer

18 of 27 SPDF API Support (Build 1037)

PDPageGetNumAnnots ■

PDPageGetNumber ■

PDPageGetRotate ■

PDPageNotifyContentsDidChange ■

PDPageNotifyContentsDidChangeEx ■

PDPageNumFromCosObj ■

PDPageRelease ■

PDPageRemoveAnnot ■

PDPageRemoveCosContents ■

PDPageRemoveCosResource ■

PD Layer

SPDF API Support (Build 1037) 19 of 27

3.11 PDTextSelect Routines

3.12 PDThread Routines

3.13 PDViewDest Routines

3.14 PDWord Routines

3.15 PDWordFinder Routines

PDTextSelectCreatePageHilite ■

PDThreadDestroy ■

PDThreadFromCosObj ■

PDThreadGetCosObj ■

PDThreadGetFirstBead ■

PDThreadGetInfo ■

PDThreadIsValid ■

PDThreadNew ■

PDThreadSetFirstBead ■

PDThreadSetInfo ■

PDViewDestCreate ■

PDViewDestFromCosObj ■

PDViewDestGetAttr ■

PDViewDestGetCosObj ■

PDViewDestIsValid ■

PDViewDestResolve ■

PDWordGetCharOffset ■ implemented in SPDF_CP

PDWordGetNthQuad ■ implemented in SPDF_CP

PDWordGetNumQuads ■ implemented in SPDF_CP

PDWordGetString ■ implemented in SPDF_CP

PDWordFinderAcquireWordList ■ implemented in SPDF_CP

PDWordFinderDestroy ■ implemented in SPDF_CP

PDWordFinderReleaseWordList ■ implemented in SPDF_CP

PD Layer

20 of 27 SPDF API Support (Build 1037)

3.16 PDXObject Routines

PDXObjectGetCosObj ■

PDXObjectGetSubtype ■

PDFL Layer

SPDF API Support (Build 1037) 21 of 27

4.0 PDFL Layer

4.1 PDFL Routines

PDFLGetVersion ■

PDFLInit ■

PDFLTerm ■

FDF Layer

22 of 27 SPDF API Support (Build 1037)

5.0 FDF Layer

FDF routines are not conventionally considered part of the Core Reference. However, to better support forms-processing applications, SPDF implements the essential routines for opening and traversing the FDF file structure. Using the SPDF implementation eliminates the need for the FDF toolkit library.

5.1 FDF Routines

FDFInitialize ■

FDFFinalize ■

FDFGetVersion ■

FDFOpen ■

FDFClose ■

FDFEnumValues ■

FDFNextFieldName ■

FDFGetValue ■

AV Layer

SPDF API Support (Build 1037) 23 of 27

6.0 AV Layer

The AV layer provides user interface support for Acrobat plug-ins. These routines are not applicable for the stand-alone applications for which SPDF was designed. As a jumpstart for developers, SPDF provides many of these routines.

It is desirable to be able to build both the plug-in and stand-alone versions of an applica-tion out of the same body of source code. Ideally, the application code would be sepa-rated into code utilizing the PD and lower layers, and the plug-in code that relies on the higher-level AV layer. However, since most Acrobat code begins as a plug-in and per-haps later evolves into an additional stand-alone version, this separation is not in place when the stand-alone version commences.

To facilitate this migration, SPDF provides the interface and linkage for many of the commonly used AV routines. Plug-ins can be compiled and linked against SPDF and then more optimally structured over time, typically by adding command line arguments and then calling into lower-level code. Calling the SPDF implementation of AV layer routines will throw an exception, which facilitates the process of ultimately separating out the GUI and non-GUI layers of application logic.

AV Layer

24 of 27 SPDF API Support (Build 1037)

6.1 AVApp Routines

6.2 AVDocRoutines

6.3 AVMenu Routines

AVAppBeginModal ■

AVAppEndModal ■

AVAppEnumDocs ■

AVAppGetActiveDoc ■

AVAppGetDocProgressMonitor ■

AVAppGetLanguage ■

AVAppGetMenubar ■

AVAppGetToolBar ■

AVAppGetVersion ■

AVAppRegisterActionHandler ■

AVAppRegisterAnnotHandler ■

AVAppRegisterNotification ■

AVAppSetPreference ■

AVAppUnregisterNotification ■

AVDocClearSelection ■

AVDocClose ■

AVDocGetAVWindow ■

AVDocGetPageView ■

AVDocGetPDDoc ■

AVDocGetSelection ■

AVDocGetSelectionType ■

AVDocOpenFromFile ■

AVDocOpenFromFileWithParams ■

AVDocSetSelection ■

AVDocShowSelection ■

AVMenuAcquireMenuItemByIndex ■

AVMenuAddMenuItem ■

AVMenuGetMenuItemIndex ■

AVMenuGetNumMenuItems ■

AV Layer

SPDF API Support (Build 1037) 25 of 27

AVMenuNew ■

AVMenuRelease ■

AV Layer

26 of 27 SPDF API Support (Build 1037)

6.4 AVMenubar Routines

6.5 AVMenuItem Routines

6.6 AVPageView Routines

AVMenubarAcquireMenuByName ■

AVMenubarAcquireMenuItemByName ■

AVMenubarAddMenu ■

AVMenubarGetMenuIndex ■

AVMenuItemAcquireSubmenu ■

AVMenuItemExecute ■

AVMenuItemGetName ■

AVMenuItemGetParentMenu ■

AVMenuItemGetTitle ■

AVMenuItemIsEnabled ■

AVMenuItemNew ■

AVMenuItemRelease ■

AVMenuItemRemove ■

AVMenuItemSetComputeEnabledProc ■

AVMenuItemSetExecuteProc ■

AVMenuItemSetTitle ■

AVPageViewAcquireMachinePort ■

AVPageViewDevicePointToPage ■

AVPageViewDrawNow ■

AVPageViewGetAnnotRect ■

AVPageViewGetAperture ■

AVPageViewGetAVDoc ■

AVPageViewGetPage ■

AVPageViewGetPageNum ■

AVPageViewGoTo ■

AVPageViewInvalidateRect ■

AVPageViewPageNumIsVisible ■

AVPageViewRectToDevice ■

AV Layer

SPDF API Support (Build 1037) 27 of 27

6.7 AVSys Routines

6.8 AVToolBar Routines

6.9 AVToolButton Routines

6.10 AVWindow Routines

AVPageViewReleaseMachinePort ■

AVPageViewUseThisDestination ■

AVSysGetCursor ■

AVSysGetStandardCursor ■

AVSysSetCursor ■

AVToolBarAddButton ■

AVToolBarGetButtonByName ■

AVToolButtonGetFlyout ■

AVToolButtonNew ■

AVToolButtonRemove ■

AVToolButtonSetComputeEnabledProc ■

AVToolButtonSetExecuteProc ■

AVToolButtonSetExternal ■

AVToolButtonSetHelpText ■

AVWindowDestroy ■

AVWindowGetPlatformThing ■

AVWindowGetTitle ■

AVWindowNew ■