AS_Layer.ASFileSys (Acrobat)

	Define
	ASFileSysCopyPath
	ASFileSysCreatePathFromCFURLRef (Macintosh)
	ASFileSysCreatePathFromCString Helper macro for the ASFileSysCreatePathName() method.
	ASFileSysCreatePathFromDIPath A helper macro for the ASFileSysCreatePathName() method.
	ASFileSysCreatePathFromDIPathText
	ASFileSysCreatePathFromFSRef (Macintosh)
	ASFileSysCreatePathFromFSRefWithCFStringRef (Macintosh)
	ASFileSysCreatePathFromFSSpec (Macintosh) Helper macro for the ASFileSysCreatePathName() method.
	ASFileSysCreatePathFromPOSIXPath (Macintosh)
	ASFileSysCreatePathWithFolderName Helper macro for the ASFileSysCreatePathName() method.
	ASFileSysCreatePathWithFolderNameWithASText
	ASFileSysReleasePath
	ASFileSysRemoveFile

	Typedef
	ASFileSys A data structure containing callbacks that implement a file system.
	ASFileSysItemProps
	ASFileSysItemPropsRec
	ASFileSysRec
	ASFolderIterator 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().
	ASIORequest A data structure representing an I/O request.
	ASIORequestRec
	ASlFileMode
	ASMDFile ASMDFile replaces MDFile. MDFile is an obsolete name for this data type for backward compatibility.
	ASPathName ASFileAcquirePathName

	Enumeration
	`ASFileSysItemType` An enumerated data type used to categorize an object associated with an ASPathName.

	Structure
	_t_ASFileSysItemProps A list of properties for the object referenced by an ASPathName. It is used in ASFileSysGetItemProps() and the folder enumeration routines.
	_t_ASFileSysRec A data structure containing callbacks that implement a file system.
	_t_ASIORequestRec The first five items in the ASIORequestSingleRec structure exactly match the parameters of an ASFileSys read or write call.

	Callback
	ASFileSysAcquireFileSysPathProc 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.
	ASFileSysAcquirePlatformPathProc 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.
	ASFileSysAsyncAbortProc A callback for ASFileSysRec that aborts all uncompleted asynchronous I/O requests for the specified file. This callback can be called at any time.
	ASFileSysAsyncReadProc 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.
	ASFileSysAsyncWriteProc 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.
	ASFileSysCanPerformOpOnItemProc 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.
	ASFileSysCanSetEofProc A callback for ASFileSysRec that determines whether ASFileSys can set the end of file marker (EOF) to a new offset for the specified file.
	ASFileSysClearOutstandingMReadsProc 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.
	ASFileSysCloseProc A callback for ASFileSysRec. This callback is responsible for closing the specified file. It is called by ASFileClose().
	ASFileSysCopyPathNameProc A callback for ASFileSysRec that copies a path name (not the underlying file). It is called by ASFileSysCopyPath().
	ASFileSysCreateFolderProc A callback for ASFileSysRec used to create an empty folder at the specified path.
	ASFileSysCreatePathNameProc 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.
	ASFileSysDestroyFolderIteratorProc A callback for ASFileSysRec used to release the resources associated with folderIter.
	ASFileSysDIPathFromPathExProc 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().
	ASFileSysDiPathFromPathProc A callback for ASFileSysRec that converts a path name to a device- independent path name. It is called by ASFileSysDIPathFromPath().
	ASFileSysDisplayASTextFromPathProc Places a representation that can be displayed to users of a path into displayText.
	ASFileSysDisplayStringFromPathProc A callback for ASFileSysRec used to obtain a representation of a path that can be displayed by the user.
	ASFileSysDisposePathNameProc A callback for ASFileSysRec that is called by ASFileSysReleasePath().
	ASFileSysFirstFolderItemProc A callback for ASFileSysRec that begins the process of iterating through the contents of a folder.
	ASFileSysFlushProc A callback for ASFileSysRec that flushes data for the specified file. It is called by ASFileFlush().
	ASFileSysFlushVolumeProc 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.
	ASFileSysGetEof64Proc 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.
	ASFileSysGetEofProc 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.
	ASFileSysGetFileFlags A callback for ASFileSysRec that gets the flags for the specified file.
	ASFileSysGetFilePositionLimitProc 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.
	ASFileSysGetFileSysNameProc A callback for ASFileSysRec that gets this file system's name.
	ASFileSysGetItemPropsAsCabProc 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.
	ASFileSysGetItemPropsProc A callback for ASFileSysRec used to retrieve a full description of the file system object associated with the path.
	ASFileSysGetNameAsASTextProc A callback for ASFileSysRec that gets the file name for the specified ASPathName as an ASText object.
	ASFileSysGetNameForDisplayProc 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.
	ASFileSysGetNameProc 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.
	ASFileSysGetParentProc A callback for ASFileSysRec used to obtain the parent of the input path.
	ASFileSysGetPlatformThingProc 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().
	ASFileSysGetPos64Proc 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.
	ASFileSysGetPosProc 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.
	ASFileSysGetStatusProc 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.
	ASFileSysGetStorageFreeSpace64Proc 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).
	ASFileSysGetStorageFreeSpaceProc A callback for ASFileSysRec that gets the amount of free space on the volume containing the specified ASPathName.
	ASFileSysGetTempPathNameProc A callback for ASFileSysRec that returns a unique path name suitable for use in creating temporary files.
	ASFileSysGetTypeAndCreatorProc 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.
	ASFileSysHardFlushProc 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.
	ASFileSysIsInUseProc A callback for ASFileSysRec that tests whether a file is in use by another process.
	ASFileSysIsSameFileProc A callback for ASFileSysRec that tests whether two files are the same.
	ASFileSysMReadRequestProc 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.
	ASFileSysNextFolderItemProc 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.
	ASFileSysOpen64Proc 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.
	ASFileSysOpenProc 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.
	ASFileSysPathFromDIPathExProc A callback for ASFileSysRec that converts a device-independent path name from an ASText object to an ASPathName. It is called by ASFileSysPathFromDIPathEx().
	ASFileSysPathFromDIPathProc A callback for ASFileSysRec that converts a device-independent path name to an ASPathName. It is called by ASFileSysPathFromDIPath().
	ASFileSysPerformOpOnItemProc A callback for ASFileSysRec that performs the specified operation on a particular file.
	ASFileSysRangeArrivedProc A callback for ASFileSysRec used when a byte range has arrived during a file load operation.
	ASFileSysReadProc 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.
	ASFileSysReleasePlatformPathProc A callback for ASFileSysRec that releases the specified platform path object when the client is done with it.
	ASFileSysRemoveFolderProc A callback for ASFileSysRec used to delete the folder at the specified path.
	ASFileSysRemoveProc A callback for ASFileSysRec that deletes a file. It is called by ASFileSysRemoveFile().
	ASFileSysRenameProc 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.
	ASFileSysReopenProc 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.
	ASFileSysSetEof64Proc 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.
	ASFileSysSetEofProc 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.
	ASFileSysSetModeProc ASFileSysSetMode() sets and gets parameters for the specified file.
	ASFileSysSetPos64Proc 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.
	ASFileSysSetPosProc 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().
	ASFileSysSetTypeAndCreatorProc 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.
	ASFileSysURLFromPathProc A callback for ASFileSysRec used to obtain the URL associated with the given ASPathName.
	ASFileSysWriteProc A callback for ASFileSysRec that writes data to the specified file.
	ASFileSysYieldProc 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.

	Method
	ASPathName ASFileSysAcquireFileSysPath(ASFileSys oldFileSys, ASPathName oldPathName, ASFileSys newFileSys) Converts an ASPathName from one file system to another. It returns an ASPathName acquired through newFileSys that refers to an image (which may possibly be cached) of the file in oldfileSys. Use this call to get a local file that is an image of a remote file (in a URL file system, for example). This is needed by programs such as the QuickTime Movie Player, because they can only work from local file-system files. The returned ASPathName may be a reference to a cache, so the file should be treated as read-only.
	ASPathName ASFileSysAcquireParent(ASFileSys fileSys, ASPathName pathName) Returns the parent folder of the file system object associated with pathName. The following rules apply in the default file systems:
	ASInt32 ASFileSysAcquirePlatformPath(ASFileSys fileSys, ASPathName path, ASAtom platformPathType, ASPlatformPath* platformPath) Returns a platform-specific file system representation of the specified path, according to the specified type, wrapped in an allocated ASPlatformPath object. It calls ASFileSysAcquirePlatformPathProc().
	ASInt32 ASFileSysCanPerformOpOnItem(ASFileSys fileSys, ASPathName pathName, const char* op) Tests whether a given operation can be performed on a particular file. It calls the canPerformOpOnItem() procedure registered for the ASFileSysRec, which determines whether the operation is one of the file system-defined operation strings for which there is a handler.
	ASInt32 ASFileSysConvertCabToItemProps(ASFileSysItemProps props, ASCab theCab) Converts a set of item properties from the ASCab format to the ASFileSysItemPropsRec format.
	ASInt32 ASFileSysConvertItemPropsToCab(ASCab theCab, const ASFileSysItemPropsRec* props) Converts a set of item properties from the ASFileSysItemPropsRec format to the ASCab format.
	ASPathName ASFileSysCopyPath(ASFileSys fileSys, ASPathName pathName) Generates and copies the specified ASPathName (but does not copy the file specified by the path name). The ASPathName must have been obtained through the specified file system. This method may be used regardless of whether the file specified by path name is open.
	ASErrorCode ASFileSysCreateFolder(ASFileSys fileSys, ASPathName path, ASBool recurse) Creates an empty folder at the specified pathName.
	ASPathName ASFileSysCreatePathName(const ASFileSys fileSys, ASAtom pathSpecType, const void* pathSpec, const void* additionalData) Creates an ASPathName based on the input type and pathSpec. Each fileSys implementation must publish the input types that it accepts.
	void ASFileSysDestroyFolderIterator(ASFileSys fileSys, ASFolderIterator folderIter) Releases the resources associated with folderIter.
	char* ASFileSysDIPathFromPath(ASFileSys fileSys, ASPathName path, ASPathName relativeToThisPath) Converts a file name, specified as an ASPathName, to a device-independent path name. It is the caller's responsibility to free the memory associated with the returned string using ASfree().
	ASErrorCode ASFileSysDIPathFromPathEx(ASFileSys fileSys, ASPathName path, ASPathName relativeToThisPath, ASText diPathText) Converts a file name, specified as an ASPathName, to a device-independent path name, which is returned as an ASText object. It calls ASFileSysDIPathFromPathExProc().
	ASErrorCode ASFileSysDisplayASTextFromPath(ASFileSys fileSys, ASPathName path, ASText displayText) Returns a user-friendly representation of a path as a text object. It calls ASFileSysDisplayASTextFromPathProc().
	char* ASFileSysDisplayStringFromPath(ASFileSys fileSys, ASPathName path) Returns a user-friendly representation of a path. It is the caller's responsibility to release the memory associated with the returned string using ASfree().
	ASFolderIterator ASFileSysFirstFolderItem(ASFileSys fileSys, ASPathName folderPath, ASFileSysItemProps props, ASPathName* itemPath) Creates an iterator which can be used to enumerate all objects inside the specified folder, and returns the properties of the first item found in the folder. The iteration can be continued by passing the returned ASFolderIterator to ASFileSysNextFolderItem.
	ASErrorCode ASFileSysFlushVolume(ASFileSys fileSys, ASPathName pathName) 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 Mac OS FlushVol or to the UNIX sync).
	ASFilePos64 ASFileSysGetFilePosLimit(ASFileSys fileSys) Returns the maximum file position that can be processed by this file system. This is not the maximum size file that can be created or the amount of room left in the file system, 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.
	ASErrorCode ASFileSysGetItemProps(ASFileSys fileSys, ASPathName pathName, ASFileSysItemProps props) Populates an ASFileSysItemProps record with a full description of the file system object associated with pathName. It calls ASFileSysGetItemPropsProc().
	ASInt32 ASFileSysGetItemPropsAsCab(ASFileSys fileSys, ASPathName pathName, ASCab theCab) Gets a full description of the file system object associated with pathName, returning the item properties in the ASCab format. Calls ASFileSysGetItemPropsAsCabProc().
	ASErrorCode ASFileSysGetNameFromPath(ASFileSys fileSys, ASPathName pathName, char* name, ASTArraySize maxLength) Extracts the file name (including extension) from the path.
	ASErrorCode ASFileSysGetNameFromPathAsASText(ASFileSys fileSys, ASPathName pathName, ASText name) Extracts the file name (including the extension) from the path as an ASText object. This method supersedes ASFileSysGetNameFromPath() in Acrobat 6.0 and later.
	ASErrorCode ASFileSysGetNameFromPathForDisplay(ASFileSys fileSys, ASPathName pathName, ASText nameForDisplay) This method writes into nameForDisplay the representation of that item as it would be shown in Windows Explorer or Mac OS Finder. For example, it will provide the localized string for "My Documents" even though, on disk, "My Documents" is always in English. It will also strip the extension if that is what Windows Explorer or the Mac Finder would do for that file.
	void* ASFileSysGetPlatformThing(ASFileSys fileSys, ASPathName path, ASAtom thing) Deprecated API: always returns NULL.
	ASDiskSpace ASFileSysGetStorageFreeSpace(ASFileSys fileSys, ASPathName pathName) Gets the amount of free space on the volume containing pathName.
	ASDiskSpace64 ASFileSysGetStorageFreeSpace64(ASFileSys fileSys, ASPathName pathName) Gets the amount of free space on the volume containing pathName. This is the same as ASFileSysGetStorageFreeSpace() without the 4 GB limit.
	ASPathName ASFileSysGetTempPathName(ASFileSys fileSys, ASPathName siblingPathName) Returns a unique path name suitable for use in creating temporary files. It is the caller's responsibility to release the returned object using ASFileSysReleasePath().
	void ASFileSysGetTypeAndCreator(ASFileSys fileSys, ASPathName path, ASUns32* type, ASUns32* creator) Gets the type and creator of the file specified by the path.
	ASBool ASFileSysIsLocal(ASFileSys fileSys) Returns true if fileSys is NULL, the default file system or the default Unicode file system.
	ASBool ASFileSysNextFolderItem(ASFileSys fileSys, ASFolderIterator folderIter, ASFileSysItemProps props, ASPathName* itemPath) Continues the iteration process associated with the ASFolderIterator object.
	ASErrorCode ASFileSysOpenFile(ASFileSys fileSys, ASPathName pathName, ASFileMode mode, ASFile* fP) Attempts to open a file in the specified file system, in the specified read/write/create mode. If the file is already open, the existing file handle is returned. The caller retains ownership of pathName.
	ASErrorCode ASFileSysOpenFile64(ASFileSys fileSys, ASPathName pathName, ASFileMode mode, ASFile* fP) Attempts to open a file in the specified file system, in the specified read/write/create mode. If the file is already open, the existing file handle is returned. The caller retains ownership of pathName.
	ASPathName ASFileSysPathFromDIPath(ASFileSys fileSys, const char* diPath, ASPathName relativeToThisPath) Converts a device-independent path name to an ASPathName. This method can only be used for files that already exist (that is, it cannot be used to create a placeholder path name for files that a plug-in intends to create in the future).
	ASPathName ASFileSysPathFromDIPathEx(ASFileSys fileSys, ASConstText diPathText, ASPathName relativeToThisPath) Converts a device-independent path name in an ASText object to an ASPathName. This method can only be used for files that already exist (that is, it cannot be used to create a placeholder path name for files that a plug-in intends to create in the future).
	ASInt32 ASFileSysPerformOpOnItem(ASFileSys fileSys, ASPathName pathName, const char* op, ASCab params) Performs a specified operation on a particular file, passing specified parameters. It calls the performOpOnItem() procedure registered for the ASFileSysRec.
	void ASFileSysReleasePath(ASFileSys fileSys, ASPathName pathName) Decrements the internal reference count for the path name and disposes of the path name (but not the file itself) if the reference count is zero. This does not result in any file-level operations, and is unaffected by whether there is an open file for this path name.
	void ASFileSysReleasePlatformPath(ASFileSys fileSys, ASPlatformPath platformPath) Releases the specified platform path object. Each call to ASFileSysAcquirePlatformPath() should have a corresponding call to this method.
	ASErrorCode ASFileSysRemoveFile(ASFileSys fileSys, ASPathName pathName) Attempts to delete the file referred to by pathName.
	ASErrorCode ASFileSysRemoveFolder(ASFileSys fileSys, ASPathName path) Deletes the folder at the specified pathName only if it is empty.
	void ASFileSysSetTypeAndCreator(ASFileSys fileSys, ASPathName path, ASUns32 type, ASUns32 creator) Sets the type and creator of a file. See Type/Creator Codes.
	char* ASFileSysURLFromPath(ASFileSys fileSys, ASPathName path) Returns the URL corresponding to pathName. It is the caller's responsibility to free the memory associated with the returned string using ASfree().
	ASFileSys ASGetDefaultFileSys() Gets the default standard file system implementation for a platform.
	ASFileSys ASGetDefaultFileSysForPath(ASAtom pathSpecType, const void* pathSpec) Gets the best file system implementation that supports the passed in path. If the path requires the Unicode file system then the default Unicode file system is returned, otherwise the default file system is returned.
	ASFileSys ASGetDefaultUnicodeFileSys() Gets the file system implementation that supports Unicode file path names. If a platform does not have a file system that supports Unicode, then NULL will be returned.
	ASFileSys ASGetRamFileSys() Gets the in-memory file system implementation for a platform.
	ASFileSys ASGetTempFileSys() Gets the temporary file system implementation for a platform.
	ASPathName ASPathFromPlatformPath(void* platformPath) This method was deprecated in Acrobat 5.0. Use ASFileSysCreatePathName() instead.
	void ASRamFileSysSetLimitKB(ASInt32 limit) Sets the temporary file system implementation for a platform.
	void ASSetTempFileSys(ASFileSys fileSys) Sets the temporary file system implementation for a platform.

Defines Detail

ASFileSysCopyPath

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax


#define ASFileSysCopyPath ASFileSysCopyPathName

File: ASCalls.h

Line: 121

ASFileSysCreatePathFromCFURLRef

Product availability: Acrobat, Reader, PDFL

Platform availability: Macintosh

Syntax


#define ASFileSysCreatePathFromCFURLRef ASFileSysCreatePathName(asfs, ASAtomFromString("CFURLRef"), \ (void *)CHECKTYPE(CFURLRef, cfURLRef), NULL);

File: ASExpT.h

Line: 3830

ASFileSysCreatePathFromCString

Product availability: All

Platform availability: All

Syntax


#define ASFileSysCreatePathFromCString ASFileSysCreatePathName(asfs, ASAtomFromString("Cstring"), \ (void *)CHECK_CHARSTR(cPath), NULL);

Description

Helper macro for the ASFileSysCreatePathName() method.

File: ASExpT.h

Line: 3803

ASFileSysCreatePathFromDIPath

Product availability: All

Platform availability: All

Syntax


#define ASFileSysCreatePathFromDIPath ASFileSysCreatePathName(asfs, ASAtomFromString("DIPath"), \ (void *)CHECK_CHARSTR(cDIPath), (void *)CHECKTYPE(ASPathName, aspRelativeTo))

Description

A helper macro for the ASFileSysCreatePathName() method.

File: ASExpT.h

Line: 3758

ASFileSysCreatePathFromDIPathText

Product availability: All

Platform availability: All

Syntax


#define ASFileSysCreatePathFromDIPathText ASFileSysCreatePathName(asfs, ASAtomFromString("DIPathWithASText"), \ (void *)CHECKTYPE(ASText, tDIPath), (void *)CHECKTYPE(ASPathName, aspRelativeTo))

File: ASExpT.h

Line: 3762

ASFileSysCreatePathFromFSRef

Product availability: Acrobat, Reader, PDFL

Platform availability: Macintosh

Syntax


#define ASFileSysCreatePathFromFSRef ASFileSysCreatePathName(asfs, ASAtomFromString("FSRef"), \ (void *)CHECKTYPE(FSRef, fsRef), NULL);

File: ASExpT.h

Line: 3822

ASFileSysCreatePathFromFSRefWithCFStringRef

Product availability: Acrobat, Reader, PDFL

Platform availability: Macintosh

Syntax


#define ASFileSysCreatePathFromFSRefWithCFStringRef ASFileSysCreatePathName(asfs, ASAtomFromString("FSRefWithCFStringRef"), \ (void *)CHECKTYPE(FSRefWithCFStringRefRec *, fsRefWithCFStringRef), NULL);

File: ASExpT.h

Line: 3826

ASFileSysCreatePathFromFSSpec

Product availability: Acrobat, Reader, PDFL

Platform availability: Macintosh

Syntax


#define ASFileSysCreatePathFromFSSpec ASFileSysCreatePathName(asfs, ASAtomFromString("FSSpec"), \ (void *)CHECKTYPE(FSSpec *, cPath), NULL);

Description

Helper macro for the ASFileSysCreatePathName() method.

File: ASExpT.h

Line: 3817

ASFileSysCreatePathFromPOSIXPath

Product availability: Acrobat, Reader, PDFL

Platform availability: Macintosh

Syntax


#define ASFileSysCreatePathFromPOSIXPath ASFileSysCreatePathName(asfs, ASAtomFromString("POSIXPath"), \ (void *)CHECK_CHARSTR(posixPath), NULL);

File: ASExpT.h

Line: 3834

ASFileSysCreatePathWithFolderName

Product availability: All

Platform availability: All

Syntax


#define ASFileSysCreatePathWithFolderName ASFileSysCreatePathName(asfs, ASAtomFromString("FolderPathName"), \ (void *)CHECKTYPE(ASPathName, aspFolder), (void *)CHECK_CHARSTR(cFileName))

Description

Helper macro for the ASFileSysCreatePathName() method.

File: ASExpT.h

Line: 3778

ASFileSysCreatePathWithFolderNameWithASText

Product availability: All

Platform availability: All

Syntax


#define ASFileSysCreatePathWithFolderNameWithASText ASFileSysCreatePathName(asfs, ASAtomFromString("FolderPathNameWithASText"), \ (void *)CHECKTYPE(ASPathName, aspFolder), (void *)CHECKTYPE(ASText, tFileName))

File: ASExpT.h

Line: 3782

ASFileSysReleasePath

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax


#define ASFileSysReleasePath ASFileSysReleasePathName

File: ASCalls.h

Line: 122

ASFileSysRemoveFile

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax


#define ASFileSysRemoveFile ASFileSysRemove

File: ASCalls.h

Line: 123

Typedefs Detail

ASFileSys

Product availability: All

Platform availability: All

Syntax

typedef _t_ASFileSysRec ASFileSys;

A data structure containing callbacks that implement a file system.

See Also

ASFileSys

File: ASExpT.h

Line: 1833

ASFileSysItemProps

Product availability: All

Platform availability: All

Syntax

typedef _t_ASFileSysItemProps ASFileSysItemProps;

File: ASExpT.h

Line: 2148

ASFileSysItemPropsRec

Product availability: All

Platform availability: All

Syntax

typedef _t_ASFileSysItemProps ASFileSysItemPropsRec;

File: ASExpT.h

Line: 2148

ASFileSysRec

Product availability: All

Platform availability: All

Syntax

typedef _t_ASFileSysRec ASFileSysRec;

File: ASExpT.h

Line: 3555

ASFolderIterator

Product availability: All

Platform availability: All

Syntax

typedef struct _t_ASFolderIterator* ASFolderIterator;

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

File: ASExpT.h

Line: 2167

ASIORequest

Product availability: All

Platform availability: All

Syntax

typedef _t_ASIORequestRec ASIORequest;

A data structure representing an I/O request.

File: ASExpT.h

Line: 1935

ASIORequestRec

Product availability: All

Platform availability: All

Syntax

typedef _t_ASIORequestRec ASIORequestRec;

File: ASExpT.h

Line: 2048

ASlFileMode

Product availability: All

Platform availability: All

Syntax

typedef ASUns32 ASlFileMode;

File: ASExpT.h

Line: 129

ASMDFile

Product availability: All

Platform availability: All

Syntax

typedef void* ASMDFile;

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.

File: ASExpT.h

Line: 1924

ASPathName

Product availability: All

Platform availability: All

Syntax

typedef struct _t_ASPathNameRec* ASPathName;

File: ASExpT.h

Line: 1846

Enumeration Detail

ASFileSysItemType

Product availability: All

Platform availability: All

Syntax

enum ASFileSysItemType {

  kASFileSysFile,


 


  kASFileSysFolder,


 


  kASFileSysUnknown = -1

}

File: ASExpT.h

Line: 2060

Elements

	kASFileSysFile	The object is associated with a file.

	kASFileSysFolder	The object is associated with a folder.

	kASFileSysUnknown	The object type is unknown.

Structure Detail

_t_ASFileSysItemProps

Product availability: All

Platform availability: All

Syntax

struct _t_ASFileSysItemProps {

  ASSize_t size;  


 


  ASBool isThere;  


 


  ASFileSysItemType type;  


 


  ASBool isHidden;  


 


  ASBool isReadOnly;  


 


  ASBool creationDateKnown;  


 


  ASTimeRec creationDate;  


 


  ASBool modDateKnown;  


 


  ASTimeRec modDate;  


 


  ASByteCount fileSize;  


 


  ASByteCount fileSizeHigh;  


 


  ASTCount folderSize;  


 


  ASUns32 creatorCode;  


 


  ASUns32 typeCode;  

}

A list of properties for the object referenced by an ASPathName. It is used in ASFileSysGetItemProps() and the folder enumeration routines.

File: ASExpT.h

Line: 2085

Elements

	size	The size of the data structure. It must be set to `sizeof(ASFileSysItemPropsRec)`.

	isThere	`true` if the object exists. If it is `false`, none of the following fields are valid.

	type	One of the ASFileSysItemType objects.

	isHidden	`true` if the object's hidden bit is set.

	isReadOnly	`true` if the object is read-only.

	creationDateKnown	`true` if the file system could determine the creation date of the object.

	creationDate	The creation date of the object. It is valid only if `creationDateKnown` is `true`.

	modDateKnown	`true` if the file system could determine the last modification date of the object.

	modDate	The modification date of the object. It is valid only if `modDateKnown` is `true`.

	fileSize	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`.

	fileSizeHigh	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`.

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

	creatorCode	The Mac OS creator code for the file. For other file systems, this will be zero.

	typeCode	The Mac OS type code for the file. For other file systems, this will be zero.

_t_ASFileSysRec

Product availability: All

Platform availability: All

Syntax

struct _t_ASFileSysRec {

  ASSize_t size;  


 


  ASFileSysOpenProc open;  


 


  ASFileSysCloseProc close;  


 


  ASFileSysFlushProc flush;  


 


  ASFileSysSetPosProc setpos;  


 


  ASFileSysGetPosProc getpos;  


 


  ASFileSysSetEofProc seteof;  


 


  ASFileSysGetEofProc geteof;  


 


  ASFileSysReadProc read;  


 


  ASFileSysWriteProc write;  


 


  ASFileSysRemoveProc remove;  


 


  ASFileSysRenameProc rename;  


 


  ASFileSysIsSameFileProc isSameFile;  


 


  ASFileSysGetNameProc getName;  


 


  ASFileSysGetTempPathNameProc getTempPathName;  


 


  ASFileSysCopyPathNameProc copyPathName;  


 


  ASFileSysDiPathFromPathProc diPathFromPath;  


 


  ASFileSysPathFromDIPathProc pathFromDIPath;  


 


  ASFileSysDisposePathNameProc disposePathName;  


 


  ASFileSysGetFileSysNameProc getFileSysName;  


 


  ASFileSysGetStorageFreeSpaceProc getStorageFreeSpace;  


 


  ASFileSysFlushVolumeProc flushVolume;  


 


  ASFileSysGetFileFlags getFileFlags;  


 


  ASFileSysAsyncReadProc readAsync;  


 


  ASFileSysAsyncWriteProc writeAsync;  


 


  ASFileSysAsyncAbortProc abortAsync;  


 


  ASFileSysYieldProc yield;  


 


  ASFileSysMReadRequestProc mreadRequest;  


 


  ASFileSysGetStatusProc getStatus;  


 


  ASFileSysCreatePathNameProc createPathName;  


 


  ASFileSysAcquireFileSysPathProc acquireFileSysPath;  


 


  ASFileSysClearOutstandingMReadsProc clearOutstandingMReads;  


 


  ASFileSysGetItemPropsProc getItemProps;  


 


  ASFileSysFirstFolderItemProc firstFolderItem;  


 


  ASFileSysNextFolderItemProc nextFolderItem;  


 


  ASFileSysDestroyFolderIteratorProc destroyFolderIterator;  


 


  ASFileSysSetModeProc setFileMode;  


 


  ASFileSysURLFromPathProc urlFromPath;  


 


  ASFileSysGetParentProc getParent;  


 


  ASFileSysCreateFolderProc createFolder;  


 


  ASFileSysRemoveFolderProc removeFolder;  


 


  ASFileSysDisplayStringFromPathProc displayStringFromPath;  


 


  ASFileSysSetTypeAndCreatorProc setTypeAndCreator;  


 


  ASFileSysGetTypeAndCreatorProc getTypeAndCreator;  


 


  ASFileSysReopenProc reopen;  


 


  ASFileSysHardFlushProc hardFlush;  


 


  ASFileSysGetPlatformThingProc getPlatformThing;  


 


  ASFileSysGetItemPropsAsCabProc getItemPropsAsCab;  


 


  ASFileSysCanPerformOpOnItemProc canPerformOpOnItem;  


 


  ASFileSysPerformOpOnItemProc performOpOnItem;  


 


  ASFileSysAcquirePlatformPathProc acquirePlatformPath;  


 


  ASFileSysReleasePlatformPathProc releasePlatformPath;  


 


  ASFileSysGetNameAsASTextProc getNameAsASText;  


 


  ASFileSysDisplayASTextFromPathProc displayASTextFromPath;  


 


  ASFileSysRangeArrivedProc rangeArrived;  


 


  ASFileSysCanSetEofProc canSetEof;  


 


  ASFileSysDIPathFromPathExProc diPathFromPathEx;  


 


  ASFileSysPathFromDIPathExProc pathFromDIPathEx;  


 


  ASFileSysGetFilePositionLimitProc getfileposlimit;  


 


  ASFileSysOpen64Proc open64;  


 


  ASFileSysSetPos64Proc setpos64;  


 


  ASFileSysGetPos64Proc getpos64;  


 


  ASFileSysSetEof64Proc seteof64;  


 


  ASFileSysGetEof64Proc geteof64;  


 


  ASFileSysGetNameForDisplayProc getNameForDisplay;  


 


  ASFileSysGetStorageFreeSpace64Proc getStorageFreeSpace64;  


 


  ASFileSysIsInUseProc isInUse;  

}

A data structure containing callbacks that implement a file system.

See Also

ASFileSys

File: ASExpT.h

Line: 3334

Elements

	size	The size of the data structure. It must be set to `sizeof( ASFileSysRec)`.

	open	Open file callback.

	close	Close file callback.

	flush	Flush callback.

	setpos	Set position callback.

	getpos	Get position callback.

	seteof	Set a file's current logical size.

	geteof	Get a file's current logical size.

	read	Read file callback.

	write	Write file callback.

	remove	Remove file callback.

	rename	Rename file callback.

	isSameFile	Is the same file.

	getName	Get the file name.

	getTempPathName	Get the temporary path name.

	copyPathName	Copy the path name.

	diPathFromPath	Get the device-independent path from the path.

	pathFromDIPath	Get the path from the device-independent path.

	disposePathName	Dispose the path name.

	getFileSysName	Get the file system name.

	getStorageFreeSpace	Get the amount of free space on the volume.

	flushVolume	Flush the volume.

	getFileFlags	Get the file flags.

	readAsync	Asynchronous read.

	writeAsync	Asynchronous write.

	abortAsync	Asynchronous abort.

	yield	Yield callback.

	mreadRequest	Asynchronous request for a byte range.

	getStatus	Retrieve the status.

	createPathName	Create the path name.

	acquireFileSysPath	Acquire the path.

	clearOutstandingMReads	Drop read request.

	getItemProps	Get the file description.

	firstFolderItem	Begin iterating through the folder.

	nextFolderItem	Get the next folder item.

	destroyFolderIterator	Destroy the folder iterator.

	setFileMode	Set the file mode.

	urlFromPath	Get the URL from the path.

	getParent	Get the parent of the input path.

	createFolder	Create a folder.

	removeFolder	Remove a folder.

	displayStringFromPath	Get a display string representing the path.

	setTypeAndCreator	Set the type and creator.

	getTypeAndCreator	Get the type and creator.

	reopen	Reopen the file.

	hardFlush	Perform a hard flush on the file.

	getPlatformThing	Deprecated. Get the platform file system representation.

	getItemPropsAsCab	Get the file item properties in `ASCab` format.

	canPerformOpOnItem	Test whether an operation can be performed.

	performOpOnItem	Perform the operation.

	acquirePlatformPath	Acquire the platform path.

	releasePlatformPath	Release the platform path.

	getNameAsASText	Get the file name as an `ASText` object.

	displayASTextFromPath	Get the path for display.

	rangeArrived	The byte range has arrived.

	canSetEof	Determine whether the `ASFileSys` can set the end of file marker (EOF) to a new offset for the specified file.

	diPathFromPathEx	Convert a path to a device-independent path.

	pathFromDIPathEx	Convert a device-independent path to a path.

	getfileposlimit	Get the maximum file position that can be processed by this file system.

	open64	Open a file over 2 GB in length.

	setpos64	Set the current position in a file over 2 GB in length.

	getpos64	Get the current position in a file over 2 GB in length.

	seteof64	Increase or decrease the logical size for a file over 2 GB in length.

	geteof64	Get a file's current logical size for a file over 2 GB in length.

	getNameForDisplay	Gets the Windows Explorer or Mac Finder representation of the specified `ASPathName` as an `ASText` object.

	getStorageFreeSpace64	Get the amount of free space on the volume.

	isInUse	Determine whether the file is in use by another process.

_t_ASIORequestRec

Product availability: All

Platform availability: All

Syntax

struct _t_ASIORequestRec {

  ASMDFile mdFile;  


 


  void* ptr;  


 


  ASTFilePos offset;  


 


  ASTArraySize count;  


 


  ASTArraySize totalBytesCompleted;  


 


  ASErrorCode pError;  


 


  void* clientData;  


 


  ASIODoneProc IODoneProc;  


 


  void* IODoneProcData;  

}

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.

File: ASExpT.h

Line: 2003

Elements

	mdFile	The MDFile corresponding to the ASFile for which this request is intended.

	ptr	A pointer to data to write to or read from `mdFile`.

	offset	An offset (specified in bytes) into `mdFile` of the first byte to read or write.

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

	totalBytesCompleted	The number of bytes actually read or written.

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

	clientData	User-supplied data that the ASFileSys can use for any purpose.

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

	IODoneProcData	User-supplied data that is available for `IODoneProc` to use.

Callbacks Detail

ASFileSysAcquireFileSysPathProc

Product availability: All

Platform availability: All

Syntax

ASPathName (*ASFileSysAcquireFileSysPathProc)(ASPathName pathName, ASFileSys newFileSys)

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.

See Also

ASFileSysCreatePathNameProc

File: ASExpT.h

Line: 2427

ASFileSysAcquirePlatformPathProc

Product availability: All

Platform availability: All

Syntax

ASInt32 (*ASFileSysAcquirePlatformPathProc)(ASPathName path, ASAtom platformPathType, ASPlatformPath *platformPath)

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.

File: ASExpT.h

Line: 3095

ASFileSysAsyncAbortProc

Product availability: All

Platform availability: All

Syntax

void (*ASFileSysAsyncAbortProc)(ASMDFile f)

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.

File: ASExpT.h

Line: 2316

ASFileSysAsyncReadProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysAsyncReadProc)(ASIORequest req)

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.

File: ASExpT.h

Line: 2280

ASFileSysAsyncWriteProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysAsyncWriteProc)(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.

File: ASExpT.h

Line: 2300

ASFileSysCanPerformOpOnItemProc

Product availability: All

Platform availability: All

Syntax

ASInt32 (*ASFileSysCanPerformOpOnItemProc)(ASPathName pathName, const char *op)

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.

File: ASExpT.h

Line: 3055

ASFileSysCanSetEofProc

Product availability: All

Platform availability: All

Syntax

ASBool (*ASFileSysCanSetEofProc)(ASMDFile f, ASFilePos pos)

A callback for ASFileSysRec that determines whether ASFileSys can set the end of file marker (EOF) to a new offset for the specified file.

File: ASExpT.h

Line: 3155

ASFileSysClearOutstandingMReadsProc

Product availability: All

Platform availability: All

Syntax

void (*ASFileSysClearOutstandingMReadsProc)(ASMDFile f)

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.

File: ASExpT.h

Line: 2390

ASFileSysCloseProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysCloseProc)(ASMDFile f)

A callback for ASFileSysRec. This callback is responsible for closing the specified file. It is called by ASFileClose().

See Also

ASFileSysOpenProc
ASFileClose

File: ASExpT.h

Line: 2458

ASFileSysCopyPathNameProc

Product availability: All

Platform availability: All

Syntax

ASPathName (*ASFileSysCopyPathNameProc)(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.

See Also

ASFileSysCopyPath

File: ASExpT.h

Line: 2649

ASFileSysCreateFolderProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysCreateFolderProc)(ASPathName path)

A callback for ASFileSysRec used to create an empty folder at the specified path.

File: ASExpT.h

Line: 2907

ASFileSysCreatePathNameProc

Product availability: All

Platform availability: All

Syntax

ASPathName (*ASFileSysCreatePathNameProc)(ASAtom pathSpecType, const void *pathSpec, const void *mustBeZero)

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.

See Also

ASFileSysCreatePathName

File: ASExpT.h

Line: 2765

ASFileSysDestroyFolderIteratorProc

Product availability: All

Platform availability: All

Syntax

void (*ASFileSysDestroyFolderIteratorProc)(ASFolderIterator folderIter)

A callback for ASFileSysRec used to release the resources associated with folderIter.

File: ASExpT.h

Line: 2840

ASFileSysDIPathFromPathExProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysDIPathFromPathExProc)(ASPathName path, ASPathName relativeToThisPath, ASText diPathText)

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

File: ASExpT.h

Line: 3180

ASFileSysDiPathFromPathProc

Product availability: All

Platform availability: All

Syntax

char * (*ASFileSysDiPathFromPathProc)(ASPathName path, ASPathName relativeToThisPath)

A callback for ASFileSysRec that converts a path name to a device- independent path name. It is called by ASFileSysDIPathFromPath().

See Also

ASFileSysDIPathFromPath

File: ASExpT.h

Line: 2671

ASFileSysDisplayASTextFromPathProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysDisplayASTextFromPathProc)(ASPathName path, ASText displayText)

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

This does not raise an error.

File: ASExpT.h

Line: 3131

ASFileSysDisplayStringFromPathProc

Product availability: All

Platform availability: All

Syntax

char * (*ASFileSysDisplayStringFromPathProc)(ASPathName path)

A callback for ASFileSysRec used to obtain a representation of a path that can be displayed by the user.

See Also

ASFileSysDisplayStringFromPath

File: ASExpT.h

Line: 2929

ASFileSysDisposePathNameProc

Product availability: All

Platform availability: All

Syntax

void (*ASFileSysDisposePathNameProc)(ASPathName pathName)

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.

See Also

ASFileSysReleasePath

File: ASExpT.h

Line: 2705

ASFileSysFirstFolderItemProc

Product availability: All

Platform availability: All

Syntax

ASFolderIterator (*ASFileSysFirstFolderItemProc)(ASPathName folderPath, ASFileSysItemProps props, ASPathName *itemPath)

A callback for ASFileSysRec that begins the process of iterating through the contents of a folder.

File: ASExpT.h

Line: 2802

ASFileSysFlushProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysFlushProc)(ASMDFile f)

A callback for ASFileSysRec that flushes data for the specified file. It is called by ASFileFlush().

See Also

ASFileSysFlushVolumeProc
ASFileFlush

File: ASExpT.h

Line: 2469

ASFileSysFlushVolumeProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysFlushVolumeProc)(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.

See Also

ASFileSysFlushProc

File: ASExpT.h

Line: 2745

ASFileSysGetEof64Proc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysGetEof64Proc)(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.

See Also

ASFileGetEOF
ASFileSetEOF

File: ASExpT.h

Line: 3292

ASFileSysGetEofProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysGetEofProc)(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.

See Also

ASFileGetEOF
ASFileSetEOF

File: ASExpT.h

Line: 2525

ASFileSysGetFileFlags

Product availability: All

Platform availability: All

Syntax

ASFlagBits (*ASFileSysGetFileFlags)(ASMDFile f)

A callback for ASFileSysRec that gets the flags for the specified file.

File: ASExpT.h

Line: 2256

ASFileSysGetFilePositionLimitProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysGetFilePositionLimitProc)(ASFilePos64 *pos)

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.

See Also

ASFileSysGetFilePosLimit

File: ASExpT.h

Line: 3236

ASFileSysGetFileSysNameProc

Product availability: All

Platform availability: All

Syntax

ASAtom (*ASFileSysGetFileSysNameProc)(void)

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.

See Also

ASFileRegisterFileSys

File: ASExpT.h

Line: 2716

ASFileSysGetItemPropsAsCabProc

Product availability: All

Platform availability: All

Syntax

ASInt32 (*ASFileSysGetItemPropsAsCabProc)(ASPathName pathName, ASCab theCab)

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;

See Also

ASFileSysGetItemPropsAsCab

File: ASExpT.h

Line: 3041

ASFileSysGetItemPropsProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysGetItemPropsProc)(ASPathName pathName, ASFileSysItemProps props)

A callback for ASFileSysRec used to retrieve a full description of the file system object associated with the path.

See Also

ASFileSysGetItemProps

File: ASExpT.h

Line: 2779

ASFileSysGetNameAsASTextProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysGetNameAsASTextProc)(ASPathName pathName, ASText name)

A callback for ASFileSysRec that gets the file name for the specified ASPathName as an ASText object.

File: ASExpT.h

Line: 3124

ASFileSysGetNameForDisplayProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysGetNameForDisplayProc)(ASPathName pathName, ASText nameForDisplay)

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.

File: ASExpT.h

Line: 3307

ASFileSysGetNameProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysGetNameProc)(ASPathName pathName, char *name, ASTArraySize maxLength)

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.

See Also

ASFileSysGetFileSysNameProc

File: ASExpT.h

Line: 2616

ASFileSysGetParentProc

Product availability: All

Platform availability: All

Syntax

ASPathName (*ASFileSysGetParentProc)(ASPathName path)

A callback for ASFileSysRec used to obtain the parent of the input path.

File: ASExpT.h

Line: 2896

ASFileSysGetPlatformThingProc

Product availability: All

Platform availability: All

Syntax

void * (*ASFileSysGetPlatformThingProc)(ASPathName path, ASAtom thing)

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.

File: ASExpT.h

Line: 2999

ASFileSysGetPos64Proc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysGetPos64Proc)(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.

File: ASExpT.h

Line: 3265

ASFileSysGetPosProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysGetPosProc)(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.

File: ASExpT.h

Line: 2497

ASFileSysGetStatusProc

Product availability: All

Platform availability: All

Syntax

ASFlagBits (*ASFileSysGetStatusProc)(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.

See Also

ASFileRead

File: ASExpT.h

Line: 2402

ASFileSysGetStorageFreeSpace64Proc

Product availability: All

Platform availability: All

Syntax

ASDiskSpace64 (*ASFileSysGetStorageFreeSpace64Proc)(ASPathName pathName)

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

File: ASExpT.h

Line: 3318

ASFileSysGetStorageFreeSpaceProc

Product availability: All

Platform availability: All

Syntax

ASDiskSpace (*ASFileSysGetStorageFreeSpaceProc)(ASPathName pathName)

A callback for ASFileSysRec that gets the amount of free space on the volume containing the specified ASPathName.

File: ASExpT.h

Line: 2726

ASFileSysGetTempPathNameProc

Product availability: All

Platform availability: All

Syntax

ASPathName (*ASFileSysGetTempPathNameProc)(ASPathName pathName)

A callback for ASFileSysRec that returns a unique path name suitable for use in creating temporary files.

See Also

ASFileSysCopyPathNameProc

File: ASExpT.h

Line: 2632

ASFileSysGetTypeAndCreatorProc

Product availability: All

Platform availability: All

Syntax

void (*ASFileSysGetTypeAndCreatorProc)(ASPathName path, ASUns32 *type, ASUns32 *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.

File: ASExpT.h

Line: 2957

ASFileSysHardFlushProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysHardFlushProc)(ASMDFile f)

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.

File: ASExpT.h

Line: 2989

ASFileSysIsInUseProc

Product availability: All

Platform availability: All

Syntax

ASBool (*ASFileSysIsInUseProc)(ASPathName pathName)

A callback for ASFileSysRec that tests whether a file is in use by another process.

File: ASExpT.h

Line: 3327

ASFileSysIsSameFileProc

Product availability: All

Platform availability: All

Syntax

ASBool (*ASFileSysIsSameFileProc)(ASMDFile f, ASPathName pathName, ASPathName newPathName)

A callback for ASFileSysRec that tests whether two files are the same.

File: ASExpT.h

Line: 2595

ASFileSysMReadRequestProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysMReadRequestProc)(ASMDFile f, ASFile aFile, ASTFilePos *blockPairs, ASTArraySize nBlockPairs)

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.

File: ASExpT.h

Line: 2376

ASFileSysNextFolderItemProc

Product availability: All

Platform availability: All

Syntax

ASBool (*ASFileSysNextFolderItemProc)(ASFolderIterator folderIter, 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.

File: ASExpT.h

Line: 2825

ASFileSysOpen64Proc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysOpen64Proc)(ASPathName pathName, ASFileMode mode, ASMDFile *fP)

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.

File: ASExpT.h

Line: 3221

ASFileSysOpenProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysOpenProc)(ASPathName pathName, ASFileMode mode, ASMDFile *fP)

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.

File: ASExpT.h

Line: 2446

ASFileSysPathFromDIPathExProc

Product availability: All

Platform availability: All

Syntax

ASPathName (*ASFileSysPathFromDIPathExProc)(ASConstText diPathText, ASPathName relativeToThisPath)

A callback for ASFileSysRec that converts a device-independent path name from an ASText object to an ASPathName. It is called by ASFileSysPathFromDIPathEx().

File: ASExpT.h

Line: 3204

ASFileSysPathFromDIPathProc

Product availability: All

Platform availability: All

Syntax

ASPathName (*ASFileSysPathFromDIPathProc)(const char *diPath, ASPathName relativeToThisPath)

A callback for ASFileSysRec that converts a device-independent path name to an ASPathName. It is called by ASFileSysPathFromDIPath().

File: ASExpT.h

Line: 2695

ASFileSysPerformOpOnItemProc

Product availability: All

Platform availability: All

Syntax

ASInt32 (*ASFileSysPerformOpOnItemProc)(ASPathName pathName, const char *op, ASCab params)

A callback for ASFileSysRec that performs the specified operation on a particular file.

File: ASExpT.h

Line: 3070

ASFileSysRangeArrivedProc

Product availability: All

Platform availability: All

Syntax

void (*ASFileSysRangeArrivedProc)(ASInt32 start, ASInt32 length, void *clientData)

A callback for ASFileSysRec used when a byte range has arrived during a file load operation.

File: ASExpT.h

Line: 3142

ASFileSysReadProc

Product availability: All

Platform availability: All

Syntax

ASSize_t (*ASFileSysReadProc)(void *ptr, ASSize_t size, ASSize_t count, ASMDFile f, ASErrorCode *pError)

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.

See Also

ASFileSysWriteProc
ASFileRead

File: ASExpT.h

Line: 2543

ASFileSysReleasePlatformPathProc

Product availability: All

Platform availability: All

Syntax

void (*ASFileSysReleasePlatformPathProc)(ASPlatformPath platformPath)

A callback for ASFileSysRec that releases the specified platform path object when the client is done with it.

File: ASExpT.h

Line: 3107

ASFileSysRemoveFolderProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysRemoveFolderProc)(ASPathName path)

A callback for ASFileSysRec used to delete the folder at the specified path.

File: ASExpT.h

Line: 2918

ASFileSysRemoveProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysRemoveProc)(ASPathName pathName)

A callback for ASFileSysRec that deletes a file. It is called by ASFileSysRemoveFile().

See Also

ASFileSysRemoveFile

File: ASExpT.h

Line: 2568

ASFileSysRenameProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysRenameProc)(ASMDFile *f, ASPathName oldPath, ASPathName newPath)

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.

See Also

ASFileSysGetNameProc

File: ASExpT.h

Line: 2581

ASFileSysReopenProc

Product availability: All

Platform availability: All

Syntax

ASMDFile (*ASFileSysReopenProc)(ASMDFile f, ASFileMode newMode, ASErrorCode *error)

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.

See Also

ASFileReopen
ASFileSysOpenFile

File: ASExpT.h

Line: 2979

ASFileSysSetEof64Proc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysSetEof64Proc)(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.

See Also

ASFileGetEOF
ASFileSetEOF

File: ASExpT.h

Line: 3278

ASFileSysSetEofProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysSetEofProc)(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.

File: ASExpT.h

Line: 2511

ASFileSysSetModeProc

Product availability: All

Platform availability: All

Syntax

ASlFileMode (*ASFileSysSetModeProc)(ASMDFile f, ASlFileMode modeValue, ASMaskBits modeMask)

ASFileSysSetMode() sets and gets parameters for the specified file.

Mode operations:

Operation	Code
Get the current mode	`ASFileSetMode(aFile, 0, 0);`
Set the mode	`ASFileSetMode( aFile, kASFileModeDoNotYieldIfBytesNotReady, kASFileModeDoNotYieldIfBytesNotReady );`
Clear the mode	`ASFileSetMode( aFile, 0, kASFileModeDoNotYieldIfBytesNotReady );`

Setting parameters:

Parameter	Effect
kASFileModeDoNotYieldIfBytesNotReady	If set, then ASFileRead() will not perform a `fileSys->yield()` if `RaiseIfBytesNotReady` is `true`. Otherwise, it may call `yield` before raising the exception `fileErrBytesNotReady`.
kASFileModeDisableExplicitMReadRequests	If set, `mread()` requests made via ASFileMReadRequest() become NOPs.
kASFileRaiseIfBytesNotReady	If set, ASFileRead() will raise `fileErrBytesNotReady` when trying to read from a file with a cache for which the requested bytes are not yet present.

File: ASExpT.h

Line: 2885

ASFileSysSetPos64Proc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysSetPos64Proc)(ASMDFile f, 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.

See Also

ASFileGetPos
ASFileSetPos

File: ASExpT.h

Line: 3251

ASFileSysSetPosProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysSetPosProc)(ASMDFile f, ASFilePos pos)

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

See Also

ASFileGetPos
ASFileSetPos

File: ASExpT.h

Line: 2483

ASFileSysSetTypeAndCreatorProc

Product availability: All

Platform availability: All

Syntax

void (*ASFileSysSetTypeAndCreatorProc)(ASPathName path, ASUns32 type, ASUns32 creator)

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.

File: ASExpT.h

Line: 2943

ASFileSysURLFromPathProc

Product availability: All

Platform availability: All

Syntax

char * (*ASFileSysURLFromPathProc)(ASPathName path)

A callback for ASFileSysRec used to obtain the URL associated with the given ASPathName.

See Also

ASFileSysURLFromPath

File: ASExpT.h

Line: 2852

ASFileSysWriteProc

Product availability: All

Platform availability: All

Syntax

ASSize_t (*ASFileSysWriteProc)(void *ptr, ASSize_t size, ASSize_t count, ASMDFile f, ASErrorCode *pError)

A callback for ASFileSysRec that writes data to the specified file.

See Also

ASFileSysReadProc
ASFileWrite

File: ASExpT.h

Line: 2558

ASFileSysYieldProc

Product availability: All

Platform availability: All

Syntax

ASErrorCode (*ASFileSysYieldProc)(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.

File: ASExpT.h

Line: 2338

Method Detail

ASFileSysAcquireFileSysPath

()

Product availability: All

Platform availability: All

Syntax





ASPathName ASFileSysAcquireFileSysPath(ASFileSys oldFileSys, ASPathName oldPathName, ASFileSys newFileSys)

Converts an ASPathName from one file system to another. It returns an ASPathName acquired through newFileSys that refers to an image (which may possibly be cached) of the file in oldfileSys. Use this call to get a local file that is an image of a remote file (in a URL file system, for example). This is needed by programs such as the QuickTime Movie Player, because they can only work from local file-system files. The returned ASPathName may be a reference to a cache, so the file should be treated as read-only.

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.

Do not remove the local file copy, since the newFileSys system does not know about the linkage to the remote (oldFileSys) file!

The source file does not have to be open.

This call is handled by oldFileSys if oldFileSys contains the appropriate procedure. Otherwise it is handled by copying the file. The source file is closed at the end of the copy if it was not open prior to the call.

It is the caller's responsibility to release the ASPathName when it is no longer needed by using ASFileSysReleasePath().

Parameters

	`oldFileSys` —	IN/OUT (May be `NULL`) The file system from which `oldPathName` was obtained. Pass `NULL` to use the default file system.

	`oldPathName` —	IN/OUT The ASPathname in the current file system.

	`newFileSys` —	IN/OUT (May be `NULL`) The file system to which the `oldPathName` is converted. Pass `NULL` to use the default file system.

Returns

The ASPathName in newFileSys or NULL if one cannot be made.

See Also

ASFileSysCreatePathName

Exceptions

ERR_NOMEMORY
fileErrIO
fileErrUserRequestedStop
fileErrBytesNotReady
fileErrIOTimeout
fileErrGeneral
fileErrWrite

Since

PI_ACROSUPPORT_VERSION >= 0x00020002

File: ASProcs.h

Line: 1469

ASFileSysAcquireParent

()

Product availability: All

Platform availability: All

Syntax





ASPathName ASFileSysAcquireParent(ASFileSys fileSys, ASPathName pathName)

Returns the parent folder of the file system object associated with pathName. The following rules apply in the default file systems:

pathName may be associated with either a file or a folder.
The file system object associated with pathName need not exist.

It is the caller's responsibility to release the returned ASPathName.

Parameters

	`fileSys` —	IN/OUT (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	IN/OUT The ASPathName.

Returns

The ASPathName associated with the parent folder. The method will return NULL if the parent could not be returned.

See Also

ASFileSysCreatePathName

Exceptions

genErrNoMemory
fileErrIO
fileErrUserRequestedStop
fileErrBytesNotReady
fileErrIOTimeout
fileErrGeneral
fileErrWrite

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1707

ASFileSysAcquirePlatformPath

()

Product availability: All

Platform availability: All

Syntax





ASInt32 ASFileSysAcquirePlatformPath(ASFileSys fileSys, ASPathName path, ASAtom platformPathType, ASPlatformPath* platformPath)

Returns a platform-specific file system representation of the specified path, according to the specified type, wrapped in an allocated ASPlatformPath object. It calls ASFileSysAcquirePlatformPathProc().

This method creates an equivalent platform-specific type (such as FSRef on Mac OS) from an ASPathName. Use ASFileSysCreatePathName() for the reverse situation to create an equivalent ASPathName from a platform-specific type.

In previous releases, you could cast an ASPathName to an FSSpec, for example, but that does not work in the Acrobat 6.0 SDK and later (because of changes to accommodate long, Unicode file names on Mac OS X). When developing for Mac OS, use this call to get an FSSpec from an ASPathName safely on Mac OS X, without casting. However, it is recommended that you transition to using newer types such as FSRef to be compatible with OS X filenames, or change to using all ASFileSys methods.

Parameters

fileSys —

(May be NULL) The file system from which pathName was obtained. Pass NULL to use the default file system.

path —

The ASPathName in the file system specified by fileSys.

platformPathType —

The platform path type, one of the following ASAtom values:

ASAtom value	Operating system
FSRefWithCFStringRef	Mac OS
FSSpec	Mac OS
CFURLRef	Mac OS
POSIXPath	Mac OS
FSRef (`pathName` object must exist)	Mac OS
`CString`	Windows/UNIX

platformPath —

(Filled by the method) The new platform path object. Always free this object with ASFileSysReleasePlatformPath() when done.

Returns

0 if the operation was successful, non-zero error code otherwise.

See Also

ASFileSysReleasePlatformPath

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2262

ASFileSysCanPerformOpOnItem

()

Product availability: All

Platform availability: All

Syntax





ASInt32 ASFileSysCanPerformOpOnItem(ASFileSys fileSys, ASPathName pathName, const char* op)

Tests whether a given operation can be performed on a particular file. It calls the canPerformOpOnItem() procedure registered for the ASFileSysRec, which determines whether the operation is one of the file system-defined operation strings for which there is a handler.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The ASPathName of the file.

	`op` —	The name of the operation to test. A file system-defined string handled by ASFileSysCanPerformOpOnItemProc().

Returns

asGenErrNoError if the operation can be performed on the item, or an error indicating why the oepration would fail.

See Also

ASFileSysPerformOpOnItem

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASExtraProcs.h

Line: 2288

ASFileSysConvertCabToItemProps

()

Product availability: All

Platform availability: All

Syntax





ASInt32 ASFileSysConvertCabToItemProps(ASFileSysItemProps props, ASCab theCab)

Converts a set of item properties from the ASCab format to the ASFileSysItemPropsRec format.

Parameters

	`props` —	(Filled by the method) The item properties structure.

	`theCab` —	Properties describing the object, in cabinet format.

Returns

0 if no error was encountered; otherwise an error code is returned.

Exceptions

genErrBadParm
genErrMethodNotImplemented

Since

PI_ACROSUPPORT_VERSION >=

File: ASExtraProcs.h

Line: 2229

ASFileSysConvertItemPropsToCab

()

Product availability: All

Platform availability: All

Syntax





ASInt32 ASFileSysConvertItemPropsToCab(ASCab theCab, const ASFileSysItemPropsRec* props)

Converts a set of item properties from the ASFileSysItemPropsRec format to the ASCab format.

The ASCab has the following potential entries:

Key Name	Type
`isThere`	ASBool
`type`	ASInt32
`isHidden`	ASBool
`isReadOnly`	ASBool
`creationDate`	`char*` (PDF style date string)
`modDate`	`char*` (PDF style date string)
`fileSizeHigh`	ASUns32
`fileSizeLow`	ASUns32
`folderSize`	ASInt32
`creatorCode`	ASUns32
`typeCode`	ASUns32
`versionMajor`	ASUns32
`versionMinor`	ASUns32
`isCheckedOut`	ASBool
`isPublished`	ASBool

Parameters

	`theCab` —	(Filled by the method) Properties describing the object, in cabinet format.

	`props` —	The item properties structure.

Returns

0 if no error was encountered; otherwise an error code is returned.

Exceptions

genErrBadParm
genErrMethodNotImplemented

Since

PI_ACROSUPPORT_VERSION >=

File: ASExtraProcs.h

Line: 2268

ASFileSysCopyPath

()

Product availability: All

Platform availability: All

Syntax





ASPathName ASFileSysCopyPath(ASFileSys fileSys, ASPathName pathName)

Generates and copies the specified ASPathName (but does not copy the file specified by the path name). The ASPathName must have been obtained through the specified file system. This method may be used regardless of whether the file specified by path name is open.

It is the caller's responsibility to release the ASPathName when it is no longer needed by using ASFileSysReleasePath().

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The ASPathName to copy.

Returns

A copy of pathName.

See Also

ASFileSysReleasePath

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 781

ASFileSysCreateFolder

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysCreateFolder(ASFileSys fileSys, ASPathName path, ASBool recurse)

Creates an empty folder at the specified pathName.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`path` —	The path of the folder to create.

	`recurse` —	Recursively create the parent folder if necessary.

Returns

0 if the operation was successful, a non-zero platform-dependent error code otherwise.

See Also

ASFileSysRemoveFolder

Exceptions

genErrMethodNotImplemented
fileErrFNF

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1868

ASFileSysCreatePathName

()

Product availability: All

Platform availability: All

Syntax





ASPathName ASFileSysCreatePathName(const ASFileSys fileSys, ASAtom pathSpecType, const void* pathSpec, const void* additionalData)

Creates an ASPathName based on the input type and pathSpec. Each fileSys implementation must publish the input types that it accepts.

It is the caller's responsibility to release the ASPathName when it is no longer needed by using ASFileSysReleasePath().

Developers should consider using the simpler helper macros instead of using the call directly.

Parameters

fileSys —

(May be NULL) The ASFileSys in which you are trying to create an ASPathName. Pass NULL to use the default file system.

pathSpecType —

An ASAtom specifying the data type in pathSpec, as follows:

Data type	Description
`"Cstring"`	Accepted by the default file system on all platforms. `pathSpec` is a `NULL`- terminated `char*`. On Mac OS it must be an absolute path separated by colons, as in `"VolumeName:Folder:file.pdf"`. On Windows the path may be absolute, as in `"C:\\folder\\file.pdf"` or relative as in `"...\\folder\\file.pdf"`. On UNIX the path may be absolute as in `"/folder/file.pdf"` or relative as in `".../folder/file.pdf"`.
`"FSSpec"`	Accepted by the default file system on Mac OS. `pathSpec` is a pointer to a valid FSSpec. This type is deprecated in Acrobat 9.0. Use FSRef, FSRefWithCFStringRef, CFURLRef, or POSIXPath instead.
`"FSRef"`	Accepted by the default file system on Mac OS. `pathSpec` is a valid FSRef.
`"FSRefWithCFStringRef"`	Accepted by the default file system on Mac OS. `pathSpec` is a pointer to a valid FSRefWithCFStringRefRec.
`"CFURLRef"`	Accepted by the default file system on Mac OS. `pathSpec` is a valid CFURLRef.
`"POSIXPath"`	Accepted by the default file system on Mac OS. `pathSpec` is a `NULL`-terminated `char*` containing a POSIX-style, UTF-8 encoded path string.
`"SFReply"`	In the past this was accepted by the default file system on Mac OS. This type is deprecated and should not be used.
`"DIPath"`	Accepted by the default file system on Windows and Mac OS. `pathSpec` is a device-independent path as documented in the PDF Reference. `pathSpec` can contain an absolute or relative path. If a relative path is used, the method will evaluate that path against an ASPathName passed in the `mustBeZero` parameter.
`"DIPathWithASText"`	Accepted by the default file system on Windows and Mac OS. `pathSpec` is a device-independent path, in the form of an ASText, as documented in the PDF Reference. `pathSpec` can contain an absolute or relative path. If a relative path is used, the method will evaluate that path against an ASPathName passed in the `mustBeZero` parameter.
`"FolderPathName"`	Accepted by the default file system on Windows and Mac OS. `pathSpec` is an ASPathName that contains the path of a folder. `mustBeZero` is a C string containing the name of the file. The returned ASPathName contains the result of appending `mustBeZero` to `pathSpec`.
`"FolderPathNameWithASText"`	Accepted by the default file system on Windows and Mac OS. `pathSpec` is an ASPathName that contains the path of a folder. `mustBeZero` is an ASText containing the name of the file. The returned ASPathName contains the result of appending `mustBeZero` to `pathSpec`.

pathSpec —

The file specification from which to create an ASPathName. Relative paths are evaluated from the directory containing the executable (if used with the PDF Library), or the directory containing Acrobat (if used in a plug-in).

additionalData —

See pathSpecType parameter description.

Returns

The newly created path name, or NULL on failure.

Exceptions

genErrBadParm on Windows if the pathSpecType is not recognized.
genErrMethodNotImplemented

Since

PI_ACROSUPPORT_VERSION >= 0x00020002

File: ASProcs.h

Line: 1417

ASFileSysDestroyFolderIterator

()

Product availability: All

Platform availability: All

Syntax





void ASFileSysDestroyFolderIterator(ASFileSys fileSys, ASFolderIterator folderIter)

Releases the resources associated with folderIter.

Parameters

	`fileSys` —	IN/OUT (May be `NULL`) The file system from which the iteration was started. Pass `NULL` to use the default file system.

	`folderIter` —	IN/OUT An ASFolderIterator object returned from a previous call to ASFileSysFirstFolderItem().

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1675

ASFileSysDIPathFromPath

()

Product availability: All

Platform availability: All

Syntax





char* ASFileSysDIPathFromPath(ASFileSys fileSys, ASPathName path, ASPathName relativeToThisPath)

Converts a file name, specified as an ASPathName, to a device-independent path name. It is the caller's responsibility to free the memory associated with the returned string using ASfree().

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`path` —	The ASPathName to convert.

	`relativeToThisPath` —	(May be `NULL`) The path name relative to which the device-independent path name is specified. If `NULL`, the device-independent path name will be an absolute, not a relative, path name.

Returns

A device-independent path name corresponding to the parameter values supplied, or NULL if the operation is not supported by the file system.

See section 3.10 in the PDF Reference for a description of the device-independent path name format. This path name may not be understood on another platform since drive specifiers may be prepended.

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 726

ASFileSysDIPathFromPathEx

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysDIPathFromPathEx(ASFileSys fileSys, ASPathName path, ASPathName relativeToThisPath, ASText diPathText)

Converts a file name, specified as an ASPathName, to a device-independent path name, which is returned as an ASText object. It calls ASFileSysDIPathFromPathExProc().

This method supersedes ASFileSysDIPathFromPath() in Acrobat 6.0 and later.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`path` —	The ASPathName to convert.

	`relativeToThisPath` —	(May be `NULL`) The path name relative to which the device-independent path name is specified. If it is `NULL`, the device-independent path name will be an absolute, not a relative, path name.

	`diPathText` —	(Filled by the method) The ASText object to contain the device-independent path. It must be allocated and freed by the client.

Returns

0 if the operation was successful, a non-zero platform-dependent error code otherwise.

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2519

ASFileSysDisplayASTextFromPath

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysDisplayASTextFromPath(ASFileSys fileSys, ASPathName path, ASText displayText)

Returns a user-friendly representation of a path as a text object. It calls ASFileSysDisplayASTextFromPathProc().

This method supersedes ASFileSysDisplayStringFromPath() in Acrobat 6.0 and later.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`path` —	The ASPathName in question.

	`displayText` —	(Filled by method) The text object containing the display representation of the path.

Returns

0 if the operation was successful, a non-zero platform-dependent error code otherwise.

See Also

ASFileSysDisplayStringFromPath

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2426

ASFileSysDisplayStringFromPath

()

Product availability: All

Platform availability: All

Syntax





char* ASFileSysDisplayStringFromPath(ASFileSys fileSys, ASPathName path)

Returns a user-friendly representation of a path. It is the caller's responsibility to release the memory associated with the returned string using ASfree().

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`path` —	The ASPathName in question.

Returns

A buffer containing the display string, or NULL if this operation is not supported by the file system or some error occurred.

Example
How to use examples

Operating system	Display string
Windows	`"C:\\Folder\\File"`
Mac OS	`"Hard Disk:Folder:File"`
UNIX	`"/Folder/File"`

See Also

ASFileSysDisplayASTextFromPath

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1934

ASFileSysFirstFolderItem

()

Product availability: All

Platform availability: All

Syntax





ASFolderIterator ASFileSysFirstFolderItem(ASFileSys fileSys, ASPathName folderPath, ASFileSysItemProps props, ASPathName* itemPath)

Creates an iterator which can be used to enumerate all objects inside the specified folder, and returns the properties of the first item found in the folder. The iteration can be continued by passing the returned ASFolderIterator to ASFileSysNextFolderItem.

Both itemProps and itemPath are optional, and may be NULL if you are not interested in that information.

The client is obligated to eventually free the resources associated with ASFolderIterator by calling ASFileSysDestroyFolderIterator().

Parameters

	`fileSys` —	IN/OUT (May be `NULL`) The file system from which `folderPath` was obtained. Pass `NULL` to use the default file system.

	`folderPath` —	IN/OUT The path associated with the target folder.

	`props` —	IN/OUT (Filled by the method, may be `NULL`) A properties structure describing the first object iterated.

	`itemPath` —	(Filled by the method, may be `NULL`) An ASPathName, allocated by ASFileSysFirstFolderItem(), which is associated with the object. The caller of ASFileSysFirstFolderItem() must free the ASPathName. This parameter contains an absolute path on Windows and UNIX.

Returns

A valid ASFolderIterator object if folderPath contained any files. NULL will be returned if the folder is empty or the operation is not supported by the file system.

Exceptions

genErrBadParm
fileErrFNF (raised by the Windows default file system)
asFileErrNotADir (raised by the Windows default file system)
ERR_NOMEMORY

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1633

ASFileSysFlushVolume

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysFlushVolume(ASFileSys fileSys, ASPathName pathName)

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 Mac OS FlushVol or to the UNIX sync).

Only the Mac OS default file system implements the callback associated with this method. This is a no-op on Windows and UNIX.

Parameters

	`fileSys` —	IN/OUT (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	IN/OUT The ASPathName from which the volume information is obtained.

Returns

0 if the operation was successful, a non-zero platform-dependent error code otherwise.

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1803

ASFileSysGetFilePosLimit

()

Product availability: All

Platform availability: All

Syntax





ASFilePos64 ASFileSysGetFilePosLimit(ASFileSys fileSys)

Returns the maximum file position that can be processed by this file system. This is not the maximum size file that can be created or the amount of room left in the file system, 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.

Parameters

fileSys —

IN/OUT (May be NULL) The file system from which the path name was obtained. Pass NULL to use the default file system.

Returns

The maximum file position that can be processed.

See Also

ASFileSysOpenFile64

Since

PI_ACROSUPPORT_VERSION >= 0x00070000

File: ASProcs.h

Line: 2672

ASFileSysGetItemProps

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysGetItemProps(ASFileSys fileSys, ASPathName pathName, ASFileSysItemProps props)

Populates an ASFileSysItemProps record with a full description of the file system object associated with pathName. It calls ASFileSysGetItemPropsProc().

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The ASPathName associated with the object.

	`props` —	(Filled by the method) A properties structure describing the object. The size field must be set on input.

Returns

0 if no error was encountered; otherwise an error code is returned. If an error code is returned, props will not be filled with valid values. If no file system object is present, an error will not be reported and the props.isThere field will be false.

Exceptions

genErrBadParm
genErrMethodNotImplemented

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1589

ASFileSysGetItemPropsAsCab

()

Product availability: All

Platform availability: All

Syntax





ASInt32 ASFileSysGetItemPropsAsCab(ASFileSys fileSys, ASPathName pathName, ASCab theCab)

Gets a full description of the file system object associated with pathName, returning the item properties in the ASCab format. Calls ASFileSysGetItemPropsAsCabProc().

If the ASCab has no keys on entry, every property known 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:

Key Name	Type
`isThere`	ASBool
`type`	ASInt32
`isHidden`	ASBool
`isReadOnly`	ASBool
`creationDate`	`char*` (PDF style date string)
`modDate`	`char*` (PDF style date string)
`fileSizeHigh`	ASUns32
`fileSizeLow`	ASUns32
`folderSize`	ASInt32
`creatorCode`	ASUns32
`typeCode`	ASUns32
`versionMajor`	ASUns32
`versionMinor`	ASUns32
`isCheckedOut`	ASBool
`isPublished`	ASBool

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The ASPathName associated with the object.

	`theCab` —	(Filled by the method) Properties describing the object, in cabinet format.

Returns

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, returns asFileErrFNF and a valid ASCab with isThere set to false.

Exceptions

genErrBadParm
genErrMethodNotImplemented

Since

PI_ACROSUPPORT_VERSION >=

File: ASExtraProcs.h

Line: 2211

ASFileSysGetNameFromPath

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysGetNameFromPath(ASFileSys fileSys, ASPathName pathName, char* name, ASTArraySize maxLength)

Extracts the file name (including extension) from the path.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The ASPathName associated with the file in question.

	`name` —	(Filled by the method) A buffer used to store the file name.

	`maxLength` —	Maximum number of bytes that buffer can hold.

Returns

0 if the operation was successful, a non-zero platform-dependent error code otherwise. The buffer is returned as a host-encoded C string.

See Also

ASFileSysGetNameFromPathAsASText

Exceptions

fileErrGeneral

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1745

ASFileSysGetNameFromPathAsASText

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysGetNameFromPathAsASText(ASFileSys fileSys, ASPathName pathName, ASText name)

Extracts the file name (including the extension) from the path as an ASText object. This method supersedes ASFileSysGetNameFromPath() in Acrobat 6.0 and later.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The ASPathName associated with the file in question.

	`name` —	(Filled by the method) The text object containing the file name.

Returns

0 if the operation was successful, a non-zero platform-dependent error code otherwise.

See Also

ASFileSysGetNameFromPath

Exceptions

fileErrGeneral

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2407

ASFileSysGetNameFromPathForDisplay

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysGetNameFromPathForDisplay(ASFileSys fileSys, ASPathName pathName, ASText nameForDisplay)

This method writes into nameForDisplay the representation of that item as it would be shown in Windows Explorer or Mac OS Finder. For example, it will provide the localized string for "My Documents" even though, on disk, "My Documents" is always in English. It will also strip the extension if that is what Windows Explorer or the Mac Finder would do for that file.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The ASPathName associated with the file in question.

	`nameForDisplay` —	(Filled by the method) The text object containing the name used for display.

Returns

0 if the operation was successful, a non-zero platform-dependent error code otherwise.

Exceptions

fileErrGeneral

Since

PI_ACROSUPPORT_VERSION >= 0x00070000

File: ASProcs.h

Line: 2760

ASFileSysGetPlatformThing

()

Product availability: All

Platform availability: All

Syntax





void* ASFileSysGetPlatformThing(ASFileSys fileSys, ASPathName path, ASAtom thing)

Deprecated API: always returns NULL.

Parameters

	`fileSys`

	`path`

	`thing`

Returns

Since

PI_ASEXTRA_VERSION >= 0x00060000

File: ASProcs.h

Line: 2214

ASFileSysGetStorageFreeSpace

()

Product availability: All

Platform availability: All

Syntax





ASDiskSpace ASFileSysGetStorageFreeSpace(ASFileSys fileSys, ASPathName pathName)

Gets the amount of free space on the volume containing pathName.

Parameters

	`fileSys` —	IN/OUT (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

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

Returns

The amount of free space in bytes, 0 otherwise. Because the free space is returned as an ASUns32, it is limited to 4 GB.

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1781

ASFileSysGetStorageFreeSpace64

()

Product availability: All

Platform availability: All

Syntax





ASDiskSpace64 ASFileSysGetStorageFreeSpace64(ASFileSys fileSys, ASPathName pathName)

Gets the amount of free space on the volume containing pathName. This is the same as ASFileSysGetStorageFreeSpace() without the 4 GB limit.

Parameters

	`fileSys` —	IN/OUT (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	IN/OUT The ASPathName.

Returns

The amount of free space in bytes, 0 otherwise.

Since

PI_ACROSUPPORT_VERSION >= 0x00080000

File: ASProcs.h

Line: 2850

ASFileSysGetTempPathName

()

Product availability: All

Platform availability: All

Syntax





ASPathName ASFileSysGetTempPathName(ASFileSys fileSys, ASPathName siblingPathName)

Returns a unique path name suitable for use in creating temporary files. It is the caller's responsibility to release the returned object using ASFileSysReleasePath().

If siblingPath is non-NULL, the returned ASPathName is created at the same folder level as this path. Otherwise the standard temporary file location is used.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `siblingPath` was obtained. Pass `NULL` to use the default file system.

	`siblingPathName` —	(May be `NULL`) An ASPathName indicating the desired location of the temporary path name. The returned ASPathName is created at the same folder level as this path.

Returns

The ASPathName if the operation was successful, NULL otherwise.

See Also

ASFileSysReleasePath

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1767

ASFileSysGetTypeAndCreator

()

Product availability: All

Platform availability: All

Syntax





void ASFileSysGetTypeAndCreator(ASFileSys fileSys, ASPathName path, ASUns32* type, ASUns32* creator)

Gets the type and creator of the file specified by the path.

See Creators and Acrobat Types.

Parameters

	`fileSys` —	The file system containing the file for which the type and creator are needed.

	`path` —	The path name of the file.

	`type` —	(Filled by method) The type of the file.

	`creator` —	(Filled by method) The creator of the file.

See Also

ASFileSysSetTypeAndCreator

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1980

ASFileSysIsLocal

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileSysIsLocal(ASFileSys fileSys)

Returns true if fileSys is NULL, the default file system or the default Unicode file system.

Parameters

fileSys

Returns

true if fileSys is NULL or a local file system.

Since

PI_ACROSUPPORT_VERSION >= 0x00080000

File: ASProcs.h

Line: 2836

ASFileSysNextFolderItem

()

Product availability: All

Platform availability: All

Syntax





ASBool ASFileSysNextFolderItem(ASFileSys fileSys, ASFolderIterator folderIter, ASFileSysItemProps props, ASPathName* itemPath)

Continues the iteration process associated with the ASFolderIterator object.

Both itemPath and itemProps are optional, and may be NULL if you are not interested in that information.

Parameters

	`fileSys` —	(May be `NULL`) The file system with which the iteration was started. Pass `NULL` to use the default file system.

	`folderIter` —	An ASFolderIterator object returned from a previous call to ASFileSysFirstFolderItem().

	`props` —	(Filled by the method, may be `NULL`) A properties structure describing the next object in the iteration.

	`itemPath` —	(Filled by the method, may be `NULL`) An ASPathName, allocated by ASFileSysNextFolderItem(), which is associated with the object. The caller of ASFileSysNextFolderItem() must free the ASPathName. This parameter contains an absolute path on Windows and UNIX.

Returns

true if another object was found, false otherwise.

Exceptions

genErrBadParm
fileErrGeneral
ERR_NOMEMORY

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1661

ASFileSysOpenFile

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysOpenFile(ASFileSys fileSys, ASPathName pathName, ASFileMode mode, ASFile* fP)

Attempts to open a file in the specified file system, in the specified read/write/create mode. If the file is already open, the existing file handle is returned. The caller retains ownership of pathName.

This call returns an error if a file over 2 GB in length is opened. ASFileSysOpenFile64() should be used instead of this call wherever possible, and must be used if files over 2 GB in length may be encountered.

In Mac OS, when this method creates a file, the file's creator is set to 'CARO' and its type is set to 'PDF ' (with a space after PDF).

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The path name of the file to open.

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

	`fP` —	(Filled by the method) The ASFile that was opened.

Returns

0 if the operation was successful, a non-zero error code otherwise. The error is platform and file-system specific:

Platform

Error

Windows

Returns fileErrWrPerm if trying to open a read-only file with write permissions.
Returns ErrSysXtnMgr (use GetLastError()) for platform-specific error conditions that CreateFile() may use.

Mac OS

Returns fileErrFNF if trying to open a file for reading that does not exist.
Returns ErrSysMDSystem for platform-specific errors that FSpCreate, FSpSetFInfo, FSpOpenRF, FSpOpenDF, or SetFPos may use).

Exceptions

genErrNoError

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 841

ASFileSysOpenFile64

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysOpenFile64(ASFileSys fileSys, ASPathName pathName, ASFileMode mode, ASFile* fP)

This call can open files over 2 GB in length and should be used instead of ASFileSysOpenFile() whenever possible.

On Mac OS, when this method creates a file, the file's creator is set to 'CARO' and its type is set to 'PDF ' (with a space after PDF).

Parameters

	`fileSys` —	IN/OUT (May be `NULL`) The file system from which the path name was obtained. Pass `NULL` to use the default file system.

	`pathName` —	IN/OUT The path name of the file to open.

	`mode` —	IN/OUT An `OR` of the ASFile Open Modes.

	`fP` —	IN/OUT (Filled by the method) The ASFile that was opened.

Returns

0 if the operation was successful, a non-zero error code otherwise. The error is platform and file-system specific:

Platform

Error

Windows

Returns fileErrWrPerm if trying to open a read-only file with write permissions.
Returns ErrSysXtnMgr (use GetLastError()) for platform-specific error conditions that CreateFile() may use.
Returns fileErrGeneral if the developer passed in an invalid ASPathName.

Mac OS

Returns fileErrFNF if trying to open a file for reading that does not exist.
Returns ErrSysMDSystem for platform-specific errors that FSpCreate, FSpSetFInfo, FSpOpenRF, FSpOpenDF, or SetFPos may use).
Returns fileErrGeneral if the developer passed in an invalid ASPathName.

Exceptions

genErrNoError

Since

PI_ACROSUPPORT_VERSION >= 0x00070000

File: ASProcs.h

Line: 2656

ASFileSysPathFromDIPath

()

Product availability: All

Platform availability: All

Syntax





ASPathName ASFileSysPathFromDIPath(ASFileSys fileSys, const char* diPath, ASPathName relativeToThisPath)

Converts a device-independent path name to an ASPathName. This method can only be used for files that already exist (that is, it cannot be used to create a placeholder path name for files that a plug-in intends to create in the future).

It is the caller's responsibility to release the returned ASPathName.

Parameters

	`fileSys` —	(May be `NULL`) The file system within which the ASPathName will be created. Pass `NULL` to use the default file system.

	`diPath` —	The device-independent path name to convert. See Section 3.10 in the PDF Reference for a description of the device-independent path name format. This path name may not be understood on another platform since drive specifiers may be prepended. On Windows, you cannot specify a UNC path name. You must have a file mounted on the file server. For example, the following path is valid: `/f/dirname/file.pdf` where `f` is `\server\people`. The following does not work: `/server/people/dirname/file.pdf`.

	`relativeToThisPath` —	The path name relative to which `diPath` is interpreted. If it is `NULL`, `diPath` is interpreted as an absolute path name, not a relative path name.

Returns

An ASPathName corresponding to the parameter values supplied, NULL if diPath cannot be converted to an ASPathName or if the specified file does not already exist.

Exceptions

genErrNoMemory

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 761

ASFileSysPathFromDIPathEx

()

Product availability: All

Platform availability: All

Syntax





ASPathName ASFileSysPathFromDIPathEx(ASFileSys fileSys, ASConstText diPathText, ASPathName relativeToThisPath)

Converts a device-independent path name in an ASText object to an ASPathName. This method can only be used for files that already exist (that is, it cannot be used to create a placeholder path name for files that a plug-in intends to create in the future).

It is the caller's responsibility to release the returned ASPathName.

This method supersedes ASFileSysPathFromDIPath() in Acrobat 6.0 and later.

Parameters

	`fileSys` —	(May be `NULL`) The file system within which the ASPathName will be created. Pass `NULL` to use the default file system.

	`diPathText` —	The device-independent path name to convert, as an ASText object. See Section 3.10 in the PDF Reference for a description of the device-independent path name format. This path name may not be understood on another platform since drive specifiers may be prepended. On Windows, you cannot specify a UNC path name. You must have a file mounted on the file server. For example, the following path is valid: `/f/dirname/file.pdf` where `f` is `\server\people`. The following does not work: `/server/people/dirname/file.pdf`.

	`relativeToThisPath` —	A path name relative to which `diPath` is interpreted. If `NULL`, `diPath` is interpreted as an absolute path name, not a relative path name.

Returns

An ASPathName corresponding to the parameter values supplied. Returns NULL if diPath cannot be converted to an ASPathName. This would occur, for example, if the specified file does not already exist.

Exceptions

genErrNoMemory

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2557

ASFileSysPerformOpOnItem

()

Product availability: All

Platform availability: All

Syntax





ASInt32 ASFileSysPerformOpOnItem(ASFileSys fileSys, ASPathName pathName, const char* op, ASCab params)

Performs a specified operation on a particular file, passing specified parameters. It calls the performOpOnItem() procedure registered for the ASFileSysRec.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The ASPathName of the file.

	`op` —	The name of the operation to perform. A file system-defined string handled by ASFileSysPerformOpOnItemProc().

	`params` —	An ASCab object containing parameters to pass to the operation.

Returns

0 if the operation was successful, a nonzero platform-dependent error code otherwise.

See Also

ASFileSysCanPerformOpOnItem

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASExtraProcs.h

Line: 2307

ASFileSysReleasePath

()

Product availability: All

Platform availability: All

Syntax





void ASFileSysReleasePath(ASFileSys fileSys, ASPathName pathName)

Decrements the internal reference count for the path name and disposes of the path name (but not the file itself) if the reference count is zero. This does not result in any file-level operations, and is unaffected by whether there is an open file for this path name.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The ASPathName to release.

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 795

ASFileSysReleasePlatformPath

()

Product availability: All

Platform availability: All

Syntax





void ASFileSysReleasePlatformPath(ASFileSys fileSys, ASPlatformPath platformPath)

Releases the specified platform path object. Each call to ASFileSysAcquirePlatformPath() should have a corresponding call to this method.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`platformPath` —	The platform path object to release.

See Also

ASFileSysAcquirePlatformPath

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2275

ASFileSysRemoveFile

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysRemoveFile(ASFileSys fileSys, ASPathName pathName)

Attempts to delete the file referred to by pathName.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`pathName` —	The file to delete.

Returns

0 if the operation was successful, a non-zero platform-dependent error code otherwise.

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 858

ASFileSysRemoveFolder

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASFileSysRemoveFolder(ASFileSys fileSys, ASPathName path)

Deletes the folder at the specified pathName only if it is empty.

Parameters

	`fileSys` —	(May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system.

	`path` —	The path of the folder to remove.

Returns

0 if the operation was successful, a non-zero platform-dependent error code otherwise.

See Also

ASFileSysCreateFolder

Exceptions

genErrMethodNotImplemented

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1882

ASFileSysSetTypeAndCreator

()

Product availability: All

Platform availability: All

Syntax





void ASFileSysSetTypeAndCreator(ASFileSys fileSys, ASPathName path, ASUns32 type, ASUns32 creator)

Sets the type and creator of a file. See Type/Creator Codes.

Parameters

	`fileSys` —	IN/OUT The file system for which the type and creator are needed.

	`path` —	IN/OUT The path name of the file.

	`type` —	IN/OUT The type of the file.

	`creator` —	IN/OUT The creator of the file.

See Also

ASFileSysGetTypeAndCreator

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1960

ASFileSysURLFromPath

()

Product availability: All

Platform availability: All

Syntax





char* ASFileSysURLFromPath(ASFileSys fileSys, ASPathName path)

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

Parameters

	`fileSys` —	IN/OUT The file system from which `path` was obtained. Pass `NULL` to use the default file system.

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

Returns

A buffer containing the URL, or NULL if some error occurred. The URL is in the standard 'file://' URL style.

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 1838

ASGetDefaultFileSys

()

Product availability: All

Platform availability: All

Syntax





ASFileSys ASGetDefaultFileSys()

Gets the default standard file system implementation for a platform.

Returns

The platform's default file system.

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 692

ASGetDefaultFileSysForPath

()

Product availability: All

Platform availability: All

Syntax





ASFileSys ASGetDefaultFileSysForPath(ASAtom pathSpecType, const void* pathSpec)

Gets the best file system implementation that supports the passed in path. If the path requires the Unicode file system then the default Unicode file system is returned, otherwise the default file system is returned.

Parameters

	`pathSpecType`

	`pathSpec`

Returns

The platform's default or Unicode file system.

Since

PI_ACROSUPPORT_VERSION >= 0x00080000

File: ASProcs.h

Line: 2824

ASGetDefaultUnicodeFileSys

()

Product availability: All

Platform availability: All

Syntax





ASFileSys ASGetDefaultUnicodeFileSys()

Gets the file system implementation that supports Unicode file path names. If a platform does not have a file system that supports Unicode, then NULL will be returned.

Returns

The platform's Unicode file system.

See Also

ASGetDefaultFileSys

Since

PI_ACROSUPPORT_VERSION >= 0x00080000

File: ASProcs.h

Line: 2772

ASGetRamFileSys

()

Product availability: All

Platform availability: All

Syntax





ASFileSys ASGetRamFileSys()

Gets the in-memory file system implementation for a platform.

Returns

The platform's in-memory file system.

See Also

ASSetDefaultFileSys
ASSetTempFileSys

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2588

ASGetTempFileSys

()

Product availability: All

Platform availability: All

Syntax





ASFileSys ASGetTempFileSys()

Gets the temporary file system implementation for a platform.

Returns

The platform's default file system.

See Also

ASSetTempFileSys

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2567

ASPathFromPlatformPath

()

Product availability: All

Platform availability: All

Syntax





ASPathName ASPathFromPlatformPath(void* platformPath)

This method was deprecated in Acrobat 5.0. Use ASFileSysCreatePathName() instead.

It converts a platform-specific path name to an ASPathName. It can create an ASPathName from a file path where the file does not already exist. It works for Windows UNC path names as well. It is the caller's responsibility to release the returned ASPathName.

Parameters

platformPath —

A pointer to a platform-specific path name. On Windows and UNIX, it is a NULL-terminated string containing the full path name with the appropriate path separators for each platform.

Returns

The ASPathName corresponding to platformPath.

See Also

ASFileSysReleasePath

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 681

ASRamFileSysSetLimitKB

()

Product availability: All

Platform availability: All

Syntax





void ASRamFileSysSetLimitKB(ASInt32 limit)

Sets the temporary file system implementation for a platform.

Parameters

limit

See Also

ASGetRamFileSys

Since

PI_ACROSUPPORT_VERSION >= 0x00070000

File: ASProcs.h

Line: 2739

ASSetTempFileSys

()

Product availability: All

Platform availability: All

Syntax





void ASSetTempFileSys(ASFileSys fileSys)

Sets the temporary file system implementation for a platform.

Parameters

fileSys

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2578

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

	ASSize_t size;

	ASBool isThere;

	ASFileSysItemType type;

	ASBool isHidden;

	ASBool isReadOnly;

	ASBool creationDateKnown;

	ASTimeRec creationDate;

	ASBool modDateKnown;

	ASTimeRec modDate;

	ASByteCount fileSize;

	ASByteCount fileSizeHigh;

	ASTCount folderSize;

	ASUns32 creatorCode;

	ASUns32 typeCode;

	ASSize_t size;

	ASFileSysOpenProc open;

	ASFileSysCloseProc close;

	ASFileSysFlushProc flush;

	ASFileSysSetPosProc setpos;

	ASFileSysGetPosProc getpos;

	ASFileSysSetEofProc seteof;

	ASFileSysGetEofProc geteof;

	ASFileSysReadProc read;

	ASFileSysWriteProc write;

	ASFileSysRemoveProc remove;

	ASFileSysRenameProc rename;

	ASFileSysIsSameFileProc isSameFile;

	ASFileSysGetNameProc getName;

	ASFileSysGetTempPathNameProc getTempPathName;

	ASFileSysCopyPathNameProc copyPathName;

	ASFileSysDiPathFromPathProc diPathFromPath;

	ASFileSysPathFromDIPathProc pathFromDIPath;

	ASFileSysDisposePathNameProc disposePathName;

	ASFileSysGetFileSysNameProc getFileSysName;

	ASFileSysGetStorageFreeSpaceProc getStorageFreeSpace;

	ASFileSysFlushVolumeProc flushVolume;

	ASFileSysGetFileFlags getFileFlags;

	ASFileSysAsyncReadProc readAsync;

	ASFileSysAsyncWriteProc writeAsync;

	ASFileSysAsyncAbortProc abortAsync;

	ASFileSysYieldProc yield;

	ASFileSysMReadRequestProc mreadRequest;

	ASFileSysGetStatusProc getStatus;

	ASFileSysCreatePathNameProc createPathName;

	ASFileSysAcquireFileSysPathProc acquireFileSysPath;

	ASFileSysClearOutstandingMReadsProc clearOutstandingMReads;

	ASFileSysGetItemPropsProc getItemProps;

	ASFileSysFirstFolderItemProc firstFolderItem;

	ASFileSysNextFolderItemProc nextFolderItem;

	ASFileSysDestroyFolderIteratorProc destroyFolderIterator;

	ASFileSysSetModeProc setFileMode;

	ASFileSysURLFromPathProc urlFromPath;

	ASFileSysGetParentProc getParent;

	ASFileSysCreateFolderProc createFolder;

	ASFileSysRemoveFolderProc removeFolder;

	ASFileSysDisplayStringFromPathProc displayStringFromPath;

	ASFileSysSetTypeAndCreatorProc setTypeAndCreator;

	ASFileSysGetTypeAndCreatorProc getTypeAndCreator;

	ASFileSysReopenProc reopen;

	ASFileSysHardFlushProc hardFlush;

	ASFileSysGetPlatformThingProc getPlatformThing;

	ASFileSysGetItemPropsAsCabProc getItemPropsAsCab;

	ASFileSysCanPerformOpOnItemProc canPerformOpOnItem;

	ASFileSysPerformOpOnItemProc performOpOnItem;

	ASFileSysAcquirePlatformPathProc acquirePlatformPath;

	ASFileSysReleasePlatformPathProc releasePlatformPath;

	ASFileSysGetNameAsASTextProc getNameAsASText;

	ASFileSysDisplayASTextFromPathProc displayASTextFromPath;

	ASFileSysRangeArrivedProc rangeArrived;

	ASFileSysCanSetEofProc canSetEof;

	ASFileSysDIPathFromPathExProc diPathFromPathEx;

	ASFileSysPathFromDIPathExProc pathFromDIPathEx;

	ASFileSysGetFilePositionLimitProc getfileposlimit;

	ASFileSysOpen64Proc open64;

	ASFileSysSetPos64Proc setpos64;

	ASFileSysGetPos64Proc getpos64;

	ASFileSysSetEof64Proc seteof64;

	ASFileSysGetEof64Proc geteof64;

	ASFileSysGetNameForDisplayProc getNameForDisplay;

	ASFileSysGetStorageFreeSpace64Proc getStorageFreeSpace64;

	ASFileSysIsInUseProc isInUse;

	ASMDFile mdFile;

	void* ptr;

	ASTFilePos offset;

	ASTArraySize count;

	ASTArraySize totalBytesCompleted;

	ASErrorCode pError;

	void* clientData;

	ASIODoneProc IODoneProc;

	void* IODoneProcData;

	kASFileSysFile,

	kASFileSysFolder,

	kASFileSysUnknown = -1

Layer	AS_Layer
Object	ASFileSys