From 43d65dc03325bcce8561423b9607f7e114355f7d Mon Sep 17 00:00:00 2001 From: ferbas Date: Wed, 13 Jan 2010 09:41:29 +0000 Subject: initial import git-svn-id: https://joinup.ec.europa.eu/svn/pdf-as/trunk@545 7b5415b0-85f9-ee4d-85bd-d5d0c3b42d1c --- .../sources/import/API/ASExpT.h | 3985 ++++++++++++++++++++ 1 file changed, 3985 insertions(+) create mode 100644 Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/ASExpT.h (limited to 'Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/ASExpT.h') diff --git a/Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/ASExpT.h b/Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/ASExpT.h new file mode 100644 index 0000000..9b1d04c --- /dev/null +++ b/Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/ASExpT.h @@ -0,0 +1,3985 @@ +/********************************************************************* + + ADOBE SYSTEMS INCORPORATED + Copyright (C) 1994-2007 Adobe Systems Incorporated + All rights reserved. + + NOTICE: Adobe permits you to use, modify, and distribute this file + in accordance with the terms of the Adobe license agreement + accompanying it. If you have received this file from a source other + than Adobe, then your use, modification, or distribution of it + requires the prior written permission of Adobe. + + --------------------------------------------------------------------- + + ASExpT.h + + - Types, macros, structures, etc. required to use the AcroSupport HFT. + +*********************************************************************/ + +#ifndef _H_ASExpT +#define _H_ASExpT + +#include "CoreExpT.h" +#include "acroassert.h" + +#if MAC_PLATFORM +#if defined(__MWERKS__) +#include +#include +#else +#include +#include +#endif +#endif + +#if PRAGMA_STRUCT_ALIGN + #pragma options align=power +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/* define types based on SDK_LEVEL */ + +/** File access modes used to specify how a file can be used when it is open. Not all modes can + be specified individually: ASFILE_CREATE can be used only in conjunction with + ASFILE_READ or ASFILE_WRITE. In addition, it is acceptable to specify + ASFILE_READ and ASFILE_WRITE together by OR-ing the two constants. + ASFILE_SERIAL and ASFILE_LOCAL (present only in version 3.0 or later) are hints that + help the Acrobat viewer optimize access to the file; they must be OR-ed with one or more + of the other constants: + + + + + + + +
ValueDescription
ASFILE_READOpen the file for reading.
ASFILE_WRITEOpen the file for writing.
ASFILE_CREATECreate the file if it does not exist.
ASFILE_SERIALA hint indicating that the file will be accessed sequentially.
ASFILE_LOCALA hint indicating that a local copy of the file will be needed.
+ @see ASFileSysOpenFile + @see ASFileReopen +*/ +typedef ASUns16 ASFileMode; + +/** + A file position value for use in callback procedures. This value cannot exceed 2 GB. + @see CosObjOffsetProc +*/ +typedef ASUns32 ASFilePos; + +/** + A file offset value for use in callback procedures. + @see CosDocEnumEOFsProc +*/ +typedef ASInt32 ASFileOffset; + +/** The absolute position within a file. This value can exceed 2 GB. */ +typedef ASUns64 ASFilePos64; + +/** + An error code value for use in ASFile and ASFileSys methods + and callbacks. Introduced in Acrobat 6.0. +*/ +typedef ASInt32 ASErrorCode; + +/** + A byte count value for use in ASProcStmRdExHandler and ASFileSysItemProps. + @see ASUUIDGenFromName +*/ +typedef ASUns32 ASByteCount; + +/** + An array size value for use in callback procedures. + @see AVDocSelectionAcquireQuadsProc + @see CosObjOffsetProc +*/ +typedef ASUns32 ASArraySize; + +/** + A flag-bits value. + @see ASFileSetMode + @see CosDocCreate + @see CosDocSaveToFile + @see CosDocSaveWithParams + @see HFTReplaceEntry + @see HFTReplaceEntryEx + @see PDAnnotInfo + @see ASFileSysGetFileFlags + @see ASFileSysGetStatusProc + @see PDAnnotHandlerGetAnnotInfoFlagsProc +*/ +typedef ASUns32 ASFlagBits; + +/** Can only contain values up to 4 GB. */ +typedef ASUns32 ASDiskSpace; + +/** */ +typedef ASUns64 ASDiskSpace64; + +/** */ +typedef ASUns32 ASlFileMode; + +/** */ +typedef ASUns32 ASMaskBits; + +/** */ +typedef ASInt32 ASDuration; + +/** + An HFT version number. + @see ASExtensionMgrGetHFT + @see HFTServerProvideHFTProc + @see HFTGetVersion +*/ +typedef ASUns32 ASVersion; + +/** May not be larger than int16. */ +typedef ASUns16 ASSmallBufferSize; + +/** + A numeric count value. + @see ASGetSecs + @see ASIsValidUTF8 + @see AVAppCreateIconBundle6 + @see AVDocGetNthPageView + @see AVDocGetNumPageViews +*/ +typedef ASUns32 ASCount; + +/** */ +typedef ASUns8 ASByte; + +/* types that may transition to unsigned types */ + +/** A signed int value. Negative values are never used. */ +typedef ASInt16 ASSmallCount; + +/** + A numeric count value for use in I/O methods and data structures. + + @see ASFileGetEOF + @see ASFileGetPos + @see ASFilePushData + @see ASFileSetPos + @see ASFileCompletionProc + @see ASFileSysMReadRequestProc +*/ +typedef ASInt32 ASTFilePos; + +/** + A numeric array size value for use in AS and Cos-level I/O + methods and data structures. + @see numerous + @see ASFileCompletionProc + @see ASFileSysGetNameProc + @see ASFileSysMReadRequestProc + @see ASStmProc +*/ +typedef ASInt32 ASTArraySize; + +/** + A cryptographic version number. + @see CosCryptGetVersion + @see CosDecryptGetMaxKeyBytes + @see CosEncryptGetMaxKeyBytes +*/ +typedef ASInt32 ASTVersion; + +/** + A numeric count value for use in stream methods. + @see ASIsValidUTF8 + @see ASStmFlush + @see ASStmRead + @see ASStmWrite + @see CosCopyStringValue + @see CosDocGetID + @see CosStreamPos + @see CosStringValue + @see CosStringValueSafe + @see HFTNew + @see ASStmProc +*/ +typedef ASInt32 ASTCount; +#if !defined(ACRO_SDK_LEVEL) || (ACRO_SDK_LEVEL < 0x00090000) +#pragma message("Warning: Using older Acrobat SDK. Define ACRO_SDK_LEVEL to 0x00090000") +#endif + +#if !defined(ACRO_SDK_LEVEL) || (ACRO_SDK_LEVEL < 2) +/** + A coordinate for a point in device space, for use in mouse click + callbacks. Values are conditionally compiled as 16-bit or + 32-bit integers, depending on the Acrobat version. + + @see ASGetSecs + @see ASIsValidUTF8 + @see AVAppCreateIconBundle6 + @see AVDocGetNthPageView + @see AVDocGetNumPageViews +*/ +typedef ASInt16 ASCoord; +#else + +/** + A coordinate for a point in device space, for use in mouse click + callbacks. Values are conditionally compiled as 16-bit or + 32-bit integers, depending on the Acrobat version. + + @see ASGetSecs + @see ASIsValidUTF8 + @see AVAppCreateIconBundle6 + @see AVDocGetNthPageView + @see AVDocGetNumPageViews +*/ +typedef ASInt32 ASCoord; + + +#if 0 + /* potential future transitions */ +typedef ASUns16 ASSmallCount; +typedef ASUns32 ASTFilePos; +typedef ASUns32 ASTArraySize; /*elements in array */ +typedef ASUns32 ASTVersion; +typedef ASUns32 ASTCount; +#endif + +#endif /* ...ACRO_SDK_LEVEL < 2 */ + + +/** */ +typedef ASEnum8 ASErrSeverity; + + +/** A stream object definition (see ASStream.h). + It is a data stream that may be a buffer in memory, a file, or an arbitrary user-written + procedure. It is typically used to extract data from a PDF file. When writing or extracting + data streams, the ASStm must be connected to a Cos stream. + @see ASFileStmRdOpen + @see ASFileStmWrOpen + @see ASMemStmRdOpen + @see ASProcStmRdOpen + @see CosStreamOpenStm + @see ASStmClose +*/ +typedef struct _t_ASStmRec ASStmRec, *ASStm; +#define ASCRYPTSTM_EOF (-1) + +/* ASCryptStm is essentially ASStm object for security handler plug-in. +** ASCryptStm callbacks are trapped by PD layer and converted into ASStm. +** See PDRegisterCryptFilter() definition on how ASCryptStm is used. +** +** These #define are used for setting modeFlag in ASCryptStmRec structure. For decryption, read flag, +** for encryption, write flag should be set. EOF and error flag should also be set as appropriate. +*/ +#define ASCryptStmModeRead 0x0001 +#define ASCryptStmModeWrite 0x0002 +#define ASCryptStmModeEOF 0x0004 +#define ASCryptStmModeError 0x0008 + +/** + An ASStm object cover used for a cryptographic filter's + stream callbacks. + @see PDCryptFilterStreamProc +*/ +typedef struct _t_ASCryptStmRec *ASCryptStm; + +/* Prototypes for ASCryptStm callback routines */ + +/** + A callback for ASCryptStm. This is called by getc when the buffer is empty. + It is called only during decryption (when reading from the stream, not when writing). + @param pistm The security stream to fill. + @return 0 when successful, a non-zero error code otherwise. + @see ASCryptStmFCloseProc + @see ASCryptStmFFlushProc + @see ASCryptStmFlsBufProc + @see ASCryptStmFPutEOFProc + @see ASCryptStmFResetProc + @see ASCryptStmUnGetcProc +*/ +typedef ASInt32 (*ASCryptStmFilBufProc)(ASCryptStm pistm); + +/** + A callback for ASCryptStm. This is called by putc when the buffer is full. + It is called only during encryption (when writing to the stream, not when reading). + @param ch The character being written to the full stream. + + @param stm The security stream that is full. + @return 0 when successful, a non-zero error code otherwise. + @see ASCryptStmFCloseProc + @see ASCryptStmFFlushProc + @see ASCryptStmFilBufProc + @see ASCryptStmFPutEOFProc + @see ASCryptStmFResetProc + @see ASCryptStmUnGetcProc +*/ +typedef ASInt32 (*ASCryptStmFlsBufProc)(ASInt32 ch, ASCryptStm stm); + +/** + A callback for ASCryptStm. It goes back one character in the + input stream, undoing a character get operation. It is called + only during decryption (when reading from the stream, not when writing). + @param ch The character being written to the stream. + @param stm The security stream to which the character + is written. + @return 0 when successful, a non-zero error code otherwise. + @see ASCryptStmFCloseProc + @see ASCryptStmFFlushProc + @see ASCryptStmFilBufProc + @see ASCryptStmFlsBufProc + @see ASCryptStmFPutEOFProc + @see ASCryptStmFResetProc +*/ +typedef ASInt32 (*ASCryptStmUnGetcProc)(ASInt32 ch, ASCryptStm stm); + +/** + A callback for ASCryptStm. This flushes a dirty buffer if necessary. + + @param stm The security stream to be flushed. + @return 0 when successful, a non-zero error code otherwise. + @see ASCryptStmFCloseProc + @see ASCryptStmFilBufProc + @see ASCryptStmFlsBufProc + @see ASCryptStmFPutEOFProc + @see ASCryptStmFResetProc + @see ASCryptStmUnGetcProc +*/ +typedef ASInt32 (*ASCryptStmFFlushProc)(ASCryptStm stm); + +/** + A callback for ASCryptStm. This closes a security stream. + @param stm The security stream to be closed. + @return 0 when successful, a non-zero error code otherwise. + @see ASCryptStmFFlushProc + @see ASCryptStmFilBufProc + @see ASCryptStmFlsBufProc + @see ASCryptStmFPutEOFProc + @see ASCryptStmFResetProc + @see ASCryptStmUnGetcProc +*/ +typedef ASInt32 (*ASCryptStmFCloseProc)(ASCryptStm stm); + +/** + A callback for ASCryptStm. This resets a security stream, discarding + any buffered data. It is called only during encryption (when writing to the stream, not when reading). + @param stm The security stream to be reset. + @return 0 when successful, a non-zero error code otherwise. + @see ASCryptStmFCloseProc + @see ASCryptStmFFlushProc + @see ASCryptStmFilBufProc + @see ASCryptStmFlsBufProc + @see ASCryptStmFPutEOFProc + @see ASCryptStmUnGetcProc +*/ +typedef ASInt32 (*ASCryptStmFResetProc)(ASCryptStm stm); + +/** + A callback for ASCryptStm. This puts an end-of-file (EOF) marker to a + security stream. + @param stm The security stream to receive the EOF. + @return 0 when successful, a non-zero error code otherwise. + @see ASCryptStmFCloseProc + @see ASCryptStmFFlushProc + @see ASCryptStmFilBufProc + @see ASCryptStmFlsBufProc + @see ASCryptStmFResetProc + @see ASCryptStmUnGetcProc +*/ +typedef ASInt32 (*ASCryptStmFPutEOFProc)(ASCryptStm stm); + +/** Callback procs for ASCryptStm */ +typedef struct { + /** Called by getc when the buffer is empty. */ + ASCryptStmFilBufProc EmptyBuff; + /** Called by putc when the buffer is full. */ + ASCryptStmFlsBufProc FullBuff; + /** Backs up an input stream. */ + ASCryptStmUnGetcProc UnGetCh; + /** Flushes a dirty buffer if necessary. */ + ASCryptStmFFlushProc FlushBuff; + /** Closes a stream. */ + ASCryptStmFCloseProc Close; + /** Discards any buffered data. */ + ASCryptStmFResetProc Reset; + /** Puts an EOF marker. */ + ASCryptStmFPutEOFProc PutEOF; +} ASCryptStmProcs; + +/** + An ASStm object cover used for a cryptographic filter's + stream callbacks. + @see PDCryptFilterStreamProc +*/ +typedef struct _t_ASCryptStmRec { + + /** The number of characters remaining in the buffer. */ + ASInt32 count; + + /** The next character to get or put. */ + char *currentPointer; + + /** The base of the buffer, if any. */ + char *basePointer; + + /** Flag to indicate mode: + + + + + + +
FlagValue
ASCryptStmModeRead0x0001 (decryption)
ASCryptStmModeWrite0x0002 (encryption)
ASCryptStmModeEOF0x0004
ASCryptStmModeError0x0008
+ */ + ASUns32 modeFlag; + + /** Handlers for security stream access. */ + ASCryptStmProcs *procs; + + /** The base ASStm object. */ + ASStm baseStm; + + /** The number of bytes requested for decryption. */ + ASInt32 nBytesWanted; + + /** A pointer to arbitrary user-defined data.*/ + void *clientData; +} ASCryptStmRec; + +/** + A callback for use by ASProcStmRdOpenEx() and ASProcStmWrOpen(). + This should place data in the buffer specified by the + parameter data. + +

If your procedure reads data from a file, it is generally + quite inefficient to open the file, read the bytes, and + close the file each time bytes are requested. Instead, consider + opening the file the first time bytes are requested from + it, reading the entire file into a secondary buffer, and + closing the file. When subsequent requests for data from + the file are received, simply copy data from the secondary + buffer, rather than reopening the file.

+ + @param data (Filled by the callback) The buffer into which + your procedure must place the number of bytes specified + by nData. + @param nData The number of bytes to read from the stream and + place into data. + @param clientData User-supplied data that was passed in + the call to ASProcStmRdOpenEx() or ASProcStmWrOpen(). + @return The number of bytes actually read or written. This should be + equal to the nData parameter unless the end of file marker (EOF) has been reached, an error + has occurred, or this is short block of data just before EOF. If + EOF has been reached, a zero should be returned. If an error has + occurred, a negative value should be returned. + @see ASProcStmDestroyProc + @see ASProcStmRdOpenEx + @see ASProcStmWrOpen +*/ +typedef ACCBPROTO1 ASTCount (ACCBPROTO2 *ASStmProc)(char *data, + ASTArraySize nData, void *clientData); + + +/** + A callback for use by ASProcStmWrOpen() and ASProcStmRdOpenEx(). + +

This is called at the end of the stream so you can do clean up and free + allocated memory.

+ + @param clientData IN/OUT User-supplied data that was passed in + the call to ASProcStmWrOpen() or ASProcStmRdOpenEx(). + @see ASStmProc + @see ASProcStmWrOpen + @see ASProcStmRdOpenEx +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASProcStmDestroyProc)(void *clientData); + +/** + A callback for use by ASProcStmRdOpenEx(). + +

This is called to set the stream position to a new location, which may be NULL if the stream + cannot be set to a new position. ASProcStmSeekProc() and ASProcStmGetLength() must + be provided together. If either is NULL, the stream will not be set to a new + position.

+ + @param newPos IN + @param clientData IN/OUT User-supplied data that was passed in + the call to ASProcStmRdOpenEx(). + @see ASStmProc + @see ASProcStmRdOpenEx +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASProcStmSeekProc)(ASFilePos64 newPos, void *clientData); + +/** + A callback for use by ASProcStmRdOpenEx(). + +

This is called to get the length of the stream, which may be NULL if the stream cannot be + set to a new position. ASProcStmSeekProc() and ASProcStmGetLength() must be + provided together. If either is NULL, the stream will not be set to a new + position.

+ + @param clientData IN/OUT User-supplied data that was passed in + the call to ASProcStmRdOpenEx(). + @return The length of the stream in bytes. + @see ASStmProc + @see ASProcStmRdOpenEx +*/ +typedef ACCBPROTO1 ASFilePos64 (ACCBPROTO2 *ASProcStmGetLength)(void *clientData); + +/** For use by ASProcStmRdOpenEx(). */ +typedef struct _s_ASProcStmRdExHandler +{ + /** Set to sizeof(ASProcStmRdExHandlerRec). */ + ASByteCount size; + /** */ + ASStmProc readProc; + /** */ + ASProcStmDestroyProc destroyProc; + /** */ + ASProcStmSeekProc seekProc; + /** */ + ASProcStmGetLength getLengthProc; + /** The size of the buffer to use for the stream. If this field + is missing, the default is 65535. If this field is present and + has a value of 0, then the default is implementation-specific. + */ + ASByteCount bufSize; +} ASProcStmRdExHandlerRec, *ASProcStmRdExHandler; + +/** */ +#define HFT_ERROR_NO_VERSION (0xFFFFFFFF) + +/** + A data structure to pass to an HFT server to create a new + HFT. New in Acrobat 6.0. + @see HFTNewEx +*/ +typedef struct _t_HFTData +{ + /** Set to sizeof(HFTDataRec) */ + ASUns32 size; + /** The number of entries in the new HFT. This determines + the number of methods that the HFT can contain; + each method occupies one entry. + */ + ASCount numSelectors; + /** The version number. */ + ASVersion version; + + /** Optional. This should point to an HFT array of function pointers. */ + const void *hftProcs; +} HFTDataRec; +typedef const HFTDataRec *HFTData; + +/** Each HFT is serviced by an HFT server. The HFT server is responsible for handling + requests to obtain or destroy its HFT. An HFTServer is an object that manages several versions of an + HFT for different clients which may have been compiled with different versions of the HFT's API. + @see HFTServerNew + @see HFTServerDestroy +*/ +typedef struct _t_HFTServer *HFTServer; + +/** + A callback for an HFT server. This returns an HFT with the specified + version number. If the HFT has not yet been created, create + and return it. If the HFT already exists, do not create + a new copy of it; simply return the existing copy. + + @param hftServer The HFT server associated with this proc. + @param version The HFT version being requested. + @param rock User-supplied data passed in the call + to HFTServerNew(). + @return The requested version of the HFT. + @see HFTServerNew + + @note The version numeric type has changed in Acrobat 6.0. +*/ +typedef ACCBPROTO1 HFT (ACCBPROTO2 *HFTServerProvideHFTProc)(HFTServer hftServer, ASVersion version, void *rock); + + +/** + A callback for an HFT server. This destroys the specified HFT (for example, by calling HFTServerDestroy()). + @param hftServer IN/OUT The HFT server associated with this destroy proc. + @param rock IN/OUT User-supplied data that was passed in the call to HFTServerNew(). + @see HFTServerNew + @see HFTDestroy +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *HFTServerDestroyProc)(HFTServer hftServer, void *rock); + +/** + The ASFixed type is a 32-bit quantity representing a rational + number with the high (low on little-endian machines) 16 + bits representing the number's mantissa and the low (high on little-endian machines) + 16 bits representing the fractional part. The definition + is platform-dependent. + +

ASFixedP is a pointer to an ASFixed object.

+ +

Addition, subtraction, and negation with ASFixed types can + be done with + and - operators, unless you are concerned with overflow. Overflow + in ASFixed-value operations is indicated by the values fixedPositiveInfinity + and fixedNegativeInfinity.

+ + @see ASFixedDiv + @see ASFixedMatrixConcat + @see ASFixedMatrixInvert + @see ASFixedMatrixTransform + @see ASFixedMatrixTransformRect + @see ASFixedMul + @see ASFixedToCString +*/ +typedef ASInt32 ASFixed, *ASFixedP; + +/* +** CONVERSION to/from standard C types and ASFixed +*/ + +/** */ +#define ASFixedPosInf ASMAXInt32 + +/** */ +#define ASFixedNegInf ASMINInt32 + +/*#define ASInt32ToFixed(i) ((ASFixed)(i) << 16) + note that an expression argument get evaluated several times and this should be avoided */ +/** + Converts an ASInt32 to a fixed point number. + @param i The ASInt32 to convert. + + @see ASFixedRoundToInt16 + @see ASFixedRoundToInt32 + @see ASFixedToFloat + @see ASFixedTruncToInt16 + @see ASFixedTruncToInt32 + @see ASFloatToFixed + @see ASFixedToFloat + @see ASInt16ToFixed +*/ +#define ASInt32ToFixed(i) (((i) < (-32767)) ? ASFixedNegInf : ((i) > 32767) ? ASFixedPosInf : ((ASFixed)(i) << 16)) + +/** + Converts a fixed point number to an ASInt32, rounding the + result. + @param f The fixed point number to convert. + + @see ASFixedRoundToInt16 + @see ASFixedToFloat + @see ASFixedTruncToInt16 + @see ASFixedTruncToInt32 + @see ASFloatToFixed + @see ASInt16ToFixed + @see ASInt32ToFixed +*/ +#define ASFixedRoundToInt32(f) ((ASInt32) (((f) + fixedHalf) >> 16)) + +/** + Converts a fixed point number to an ASInt32, truncating + the result. + @param f The fixed point number to convert. + + @see ASFixedRoundToInt16 + @see ASFixedRoundToInt32 + @see ASFixedToFloat + @see ASFixedTruncToInt16 + @see ASFloatToFixed + @see ASInt16ToFixed + @see ASInt32ToFixed +*/ +#define ASFixedTruncToInt32(f) ((ASInt32) ((f) >> 16)) + +/** + Converts an ASInt16 to a fixed point number. + @param i The ASInt16 to convert. + + @see ASFixedRoundToInt16 + @see ASFixedRoundToInt32 + @see ASFixedToFloat + @see ASFixedTruncToInt16 + @see ASFixedTruncToInt32 + @see ASFloatToFixed + @see ASInt32ToFixed +*/ +#define ASInt16ToFixed(i) ((ASFixed)(i) << 16) +#define ASUns16ToFixed(i) (((i) > 32767) ? ASFixedPosInf : ((ASFixed)(i) << 16)) + +/** + Converts a fixed point number to an ASInt16, rounding the + result. + @param f The fixed point number to convert. + + @see ASFixedRoundToInt32 + @see ASFixedToFloat + @see ASFixedTruncToInt16 + @see ASFixedTruncToInt32 + @see ASFloatToFixed + @see ASInt16ToFixed + @see ASInt32ToFixed +*/ +#define ASFixedRoundToInt16(f) ((ASInt16) (((f) + fixedHalf) >> 16)) + +/** + Converts a fixed point number to an ASInt16, truncating + the result. + @param f The fixed point number to convert. + + @see ASFixedRoundToInt16 + @see ASFixedRoundToInt32 + @see ASFixedToFloat + @see ASFixedTruncToInt32 + @see ASFloatToFixed + @see ASInt16ToFixed + @see ASInt32ToFixed +*/ +#define ASFixedTruncToInt16(f) ((ASInt16) ((f) >> 16)) + +/* Float <-> ASFixed */ +#ifdef __cplusplus + +/** + The ASFixed type is a 32 bit quantity representing a rational + number with the high (low on little-endian machines) 16 + bits representing the number's mantissa and the low (high on little-endian machines) + 16 bits representing the fractional part. The definition + is platform-dependent. + +

ASFixedP is a pointer to an ASFixed object.

+ +

Addition, subtraction, and negation with ASFixed types can + be done with + and - operators, unless you are concerned with overflow. Overflow + in ASFixed-value operations is indicated by the values fixedPositiveInfinity + and fixedNegativeInfinity.

+ + @see ASFixedDiv + @see ASFixedMatrixConcat + @see ASFixedMatrixInvert + @see ASFixedMatrixTransform + @see ASFixedMatrixTransformRect + @see ASFixedMul + @see ASFixedToCString +*/ +inline ASFixed FloatNToFixed(const double& x) {return (ACROASSERT(x>=0),((x)>32767)?ASFixedPosInf:(ASFixed)(((x)*65536.0f +0.5f))); } +/** + The ASFixed type is a 32 bit quantity representing a rational + number with the high (low on little-endian machines) 16 + bits representing the number's mantissa and the low (high on little-endian machines) + 16 bits representing the fractional part. The definition + is platform-dependent. + +

ASFixedP is a pointer to an ASFixed object.

+ +

Addition, subtraction, and negation with ASFixed types can + be done with + and - operators, unless you are concerned with overflow. Overflow + in ASFixed-value operations is indicated by the values fixedPositiveInfinity + and fixedNegativeInfinity.

+ + @see ASFixedDiv + @see ASFixedMatrixConcat + @see ASFixedMatrixInvert + @see ASFixedMatrixTransform + @see ASFixedMatrixTransformRect + @see ASFixedMul + @see ASFixedToCString +*/ +inline ASFixed FloatIToFixed(const double& x) {return (ACROASSERT((x)*65536.0f==(double)(((ASFixed)x)<<16)),((x)<(-32767))?ASFixedNegInf:((x)>32767)?ASFixedPosInf:((ASFixed)x)<<16); } +#else + +/** FloatN to ASFixed (for use when you know that float numbers are non-negative). */ +#define FloatNToFixed(x) ((x)<(-32767))?ASFixedNegInf:((x)>32767)?ASFixedPosInf:(((ASFixed)(((x)*65536.0f +0.5f))) + +/** FloatI to ASFixed (for use when you know that float numbers are integer values). */ +#define FloatIToFixed(x) ((x)>32767)?ASFixedPosInf:(((ASFixed)x)<<16) + + +#endif /* __cplusplus */ + +/* Backward compatibility #defines. DO NOT use these in new code */ +#define Int32ToFixed ASInt32ToFixed +#define FixedRoundToInt32 ASFixedRoundToInt32 +#define FixedTruncToInt32 ASFixedTruncToInt32 +#define Int16ToFixed ASInt16ToFixed +#define FixedRoundToInt16 ASFixedRoundToInt16 +#define FixedTruncToInt16 ASFixedTruncToInt16 + + +/** + @ingroup ASFixedConstants +*/ +#define fixedZero ((ASFixed) 0x00000000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedHundredth ((ASFixed) 0x0000028FL) + +/** + @ingroup ASFixedConstants +*/ +#define fixedSixteenth ((ASFixed) 0x00001000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedTwelfth ((ASFixed) 0x00001555L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedTenth ((ASFixed) 0x00001999L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedEighth ((ASFixed) 0x00002000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedQuarter ((ASFixed) 0x00004000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedThird ((ASFixed) 0x00005555L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedHalf ((ASFixed) 0x00008000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedTwoThirds ((ASFixed) 0x0000AAAAL) + +/** + @ingroup ASFixedConstants +*/ +#define fixedThreeQuarters ((ASFixed) 0x0000C000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedPi4 ((ASFixed) 0x0000c910L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedSevenEighths ((ASFixed) 0x0000E000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedOne1 ((ASFixed) 0x0000ffffL) + +/** + @ingroup ASFixedConstants +*/ +#define fixedOne ((ASFixed) 0x00010000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedOneAndQuarter ((ASFixed) 0x00014000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedFourThirds ((ASFixed) 0x00015555L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedSqrtTwo ((ASFixed) 0x00016A0AL) + +/** + @ingroup ASFixedConstants +*/ +#define fixedThreeHalves ((ASFixed) 0x00018000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedOneAnd3Qtr ((ASFixed) 0x0001C000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedPi2 ((ASFixed) 0x00019220L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedGolden ((ASFixed) 0x00019e37L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedTwo ((ASFixed) 0x00020000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedThree ((ASFixed) 0x00030000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedFour ((ASFixed) 0x00040000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedFive ((ASFixed) 0x00050000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedSix ((ASFixed) 0x00060000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedSeven ((ASFixed) 0x00070000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedEight ((ASFixed) 0x00080000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedNine ((ASFixed) 0x00090000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedTen ((ASFixed) 0x000A0000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedEleven ((ASFixed) 0x000B0000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedTwelve ((ASFixed) 0x000C0000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedSixteen ((ASFixed) 0x00100000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedThirtyTwo ((ASFixed) 0x00200000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedFifty ((ASFixed) 0x00320000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedSeventyTwo ((ASFixed) 0x00480000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedNinety ((ASFixed) 0x005a0000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedHundred ((ASFixed) 0x00640000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedHundredFifty ((ASFixed) 0x00960000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedOneEighty ((ASFixed) 0x00b40000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedTwoSeventy ((ASFixed) 0x010e0000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedFiveHundred ((ASFixed) 0x01F40000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedThousand ((ASFixed) 0x03E80000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedTenThousand ((ASFixed) 0x27100000L) + +/** + @ingroup ASFixedConstants +*/ +#define fixedNegativeInfinity ASFixedNegInf + +/** + @ingroup ASFixedConstants +*/ +#define fixedPositiveInfinity ASFixedPosInf + + +#ifndef __ASTypes__ /* Newer ASTypes.h defines these types */ +/** + Matrix containing fixed numbers. +*/ +typedef struct _t_ASFixedMatrix +{ + + /** */ + ASFixed a; + + /** */ + ASFixed b; + + /** */ + ASFixed c; + + /** */ + ASFixed d; + + /** */ + ASFixed h; + + /** */ + ASFixed v; +} +ASFixedMatrix, *ASFixedMatrixP; + + +/** + A point (in two-dimensional space) represented by two fixed + numbers. +*/ +typedef struct _t_ASFixedPoint +{ + + /** */ + ASFixed h; + + /** */ + ASFixed v; +} +ASFixedPoint, *ASFixedPointP; + + +/** + A rectangle represented by the coordinates of its four sides. + In the Acrobat viewer, a rectangle differs from a quadrilateral + in that a rectangle must always have horizontal and vertical + sides, and opposite sides must be parallel. +*/ +typedef struct _t_ASFixedRect +{ + + /** */ + ASFixed left; + + /** */ + ASFixed top; + + /** */ + ASFixed right; + + /** */ + ASFixed bottom; +} +ASFixedRect, *ASFixedRectP; +#endif /* ndef __ASTypes */ + +/** + A structure that represents a quadrilateral defined by four + corner points. + + @see AVPageViewInvertQuad + + @note The coordinate numeric types changed in Acrobat 6. +*/ +typedef struct _t_Quad { + /** */ + ASCoord tlh, tlv; + /** */ + ASCoord trh, trv; + /** */ + ASCoord blh, blv; + /** */ + ASCoord brh, brv; +} Quad, *QuadP; + + +/** + A quadrilateral represented by four fixed points (one at each + corner). In the Acrobat viewer, a quadrilateral differs + from a rectangle in that a rectangle must always have horizontal + and vertical sides, and opposite sides must be parallel. +*/ +typedef struct _t_ASFixedQuad { + /** */ + ASFixedPoint tl, tr, bl, br; +} ASFixedQuad, *ASFixedQuadP; + + +/** Definition of ASFract. */ +typedef long ASFract; + +/** Definition of ASReal. */ +typedef float ASReal; + +#ifndef __ASTypes__ /* Newer ASTypes.h defines these types */ +/** */ +typedef struct _t_ASRealPoint { + /** */ + ASReal h, v; +} ASRealPoint; + +/** */ +typedef struct _t_ASRealRect { + /** */ + ASReal left, top, right, bottom; +} ASRealRect; + +/** */ +typedef struct _t_ASRealMatrix { + /** */ + ASReal a, b, c, d, tx, ty; +} ASRealMatrix; +#endif /* ndef __ASTypes.h__ */ + +/** + A time/date structure. + +

The millisecond field is currently unused.

+ @see ASDateGetLocalTime + @see ASDateGetUTCTime + @see ASDateSetTimeFromRec + @see PDAnnotGetDate + @see PDAnnotSetDate +*/ +typedef struct _t_ASTimeRec +{ + + /** Only common era years are displayed appropriately. + */ + ASInt16 year; + + /** Jan = 1, ..., Dec = 12. + */ + ASInt16 month; + + /** 1..31 + */ + ASInt16 date; + + /** 0..23 + */ + ASInt16 hour; + + /** 0..59 + */ + ASInt16 minute; + + /** 0..59 + */ + ASInt16 second; + + /** 0..999 + */ + ASInt16 millisecond; + + /** Sun = 0, ... Sat = 6. + */ + ASInt16 day; + + /** GMT offset in half hours east of Greenwich. + -48 signifies an unknown value. + */ + ASInt16 gmtOffset; +} +ASTimeRec, *ASTimeRecP; + +/* ASCab +** +** An opaque type. +*/ + +/** ASCab objects (cabinets) can be used to store arbitrary key/value pairs. The keys + are always NULL-terminated strings containing only low ASCII alphanumeric characters + and spaces (ASCII character 32). Key names cannot begin or end with a space. + +

Every time you place a non-scalar value inside a cabinet, you are handing that value to + the ASCab implementation to manage. Putting a value in a cabinet is always a + handoff operation. For example, if you create an ASText object and add it as a value + in an ASCab, the ASText object is no longer managed by you; it is managed by the + ASCab. The ASCab will destroy the ASText object when its associated key is + removed or the key's value is overwritten. Pointer values are a special case + discussed in more detail below.

+ +

The routine naming convention is as follows:

+ + + + + + +
NameDescription
GetGet routines return a value. These objects are owned by the ASCab and should + not be destroyed by the caller of Get.
GetCopyGetCopy routines make a copy of the data; the GetCopy client owns the + resulting information and can modify it at will; it is also responsible for destroying + it.
DetachDetach routines work the same way as Get routines, but the key is removed from + the ASCab without destroying the associated value that is passed back to the client + of Detach. The client is responsible for destroying the returned object.
+ + +

Normally, pointers are treated the same way as scalars; the ASCab passes the pointer + value back and forth but does not manage the data to which it points. This all changes + if the pointer has an associated destroyProc. If the destroyProc is set, the ASCab + will reference count the pointer to track how many times the pointer is referenced from + any ASCab. For example, the reference count will be bumped up whenever the pointer is + copied via ASCabCopy() or added to another ASCab via ASCabPutPointer(), and will + destroy the data associated with the pointer when the reference count goes to 0. The data is + destroyed by calling the destroyProc. Detaching a pointer removes one reference to + the pointer without ever destroying the information to which it points. + ASCabDetachPointer() returns a separate value indicating whether the pointer can + safely be destroyed by the client or is still referred to by other key/value pairs inside + any ASCab objects (for example, whether the reference count went to zero when the pointer was + detached from the ASCab).

+ +

Any of the ASCab API's can take a compound name: a string consisting of multiple + keys separated by the colon (:) character. For example, "Grandparent:Parent:Child:Key" can be such a compound name. The + implementation will burrow down through such a compound string until it reaches the + most deeply nested cabinet. Also, any of the Put routines can take a NULL key + name. If the key name is NULL, the routine creates a new numeric key name. If the + cabinet is empty, the first generated key name will be "0" and subsequent names will + increase in ascending order. This is useful when treating an ASCab as a bag of + unnamed items, or when adding an ordered list of items to an empty ASCab.

+ @see ASCabNew + @see ASCabDestroy + */ +typedef struct _t_ASCabinet *ASCab; +typedef const struct _t_ASCabinet *ASConstCab; + +/*------------------------------------------------------------------------ + typedefs for ASText +------------------------------------------------------------------------*/ + +/** An opaque object holding encoded text. + +

An ASText object represents a Unicode string. ASText objects can also be used to + convert between Unicode and various platform-specific text encodings, as well as + conversions between various Unicode formats such as UTF-16 or UTF-8. Since it is + common for a Unicode string to be repeatedly converted to or from the same + platform-specific text encoding, ASText objects are optimized for this operation. + For example, they can cache both the Unicode and platform-specific text strings.

+ +

There are several ways of creating an ASText object depending on the type and + format of the original text data. The following terminology is used throughout this API + to describe the various text formats:

+ + + + + + + +
Text FormatDescription
EncodedA multi-byte string terminated with a single 0 character and coupled + with a specific host encoding indicator. On Mac OS, the text encoding is + specified using a script code. On Windows, the text encoding is specified + using a CHARSET code. On UNIX the only valid host encoding indicator is 0, which + specifies text in the platform's default Roman encoding. On all platforms, Asian text + is typically specified using multi-byte strings.
ScriptTextA multi-byte string terminated with a single 0 character and coupled + with an ASScript code. This is merely another way of specifying the Encoded + case; the ASScript code is converted to a host encoding using ASScriptToHostEncoding().
UnicodeText specified using UTF-16 or UTF-8. In the UTF-16 case, the bytes can + be in either big-endian format or the endian-ness that matches the platform, and + are always terminated with a single ASUns16 0 value. In the UTF-8 case, the text is + always terminated with a trailing 0 byte. Unicode usage in this case is straight Unicode without + the 0xFE 0xFF prefix or language and country codes that can be encoded inside a + PDF document.
PDTextA string of text pulled out of a PDF document. This will either be a big-endian + Unicode string pre-appended with the bytes 0xFE 0xFF, or a string in + PDFDocEncoding. In this case, the Unicode string may have embedded language + and country identifiers. ASText objects strip language and country information out + of the PDText string and track them separately. See below for more details.
+ + +

ASText objects can also be used to accomplish encoding and format conversions; you can + request a string in any of the formats specified above. + In all cases the ASText code attempts to preserve all characters. For example, if you + attempt to concatenate two strings in separate host encodings, the implementation may + convert both to Unicode and perform the concatenation in Unicode space.

+ +

When creating a new ASText object or putting new data into an existing object, the + implementation will always copy the supplied data into the ASText object. The + original data is yours to do with as you wish (and release if necessary).

+ +

The size of ASText data is always specified in bytes. For example, the len argument to + ASTextFromSizedUnicode() specifies the number of bytes in the string, not the + number of Unicode characters.

+ +

Host encoding and Unicode strings are always terminated with a NULL character + (which consists of one NULL byte for host encoded strings and two NULL bytes for + Unicode strings). You cannot create a string with an embedded NULL character, even + using the calls which take an explicit length parameter.

+ +

The Getxxx calls return pointers to data held by the ASText object. You cannot free + or manipulate this data directly. The GetxxxCopy calls return data you can + manipulate and that you are responsible for freeing.

+ +

An ASText object can have language and country codes associated with it. A + language code is a 2-character ISO 639 language code. A country code is a 2- + character ISO 3166 country code. In both cases the 2-character codes are packed + into an ASUns16 value: the first character is packed in bits 8-15, and the second character is packed in + bits 0-7. These language and country codes can be encoded into a UTF-16 variant of + PDText encoding using an escape sequence; see Section 3.8 in the PDF Reference. + The ASText calls will automatically parse the language and country codes + embedded inside a UTF-16 PDText object, and will also author appropriate escape + sequences to embed the language and country codes (if present) when generating a + UTF-16 PDText object.

+ + @see ASTextNew + @see ASTextFromEncoded + @see ASTextFromInt32 + @see ASTextFromPDText +*/ +typedef struct _t_ASTextRec *ASText; + +/** + An opaque object holding constant encoded text. + @see ASText +*/ +typedef const struct _t_ASTextRec *ASConstText; + +/*------------------------------------------------------------------------ + typedefs for ASFile.h +------------------------------------------------------------------------*/ + + +/** Open the file for reading. + @ingroup ASFileOpenModes +*/ +#define ASFILE_READ 1 + +/** Open the file for writing. + @ingroup ASFileOpenModes +*/ +#define ASFILE_WRITE 2 + +/** Create the file if it does not exist. + @ingroup ASFileOpenModes +*/ +#define ASFILE_CREATE 4 + + +/** A hint indicating that the file will be primarily accessed sequentially. + @ingroup ASFileOpenModes +*/ +#define ASFILE_SERIAL 8 + +/** A hint indicating that a local copy of the file will be needed. + @ingroup ASFileOpenModes +*/ +#define ASFILE_LOCAL 16 + +/** A hint indicating that the file will be primarily accessed randomly. +@ingroup ASFileOpenModes +*/ +#define ASFILE_RANDOMACCESS 32 + + +/** Set if the file's data transfer rate + is generally slow. For example, the file is on a floppy + disk or is being accessed via modem. + + @ingroup ASFileFlags +*/ +#define kASFileSlowTransfer 0x00000001L + +/** Set if initiating each access to the file is slow. For example, + access may be slow because the file is served by an HTTP server that spawns + a new process for each request. + + @ingroup ASFileFlags +*/ +#define kASFileSlowConnect 0x00000002L + +/** Use multi-read commands to access the file. + @ingroup ASFileFlags +*/ +#define kASFileUseMRead 0x00000004L + +/** Set if the file is to be cached (requires kASFileUseMRead to be set as well). + @ingroup ASFileFlags +*/ +#define kASFileDoCaching 0x00000008L + +/** (Acrobat 5.0 and later) Set if media/access is a dial up connection. + This flag is only fully implemented on Windows. On Mac OS, + this flag is always conservatively set to true. + @ingroup ASFileFlags +*/ +#define kASFileDialUp 0x00000010L + +/** Set if the file is still being loaded. + @ingroup ASFileFlags +*/ +#define kASFileStillFetching 0x00000020L + +/** true if the file has outstanding MReads. + @ingroup ASFileFlags +*/ +#define kASFileHasOutstandingMReads 0x00000040L + + +/* ASFileMode flags */ + +/** If set, ASFileRead does not yield if bytes + are not ready (which raises the fileErrBytesNotReady exception). + @ingroup ASFileModeFlags +*/ +#define kASFileModeDoNotYieldIfBytesNotReady 0x0001 + +/** If set, the file will be read all at once regardless of + multiple read requests. + + @ingroup ASFileModeFlags +*/ +#define kASFileModeDisableExplicitMReadRequests 0x0002 + +/** If set, ASFileRead will raise the fileErrBytesNotReady exception when + trying to read from a file with a cache for which the requested + bytes are not yet present. + @ingroup ASFileModeFlags +*/ +#define kASFileRaiseIfBytesNotReady 0x0004 + +/** If set, no read requests are issued if bytes are not ready + (that is, the bytes are not in the cache). + @ingroup ASFileModeFlags +*/ +#define kASFileNoRequestIfBytesNotReady 0x0008 + +/** If set, ASFileRead will suspend the current thread when + trying to read from a file with a cache for which the requested + bytes are not yet present. Note that if kASFileSuspendIfBytesNotReady + is set, the kASFileRaiseIfBytesNotReady is ignored. + @ingroup ASFileModeFlags +*/ + + +#define kASFileSuspendIfBytesNotReady 0x0010 + +/* Type/Creator codes for ASFileSysSetTypeAndCreator */ +#if MAC_PLATFORM +#define ASFourCharCode(x) (x) +#else +#define ASFourCharCode(x) (0U) +#endif + + + +/** Acrobat creator code. + @ingroup Creators +*/ +#define kAcrobatCreatorCode ASFourCharCode('CARO') + +/** Adobe Photoshop creator code. + @ingroup Creators +*/ +#define kPhotoshopCreatorCode ASFourCharCode('8BIM') + +/** Adobe ImageReady creator code. + @ingroup Creators +*/ +#define kImageReadyCreatorCode ASFourCharCode('MeSa') + +/** Adobe Illustrator creator code. + @ingroup Creators +*/ +#define kIllustratorCreatorCode ASFourCharCode('ART5') + + + +/** Portable document format (PDF). + @ingroup AcrobatTypes +*/ +#define kPDFTypeCode ASFourCharCode('PDF ') + +/** Forms data format. + @ingroup AcrobatTypes +*/ +#define kFDFTypeCode ASFourCharCode('FDF ') + +/** XML forms data format. + @ingroup AcrobatTypes +*/ +#define kXFDFTypeCode ASFourCharCode('XFDF') + +/** XML data package. + @ingroup AcrobatTypes +*/ +#define kXDPTypeCode ASFourCharCode('XDP ') + +/** XML PDF. + @ingroup AcrobatTypes +*/ +#define kPXDFTypeCode ASFourCharCode('MARS') + +/** Preferences file. + @ingroup AcrobatTypes +*/ +#define kPrefsTypeCode ASFourCharCode('PREF') + +/** Acrobat catalog index file. + @ingroup AcrobatTypes +*/ +#define kPDXTypeCode ASFourCharCode('PDX ') + +/** Adobe Web Buy rights management file. + @ingroup AcrobatTypes +*/ +#define kRMFTypeCode ASFourCharCode('RMF ') + +/** Acrobat profile format (PPKLite). + @ingroup AcrobatTypes +*/ +#define kAPFTypeCode ASFourCharCode('APF ') + +/** Acrobat sequence file. + @ingroup AcrobatTypes +*/ +#define kSequenceTypeCode ASFourCharCode('SEQU') + +/** Spelling dictionary file. + @ingroup AcrobatTypes +*/ +#define kDictionaryTypeCode ASFourCharCode('DICT') + +/** Web-hosted applications file. + @ingroup AcrobatTypes +*/ +#define kWHATypeCode ASFourCharCode('WHA ') + +/** Locale file. + @ingroup AcrobatTypes +*/ +#define kLocaleTypeCode ASFourCharCode('LANG') + +/** Plug-in file. + @ingroup AcrobatTypes +*/ +#define kPluginTypeCode ASFourCharCode('XTND') + +/** Plug-in file (preferred, supported by 5.0.5 and later). + Using this file type will allows shipping + a Carbonized plug-in without worrying that it will try to load + and show an error when installed under Acrobat 4 or earlier. + @ingroup AcrobatTypes +*/ +#define kPluginNewTypeCode ASFourCharCode('XTNc') + +/** eBook Exchange Transfer Data (ETD) file. + @ingroup AcrobatTypes +*/ +#define kETDTypeCode ASFourCharCode('fETD') + +/** eBook EDN activation file. + @ingroup AcrobatTypes +*/ +#define kEDNTypeCode ASFourCharCode('fEDN') + + + +/** Adobe Photoshop PSD file. + @ingroup PhotoshopTypes +*/ +#define kPSDTypeCode ASFourCharCode('8BIM') + +/** Mac OS PICT file. + @ingroup PhotoshopTypes +*/ +#define kPICTTypeCode ASFourCharCode('PICT') + +/** TIFF file. + @ingroup PhotoshopTypes +*/ +#define kTIFFTypeCode ASFourCharCode('TIFF') + +/** GIF file. + @ingroup PhotoshopTypes +*/ +#define kGIFTypeCode ASFourCharCode('GIFf') + +/** JPEG file. + @ingroup PhotoshopTypes +*/ +#define kJPEGTypeCode ASFourCharCode('JPEG') + +/** PNG file. + @ingroup PhotoshopTypes +*/ +#define kPNGTypeCode ASFourCharCode('PNGf') + + + +/** Adobe Illustrator AI file. + @ingroup IllustratorTypes +*/ +#define KAITypeCode ASFourCharCode('TEXT') + +/** EPS file. + @ingroup IllustratorTypes +*/ +#define kEPSTypeCode ASFourCharCode('EPSF') + + +/** Text file. + @ingroup MiscCreatorTypes +*/ +#define kTextTypeCode ASFourCharCode('TEXT') + +/** Text file. + @ingroup MiscCreatorTypes +*/ +#define kRTFTypeCode ASFourCharCode('RTF ') + +/** SimpleText. + @ingroup MiscCreatorTypes +*/ +#define kTextCreatorCode ASFourCharCode('ttxt') + +/** QuickTime file. + @ingroup MiscCreatorTypes +*/ +#define kQuickTimeTypeCode ASFourCharCode('MooV') + +/** QuickTime player. + @ingroup MiscCreatorTypes +*/ +#define kQuickTimeCreatorCode ASFourCharCode('TVOD') + +/** HTML file. + @ingroup MiscCreatorTypes +*/ +#define kHTMLTypeCode ASFourCharCode('TEXT') + +/** Microsoft Internet Explorer. + @ingroup MiscCreatorTypes +*/ +#define kHTMLCreatorCode ASFourCharCode('MSIE') + +/** XML file. + @ingroup MiscCreatorTypes +*/ +#define kXMLTypeCode ASFourCharCode('TEXT') + +/** Microsoft Excel. + @ingroup MiscCreatorTypes +*/ +#define kExcelCreatorCode ASFourCharCode('XCEL') + +/** Microsoft Word. + @ingroup MiscCreatorTypes +*/ +#define kWordCreatorCode ASFourCharCode('W8BN') + +/** Microsoft PowerPoint. + @ingroup MiscCreatorTypes +*/ +#define kPowerPointCreatorCode ASFourCharCode('SLD8') + +/** Unknown file. + @ingroup MiscCreatorTypes +*/ +#define kUnknownTypeCode 0x3f3f3f3f + +/** Unknown application. + @ingroup MiscCreatorTypes +*/ +#define kUnknownCreatorCode 0x3f3f3f3f + + +/** + A data structure containing callbacks that implement a file + system. + @see ASFileSys +*/ +typedef struct _t_ASFileSysRec *ASFileSys; + + +/** + @see ASFileAcquirePathName + @see ASFileSysAcquireParent + @see ASFileSysCreatePathName + @see ASFileSysPathFromDIPath + @see ASPathFromPlatformPath + @see PDFileSpecAcquireASPath + @see ASFileSysReleasePath + @see ASFileSysDIPathFromPath +*/ +typedef struct _t_ASPathNameRec *ASPathName; + +/** + An opaque representation of a particular open + file. Each open file has a unique ASFile. The ASFile value + has meaning only to the common ASFile implementation and bears + no relationship to platform-specific file objects. + @see PDDocGetFile + @see ASFileSysOpenFile + @see ASFileFromMDFile +*/ +typedef struct _t_ASFile *ASFile; + +/** + Called when an asynchronous read or write request has completed. + + @param aFile IN/OUT The ASFile for which data is read or written. + + @param p IN/OUT A pointer to the buffer provided by the client. + It contains nBytesRead bytes of data if error is zero. + @param fileOffsetRequested IN/OUT The file offset requested by the + client. + @param countRequested IN/OUT The number of bytes requested by the + client. + @param nBytesRead IN/OUT The number of bytes actually read or written. + + @param error IN/OUT The error condition if it is non-zero; see AcroErr.h. + + @param compProcClientData IN/OUT The client data parameter provided + by client. + @see ASFileSysAsyncAbortProc + @see ASFileSysAsyncReadProc + @see ASFileSysAsyncWriteProc + @see ASFileSysYieldProc +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASFileCompletionProc)(ASFile aFile, const char *p, + ASTFilePos fileOffsetRequested, ASTArraySize countRequested, + ASTArraySize nBytesRead, ASErrorCode error, void *compProcClientData); + +/*------------------------------------------------------------------------ + typedefs: see ASTypes.h for definitions of ASFileSys, ASPathName, and ASFileNum + as well as flags for ASFileSysOpenFile mode. +------------------------------------------------------------------------*/ + + +/** + ASMDFile replaces MDFile. MDFile is an obsolete + name for this data type for backward compatibility. + +

An MDFile is an opaque representation of a file instance + for a particular file system. File system implementors may + choose any convenient representation for an MDFile. In particular, + file systems need not worry about MDFile space conflicts; + the ASFile object exported by the common implementation + is guaranteed to be unique across all open files, and the + common implementation maps calls of ASFile methods to calls + of ASFileSystem callbacks with the corresponding MDFile.

+ + @see ASFileFromMDFile + @see ASFileGetMDFile + @see ASFileSysAsyncAbortProc + @see ASFileSysGetFileFlags + @see ASFileSysYieldProc + @see ASFileSysMReadRequestProc + @see ASFileSysClearOutstandingMReadsProc + @see ASFileSysGetStatusProc + @see ASFileSysOpenProc + @see ASFileSysCloseProc + @see ASFileSysFlushProc + @see ASFileSysSetPosProc + @see ASFileSysGetPosProc + @see ASFileSysSetEofProc + @see ASFileSysGetEofProc + @see ASFileSysReadProc + @see ASFileSysWriteProc + @see ASFileSysRenameProc + @see ASFileSysIsSameFileProc +*/ +typedef void *ASMDFile; +/* Obsolete name for this data type, for backward compatibility */ +#define MDFile ASMDFile + + +/** + A data structure representing an I/O request. + @see ASFileSysAsyncReadProc + @see ASFileSysAsyncWriteProc + @see ASIODoneProc +*/ +typedef struct _t_ASIORequestRec *ASIORequest; + + +/** + Values returned by ASFileSysGetStatusProc(). + @see ASFileRead + @see ASFileSysGetStatusProc +*/ +typedef enum { + + /** The MDFile is in a valid state. + */ + kASFileOkay = 0x0000, + + /** The MDFile is being closed (for example, + because the file is being displayed in a web browser's window + and the user cancelled downloading). + */ + kASFileIsTerminating = 0x0001 + } ASFileStatusFlags; + + +/** + A callback in ASIORequest used by the asynchronous read/write + ASFileSys implementation and provided by the ASFile implementation + to the ASFileSys. The ASFileSys must call this method when + an asynchronous request is completed: + +
    +
  • + When an I/O request has some or all of its data. +
    • +
  • + If the request is successfully queued but an error prevents + it from completing. +
    • +
  • + If the request is aborted by calling ASFileSysAsyncAbortProc(). + In this case, totalBytesCompleted = 0 and pError = -1. +
    • +
+ +

If the request fails, this method must still be called, + with the error. It is not called, however, if there is an error queueing + the read or write request.

+ + @param req The I/O request for which data has been read/written. + @see ASFileSysAsyncAbortProc + @see ASFileSysAsyncReadProc + @see ASFileSysAsyncWriteProc + @see ASFileSysYieldProc +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASIODoneProc)(ASIORequest req); + +/** + The first five items in the ASIORequestSingleRec structure exactly + match the parameters of an ASFileSys read or write call. + +

totalBytesRead is filled in before the IODoneProc is called. + If totalBytesRead is 0 or if pError is non-zero, the read was + either terminated or did not complete.

+ +

If IODoneProc is non-zero, it points to a procedure that must be + called either when the request has terminated due to an error or other + condition, or when all of the bytes have been received for this + request.

+*/ +typedef struct _t_ASIORequestRec +{ + + /** The MDFile corresponding to the ASFile for which this request is intended. + */ + ASMDFile mdFile; + + /** A pointer to data to write to or read from mdFile. + */ + void* ptr; + + /** An offset (specified in bytes) into mdFile of the first byte to read or write. + */ + ASTFilePos offset; + + /** The number of bytes to read or write. It must be filled + in before IODoneProc is called. If is value is 0, the read was either + terminated or did not complete. + */ + ASTArraySize count; + + + /** The number of bytes actually read or written. + */ + ASTArraySize totalBytesCompleted; + + /** An error code. This code is filled by the ASFileSys before IODoneProc is called. + If its value is non-zero, the read was either terminated or did not complete. + */ + ASErrorCode pError; + + /** User-supplied data that the ASFileSys can use for any purpose. + */ + void* clientData; + + + /** A user-supplied callback for use by the ASFileSys when the operation has completed. If it is non-NULL, + it points to a procedure that must be called either when the request has terminated due to an + error or other condition, or when all of the bytes have been received for this request. + @note This callback may be called at interrupt time. + */ + ASIODoneProc IODoneProc; + + /** User-supplied data that is available for IODoneProc to use. + */ + void* IODoneProcData; +} ASIORequestRec; + +/** + An enumerated data type used to categorize an object associated + with an ASPathName. + @see ASFileSysGetItemPropsProc + @see ASFileSysFirstFolderItemProc + @see ASFileSysNextFolderItemProc + @see ASFileSysGetItemProps + @see ASFileSysFirstFolderItem + @see ASFileSysNextFolderItem +*/ +enum { + + /** The object is associated with a file. + */ + kASFileSysFile, + + /** The object is associated with a folder. + */ + kASFileSysFolder, + + /** The object type is unknown. + */ + kASFileSysUnknown = -1 +}; +typedef ASEnum16 ASFileSysItemType; + + +/** + A list of properties for the object referenced by an ASPathName. + It is used in ASFileSysGetItemProps() and the folder enumeration + routines. + @see ASFileSysGetItemProps + @see ASFileSysFirstFolderItem + @see ASFileSysNextFolderItem +*/ +typedef struct _t_ASFileSysItemProps { + + /** The size of the data structure. It must be set to sizeof(ASFileSysItemPropsRec). + */ + ASSize_t size; + + /** true if the object exists. If it is false, none of the following fields are valid. + */ + ASBool isThere; + + /** One of the ASFileSysItemType objects. + */ + ASFileSysItemType type; + + /** true if the object's hidden bit is set. + */ + ASBool isHidden; + + /** true if the object is read-only. + */ + ASBool isReadOnly; + + /** true if the file system could determine the creation date of the object. + */ + ASBool creationDateKnown; + + /** The creation date of the object. It is valid only if creationDateKnown is true. + */ + ASTimeRec creationDate; + + /** true if the file system could determine the last modification date of the object. + */ + ASBool modDateKnown; + + /** The modification date of the object. It is valid only if modDateKnown is true. + */ + ASTimeRec modDate; + + /** If the type is kASFileSysFile, this field holds the lower 32 bits of the size of the file (the upper 32 + bits are maintained by fileSizeHigh. + */ + ASByteCount fileSize; + + /** If the type is kASFileSysFile, this field holds the upper 32 bits of the size of the file (the lower 32 + bits are maintained by fileSize. + */ + ASByteCount fileSizeHigh; + + /** If the type is kASFileSysFolder, this field specifies how many items are in the folder. If this value + is -1, the file system was unable to easily determine the number of objects. You will need to explicitly + enumerate the objects to determine how many are in the folder. + */ + ASTCount folderSize; + + /** The Mac OS creator code for the file. + For other file systems, this will be zero. + */ + ASUns32 creatorCode; + + /** The Mac OS type code for the file. + For other file systems, this will be zero. + */ + ASUns32 typeCode; +} ASFileSysItemPropsRec, *ASFileSysItemProps; + + +/** + An opaque object used to iterate through the contents of + a folder. ASFileSysFirstFolderItem() returns the first item + in the folder along with an ASFolderIterator object for + iterating through the rest of the items in the folder. Call + ASFileSysNextFolderItem() with this object to return the next + object in the folder until the method returns false. To + discard the ASFolderIterator object, call ASFileSysDestroyFolderIterator(). + + @see ASFileSysFirstFolderItemProc + @see ASFileSysNextFolderItemProc + @see ASFileSysDestroyFolderIteratorProc + @see ASFileSysFirstFolderItem + @see ASFileSysNextFolderItem + @see ASFileSysDestroyFolderIterator +*/ +typedef struct _t_ASFolderIterator *ASFolderIterator; + + +/** An ASPlatformPath and associated platform path types. + This is an opaque object used to retrieve a platform path object. + ASFileSysAcquirePlatformPath() allocates and initializes this + object. ASPlatformPath* calls are used to access its contents. + To discard this object, call ASFileSysReleasePlatformPath(). +*/ +typedef struct _t_ASPlatformPath *ASPlatformPath; + +/** A UNIX or Windows platform-specific path value. + @see ASPlatformPathGetCstringPtr +*/ +typedef char* Cstring_Ptr; /* generally for Win_K, Unix */ +/** + A C string containing a POSIX path (UTF-8 encoding). + @see ASPlatformPathGetPOSIXPathPtr +*/ +typedef char* POSIXPath_Ptr; + +#if MAC_PLATFORM + +/** + A pointer to a Mac OS platform-specific FSSpec. + @see ASPlatformPathGetFSSpecPtr +*/ +typedef struct FSSpec *FSSpec_Ptr; /* for Mac_K (here on down) */ + +/** + A pointer to a Mac OS platform-specific FSRef. + @see ASPlatformPathGetFSRefPtr +*/ +typedef struct FSRef *FSRef_Ptr; + +/** + A structure containing the equivalent of two Mac OS platform-specific types: a pointer to + an FSRef and a CFStringRef. + + @see ASPlatformPathGetFSRefWithCFStringRefRecPtr +*/ +typedef struct _t_FSRefWithCFStringRefRec { + /** */ + struct FSRef *ref; + /** Definition of a CFStringRef. */ + const struct __CFString *str; +} FSRefWithCFStringRefRec; + +/** */ +typedef FSRefWithCFStringRefRec *FSRefWithCFStringRefRec_Ptr; + +/** + A structure containing the equivalent of a Mac OS platform-specific CFURLRef. + + @see ASPlatformPathGetCFURLRefRecPtr +*/ +typedef struct _t_CFURLRefRec { + /** */ + const struct __CFURL *url; /* definition of a CFURLRef */ +} CFURLRefRec; + +/** */ +typedef CFURLRefRec *CFURLRefRec_Ptr; + +#else /* this is to prevent type redefinitions, e.g. with PhotoshopSDK which defines FSSpec for Win */ + +typedef struct FSSpecPlacebo *FSSpec_Ptr; +typedef struct FSRefPlacebo *FSRef_Ptr; +typedef struct _t_FSRefWithCFStringRefRecPlacebo { + struct FSRefPlacebo *ref; + const struct __CFStringPlacebo *str; +} FSRefWithCFStringRefRecPlacebo; +typedef FSRefWithCFStringRefRecPlacebo *FSRefWithCFStringRefRec_Ptr; +typedef struct _t_CFURLRefRecPlacebo { + const struct __CFURLPlacebo *url; +} CFURLRefRecPlacebo; +typedef CFURLRefRecPlacebo *CFURLRefRec_Ptr; + +#endif /* #if MAC_PLATFORM */ + + +/** + A callback for ASFileSysRec that gets the flags for the specified + file. + @param f IN/OUT The file whose flags are obtained. + @return A bit field using ASFile flags. +*/ +typedef ACCBPROTO1 ASFlagBits (ACCBPROTO2 *ASFileSysGetFileFlags)(ASMDFile f); + +/** + A callback for ASFileSysRec that asynchronously reads the specified + data, returning immediately after the request has been queued. + The ASFileSys must call the ASIODoneProc() (if one was provided) + when the specified data has been read. + +

This callback is similar to the ASFileSysMReadRequestProc(), + except that this callback contains a caller-provided ASIODoneProc() + and can only be used for a single byte range.

+ @param req A data structure specifying the data to read. + It contains information about the request including the ASMDFile, + the file offset, the buffer for the request, the number + of bytes in the request, an ASIODoneProc(), and client data + for the ASIODoneProc(). If the ASIODoneProc() in req is non-NULL + and there is an error queueing the read request, the ASIODoneProc() + must not be called. + @return 0 if the request was successfully queued, + a non-zero platform-dependent error code otherwise. + @see ASFileSysAsyncAbortProc + @see ASFileSysAsyncWriteProc + @see ASFileSysYieldProc +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysAsyncReadProc)(ASIORequest req); + +/** + A callback for ASFileSysRec that asynchronously writes the specified + data, returning immediately after the request has been queued. + The ASFileSys must call the ASIODoneProc() (if one was provided) + when the specified data has been written. + @param req A data structure specifying the data to write. + It contains information about the request including the ASMDFile, + the file offset, the buffer for the request, the number + of bytes in the request, an ASIODoneProc(), and client data + for the ASIODoneProc(). If the ASIODoneProc() in req is non-NULL + and there is an error queueing the write request, the ASIODoneProc() + must not be called. + @return 0 if the request was successfully queued, + a non-zero platform-dependent error code otherwise. + @see ASFileSysAsyncAbortProc + @see ASFileSysAsyncReadProc + @see ASFileSysYieldProc +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysAsyncWriteProc)(ASIORequest req); + +/** + A callback for ASFileSysRec that aborts all uncompleted asynchronous + I/O requests for the specified file. This callback can + be called at any time. + +

This callback calls each outstanding ASIORequest object's ASIODoneProc() + to be called with totalBytes = 0 and error = -1.

+ + @param f IN/OUT The file for which all uncompleted asynchronous + read and write requests are aborted. + @see ASFileSysAsyncReadProc + @see ASFileSysAsyncWriteProc + @see ASFileSysYieldProc +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASFileSysAsyncAbortProc)(ASMDFile f); + + +/** + A callback for ASFileSysRec that yields the asynchronous I/O requests + for the specified file. This allows other processes + to process events that may be required for a file + read to complete. An ASFileSys should implement a yield + mechanism to complement asynchronous read and write requests. + +

On Windows, this could be a normal PeekMessage-based yield.

+ +

In UNIX, it could mean using select on a file descriptor.

+ + @param f IN/OUT The file whose asynchronous I/O requests are yielded. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysAsyncAbortProc + @see ASFileSysAsyncReadProc + @see ASFileSysAsyncWriteProc + @see ASFileRead +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysYieldProc)(ASMDFile f); + + +/** + A callback for ASFileSysRec that queues asynchronous requests + for one or more byte ranges that the caller (usually the + Acrobat viewer or library) will need in the near future. + This callback is important for slow file systems, such as + the web, to improve overall performance. It allows the + file system to begin retrieving bytes before they are actually + needed, while the Acrobat software continues processing + as much as it can with the data that has already been downloaded. + +

This callback does not actually read the data, but merely + queues the requests, starts the asynchronous code that reads + the data, and returns. The asynchronous code that reads + the data must use ASFilePushData() to push the data from each + byte range to the Acrobat software as soon as the data is + ready.

+ +

This callback is similar to the ASFileSysAsyncReadProc(), + except that this callback contains a caller-provided ASIODoneProc() + and can only be used for a single byte range.

+ + @param f The file whose data is read. + @param aFile The corresponding ASFile, for use with ASFilePushData(). + + @param blockPairs An array of file offsets and byte lengths. + + @param nBlockPairs The number of block pairs in blockPairs. + @return 0 if the request was successfully queued, + a non-zero platform-dependent error code otherwise. + @see ASFileSysAsyncReadProc + @see ASFileSysClearOutstandingMReadsProc + @see ASFileRead + @see ASFileHasOutstandingMReads +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysMReadRequestProc) + (ASMDFile f, ASFile aFile, ASTFilePos *blockPairs, ASTArraySize nBlockPairs); + + +/** + A callback for ASFileSysRec that is used to advise a file system + that the previous range of bytes requested to read are not + needed, so that it may drop the read requests. The file + system can continue pushing the bytes if it cannot stop + the reads. + @param f The file that was being read. + @see ASFileSysMReadRequestProc + @see ASFileRead + @see ASFileHasOutstandingMReads +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASFileSysClearOutstandingMReadsProc)(ASMDFile f); + +/** + A callback for ASFileSysRec that gets the status of the specified + file. This callback is used for asynchronous I/O. For example, + it can indicate that an underlying file connection has been + closed. + @param f IN/OUT The file whose status is obtained. + @return The file's status, which must be one of the ASFileStatusFlags + values. + @see ASFileRead +*/ +typedef ACCBPROTO1 ASFlagBits (ACCBPROTO2 *ASFileSysGetStatusProc)(ASMDFile f); + +/** + A callback for ASFileSysRec that is used for non-local file systems. + It returns an ASPathName on the new ASFileSys that refers to + an image (which may be cached) of the remote file. Because of + the possibility of cache flushing, you must hold a copy + of the remote file's ASPathName for the duration of use + of the local file. + + @param pathName IN/OUT The ASPathName for which an equivalent + in newFileSys is obtained. + @param newFileSys IN/OUT The file system in which an equivalent + of pathName is obtained. + @return The ASPathName (in newFileSys) for the specified file. It returns + NULL if one can not be made. + @see ASFileSysCreatePathNameProc + @note Do not remove the local file copy, since the default + file system does not know about the linkage to the remote + file. The removal of this temporary file should be left to the file system. + + @note The ASPathName returned should be released with the + ASFileSysReleasePath() method when it is no longer needed. +*/ +typedef ACCBPROTO1 ASPathName (ACCBPROTO2 *ASFileSysAcquireFileSysPathProc) + (ASPathName pathName, ASFileSys newFileSys); + +/** + A callback for ASFileSysRec that opens the specified file. It + is called by ASFileSysOpenFile() and ASFileReopen(). This callback + returns an error if the file is over 2 GB in length. + + @param pathName IN/OUT The path name for the file to open. + @param mode IN/OUT The mode in which the file is opened, which must + be an OR of the ASFile Open Modes. + @param fP IN/OUT (Filled by the callback) The newly opened file. + + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysCloseProc + @see ASFileSysOpenFile + @see ASFileReopen + @see ASFileClose +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysOpenProc)(ASPathName pathName, ASFileMode mode, ASMDFile *fP); + +/** + A callback for ASFileSysRec. This callback is responsible + for closing the specified file. It is called by ASFileClose(). + + @param f IN/OUT The file to close. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysOpenProc + @see ASFileClose +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysCloseProc)(ASMDFile f); + +/** + A callback for ASFileSysRec that flushes data for the specified + file. It is called by ASFileFlush(). + @param f IN/OUT The file to flush. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysFlushVolumeProc + @see ASFileFlush +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysFlushProc)(ASMDFile f); + +/** + A callback for ASFileSysRec that sets the current position in + a file (the point from which data will next be + read). It is called by ASFileSetPos(). + @param f IN/OUT The file in which the position is set. + @param pos IN/OUT The desired new position (specified in bytes + from the beginning of the file). + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileGetPos + @see ASFileSetPos +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysSetPosProc)(ASMDFile f, ASFilePos pos); + +/** + A callback for ASFileSysRec that gets the current position for + the specified file. It is called by ASFileGetPos(), and is not capable of handling file positions over 2 GB. + @param f The file whose current position is obtained. + @param pos (Must by filled by the callback) The current + position. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysSetPosProc + @see ASFileGetPos + @see ASFileSetPos +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysGetPosProc)(ASMDFile f, ASFilePos *pos); + +/** + A callback for ASFileSysRec that increases or decreases the logical + size of a file. It is called by ASFileSetEOF(). It returns an error + if the current file position is over 2 GB. + @param f The file to expand or shrink. + @param pos The desired size in bytes. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysCanSetEofProc + @see ASFileGetEOF + @see ASFileSetEOF +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysSetEofProc)(ASMDFile f, ASFilePos pos); + +/** + A callback for ASFileSysRec that gets a file's current logical + size. It is called by ASFileGetEOF(), and is not capable of handling file sizes over + 2 GB. + @param f IN/OUT The file whose logical size is obtained. + @param pos IN/OUT (Filled by the callback) The file's logical + size in bytes. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileGetEOF + @see ASFileSetEOF +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysGetEofProc)(ASMDFile f, ASFilePos *pos); + +/** + A callback for ASFileSysRec that reads data from the specified + file. It is called by ASFileRead() and returns an error if the file size + is over 2 GB. + @param ptr IN/OUT (Filled by the callback) The data read from + the file. + @param size IN/OUT The size of each item to read. + @param count IN/OUT The number of items to read. + @param f IN/OUT The file from which data is read. + @param pError IN/OUT (Filled by the callback) An error code. This + value is filled only if an error occurs. In that case, + it should contain an error code. + @return The number of bytes read, or 0 if there was an error. + @see ASFileSysWriteProc + @see ASFileRead +*/ +typedef ACCBPROTO1 ASSize_t (ACCBPROTO2 *ASFileSysReadProc)(void *ptr, ASSize_t size, ASSize_t count, ASMDFile f, ASErrorCode *pError); + +/** + A callback for ASFileSysRec that writes data to the specified + file. + @param ptr IN/OUT A buffer containing data to write. + @param size IN/OUT The size of each item to write. + @param count IN/OUT The number of items to write. + @param f IN/OUT The file into which data is written. + @param pError IN/OUT (Filled by the callback) Error. + @return The number of bytes written, or 0 if there was an error. + + @see ASFileSysReadProc + @see ASFileWrite +*/ +typedef ACCBPROTO1 ASSize_t (ACCBPROTO2 *ASFileSysWriteProc)(void *ptr, ASSize_t size, ASSize_t count, ASMDFile f, ASErrorCode *pError); + +/** + A callback for ASFileSysRec that deletes a file. It is called + by ASFileSysRemoveFile(). + @param pathName IN/OUT The file to delete. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysRemoveFile +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysRemoveProc)(ASPathName pathName); + +/** + A callback for ASFileSysRec that renames a file. It is not called + directly by any method in the client API, but is used internally + by the Acrobat viewer. + @param f The file to rename. + @param oldPath The file's old path name. + @param newPath The file's new path name. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysGetNameProc +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysRenameProc)(ASMDFile* f, ASPathName oldPath, ASPathName newPath); + +/** + A callback for ASFileSysRec that tests whether two files are the + same. + @param f IN/OUT The ASFile of the first file to compare. In many implementations + it may be unnecessary to use this information: pathName + and newPathName may provide sufficient information. + @param pathName IN/OUT The ASPathName of the first file to compare. + + @param newPathName IN/OUT The ASPathName of the second file to compare. + + @return 0 if the files are different, a non-zero value if they are the same. +*/ +typedef ACCBPROTO1 ASBool (ACCBPROTO2 *ASFileSysIsSameFileProc)(ASMDFile f, ASPathName pathName, ASPathName newPathName); + +/** + A callback for ASFileSysRec that returns a character string containing + the file name for the specified ASPathName. The character + string contains only the file name; it is not a complete + path name. + +

This callback is not called directly from any plug-in API + method. It is used internally by the Acrobat viewer.

+ + @param pathName IN/OUT The ASPathName for which the file name is + returned. + @param name IN/OUT (Filled by the callback) A character string containing + the file name for pathName. + @param maxLength IN/OUT The maximum number of characters that name + can hold. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysGetFileSysNameProc +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysGetNameProc)(ASPathName pathName, char *name, ASTArraySize maxLength); + +/** + A callback for ASFileSysRec that returns a unique path name suitable + for use in creating temporary files. + + @param pathName IN/OUT If pathName is non-NULL, the temporary + file must be stored such that a renaming of pathName will + succeed. For example, the file is stored on the same volume if renaming across different + volumes is illegal on the file system. + @return The path name for a temporary file. + @see ASFileSysCopyPathNameProc + + @note The ASPathName returned should be released by the + ASFileSysReleasePath() method when it is no longer needed. +*/ +typedef ACCBPROTO1 ASPathName (ACCBPROTO2 *ASFileSysGetTempPathNameProc)(ASPathName pathName); + +/** + A callback for ASFileSysRec that copies a path name (not the underlying + file). It is called by ASFileSysCopyPath(). + +

Copying a path name does not result in any file-level operations, + and does not depend on the existence of an open + file for the path name.

+ + @param pathName IN/OUT The path name to copy. + @return A new copy of the path name. + @see ASFileSysCopyPath + + @note The ASPathName returned should be released by the + ASFileSysReleasePath() method when it is no longer needed. +*/ +typedef ACCBPROTO1 ASPathName (ACCBPROTO2 *ASFileSysCopyPathNameProc)(ASPathName pathName); + +/** + A callback for ASFileSysRec that converts a path name to a device- + independent path name. It is called by ASFileSysDIPathFromPath(). + + @param path IN/OUT The pathname to convert to a device-independent + path name. + @param relativeToThisPath IN/OUT The path relative to which the + device-independent path name is specified. Pass NULL if the + device-independent path name is an absolute path name (for example, c:\\dir1\\dir2\\...dir3\\myfile.pdf ) + instead of a relative path name (for example, ../../dir3/myfile.pdf). + + @return The device-independent path name. + @see ASFileSysDIPathFromPath + + @note The memory for the char* returned should be freed + with the ASfree() method when it is no longer needed. +*/ +typedef ACCBPROTO1 char * (ACCBPROTO2 *ASFileSysDiPathFromPathProc)( + ASPathName path, + ASPathName relativeToThisPath + ); + +/** + A callback for ASFileSysRec that converts a device-independent + path name to an ASPathName. It is called by ASFileSysPathFromDIPath(). + + + @param diPath IN/OUT A device-independent path name to convert to + an ASPathName. + @param relativeToThisPath IN/OUT If diPath is an absolute path name, + the value of this parameter is NULL. If diPath is a relative path name, + the parameter is the path name relative to which it is specified. + @return The ASPathName corresponding to the specified device-independent + path name. + @see ASFileSysPathFromDIPath + @see ASFileSysDIPathFromPath + + @note The ASPathName returned should be released by the + ASFileSysReleasePath() method when it is no longer needed. +*/ +typedef ACCBPROTO1 ASPathName (ACCBPROTO2 *ASFileSysPathFromDIPathProc)( + const char * diPath, + ASPathName relativeToThisPath + + ); +/** + A callback for ASFileSysRec that is called by ASFileSysReleasePath(). + +

This callback frees any memory occupied by pathname. It + does not result in any file-level operations.

+ + @param pathName The path name to release. + @see ASFileSysReleasePath +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASFileSysDisposePathNameProc)(ASPathName pathName); + +/** + A callback for ASFileSysRec that gets this file system's name. + +

This callback is not called directly by any method in the + client API, but is used internally by the Acrobat viewer.

+ + @return The ASAtom containing the name of this file system. + @see ASFileRegisterFileSys +*/ +typedef ACCBPROTO1 ASAtom (ACCBPROTO2 *ASFileSysGetFileSysNameProc)(void); + +/** + A callback for ASFileSysRec that gets the amount of free space + on the volume containing the specified ASPathName. + @param pathName The ASPathName for a file on the volume + whose free space is obtained. + @return The free space in bytes. Because the free space is returned + as an ASInt32 object, it is limited to 4 GB. +*/ +typedef ACCBPROTO1 ASDiskSpace (ACCBPROTO2 *ASFileSysGetStorageFreeSpaceProc)(ASPathName pathName); + +/** + A callback for ASFileSysRec that flushes the volume on which the + specified file resides. This ensures that any data written + to the system for the volume containing pathName is flushed + out to the physical volume (equivalent to the Mac OS + FlushVol, or to the UNIX sync). Call this after you are finished + writing a complete transaction to force a commit. + +

This callback is not called directly from any client API + method, but is used internally by the Acrobat viewer.

+ + @param pathName The path name for the file whose volume + is flushed. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysFlushProc +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysFlushVolumeProc)(ASPathName pathName); + +/** + A callback for ASFileSysRec that creates an ASPathName based on + the input type and PDFileSpec. Each ASFileSys implementation + must publish the input types that it accepts. For example, + the Mac OS ASFileSys may accept the type FSSpecPtr, and + the MS-DOS ASFileSys may only accept types of CString. + + @param pathSpecType The type of the input PDFileSpec. + @param pathSpec The file specification from which to create + an ASPathName. + @param mustBeZero Reserved for future use. + @return The newly created path name. + @see ASFileSysCreatePathName + + @note The ASPathName returned should be released by the + ASFileSysReleasePath() method when it is no longer needed. +*/ +typedef ACCBPROTO1 ASPathName (ACCBPROTO2 *ASFileSysCreatePathNameProc)(ASAtom pathSpecType, const void *pathSpec, + const void *mustBeZero); + + +/** + A callback for ASFileSysRec used to retrieve a full description + of the file system object associated with the path. + @param pathName The ASPathName associated with the object. + + @param props (Filled by the callback) A properties structure + describing the object. + @return 0 to denote success, an error code otherwise. + @see ASFileSysGetItemProps +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysGetItemPropsProc) + (ASPathName pathName, ASFileSysItemProps props); + + +/** + A callback for ASFileSysRec that begins the process of iterating + through the contents of a folder. + @param folderPath The path to the folder through which to iterate. + + @param props (Filled by the callback) A properties structure + describing the object. + @param itemPath (Filled by the callback) A newly allocated + ASPathName associated with the object (which the client + must free). It contains an absolute path. + @return An ASFolderIterator object used for iterating through subsequent + items. If there are no items in the folder, this callback + returns NULL. + @see ASFileSysNextFolderItemProc + @see ASFileSysDestroyFolderIteratorProc + @see ASFileSysFirstFolderItem + @see ASFileSysNextFolderItem + @see ASFileSysDestroyFolderIterator +*/ +typedef ACCBPROTO1 ASFolderIterator (ACCBPROTO2 *ASFileSysFirstFolderItemProc) + (ASPathName folderPath, ASFileSysItemProps props, ASPathName *itemPath); + + +/** + A callback for ASFileSysRec used to continue the iteration + process associated with the ASFolderIterator object. Both + itemPath and props are optional and can be NULL if the caller + is not interested in that information. + @param folderIter An ASFolderIterator object returned + from a previous call to ASFileSysFirstFolderItemProc(). + @param props (Filled by the callback) A properties structure + describing the object. + @param itemPath (Filled by the callback) A newly allocated + ASPathName associated with the object (which the client + must free). It contains an absolute path. + @return false if no other objects were found, true otherwise. + @see ASFileSysFirstFolderItemProc + @see ASFileSysDestroyFolderIteratorProc + @see ASFileSysFirstFolderItem + @see ASFileSysNextFolderItem + @see ASFileSysDestroyFolderIterator +*/ +typedef ACCBPROTO1 ASBool (ACCBPROTO2 *ASFileSysNextFolderItemProc) + (ASFolderIterator folderIter, ASFileSysItemProps props, ASPathName *itemPath); + + +/** + A callback for ASFileSysRec used to release the resources + associated with folderIter. + @param folderIter An ASFolderIterator object returned + from a previous call to ASFileSysFirstFolderItem(). + @see ASFileSysFirstFolderItemProc + @see ASFileSysNextFolderItemProc + @see ASFileSysFirstFolderItem + @see ASFileSysNextFolderItem + @see ASFileSysDestroyFolderIterator +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASFileSysDestroyFolderIteratorProc) + (ASFolderIterator folderIter); + + +/** + A callback for ASFileSysRec used to obtain the URL associated + with the given ASPathName. + @param path The ASPathName in question. + @return The URL or NULL if it cannot be determined. It must be possible to release + the allocated memory with ASfree(). + @see ASFileSysURLFromPath +*/ +typedef ACCBPROTO1 char * (ACCBPROTO2 *ASFileSysURLFromPathProc) + (ASPathName path); + +/** + ASFileSysSetMode() sets and gets parameters for the specified file. + +

Mode operations:

+ + + + + +
OperationCode
Get the current modeASFileSetMode(aFile, 0, 0);
Set the modeASFileSetMode( aFile, kASFileModeDoNotYieldIfBytesNotReady, kASFileModeDoNotYieldIfBytesNotReady );
Clear the modeASFileSetMode( aFile, 0, kASFileModeDoNotYieldIfBytesNotReady );
+ +

Setting parameters:

+ + + + + +
ParameterEffect
kASFileModeDoNotYieldIfBytesNotReadyIf set, then ASFileRead() will not perform a + fileSys->yield() if RaiseIfBytesNotReady is true. + Otherwise, it may call yield before raising the + exception fileErrBytesNotReady.
kASFileModeDisableExplicitMReadRequestsIf set, mread() requests made via ASFileMReadRequest() + become NOPs.
kASFileRaiseIfBytesNotReadyIf set, ASFileRead() will raise fileErrBytesNotReady + when trying to read from a file with a cache for + which the requested bytes are not yet present.
+ + @param asFile The file handle. + @param modeValue The value of bits to be set or cleared. + @param modeMask A mask indicating which bits are to be set or cleared. + +*/ +typedef ACCBPROTO1 ASlFileMode (ACCBPROTO2 *ASFileSysSetModeProc) + (ASMDFile f, ASlFileMode modeValue, ASMaskBits modeMask); + +/** + A callback for ASFileSysRec used to obtain the parent of + the input path. + @param path The ASPathName in question. + @return The parent path, or NULL if path is a root directory. It + is the client's responsibility to free the returned ASPathName. + +*/ +typedef ACCBPROTO1 ASPathName (ACCBPROTO2 *ASFileSysGetParentProc) + (ASPathName path); + +/** + A callback for ASFileSysRec used to create an empty folder + at the specified path. + @param path The path of the folder to create. + @return 0 to denote success, an error code otherwise. + @see ASFileSysRemoveFolderProc + @see ASFileSysCreateFolder +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysCreateFolderProc) + (ASPathName path); + +/** + A callback for ASFileSysRec used to delete the folder at + the specified path. + @param path The path of the folder to remove. + @return 0 to denote success, an error code otherwise. + @see ASFileSysCreateFolderProc + @see ASFileSysRemoveFolder +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysRemoveFolderProc) + (ASPathName path); + +/** + A callback for ASFileSysRec used to obtain a representation + of a path that can be displayed by the user. + @param path The ASPathName in question. + @return The display string, or NULL if some error occurred. It must be possible to release + its memory with ASfree(). + @see ASFileSysDisplayStringFromPath +*/ +typedef ACCBPROTO1 char * (ACCBPROTO2 *ASFileSysDisplayStringFromPathProc) + (ASPathName path); + +/** + A callback for ASFileSysRec that sets the file type and creator + for the file. This callback is currently only implemented on Mac OS. It does + not raise an error. + @param path Path to the file. + @param type File type. + @param creator File creator. + @see ASFileSysGetTypeAndCreatorProc + @see ASFileSysGetTypeAndCreator + @see ASFileSysSetTypeAndCreator +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASFileSysSetTypeAndCreatorProc) + (ASPathName path, ASlFileMode type, ASlFileMode creator); + +/** + A callback for ASFileSysRec that gets the file type and creator + for the file. This callback is currently only implemented on Mac OS. It does + not raise an error. + @param path The path to the file. + @param type (Filled by the callback) The file type. + @param creator (Filled by the callback) The file creator. + @see ASFileSysSetTypeAndCreatorProc + @see ASFileSysGetTypeAndCreator + @see ASFileSysSetTypeAndCreator +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASFileSysGetTypeAndCreatorProc) + (ASPathName path, ASlFileMode *type, ASlFileMode *creator); + +/** + A callback for ASFileSysRec that reopens a file in the specified + mode. ASFileReopen() calls this method if it is present. If + this method is not present, or if it returns NULL and error + is 0, ASFileReopen() does a close followed by an open. If + error is non-zero, ASFileReopen() ignores the return value + and fails with that error. + +

On success, the old file should not need to be closed. On + failure, the old file should remain unchanged.

+ + @param f The file to reopen. + @param newMode The mode for the new session. + @param error The error code for the operation. 0 if the + operation was successful, a non-zero error code otherwise. The error is platform and file-system specific. + @return The newly reopened file or NULL. + @see ASFileReopen + @see ASFileSysOpenFile +*/ +typedef ACCBPROTO1 ASMDFile (ACCBPROTO2 *ASFileSysReopenProc) + (ASMDFile f, ASFileMode newMode, ASErrorCode *error); + +/** + Does a hard flush on the file. A hard flush makes sure + the data is flushed even if the file is remote. This + proc should succeed and do nothing if it is not supported. + +

This does not raise an error.

+*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysHardFlushProc) + (ASMDFile f); + +/** + Returns a platform file system representation of the ASPathName + passed according to the atom selector. It allocates memory for the + returned structure, which the caller must release with ASfree(). + +

This does not raise an error.

+*/ +typedef ACCBPROTO1 void * (ACCBPROTO2 *ASFileSysGetPlatformThingProc) + (ASPathName path, ASAtom thing); + +/** + A callback for ASFileSysRec that gets a full description of the + file system object associated with pathName, returning the + item properties in the ASCab format. + +

If the ASCab has no keys on entry, every known property + is filled in. If it is not empty, only properties corresponding + to keys in the ASCab are filled in. Keys that do not map + to a property of the object are removed. The ASCab has the + following potential entries:

+ + +

ASBool isThere;

+

ASInt32 type;

+

ASBool isHidden;

+

ASBool isReadOnly;

+

char * creationDate; // PDF style date

+

string char * modDate; // PDF style date string

+

ASUns32 fileSizeHigh;

+

ASUns32 fileSizeLow;

+

ASInt32 folderSize;

+

ASUns32 creatorCode;

+

ASUns32 typeCode;

+

ASUns32 versionMajor;

+

ASUns32 versionMinor;

+

ASBool isCheckedOut;

+

ASBool isPublished;

+ + + @param pathName The ASPathName associated with the object. + + @param theCab (Filled by the method) Properties describing + the object, in cabinet format. + @return 0 if no error was encountered; otherwise an error code is + returned. If an error code is returned, theCab is not filled + with valid values. If the path name does not point to an + object on the file system, asFileErrFNF is returned and a valid + ASCab with isThere is set to false. + @see ASFileSysGetItemPropsAsCab +*/ +typedef ACCBPROTO1 ASInt32 (ACCBPROTO2 *ASFileSysGetItemPropsAsCabProc)(ASPathName pathName, ASCab theCab); + +/** + A callback for ASFileSysRec that tests whether a specified operation + can be performed on the file, which means that it tests whether a handler + is defined for that operation in ASFileSysPerformOpOnItemProc. + + @param pathName The ASPathName of the file. + @param op The name of the operation to test. + @return 0 if the operation was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysPerformOpOnItemProc + @see ASFileSysCanPerformOpOnItem +*/ +typedef ACCBPROTO1 ASInt32 (ACCBPROTO2 *ASFileSysCanPerformOpOnItemProc)(ASPathName pathName, const char *op); + +/** + A callback for ASFileSysRec that performs the specified operation + on a particular file. + @param pathName The ASPathName of the file. + @param op The name of the operation to perform (a file system-defined + string). + @param params An ASCab object containing parameters to + pass to the operation. + @return 0 if the operation was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysCanPerformOpOnItemProc + @see ASFileSysPerformOpOnItem +*/ +typedef ACCBPROTO1 ASInt32 (ACCBPROTO2 *ASFileSysPerformOpOnItemProc)(ASPathName pathName, const char *op, ASCab params); + +/** + A callback for ASFileSysRec that acquires a platform-specific + file system representation of the specified path, according + to the specified type, wrapped in an allocated ASPlatformPath + object. Use the ASPlatformPath* calls to get the actual + platform object. + @param path The ASPathName in the current file system. + + @param platformPathType The platform path type, which is one of + the following constants: +
    +
  • FSSpec
    • +
  • FSRef
    • +
  • FSRefWithCFStringRefRec
    • +
  • CFURLRefRec
    • +
+ @param platformPath (Filled by the method) The new platform path object. + @return 0 if the operation was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysAcquireFileSysPathProc + @see ASFileSysAcquirePlatformPath +*/ +typedef ACCBPROTO1 ASInt32 (ACCBPROTO2 *ASFileSysAcquirePlatformPathProc) + (ASPathName path, ASAtom platformPathType, ASPlatformPath *platformPath); + +/** + A callback for ASFileSysRec that releases the specified platform + path object when the client is done with it. + @param platformPath The ASPathName of the file. + @return 0 if the operation was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysAcquirePlatformPathProc + @see ASFileSysReleasePlatformPath +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *ASFileSysReleasePlatformPathProc) + (ASPlatformPath platformPath); + +/** + A callback for ASFileSysRec that gets the file name for the specified + ASPathName as an ASText object. + + @param pathName The ASPathName for which the file name + is returned. + @param name (Filled by the callback) An ASText object for + the file name for pathName. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysGetFileSysNameProc + @see ASFileSysGetNameProc + @note This supersedes ASFileSysGetNameProc() for Acrobat 6.0. +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysGetNameAsASTextProc) + (ASPathName pathName, ASText name); +/** +

Places a representation that can be displayed to users of a path into displayText.

+ +

This does not raise an error.

+*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysDisplayASTextFromPathProc) + (ASPathName path, ASText displayText); + +/** + A callback for ASFileSysRec used when a byte range has + arrived during a file load operation. + @param start The offset from the beginning of the file + to the start of the byte range. + @param length The number of bytes in the byte range. + @param clientData A pointer to the data to pass to the callback. +*/ + typedef ACCBPROTO1 void (ACCBPROTO2 *ASFileSysRangeArrivedProc) + (ASInt32 start, ASInt32 length, void* clientData); + +/** + A callback for ASFileSysRec that determines whether ASFileSys + can set the end of file marker (EOF) to a new offset for the specified file. + @param f The file. + @param pos The new EOF offset. + @return true if the EOF can be set for the file. + @see ASFileSysSetEofProc + @see ASFileGetEOF + @see ASFileSetEOF +*/ +typedef ACCBPROTO1 ASBool (ACCBPROTO2 *ASFileSysCanSetEofProc) + (ASMDFile f, ASFilePos pos); + +/** + A callback for ASFileSysRec that converts a path name to a device-independent + path name, returned as an ASText object. It is called by + ASFileSysDIPathFromPathEx(). + @param path The path name to convert to a device-independent + path name. + @param relativeToThisPath The path relative to which the + device-independent path name is specified. Pass NULL if the + device-independent path name + is an absolute path name (for example, c:\\dir1\\dir2\\dir3\\myfile.pdf) + instead of a relative pathname (for example, ../../dir3/myfile.pdf). + @param diPathText (Filled by the method) The ASText object + to contain the device-independent path. Must be allocated + and freed by the client. + @return 0 if the operation was successful, a non-zero platform-independent error code otherwise. + @see ASFileSysPathFromDIPathExProc + @see ASFileSysDIPathFromPathEx + @see ASFileSysPathFromDIPathEx +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysDIPathFromPathExProc)( + ASPathName path, + ASPathName relativeToThisPath, + ASText diPathText + ); + +/** + A callback for ASFileSysRec that converts a device-independent + path name from an ASText object to an ASPathName. It is called + by ASFileSysPathFromDIPathEx(). + + @param diPathText A device-independent path name to convert to + an ASPathName, as an ASText object. + @param relativeToThisPath If diPath is an absolute path name, + this parameter's value is NULL. If diPath is a relative path name, + its value is the path name relative to which it is specified. + @return The ASPathName corresponding to the specified device-independent + path name. + @see ASFileSysDIPathFromPathExProc + @see ASFileSysPathFromDIPathEx + @see ASFileSysDIPathFromPathEx + + @note The ASPathName returned should be released by the + ASFileSysReleasePath() method when it is no longer needed. +*/ +typedef ACCBPROTO1 ASPathName (ACCBPROTO2 *ASFileSysPathFromDIPathExProc)( + ASConstText diPathText, + ASPathName relativeToThisPath + ); + +/** + A callback for ASFileSysRec that opens the specified file. It + is called by ASFileSysOpen64(). This callback must be used if the file + is over 2 GB in length. + @param pathName IN/OUT The path name for the file to open. + @param mode IN/OUT The mode in which the file is opened. It must + be an OR of the ASFile Open Modes. + @param fP IN/OUT (Filled by the callback) The newly opened file. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysCloseProc + @see ASFileSysOpenFile + @see ASFileReopen + @see ASFileClose +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysOpen64Proc)(ASPathName pathName, ASFileMode mode, ASMDFile *fP); + +/** + A callback for ASFileSysRec that returns the maximum file position that + can be processed by this file system. This is not the maximum size file + that can be created, but the maximum file position that can be handled + by the arithmetic in the file system implementation. This will typically + be (2 ^ 31) - 1 or (2 ^ 63) - 1. If this entry is not present, a value of + (2 ^ 31) - 1 should be assumed. + @param pos IN/OUT The maximum file position that can be handled. + + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysGetFilePosLimit +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysGetFilePositionLimitProc)(ASFilePos64 *pos); + +/** + A callback for ASFileSysRec that sets the current position in + a file, which is the point from which data will next be + read. It is called by ASFileSetPos() and is capable of handling file postions + over 2 GB. + @param f IN/OUT The file in which the position is set. + @param pos IN/OUT The desired new position, specified in bytes + from the beginning of the file. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileGetPos + @see ASFileSetPos +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysSetPos64Proc)(ASMDFile f, ASFilePos64 pos); + +/** + A callback that gets the current position for the specified file. It is called + by ASFileGetPos(), and is capable of handling file postions over 2 GB. + @param f IN/OUT The file whose current position is obtained. + @param pos IN/OUT (Must by filled by the callback) The current + position. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileSysSetPosProc + @see ASFileGetPos + @see ASFileSetPos +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysGetPos64Proc)(ASMDFile f, ASFilePos64 *pos); + +/** + A callback for ASFileSysRec that increases or decreases the logical + size of a file. It is called by ASFileSetEOF() and is capable of handling + file sizes over 2 GB. + @param f IN/OUT The file to expand or shrink. + @param pos IN/OUT The desired size in bytes. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileGetEOF + @see ASFileSetEOF +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysSetEof64Proc)(ASMDFile f, ASFilePos64 pos); + +/** + A callback for ASFileSysRec that gets a file's current logical + size. It is called by ASFileGetEOF() and is capable of handling file sizes over + 2 GB. + @param f IN/OUT The file whose logical size is obtained. + @param pos IN/OUT (Filled by the callback) The file's logical + size in bytes. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. + @see ASFileGetEOF + @see ASFileSetEOF +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysGetEof64Proc)(ASMDFile f, ASFilePos64 *pos); + +/** + A callback for ASFileSysRec that gets the Windows Explorer/Mac Finder + representation for the specified ASPathName as an ASText object. This + may be a localized and extension-stripped version of the filename. + + @param pathName The ASPathName for which the name + is returned. + @param nameForDisplay (Filled by the callback) An ASText object for + the name for pathName. + @return 0 if the request was successful, a non-zero + platform-dependent error code otherwise. +*/ +typedef ACCBPROTO1 ASErrorCode (ACCBPROTO2 *ASFileSysGetNameForDisplayProc) + (ASPathName pathName, ASText nameForDisplay); + +/** + A callback for ASFileSysRec that gets the amount of free space + on the volume containing the specified ASPathName. + It is similar to ASFileSysGetStorageFreeSpace(), except that the return + value is not limited to 4 GB (with a 64-bit return value). + @param pathName The ASPathName for a file on the volume + whose free space is obtained. + @return The free space in bytes. +*/ +typedef ACCBPROTO1 ASDiskSpace64 (ACCBPROTO2 *ASFileSysGetStorageFreeSpace64Proc)(ASPathName pathName); + +/** + A callback for ASFileSysRec that tests whether a file is in use by + another process. + @param pathName IN The ASPathName of the file to be tested. + + @return 0 if the file is not in use, a non-zero value if the file is in use. +*/ +typedef ACCBPROTO1 ASBool (ACCBPROTO2 *ASFileSysIsInUseProc)(ASPathName pathName); + +/** + A data structure containing callbacks that implement a file + system. + @see ASFileSys +*/ +typedef struct _t_ASFileSysRec { + + /** The size of the data structure. It must be set to sizeof( ASFileSysRec). */ + ASSize_t size; + + /** Open file callback. */ + ASFileSysOpenProc open; + + /** Close file callback. */ + ASFileSysCloseProc close; + + /** Flush callback. */ + ASFileSysFlushProc flush; + + /** Set position callback. */ + ASFileSysSetPosProc setpos; + + /** Get position callback. */ + ASFileSysGetPosProc getpos; + + /** Set a file's current logical size. */ + ASFileSysSetEofProc seteof; + + /** Get a file's current logical size. */ + ASFileSysGetEofProc geteof; + + /** Read file callback. */ + ASFileSysReadProc read; + + /** Write file callback. */ + ASFileSysWriteProc write; + + /** Remove file callback. */ + ASFileSysRemoveProc remove; + + /** Rename file callback. */ + ASFileSysRenameProc rename; + + /** Is the same file. */ + ASFileSysIsSameFileProc isSameFile; + + /** Get the file name. */ + ASFileSysGetNameProc getName; + + /** Get the temporary path name. */ + ASFileSysGetTempPathNameProc getTempPathName; + + /** Copy the path name. */ + ASFileSysCopyPathNameProc copyPathName; + + /** Get the device-independent path from the path. */ + ASFileSysDiPathFromPathProc diPathFromPath; + + /** Get the path from the device-independent path. */ + ASFileSysPathFromDIPathProc pathFromDIPath; + + /** Dispose the path name. */ + ASFileSysDisposePathNameProc disposePathName; + + /** Get the file system name.*/ + ASFileSysGetFileSysNameProc getFileSysName; + + /** Get the amount of free space on the volume. */ + ASFileSysGetStorageFreeSpaceProc getStorageFreeSpace; + + /** Flush the volume. */ + ASFileSysFlushVolumeProc flushVolume; + /* Added for Acrobat 3.0) */ + + /** Get the file flags. */ + ASFileSysGetFileFlags getFileFlags; + /* + ** These functions return zero on successful queue, and a non-zero + ** platform dependent error code on failure to queue. If IODoneProc is + ** non-zero (meaning try to operate async), and Read or Write returns + ** non-zero (meaning failure to queue), IODoneProc MUST NOT BE CALLED. + */ + + /** Asynchronous read. */ + ASFileSysAsyncReadProc readAsync; + + /** Asynchronous write. */ + ASFileSysAsyncWriteProc writeAsync; + + /** Asynchronous abort. */ + ASFileSysAsyncAbortProc abortAsync; + + /** Yield callback. */ + ASFileSysYieldProc yield; + + /** Asynchronous request for a byte range. */ + ASFileSysMReadRequestProc mreadRequest; + + /** Retrieve the status. */ + ASFileSysGetStatusProc getStatus; + + + /** Create the path name. */ + ASFileSysCreatePathNameProc createPathName; + + /** Acquire the path. */ + ASFileSysAcquireFileSysPathProc acquireFileSysPath; + + /** Drop read request. */ + ASFileSysClearOutstandingMReadsProc clearOutstandingMReads; + /* END of Acrobat 3.0 ASFileSys definition */ + + /* Added for Acrobat 5.0 */ + + /** Get the file description. */ + ASFileSysGetItemPropsProc getItemProps; + + /** Begin iterating through the folder. */ + ASFileSysFirstFolderItemProc firstFolderItem; + + /** Get the next folder item. */ + ASFileSysNextFolderItemProc nextFolderItem; + + /** Destroy the folder iterator. */ + ASFileSysDestroyFolderIteratorProc destroyFolderIterator; + + /** Set the file mode. */ + ASFileSysSetModeProc setFileMode; + + /** Get the URL from the path. */ + ASFileSysURLFromPathProc urlFromPath; + + /** Get the parent of the input path. */ + ASFileSysGetParentProc getParent; + + /** Create a folder. */ + ASFileSysCreateFolderProc createFolder; + + /** Remove a folder. */ + ASFileSysRemoveFolderProc removeFolder; + + /** Get a display string representing the path. */ + ASFileSysDisplayStringFromPathProc displayStringFromPath; + + /** Set the type and creator. */ + ASFileSysSetTypeAndCreatorProc setTypeAndCreator; + + /** Get the type and creator. */ + ASFileSysGetTypeAndCreatorProc getTypeAndCreator; + + /** Reopen the file. */ + ASFileSysReopenProc reopen; + + /** Perform a hard flush on the file. */ + ASFileSysHardFlushProc hardFlush; + + /* Added for Acrobat 6.0 */ + + /** Deprecated. Get the platform file system representation. */ + ASFileSysGetPlatformThingProc getPlatformThing; /* deprecated */ + + /** Get the file item properties in ASCab format. */ + ASFileSysGetItemPropsAsCabProc getItemPropsAsCab; + + /** Test whether an operation can be performed. */ + ASFileSysCanPerformOpOnItemProc canPerformOpOnItem; + + /** Perform the operation. */ + ASFileSysPerformOpOnItemProc performOpOnItem; + + /** Acquire the platform path. */ + ASFileSysAcquirePlatformPathProc acquirePlatformPath; + + /** Release the platform path. */ + ASFileSysReleasePlatformPathProc releasePlatformPath; + + /** Get the file name as an ASText object. */ + ASFileSysGetNameAsASTextProc getNameAsASText; + + /** Get the path for display. */ + ASFileSysDisplayASTextFromPathProc displayASTextFromPath; + + /** The byte range has arrived. */ + ASFileSysRangeArrivedProc rangeArrived; + + /** Determine whether the ASFileSys can set the end of file marker (EOF) to a new offset for the specified file. */ + ASFileSysCanSetEofProc canSetEof; + + /** Convert a path to a device-independent path. */ + ASFileSysDIPathFromPathExProc diPathFromPathEx; + + /** Convert a device-independent path to a path. */ + ASFileSysPathFromDIPathExProc pathFromDIPathEx; + + /** Get the maximum file position that can be processed by this file system. */ + ASFileSysGetFilePositionLimitProc getfileposlimit; + + /** Open a file over 2 GB in length. */ + ASFileSysOpen64Proc open64; + + /** Set the current position in a file over 2 GB in length. */ + ASFileSysSetPos64Proc setpos64; + + /** Get the current position in a file over 2 GB in length. */ + ASFileSysGetPos64Proc getpos64; + + /** Increase or decrease the logical size for a file over 2 GB in length. */ + ASFileSysSetEof64Proc seteof64; + + /** Get a file's current logical size for a file over 2 GB in length. */ + ASFileSysGetEof64Proc geteof64; + + /** Gets the Windows Explorer or Mac Finder representation of the specified ASPathName as an ASText object. */ + ASFileSysGetNameForDisplayProc getNameForDisplay; + + /* Added for Acrobat 8.0 */ + + /** Get the amount of free space on the volume. */ + ASFileSysGetStorageFreeSpace64Proc getStorageFreeSpace64; + + + /* Added for Acrobat 9.0 */ + + /** Determine whether the file is in use by another process. */ + ASFileSysIsInUseProc isInUse; + +} ASFileSysRec; + +/*------------------------------------------------------------------------ + Generic monitor typedefs +-------------------------------------------------------------------------*/ + + +/** + A callback used in ASProgressMonitor that initializes the progress + monitor and displays it with a current value of zero. This + method must be called first when the progress monitor is + used. + @param clientData IN/OUT User-supplied data that was passed in + the call to whatever API method required the progress monitor. + + @see PMEndOperationProc +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *PMBeginOperationProc)(void *clientData); + +/** + A callback used in ASProgressMonitor that draws the progress monitor + with its current value set to the progress monitor's duration + (a full progress monitor), then removes the progress monitor + from the display. + @param clientData IN/OUT User-supplied data that was passed in + the call to whatever API method required the progress monitor. + + @see PMBeginOperationProc +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *PMEndOperationProc)(void *clientData); + +/** + A callback used in ASProgressMonitor that sets the value that corresponds + to a full progress monitor display. The progress monitor + is subsequently filled in by setting its current value. + This method must be called before you can set the progress + monitor's current value. + @param duration IN/OUT The maximum value the progress monitor + will be allowed to have. + @param clientData IN/OUT User-supplied data that was passed in + the call to whatever API method required the progress monitor. + + @see PMGetDurationProc +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *PMSetDurationProc)(ASDuration duration, void *clientData); + +/** + A callback used in ASProgressMonitor that sets the current value + of the progress monitor and updates the display. The allowed + value ranges from 0 (empty) to the value passed to setDuration. + For example, if the progress monitor's duration is 10, the + current value must be between 0 and 10, inclusive. + @param currValue IN/OUT The progress monitor's current value. + + @param clientData IN/OUT User-supplied data that was passed in + the call to whatever API method required the progress monitor. + + @see PMGetCurrValueProc +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *PMSetCurrValueProc)(ASDuration currValue, void *clientData); + +/** + A callback used in ASProgressMonitor that gets the progress monitor's + duration, set by the most recent call to the progress monitor's + PMSetDurationProc(). + @param clientData IN/OUT User-supplied data that was passed in + the call to whatever API method required the progress monitor. + + @return The progress monitor's maximum value. + @see PMSetDurationProc +*/ +typedef ACCBPROTO1 ASDuration (ACCBPROTO2 *PMGetDurationProc)(void *clientData); + +/** + A callback used in ASProgressMonitor that gets the progress monitor's + duration, set by the most recent call to the progress monitor's + PMSetCurrValueProc(). + @param clientData IN/OUT User-supplied data that was passed in + the call to whatever API method required the progress monitor. + + @see PMSetCurrValueProc +*/ +typedef ACCBPROTO1 ASDuration (ACCBPROTO2 *PMGetCurrValueProc)(void *clientData); + +/** + A callback within ASProgressMonitorRec that sets the text + string that is displayed by the progress monitor. + +

The built-in document progress monitor (see AVAppGetDocProgressMonitor()) + makes a copy of the text. As such, it is the client's responsibility + to destroy it.

+ + @param text IN/OUT The string to display. + @param clientData IN/OUT A pointer to the data associated with + the progress monitor (which should be passed in with + the progress monitor). +*/ +typedef ACCBPROTO1 void (ACCBPROTO2 *PMSetTextProc)(ASText text, void *clientData); + +/** +

Replaced by ASProgressMonitor in Acrobat 5.0.

+ +

A data structure containing callbacks that implement a progress + monitor. The callbacks implement the progress monitor functions. + A progress monitor is used to display progress during potentially + time-consuming operations. Progress monitors are included + as parameters in many API calls. Acrobat's built-in progress + monitor can be obtained by calling AVAppGetDocProgressMonitor().

+ + @see AVAppGetDocProgressMonitor + @see PDDocCreateThumbs + @see PDDocSave +*/ +typedef struct _t_ProgressMonitor +{ + + /** The size of the data structure. It must be set to sizeof(ProgressMonitorRec). + */ + ASSize_t size; + + /** Initialize the progress monitor and display it with a current value of zero. */ + PMBeginOperationProc beginOperation; + + /** Draw the progress monitor with its current value set to the progress monitor's duration (a full progress monitor). */ + PMEndOperationProc endOperation; + + /** Set the progress monitor's duration. */ + PMSetDurationProc setDuration; + + /** Set the current value of the progress monitor and update the display. */ + PMSetCurrValueProc setCurrValue; + + /** Get the progress monitor's duration. */ + PMGetDurationProc getDuration; + + /** Get the progress monitor's duration. */ + PMGetCurrValueProc getCurrValue; + + /** Set the text string that is displayed by the progress monitor. */ + PMSetTextProc setText; +} +ASProgressMonitorRec, *ASProgressMonitor; + +/* Allow clients to use the older names, without the "AS" prefix. +These are present only for backward compatibility - they must +not be used for new code. */ +#define ProgressMonitor ASProgressMonitor +#define ProgressMonitorRec ASProgressMonitorRec + +/** +

This callback replaces CancelProc().

+ +

A callback to check for cancelling operations. An ASCancelProc() + is typically passed to some method that takes a long time + to complete. At frequent intervals, the method calls the + ASCancelProc(). If it returns true, the method cancels + its operation; if it returns false, it continues.

+ @param clientData IN/OUT User-supplied data that was passed to + the method that uses the ASCancelProc(). + @return true if the processing is to be canceled, false otherwise. + + @see PDFLPrintCancelProc (Only available with the PDF Library SDK) + + @see AVAppGetCancelProc + @see PDDocCreateThumbs + @see PDDocInsertPages +*/ +typedef ACCBPROTO1 ASBool (ACCBPROTO2 *ASCancelProc)(void *clientData); + +/* Define older name for backward compatibilty. Do not use this older name +in new code */ +#define CancelProc ASCancelProc + +/* ASPortRef */ +#if MAC_PLATFORM +typedef CGrafPtr ASPortRef; +#elif WIN_PLATFORM + +/** + Provides access to a port. On Windows, ASPortRef is the same as HDC. +*/ +typedef void* ASPortRef; +#elif UNIX_PLATFORM +typedef void* ASPortRef; +#endif + +/* ASWindowRef */ +#if MAC_PLATFORM +typedef WindowRef ASWindowRef; +#elif WIN_PLATFORM + +/** + A platform-dependent window handle corresponding to an HWND in Windows, + a WindowPtr on Mac OS, and a Widget on UNIX. +*/ +typedef void* ASWindowRef; +#elif UNIX_PLATFORM +typedef void* ASWindowRef; +#endif + +#if DEBUG +#define CHECKTYPE(type, data) ((void *)((data) == ((type)data) ? data : data)) +#else /* !DEBUG */ +#define CHECKTYPE(type, data) ((void *)data) +#endif /* !DEBUG */ + +/* Helper defines for the mystical ASFileSysCreatePathName. */ +/** + A helper macro for the ASFileSysCreatePathName() method. + @param asfs (May be NULL) The file system through which + the ASPathName is obtained. + @param cDIPath A C string containing the device-independent + path for which the ASPathName is obtained. + @param aspRelativeTo (May be NULL) An ASPathName against which + cDIPath will be evaluated if it contains a relative + path. + @see ASFileSysCreatePathFromCString + @see ASFileSysCreatePathFromFSSpec + @see ASFileSysCreatePathWithFolderName +*/ +#define ASFileSysCreatePathFromDIPath(asfs, cDIPath, aspRelativeTo) \ + ASFileSysCreatePathName(asfs, ASAtomFromString("DIPath"), \ + (void *)CHECKTYPE(char *, cDIPath), (void *)CHECKTYPE(ASPathName, aspRelativeTo)) +/** */ +#define ASFileSysCreatePathFromDIPathText(asfs, tDIPath, aspRelativeTo) \ + ASFileSysCreatePathName(asfs, ASAtomFromString("DIPathWithASText"), \ + (void *)CHECKTYPE(ASText, tDIPath), (void *)CHECKTYPE(ASPathName, aspRelativeTo)) +/** + Helper macro for the ASFileSysCreatePathName() method. + @param asfs (May be NULL) The file system through which + the ASPathName is obtained. + @param aspFolder An ASPathName containing the path of the + folder. + @param cFileName A C string containing the name of the + file. The returned ASPathName contains the result of appending + cFileName to aspFolder. + @see ASFileSysCreatePathFromCString + @see ASFileSysCreatePathFromDIPath + @see ASFileSysCreatePathFromFSSpec +*/ +#define ASFileSysCreatePathWithFolderName(asfs, aspFolder, cFileName) \ + ASFileSysCreatePathName(asfs, ASAtomFromString("FolderPathName"), \ + (void *)CHECKTYPE(ASPathName, aspFolder), (void *)CHECKTYPE(char *, cFileName)) +/** */ +#define ASFileSysCreatePathWithFolderNameWithASText(asfs, aspFolder, tFileName) \ + ASFileSysCreatePathName(asfs, ASAtomFromString("FolderPathNameWithASText"), \ + (void *)CHECKTYPE(ASPathName, aspFolder), (void *)CHECKTYPE(ASText, tFileName)) +/** + Helper macro for the ASFileSysCreatePathName() method. + + @param asfs (May be NULL) The file system through which + the ASPathName is obtained. + @param cPath A C string containing the path for which + the ASPathName is obtained. + @see ASFileSysCreatePathFromDIPath + @see ASFileSysCreatePathFromFSSpec + @see ASFileSysCreatePathWithFolderName + @note This macro uses a local variable named scratchFourBytes: + (void* scratchFourBytes). PDF Library users need to provide + this variable in order to utilize the macro; the variable + must be local to the client application, not to the library. + Any client can use this macro provided that it has code + similar to the following, in the same source file that uses + the macro: static void* scratchFourBytes; +*/ +#define ASFileSysCreatePathFromCString(asfs, cPath) \ + ASFileSysCreatePathName(asfs, ASAtomFromString("Cstring"), \ + (void *)CHECKTYPE(char *, cPath), NULL); +#if MAC_PLATFORM +/** + Helper macro for the ASFileSysCreatePathName() method. + @param asfs (May be NULL) The file system through which + the ASPathName is obtained. + @param cPath The FSSpec for which the ASPathName is obtained. + @see ASFileSysCreatePathFromCString + @see ASFileSysCreatePathFromDIPath + @see ASFileSysCreatePathWithFolderName +*/ +#define ASFileSysCreatePathFromFSSpec(asfs, cPath) \ + ASFileSysCreatePathName(asfs, ASAtomFromString("FSSpec"), \ + (void *)CHECKTYPE(FSSpec *, cPath), NULL); +/** */ +#define ASFileSysCreatePathFromFSRef(asfs, fsRef) \ + ASFileSysCreatePathName(asfs, ASAtomFromString("FSRef"), \ + (void *)CHECKTYPE(FSRef, fsRef), NULL); +/** */ +#define ASFileSysCreatePathFromFSRefWithCFStringRef(asfs, fsRefWithCFStringRef) \ + ASFileSysCreatePathName(asfs, ASAtomFromString("FSRefWithCFStringRef"), \ + (void *)CHECKTYPE(FSRefWithCFStringRefRec *, fsRefWithCFStringRef), NULL); +/** */ +#define ASFileSysCreatePathFromCFURLRef(asfs, cfURLRef) \ + ASFileSysCreatePathName(asfs, ASAtomFromString("CFURLRef"), \ + (void *)CHECKTYPE(CFURLRef, cfURLRef), NULL); +/** */ +#define ASFileSysCreatePathFromPOSIXPath(asfs, posixPath) \ + ASFileSysCreatePathName(asfs, ASAtomFromString("POSIXPath"), \ + (void *)CHECKTYPE(char *, posixPath), NULL); +#endif + +/* Definitions related to encodings and encoding conversions */ + + +/** + Describes the various Unicode formats you can place into + and read out of an ASText object. + @see ASTextFromUnicode + @see ASTextFromSizedUnicode + @see ASTextSetUnicode + @see ASTextSetSizedUnicode + @see ASTextGetUnicodeCopy +*/ +enum { + /** Always returns the bytes in big-endian order.*/ + kUTF16BigEndian, + /** Returns the bytes in the host's native endian order, whatever is natural for an ASUns16.*/ + kUTF16HostEndian, + /** Endian neutral.*/ + kUTF8, + /** Always returns the bytes in big-endian order.*/ + kUTF32BigEndian, + /** Returns the bytes in the host's native endian order, whatever is natural for an ASUns32.*/ + kUTF32HostEndian +}; +typedef ASEnum16 ASUnicodeFormat; + +/** + An integer specifying the host encoding for text. On Mac OS, + it is a script code. On Windows, it is a CHARSET id. + In UNIX, Acrobat currently only supports English, so the + only valid ASHostEncoding is 0 (Roman). See ASScript. +*/ +typedef ASInt32 ASHostEncoding; + +/** An ASUnicodeChar is large enough to hold any Unicode character + (at least 21 bits wide). +*/ +typedef ASUns32 ASUnicodeChar; +typedef ASUns32 ASUTF32Val; + +/** + Holds a single 16-bit value from a UTF-16 encoded Unicode + string. It is typically used to point to the beginning of an UTF-16 + string. For example: ASUTF16Val *utf16String = ... +

This data type is not large enough to hold any arbitrary + Unicode character. Use ASUnicodeChar to pass individual + Unicode characters.

+ @see ASTextGetUnicode + @see ASTextGetUnicodeCopy +*/ +typedef ASUns16 ASUTF16Val; + +/** An ASUTF8Val holds a single 8-bit value from a UTF-8 encoded + Unicode string. +*/ +typedef ASUns8 ASUTF8Val; + +/** + An enumeration of writing scripts. Not all of these scripts + are supported on all platforms. +*/ +enum { + + /** Roman. */ + kASRomanScript, + /** Japanese. */ + kASJapaneseScript, + /** Traditional Chinese. */ + kASTraditionalChineseScript, + /** Korean. */ + kASKoreanScript, + /** Arabic. */ + kASArabicScript, + /** Hebrew. */ + kASHebrewScript, + /** Greek. */ + kASGreekScript, + /** Cyrillic. */ + kASCyrillicScript, + /** RightLeft. */ + kASRightLeftScript, + /** Devanagari. */ + kASDevanagariScript, + /** Gurmukhi. */ + kASGurmukhiScript, + /** Gujarati. */ + kASGujaratiScript, + /** Oriya. */ + kASOriyaScript, + /** Bengali. */ + kASBengaliScript, + /** Tamil. */ + kASTamilScript, + /** Telugu. */ + kASTeluguScript, + /** Kannada. */ + kASKannadaScript, + /** Malayalam. */ + kASMalayalamScript, + /** Sinhalese. */ + kASSinhaleseScript, + /** Burmese. */ + kASBurmeseScript, + /** Khmer */ + kASKhmerScript, + /** Thai */ + kASThaiScript, + /** Laotian. */ + kASLaotianScript, + /** Georgian. */ + kASGeorgianScript, + /** Armenian. */ + kASArmenianScript, + /** Simplified Chinese. */ + kASSimplifiedChineseScript, + /** Tibetan. */ + kASTibetanScript, + /** Mongolian. */ + kASMongolianScript, + /** Ge'ez. */ + kASGeezScript, + /** East European Roman. */ + kASEastEuropeanRomanScript, + /** Vietnamese. */ + kASVietnameseScript, + /** Extended Arabic. */ + kASExtendedArabicScript, + /** Unicode. */ + kASEUnicodeScript, + /** Unknown. */ + kASDontKnowScript = -1 +}; +typedef ASInt32 ASScript; + +/* UUID structure */ +/** + A structure representing a universal unique identifier (UUID) for the current user or the + current session. +*/ +typedef struct +{ + /** Timestamp low field. */ + ASUns32 timeLow; + /** Timestamp middle field. */ + ASUns16 timeMid; + /** Timestamp middle field multiplexed with the version number.*/ + ASUns16 timeHiAndVersion; + /** High field of the clock sequence multiplexed with the variant. */ + ASUns8 clockSeqHiAndReserved; + /** Low field of the clock sequence. */ + ASUns8 clockSeqLow; + /** The spatially unique node identifier. */ + ASUns8 node[6]; +} ASUUID; + +/** + A constant for the maximum string length of a unique identifier + (UUID). + @see ASUUIDToCString +*/ +#define ASUUIDMaxStringLen 40 /* leave a bit of padding just in case */ + +/*------------------------------------------------------------------------ + typedefs for ASDate +------------------------------------------------------------------------*/ + +/* ASDate +* +*/ + +/* string formats + kASTimePDF = "D:20000911121643-08'00'" + kASTimeUniversal = "2000.09.11 13:30:20 -08'00' DST" + kASTimeUniversalH = "2000-09-11 13:30:20 -08'00' DST" + kASTimeUTC_ASN1 = "000911203020Z" + kASTimeGENERALIZED_ASN1 = "20000911203020Z" */ + +/** A constant indicating a string format for representing a date and time. */ +enum { + /** None. */ + kASTimeNone=0, + /** PDF date format, as defined in the PDF Reference. */ + kASTimePDF, + /** Slight variations of the time format expressed in ISO 8601. */ + kASTimeUniversal, + /** Slight variations of the time format expressed in ISO 8601. */ + kASTimeUniversalH, + /** UTC ASN1 format. */ + kASTimeUTC_ASN1, + /** ASN1 format. */ + kASTimeGENERALIZED_ASN1 + }; +typedef ASEnum8 ASDateTimeFormat; + +/** An opaque object holding information for a particular date and time. + All ASDate objects are guaranteed to give accurate representation of UTC time, unadjusted for + leap seconds. This is due to the fact that the introduction of leap seconds + to the international calendar does not happen according to a well-defined + rule. + @see ASDateGetCurrentLocalTime + @note ASDate objects are not guaranteed to represent local time accurately. + To be exact, in Mac OS and UNIX, ASDate cannot always determine the prevailing + daylight saving rule for the operating system's time zone. See ASDateGetCurrentLocalTime() + for further explanation. +*/ +typedef struct _t_ASDateRec *ASDate; + +/** + Represents a calendar time span used to calculate ambiguous + time spans such as 1 year and 3 months. A calendar time + span cannot be negative. + @see ASCalendarTimeSpanAddWithBase + @see ASCalendarTimeSpanCompare + @see ASCalendarTimeSpanDiff +*/ +typedef struct _t_ASCalendarTimeSpan{ + /** Year. */ + ASUns32 Year; + /** Month. */ + ASUns32 Month; + /** Day. */ + ASUns32 Day; + /** Hour. */ + ASUns32 Hour; + /** Minute. */ + ASUns32 Minute; + /** Second. */ + ASUns32 Second; +} ASCalendarTimeSpanRec, *ASCalendarTimeSpan; + +/** + An ASTimeSpan represents an exact time span, measured in seconds. The internal representation uses + 64-bit signed integers to avoid the year 2037 problem. Negative timespans are allowed. +*/ +typedef struct _t_ASTimeSpanRec *ASTimeSpan; + +#ifdef __cplusplus +} +#endif + +#if PRAGMA_STRUCT_ALIGN + #pragma options align=reset +#endif + +#endif /* _H_ASExpT */ -- cgit v1.2.3