LayerAS_Layer
ObjectASFile

The ASFile interface encapsulates Acrobat's access to file services. It provides a common interface for Acrobat, applications, and plug-ins to access file system services on different platforms, and enables you to provide your own file storage implementations.

ASFile is related to the ASFileSys object, the ASPlatformPath object, and the ASPathName structure.

An ASFile is an opaque representation of an open file. It is similar to an ASStm, although it is a lower-level abstraction. An ASFile knows its ASPathName and ASFileSys. Acrobat creates one ASFile for each open file, and layers one or more ASStm objects on each ASFile. Logically, an ASFile is analogous to a file as used in the standard UNIX/POSIX low-level file I/O functions open, close, read, write, and so forth (located in fcntl.h), and an ASStm is analogous to a buffered file stream as used in standard C file I/O functions fopen(), fread(), fwrite(), and so forth (located in stdio.h).



Define Summary
 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 Summary
 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 Summary
 Enumeration
  ASFileStatusFlags
Values returned by ASFileSysGetStatusProc().
Callback Summary
 Callback
 ASFileCompletionProc
Called when an asynchronous read or write request has completed.
Method Summary
 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.
 
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.
 
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.
 
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.
 
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.
 
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.

See Also


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


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


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


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.

See Also


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

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

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

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.

See Also

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

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

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.

See Also

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

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

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

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

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.

See Also

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

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

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

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

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

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.

See Also

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

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.

See Also

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

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

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.

See Also

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

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

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

Exceptions

fileErrIO
fileErrWrite

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h
Line: 996