AS_Layer.ASFile (Acrobat)

	Define
	ASFILE_CREATE Create the file if it does not exist.
	ASFILE_ENCRYPT File is to be encrypted when written to disk Encryption is with an instance specific key, so that the file is NOT readable if it is accidentally left when Acrobat exits (say, on a crash)
	ASFileError
	ASFILE_LOCAL A hint indicating that a local copy of the file will be needed.
	ASFILE_RANDOMACCESS A hint indicating that the file will be primarily accessed randomly.
	ASFILE_READ Open the file for reading.
	ASFILE_SERIAL A hint indicating that the file will be primarily accessed sequentially.
	ASFILE_TEMPORARY A hint that file is for temporary usage. Disk backing store is deleted on close, writes are not flushed to disk on close. If possible the file will be kept in memory.
	ASFILE_WRITE Open the file for writing.
	kASFileDialUp (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.
	kASFileDoCaching Set if the file is to be cached (requires kASFileUseMRead to be set as well).
	kASFileHasOutstandingMReads true if the file has outstanding MReads.
	kASFileHasVirtualEOF true if the file is built with a Virtual EOF (Acrobat 10).
	kASFileModeDisableExplicitMReadRequests If set, the file will be read all at once regardless of multiple read requests.
	kASFileModeDoNotYieldIfBytesNotReady If set, ASFileRead does not yield if bytes are not ready (which raises the fileErrBytesNotReady exception).
	kASFileNoRequestIfBytesNotReady If set, no read requests are issued if bytes are not ready (that is, the bytes are not in the cache).
	kASFileRaiseIfBytesNotReady 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.
	kASFileSlowConnect 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.
	kASFileSlowTransfer 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.
	kASFileStillFetching Set if the file is still being loaded.
	kASFileSuspendIfBytesNotReady 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.
	kASFileUseMRead Use multi-read commands to access the file.
	MDFile

	Typedef
	ASFile 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.
	ASFileMode 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: Value Description ASFILE_READ Open the file for reading. ASFILE_WRITE Open the file for writing. ASFILE_CREATE Create the file if it does not exist. ASFILE_SERIAL A hint indicating that the file will be accessed sequentially. ASFILE_LOCAL A hint indicating that a local copy of the file will be needed.
	ASFilePos A file position value for use in callback procedures. This value cannot exceed 2 GB.
	ASFilePos64 The absolute position within a file. This value can exceed 2 GB.

	Enumeration
	`ASFileStatusFlags` Values returned by ASFileSysGetStatusProc().

	Callback
	ASFileCompletionProc Called when an asynchronous read or write request has completed.

	Method
	ASPathName ASFileAcquirePathName(ASFile aFile) Gets the path name for a file and increments an internal reference count. It is the caller's responsibility to release the ASPathName when it is no longer needed by using ASFileSysReleasePath().
	void ASFileAttachmentCreatePathName(PDDoc pdDoc, ASText pathText, ASFileSys* fileSys, ASPathName* pathName) Creates an ASPathName corresponding to the specified file or folder in the collection.
	ASBool ASFileAttachmentGetPDFileAttachment(ASFileSys fileSys, ASPathName pathName, PDFileAttachment* attachment) Produces a PDFileAttachment corresponding to the ASFileSys and ASPathName. It raises an exception if the ASFileSys is is not the embedded files file system, or if the ASPathName or PDFileAttachment parameters are NULL.
	ASBool ASFileAttachmentGetPDFolder(ASFileSys fileSys, ASPathName pathName, PDFolder* folder) Produces a PDFolder corresponding to the ASFileSys and ASPathName. It raises an exception if the ASFileSys is is not the embedded files file system, or if the ASPathName or PDFolder parameters are NULL.
	ASBool ASFileCanSetEOF(ASFile file, ASInt32 newFileSize) Checks if ASFileSetEOF() can be done for this file with a specified new file size.
	void ASFileClearOutstandingMReads(ASFile fN) Clears all outstanding mreads for the given file.
	ASErrorCode ASFileClose(ASFile aFile) Closes the specified file. After a call to ASFileClose(), the file handle is no longer valid but may be reused as the result of a subsequent call to ASFileSysOpenFile().
	void ASFileFlush(ASFile aFile) Flushes any buffered data to a file. This method may raise file system or platform-specific exceptions.
	ASBool ASFileFromMDFile(ASMDFile mdFile, ASFileSys fileSys, ASFile* pfN) Gets the ASFile associated with the specified ASMDFile and ASFileSys.
	ASTFilePos ASFileGetEOF(ASFile aFile) Gets the current size of a file. It calls ASFileSysGetEofProc(). This call returns an error if the file size is greater than 2 GB.
	ASFilePos64 ASFileGetEOF64(ASFile aFile) Gets the current size of a file.
	ASFileSys ASFileGetFileSys(ASFile aFile) Gets the file system through which a file was opened.
	ASFileSys ASFileGetFileSysByName(ASAtom name) Gets the file system that was registered with the specified name.
	ASBool ASFileGetMDFile(ASFile fN, ASMDFile* pFileID, ASFileSys* pFileSys) Given an ASFile, returns the fileSys and the ASMDFile identification in that fileSys. This call is needed for a file system in a plug-in to be able to call the inner routines in another file system.
	ASFileMode ASFileGetOpenMode(ASFile fN) Gets the file access mode(s) specified for the file when it was opened.
	ASTFilePos ASFileGetPos(ASFile aFile) Gets the current seek position in a file. This is the position at which the next read or write will begin. This call returns an error if the file position is greater than 2 GB.
	ASFilePos64 ASFileGetPos64(ASFile aFile) Gets the current seek position in a file. This is the position at which the next read or write will begin. This call will work with files over 2 GB in length.
	char* ASFileGetURL(ASFile asf) Returns the URL associated with file. It is the caller's responsibility to release the memory associated with the returned string using ASfree().
	ASErrorCode ASFileHardFlush(ASFile aFile) Causes a hard flush on a file, which means that the file is flushed to the physical destination. For example, if a WebDAV-based file is opened, ASFileFlush() only flushes changes to the local cached version of the file. This method would flush changes all the way to the WebDAV server.
	ASBool ASFileHasOutstandingMReads(ASFile fN) Determines whether there are any outstanding multi-byte range requests for a file. A document can have outstanding mreads if it was opened in a browser, Acrobat requested some byte ranges, and the byte ranges have not yet arrived.
	ASBool ASFileIsSame(ASFile fN, ASPathName pathName, ASFileSys fileSys) Performs a comparison between the file and path to determine if they represent the same file. This method will return false if the file was not opened through the fileSys file system.
	void ASFileMReadRequest(ASFile fN, ASInt32* blockPairs, ASTCount nBlockPairs) Initiates a byte range request for a given file, if the file is in the browser.
	ASInt32 ASFileOpenWithVirtualEOF(ASFile fN, ASFilePos64 virtualEOF, ASFile* newFile) ASFileOpenWithVirtualEOF attempts to create a second ASFile instance to a file that is already open. Both the current instance fN and the new instance must be read only. The new instance shall set a virtual end of file. This virtual EOF and no effect on the first instance or on the physical file. It only effect the ASFile calls where newFile is passed in has the file. Each instance maintains it's own file position marker. The original instance of the file should be close after all other instances have been closed. This routine does not raise, but returns an error code.
	void ASFilePushData(ASFile aFile, const char* p, ASTFilePos offset, ASTArraySize length) Sends data from a file system implementation to an ASFile. The data may be for a multi-read request call, or may be unsolicited.
	ASTArraySize ASFileRead(ASFile aFile, char* p, ASTArraySize count) Reads data from a file, beginning at the current seek position.
	ASBool ASFileRegisterFileSys(ASExtension extension, ASFileSys fileSys) Allows an implementor to provide a file system for use by external clients. An external client can locate the file system using ASFileGetFileSysByName(). fileSys provides its name via the ASFileSysGetFileSysNameProc() callback. This method returns false if a file system with the same name is already registered.
	ASErrorCode ASFileReopen(ASFile aFile, ASFileMode mode) Attempts to reopen a file using the specified read/write mode. On some platforms, this may result in the file being closed and then reopened, and some error conditions may render the file invalid.
	void ASFileSetEOF(ASFile aFile, ASTFilePos newFileSize) Changes the size of a file. The new size may by larger or smaller than the original size. Since this method does not return any values, the status can be assessed by examining the error code in the HANDLER clause. This method may raise file system or platform-specific exceptions. This call only works when the desired file size is less than 2 GB.
	void ASFileSetEOF64(ASFile aFile, ASFilePos64 newFileSize) Changes the size of a file. The new size may by larger or smaller than the original size. This method may raise file system or platform-specific exceptions. This call will work with files over 2 GB in length.
	ASFlagBits ASFileSetMode(ASFile fN, ASFlagBits modeValue, ASFlagBits modeMask) Gets or sets the mode flags for a file. Pass 0 for modeValue and modeMask to simply get the current mode flags.
	void ASFileSetPos(ASFile aFile, ASTFilePos pos) Seeks to the specified position in a file. This is the position at which the next read or write will begin. This call only works when the desired file position is less than 2 GB.
	void ASFileSetPos64(ASFile aFile, ASFilePos64 pos) Seeks to the specified position in a file. This is the position at which the next read or write will begin. This call will work with files over 2 GB in length.
	ASBool ASFileUnregisterFileSys(ASExtension extension, ASFileSys fileSys) Allows a fileSys to be unregistered. In general, a fileSys is only unregistered by the extension that registered it.
	ASTArraySize ASFileWrite(ASFile aFile, const char* p, ASTArraySize count) Writes data to a file, beginning at the current seek position.

Defines Detail

ASFILE_CREATE

Product availability: All

Platform availability: All

Syntax


#define ASFILE_CREATE 4

Description

Create the file if it does not exist.

File: ASExpT.h

Line: 1477

ASFILE_ENCRYPT

Product availability: All

Platform availability: All

Syntax


#define ASFILE_ENCRYPT 128

Description

File is to be encrypted when written to disk Encryption is with an instance specific key, so that the file is NOT readable if it is accidentally left when Acrobat exits (say, on a crash)

File: ASExpT.h

Line: 1508

ASFILE_LOCAL

Product availability: All

Platform availability: All

Syntax


#define ASFILE_LOCAL 16

Description

A hint indicating that a local copy of the file will be needed.

File: ASExpT.h

Line: 1488

ASFILE_RANDOMACCESS

Product availability: All

Platform availability: All

Syntax


#define ASFILE_RANDOMACCESS 32

Description

A hint indicating that the file will be primarily accessed randomly.

File: ASExpT.h

Line: 1493

ASFILE_READ

Product availability: All

Platform availability: All

Syntax


#define ASFILE_READ 1

Description

Open the file for reading.

File: ASExpT.h

Line: 1467

ASFILE_SERIAL

Product availability: All

Platform availability: All

Syntax


#define ASFILE_SERIAL 8

Description

A hint indicating that the file will be primarily accessed sequentially.

File: ASExpT.h

Line: 1483

ASFILE_TEMPORARY

Product availability: All

Platform availability: All

Syntax


#define ASFILE_TEMPORARY 64

Description

A hint that file is for temporary usage. Disk backing store is deleted on close, writes are not flushed to disk on close. If possible the file will be kept in memory.

File: ASExpT.h

Line: 1500

ASFILE_WRITE

Product availability: All

Platform availability: All

Syntax


#define ASFILE_WRITE 2

Description

Open the file for writing.

File: ASExpT.h

Line: 1472

ASFileError

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define ASFileError ErrBuildCode(ErrAlways, ErrSysASFile, e)

File: AcroErr.h

Line: 310

kASFileDialUp

Product availability: All

Platform availability: All

Syntax


#define kASFileDialUp 0x00000010L

Description

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

File: ASExpT.h

Line: 1542

kASFileDoCaching

Product availability: All

Platform availability: All

Syntax


#define kASFileDoCaching 0x00000008L

Description

Set if the file is to be cached (requires kASFileUseMRead to be set as well).

File: ASExpT.h

Line: 1535

kASFileHasOutstandingMReads

Product availability: All

Platform availability: All

Syntax


#define kASFileHasOutstandingMReads 0x00000040L

Description

true if the file has outstanding MReads.

File: ASExpT.h

Line: 1552

kASFileHasVirtualEOF

Product availability: All

Platform availability: All

Syntax


#define kASFileHasVirtualEOF 0x00000080L

Description

true if the file is built with a Virtual EOF (Acrobat 10).

File: ASExpT.h

Line: 1557

kASFileModeDisableExplicitMReadRequests

Product availability: All

Platform availability: All

Syntax


#define kASFileModeDisableExplicitMReadRequests 0x0002

Description

If set, the file will be read all at once regardless of multiple read requests.

File: ASExpT.h

Line: 1573

kASFileModeDoNotYieldIfBytesNotReady

Product availability: All

Platform availability: All

Syntax


#define kASFileModeDoNotYieldIfBytesNotReady 0x0001

Description

If set, ASFileRead does not yield if bytes are not ready (which raises the fileErrBytesNotReady exception).

File: ASExpT.h

Line: 1566

kASFileNoRequestIfBytesNotReady

Product availability: All

Platform availability: All

Syntax


#define kASFileNoRequestIfBytesNotReady 0x0008

Description

If set, no read requests are issued if bytes are not ready (that is, the bytes are not in the cache).

File: ASExpT.h

Line: 1586

kASFileRaiseIfBytesNotReady

Product availability: All

Platform availability: All

Syntax


#define kASFileRaiseIfBytesNotReady 0x0004

Description

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.

File: ASExpT.h

Line: 1580

kASFileSlowConnect

Product availability: All

Platform availability: All

Syntax


#define kASFileSlowConnect 0x00000002L

Description

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.

File: ASExpT.h

Line: 1525

kASFileSlowTransfer

Product availability: All

Platform availability: All

Syntax


#define kASFileSlowTransfer 0x00000001L

Description

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.

File: ASExpT.h

Line: 1517

kASFileStillFetching

Product availability: All

Platform availability: All

Syntax


#define kASFileStillFetching 0x00000020L

Description

Set if the file is still being loaded.

File: ASExpT.h

Line: 1547

kASFileSuspendIfBytesNotReady

Product availability: All

Platform availability: All

Syntax


#define kASFileSuspendIfBytesNotReady 0x0010

Description

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.

File: ASExpT.h

Line: 1596

kASFileUseMRead

Product availability: All

Platform availability: All

Syntax


#define kASFileUseMRead 0x00000004L

Description

Use multi-read commands to access the file.

File: ASExpT.h

Line: 1530

MDFile

Product availability: All

Platform availability: All

Syntax


#define MDFile ASMDFile

File: ASExpT.h

Line: 1926

Typedefs Detail

ASFile

Product availability: All

Platform availability: All

Syntax

typedef struct _t_ASFile* ASFile;

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.

File: ASExpT.h

Line: 1857

ASFileMode

Product availability: All

Platform availability: All

Syntax

typedef ASUns16 ASFileMode;

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:

Value	Description
ASFILE_READ	Open the file for reading.
ASFILE_WRITE	Open the file for writing.
ASFILE_CREATE	Create the file if it does not exist.
ASFILE_SERIAL	A hint indicating that the file will be accessed sequentially.
ASFILE_LOCAL	A hint indicating that a local copy of the file will be needed.

See Also

ASFileSysOpenFile
ASFileReopen

File: ASExpT.h

Line: 70

ASFilePos

Product availability: All

Platform availability: All

Syntax

typedef ASUns32 ASFilePos;

A file position value for use in callback procedures. This value cannot exceed 2 GB.

See Also

CosObjOffsetProc

File: ASExpT.h

Line: 76

ASFilePos64

Product availability: All

Platform availability: All

Syntax

typedef ASUns64 ASFilePos64;

The absolute position within a file. This value can exceed 2 GB.

File: ASExpT.h

Line: 86

Enumeration Detail

ASFileStatusFlags

Product availability: All

Platform availability: All

Syntax

enum ASFileStatusFlags {

  kASFileOkay = 0x0000,


 


  kASFileIsTerminating = 0x0001

}

See Also

ASFileRead
ASFileSysGetStatusProc

File: ASExpT.h

Line: 1943

Elements

	kASFileOkay	The MDFile is in a valid state.

	kASFileIsTerminating	The MDFile is being closed (for example, because the file is being displayed in a web browser's window and the user cancelled downloading).

Callbacks Detail

ASFileCompletionProc

Product availability: All

Platform availability: All

Syntax

void (*ASFileCompletionProc)(ASFile aFile, const char *p, ASTFilePos fileOffsetRequested, ASTArraySize countRequested, ASTArraySize nBytesRead, ASErrorCode error, void *compProcClientData)

Called when an asynchronous read or write request has completed.

File: ASExpT.h

Line: 1883

Method Detail

ASFileAcquirePathName

()

Product availability: All

Platform availability: All

Syntax





ASPathName ASFileAcquirePathName(ASFile aFile)

Gets the path name for a file and increments an internal reference count. It is the caller's responsibility to release the ASPathName when it is no longer needed by using ASFileSysReleasePath().

Parameters

aFile —

IN/OUT The file whose path name is acquired.

Returns

The ASPathName associated with asFile. You can use ASFileSysDIPathFromPath() to convert this to a device-independent path name.

See Also

ASFileSysReleasePath

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 1019

ASFileAttachmentCreatePathName

()

Product availability: All

Platform availability: All

Syntax





void ASFileAttachmentCreatePathName(PDDoc pdDoc, ASText pathText, ASFileSys* fileSys, ASPathName* pathName)

Creates an ASPathName corresponding to the specified file or folder in the collection.

Parameters

	`pdDoc` —	The document containing the specified file or folder.

	`pathText` —	The text-based representation of the path. The path consists of a file name or sequence of file names. A file name may not contain any of the characters `'\', '/', ':', '*', '?', '<', '>', '\|'`, and may not contain `'.'` as the final character. When `'/'` appears in a path, it signifies that the preceding file name is a folder, and that the subsequent file name is a child of that folder. The root of a collection may be identified by passing `"/"`, `NULL`, or an empty string for `pathText`.

	`fileSys` —	A pointer that will be filled by the function. This parameter provides the caller with the `ASFileSys` to use in conjunction with the specified file or folder.

	`pathName` —	A pointer that will be filled by the function. This parameter provides the caller with the `ASPathName` to use in conjunction with the specified file or folder.

File: PDProcs.h

Line: 12540

ASFileAttachmentGetPDFileAttachment

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileAttachmentGetPDFileAttachment(ASFileSys fileSys, ASPathName pathName, PDFileAttachment* attachment)

Produces a PDFileAttachment corresponding to the ASFileSys and ASPathName. It raises an exception if the ASFileSys is is not the embedded files file system, or if the ASPathName or PDFileAttachment parameters are NULL.

Parameters

	`fileSys` —	The `ASFileSys` for file attachments.

	`pathName` —	The `ASPathName` identifying the file attachment of interest.

	`attachment` —	A pointer that will be receive the file attachment.

Returns

true if the file attachment was found, false otherwise.

File: PDProcs.h

Line: 12551

ASFileAttachmentGetPDFolder

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileAttachmentGetPDFolder(ASFileSys fileSys, ASPathName pathName, PDFolder* folder)

Produces a PDFolder corresponding to the ASFileSys and ASPathName. It raises an exception if the ASFileSys is is not the embedded files file system, or if the ASPathName or PDFolder parameters are NULL.

Parameters

	`fileSys` —	The `ASFileSys` for file attachments

	`pathName` —	The `ASPathName` identifying the folder of interest.

	`folder` —	A pointer that will be receive the folder.

Returns

true if the folder was found, false otherwise.

File: PDProcs.h

Line: 12562

ASFileCanSetEOF

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileCanSetEOF(ASFile file, ASInt32 newFileSize)

Checks if ASFileSetEOF() can be done for this file with a specified new file size.

Parameters

	`file` —	The file in question.

	`newFileSize` —	The proposed new file size. This parameter will be treated as unsigned.

Returns

See Also

ASFileSetEOF
ASFileGetEOF
ASFileGetPos

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2459

ASFileClearOutstandingMReads

()

Product availability: All

Platform availability: All

Syntax





void ASFileClearOutstandingMReads(ASFile fN)

Clears all outstanding mreads for the given file.

Parameters

fN —

The file to clear mreads for.

See Also

ASFileHasOutstandingMReads

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 1824

ASFileClose

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileClose(ASFile aFile)

Closes the specified file. After a call to ASFileClose(), the file handle is no longer valid but may be reused as the result of a subsequent call to ASFileSysOpenFile().

Parameters

aFile —

IN/OUT The file to close. The file must have been opened previously using ASFileSysOpenFile().

Returns

0 if the operation was successful; some file system or platform-dependent error code is returned otherwise.

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 893

ASFileFlush

()

Product availability: All

Platform availability: All

Syntax





void ASFileFlush(ASFile aFile)

Flushes any buffered data to a file. This method may raise file system or platform-specific exceptions.

Parameters

aFile —

The file whose data is flushed.

See Also

ASFileHardFlush

Exceptions

fileErrIO

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 1006

ASFileFromMDFile

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileFromMDFile(ASMDFile mdFile, ASFileSys fileSys, ASFile* pfN)

Gets the ASFile associated with the specified ASMDFile and ASFileSys.

Parameters

	`mdFile` —	IN/OUT The ASMDFile for which the information is desired.

	`fileSys` —	IN/OUT The ASFileSys through which `fileID` was opened.

	`pfN` —	IN/OUT (Filled by the method, may be `NULL`) The ASFile representing `fileID` within `fileSys`.

Returns

true if fileID is determined to be a valid file opened through fileSys, false otherwise.

See Also

ASFileGetFileSys
ASFileGetMDFile

Since

PI_ACROSUPPORT_VERSION >= 0x00020002

File: ASProcs.h

Line: 1265

ASFileGetEOF

()

Product availability: All

Platform availability: All

Syntax





ASTFilePos ASFileGetEOF(ASFile aFile)

Gets the current size of a file. It calls ASFileSysGetEofProc(). This call returns an error if the file size is greater than 2 GB.

Parameters

aFile —

The ASFile whose size is obtained.

Returns

The size of the file.

Exceptions

fileErrIO

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 958

ASFileGetEOF64

()

Product availability: All

Platform availability: All

Syntax





ASFilePos64 ASFileGetEOF64(ASFile aFile)

Gets the current size of a file.

Parameters

aFile —

IN/OUT The ASFile whose size is obtained. This call will work with files over 2 GB in length.

Returns

The size of the file.

See Also

ASFileSetEOF64
ASFileSetPos

Exceptions

fileErrIO

Since

PI_ACROSUPPORT_VERSION >= 0x00070000

File: ASProcs.h

Line: 2731

ASFileGetFileSys

()

Product availability: All

Platform availability: All

Syntax





ASFileSys ASFileGetFileSys(ASFile aFile)

Gets the file system through which a file was opened.

Parameters

aFile —

IN/OUT The open file whose file system is obtained.

Returns

The file's ASFileSys.

See Also

ASFileGetFileSysByName

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 1030

ASFileGetFileSysByName

()

Product availability: All

Platform availability: All

Syntax





ASFileSys ASFileGetFileSysByName(ASAtom name)

Gets the file system that was registered with the specified name.

Parameters

name —

IN/OUT The ASAtom corresponding to the name of the file system to obtain. It may be one of the following:

String	Description
`"Mac_K"`	Mac OS file system
`"DOS_K"`	Classic Windows file system (it only supports host-encoded paths)
`"Win_K"`	Unicode Windows file system
`"Unix_K"`	UNIX file system
`"CHTTP"`	HTTP file system
`"CDocumentum"`	Documentum file system
`"CODMA"`	Open Document Management file system

Returns

The file system, otherwise NULL if no matching file system was found.

See Also

ASFileGetFileSys

Since

PI_ACROSUPPORT_VERSION >= 0x00020002

File: ASProcs.h

Line: 1247

ASFileGetMDFile

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileGetMDFile(ASFile fN, ASMDFile* pFileID, ASFileSys* pFileSys)

Given an ASFile, returns the fileSys and the ASMDFile identification in that fileSys. This call is needed for a file system in a plug-in to be able to call the inner routines in another file system.

Parameters

	`fN` —	IN/OUT The ASFile for which the information is desired.

	`pFileID` —	IN/OUT (Filled by the method, may be `NULL`) The ASMDFile identifier associated with file.

	`pFileSys` —	IN/OUT (Filled by the method, may be `NULL`) The file system through which this file was opened.

Returns

true if the file is an open file, false otherwise.

See Also

ASFileFromMDFile
ASFileGetFileSys

Since

PI_ACROSUPPORT_VERSION >= 0x00020002

File: ASProcs.h

Line: 1284

ASFileGetOpenMode

()

Product availability: All

Platform availability: All

Syntax





ASFileMode ASFileGetOpenMode(ASFile fN)

Gets the file access mode(s) specified for the file when it was opened.

Parameters

fN —

The file in question.

Returns

A value corresponding to one or more ASFileMode objects used to access or create the file, as shown in the table below. The values that can be returned include combinations of the following, OR'd with each other:

Return value from ASFileGetOpenMode():

Return value	Meaning
`0`	created
`1`	readable
`2`	readable and writable
`8`	sequential access
`16`	local

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1905

ASFileGetPos

()

Product availability: All

Platform availability: All

Syntax





ASTFilePos ASFileGetPos(ASFile aFile)

Gets the current seek position in a file. This is the position at which the next read or write will begin. This call returns an error if the file position is greater than 2 GB.

Parameters

aFile —

IN/OUT The file in which to get the seek position.

Returns

The current seek position.

Exceptions

fileErrIO

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 926

ASFileGetPos64

()

Product availability: All

Platform availability: All

Syntax





ASFilePos64 ASFileGetPos64(ASFile aFile)

Gets the current seek position in a file. This is the position at which the next read or write will begin. This call will work with files over 2 GB in length.

Parameters

aFile —

IN/OUT The file in which to get the seek position.

Returns

The current seek position.

See Also

ASFileSetPos64
ASFileRead
ASFileWrite

Exceptions

fileErrIO

Since

PI_ACROSUPPORT_VERSION >= 0x00070000

File: ASProcs.h

Line: 2703

ASFileGetURL

()

Product availability: All

Platform availability: All

Syntax





char* ASFileGetURL(ASFile asf)

Returns the URL associated with file. It is the caller's responsibility to release the memory associated with the returned string using ASfree().

Parameters

asf —

IN/OUT The file in question.

Returns

A buffer containing the URL, or NULL if it could not be determined. On all file systems, the path will be URL-escaped. On the default file system, encoding will be platform-encoded. On Unicode and browser file systems, encoding will be UTF8.

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1852

ASFileHardFlush

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileHardFlush(ASFile aFile)

Causes a hard flush on a file, which means that the file is flushed to the physical destination. For example, if a WebDAV-based file is opened, ASFileFlush() only flushes changes to the local cached version of the file. This method would flush changes all the way to the WebDAV server.

Parameters

aFile —

The file that is flushed.

Returns

0 if the operation succeeded, -1 if there was an error.

See Also

ASFileFlush

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 2033

ASFileHasOutstandingMReads

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileHasOutstandingMReads(ASFile fN)

Determines whether there are any outstanding multi-byte range requests for a file. A document can have outstanding mreads if it was opened in a browser, Acrobat requested some byte ranges, and the byte ranges have not yet arrived.

Parameters

fN —

The file in question.

Returns

true if the file has outstanding mreads, false otherwise.

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2448

ASFileIsSame

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileIsSame(ASFile fN, ASPathName pathName, ASFileSys fileSys)

Performs a comparison between the file and path to determine if they represent the same file. This method will return false if the file was not opened through the fileSys file system.

Parameters

	`fN` —	IN/OUT The file in question.

	`pathName` —	IN/OUT The ASPathName in question.

	`fileSys` —	IN/OUT The file system from which the path was obtained.

Returns

false if the comparison fails, true otherwise.

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1724

ASFileMReadRequest

()

Product availability: All

Platform availability: All

Syntax





void ASFileMReadRequest(ASFile fN, ASInt32* blockPairs, ASTCount nBlockPairs)

Initiates a byte range request for a given file, if the file is in the browser.

Parameters

	`fN` —	The file for which you wish to make read requests.

	`blockPairs` —	The array of `ASInt32` pairs. The first `ASInt32` in the pair is the offset into the file to read, and the second `ASInt32` is the length of the range to request.

	`nBlockPairs` —	The number of block pairs to request.

See Also

ASFileHasOutstandingMReads

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1816

ASFileOpenWithVirtualEOF

()

Product availability: All

Platform availability: All

Syntax





ASInt32 ASFileOpenWithVirtualEOF(ASFile fN, ASFilePos64 virtualEOF, ASFile* newFile)

ASFileOpenWithVirtualEOF attempts to create a second ASFile instance to a file that is already open. Both the current instance fN and the new instance must be read only. The new instance shall set a virtual end of file. This virtual EOF and no effect on the first instance or on the physical file. It only effect the ASFile calls where newFile is passed in has the file. Each instance maintains it's own file position marker. The original instance of the file should be close after all other instances have been closed. This routine does not raise, but returns an error code.

Parameters

	`fN` —	IN The ASFile to base the new file on

	`virtualEOF` —	IN The new EOF.

	`newFile`

Returns

Error code if the newFile could not be created.

Since

PI_ACROSUPPORT_VERSION >= 0x000A0000

File: ASProcs.h

Line: 3007

ASFilePushData

()

Product availability: All

Platform availability: All

Syntax





void ASFilePushData(ASFile aFile, const char* p, ASTFilePos offset, ASTArraySize length)

Sends data from a file system implementation to an ASFile. The data may be for a multi-read request call, or may be unsolicited.

This method can only be called from within a file system implementation. It must not be called by clients of the ASFile, such as a caller that acquired the file with ASFileSysOpenFile().

Parameters

	`aFile` —	IN/OUT The file to which data is sent.

	`p` —	IN/OUT The data being pushed.

	`offset` —	IN/OUT A byte offset into the file at which the data should be written.

	`length` —	IN/OUT The number of bytes held in the buffer.

See Also

ASFileRead
ASFileWrite

Exceptions

fileErrGeneral

Since

PI_ACROSUPPORT_VERSION >= 0x00020002

File: ASProcs.h

Line: 1203

ASFileRead

()

Product availability: All

Platform availability: All

Syntax





ASTArraySize ASFileRead(ASFile aFile, char* p, ASTArraySize count)

Reads data from a file, beginning at the current seek position.

Parameters

	`aFile` —	IN/OUT The file from which data is read.

	`p` —	IN/OUT (Filled by the method) A buffer into which data is written. The buffer must be able to hold at least `count` bytes.

	`count` —	IN/OUT The number of bytes to read.

Returns

The number of bytes actually read from the file.

See Also

ASFileSetPos
ASFileWrite

Exceptions

fileErrIO
fileErrUserRequestedStop
fileErrBytesNotReady
fileErrIOTimeout
fileErrGeneral

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 979

ASFileRegisterFileSys

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileRegisterFileSys(ASExtension extension, ASFileSys fileSys)

Allows an implementor to provide a file system for use by external clients. An external client can locate the file system using ASFileGetFileSysByName(). fileSys provides its name via the ASFileSysGetFileSysNameProc() callback. This method returns false if a file system with the same name is already registered.

Parameters

	`extension` —	IN/OUT The gExtensionID of the plug-in registering the `fileSys`.

	`fileSys` —	IN/OUT The ASFileSys being registered.

Returns

true if fileSys is successfully registered, false otherwise.

Since

PI_ACROSUPPORT_VERSION >= 0x00020002

File: ASProcs.h

Line: 1222

ASFileReopen

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileReopen(ASFile aFile, ASFileMode mode)

Attempts to reopen a file using the specified read/write mode. On some platforms, this may result in the file being closed and then reopened, and some error conditions may render the file invalid.

Parameters

	`aFile` —	The file to reopen.

	`mode` —	An open-mode value as specified for ASFileMode.

Returns

0 if the operation was successful; some file system or platform-dependent error code is returned otherwise.

See Also

ASFileSysOpenFile
ASFileClose

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 875

ASFileSetEOF

()

Product availability: All

Platform availability: All

Syntax





void ASFileSetEOF(ASFile aFile, ASTFilePos newFileSize)

Changes the size of a file. The new size may by larger or smaller than the original size. Since this method does not return any values, the status can be assessed by examining the error code in the HANDLER clause. This method may raise file system or platform-specific exceptions. This call only works when the desired file size is less than 2 GB.

Parameters

	`aFile` —	The file whose size is changed.

	`newFileSize` —	The new size of file.

Exceptions

fileErrIO
asGenErrMethodNotImplemented
asFileErrGeneral

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 945

ASFileSetEOF64

()

Product availability: All

Platform availability: All

Syntax





void ASFileSetEOF64(ASFile aFile, ASFilePos64 newFileSize)

Changes the size of a file. The new size may by larger or smaller than the original size. This method may raise file system or platform-specific exceptions. This call will work with files over 2 GB in length.

Parameters

	`aFile` —	IN/OUT The file whose size is changed.

	`newFileSize` —	IN/OUT The new size of the file.

See Also

ASFileGetEOF64
ASFileGetPos

Exceptions

fileErrIO

Since

PI_ACROSUPPORT_VERSION >= 0x00070000

File: ASProcs.h

Line: 2718

ASFileSetMode

()

Product availability: All

Platform availability: All

Syntax





ASFlagBits ASFileSetMode(ASFile fN, ASFlagBits modeValue, ASFlagBits modeMask)

Gets or sets the mode flags for a file. Pass 0 for modeValue and modeMask to simply get the current mode flags.

Parameters

	`fN` —	The file for which to get or set the mode.

	`modeValue` —	The mode flag values to get or set, which are described in ASFileMode Flags.

	`modeMask` —	The mask for the mode flags to get or set.

Returns

The previous value of the mode, or 0 if the file system does not support this operation.

See Also

ASFileRead
ASFileSysOpenFile

Since

PI_ACROSUPPORT_VERSION >= 0x00020002

File: ASProcs.h

Line: 1490

ASFileSetPos

()

Product availability: All

Platform availability: All

Syntax





void ASFileSetPos(ASFile aFile, ASTFilePos pos)

Seeks to the specified position in a file. This is the position at which the next read or write will begin. This call only works when the desired file position is less than 2 GB.

Parameters

	`aFile` —	IN/OUT The file in which to seek.

	`pos` —	IN/OUT The position to seek.

Exceptions

fileErrIO

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 909

ASFileSetPos64

()

Product availability: All

Platform availability: All

Syntax





void ASFileSetPos64(ASFile aFile, ASFilePos64 pos)

Seeks to the specified position in a file. This is the position at which the next read or write will begin. This call will work with files over 2 GB in length.

Parameters

	`aFile` —	IN/OUT The file in which to seek.

	`pos` —	IN/OUT The position to seek.

See Also

ASFileGetPos64
ASFileRead
ASFileWrite

Exceptions

fileErrIO

Since

PI_ACROSUPPORT_VERSION >= 0x00070000

File: ASProcs.h

Line: 2687

ASFileUnregisterFileSys

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileUnregisterFileSys(ASExtension extension, ASFileSys fileSys)

Allows a fileSys to be unregistered. In general, a fileSys is only unregistered by the extension that registered it.

Parameters

	`extension` —	IN/OUT The gExtensionID of the plug-in un-registering `fileSys`.

	`fileSys` —	IN/OUT The ASFileSys to un-register.

Returns

true if fileSys successfully unregistered, false if there are any open files that were opened through fileSys.

See Also

ASFileRegisterFileSys

Since

PI_ACROSUPPORT_VERSION >= 0x00020002

File: ASProcs.h

Line: 1181

ASFileWrite

()

Product availability: All

Platform availability: All

Syntax





ASTArraySize ASFileWrite(ASFile aFile, const char* p, ASTArraySize count)

Writes data to a file, beginning at the current seek position.

Parameters

	`aFile` —	IN/OUT The file to which data is written.

	`p` —	IN/OUT A buffer holding the data that is to be written. The buffer must be able to hold at least `count` bytes.

	`count` —	IN/OUT The number of bytes to write.

Returns

The number of bytes actually written to the file.

See Also

ASFileRead
ASFileSetPos

Exceptions

fileErrIO
fileErrWrite

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 996

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
ASFile	Defines \| Typedefs \| Enumerations \| Callbacks \| Methods

Layer	AS_Layer
Object	ASFile