PD_Layer.PDFileSpec (Acrobat)

	Typedef
	PDFileSpec The PDF file specification object. It is used to specify a file in an action (see PDAction). A file specification in a PDF file can take two forms:
	PDFileSpecHandler
	PDFileSpecHandlerRec

	Structure
	_t_PDFileSpecHandler A data structure that implements a file specification handler. It contains callbacks that implement the file specification handler's functions (converting from a file specification to an ASPathName, creating a new file specification from an ASPathName, and launching the specified file).

	Callback
	PDFileSpecAcquireASPathProc A callback for PDFileSpecHandler. It aquires the ASPath corresponding to a file specification.
	PDFileSpecNewFromASPathProc A callback for PDFileSpecHandler. It creates a file specification from an ASPath.

	Method
	ASPathName PDFileSpecAcquireASPath(PDFileSpec fileSpec, ASPathName relativeToThisPath) Acquires an ASPathName for the specified file specification and relative path.
	ASPathName PDFileSpecAcquireASPathEx(PDFileSpec fileSpec, ASFileSys relPathFileSys, ASPathName relativeToThisPath, ASFileSys* retFileSys, ASBool pathMustExist) Acquires an ASPathName for the specified file specification and relative path.
	PDFileSpec PDFileSpecFromCosObj(CosObj obj) Converts an appropriate string or dictionary Cos object to a file specification. This method does not copy the object, but is instead the logical equivalent of a type cast.
	CosObj PDFileSpecGetCosObj(PDFileSpec fileSpec) Gets the Cos object associated with a file specification. This method does not copy the object, but is instead the logical equivalent of a type cast.
	ASInt32 PDFileSpecGetDIPath(PDFileSpec fileSpec, char* buffer, ASInt32 bufLen) Gets the device-independent path name from a file specification.
	void PDFileSpecGetDIPathEx(PDFileSpec fileSpec, ASText diPath) Gets the device-independent path name from a file specification.
	PDDoc PDFileSpecGetDoc(PDFileSpec fileSpec) Gets the PDDoc that contains fileSpec.
	ASFileSys PDFileSpecGetFileSys(PDFileSpec fileSpec) Gets the file system that services the specified file specification.
	ASAtom PDFileSpecGetFileSysName(PDFileSpec fileSpec) Gets the name of the file system that a PDFileSpec belongs to. For a simple fileSpec (string form), the name of the file system is the name of the document's file system if the CosObj that is the fileSpec is contained in a document. For a complex fileSpec (dictionary form) with an FS key, the name of the file system is the atom associated with the FS key.
	ASBool PDFileSpecIsValid(PDFileSpec fileSpec) Tests whether a file specification is valid. This is intended only to ensure that the file specification has not been deleted, not to ensure that all necessary information is present and valid.
	PDFileSpec PDFileSpecNewFromASPath(PDDoc pdDoc, ASFileSys fileSys, ASPathName path, ASPathName relativeToThisPath) Creates a new file specification from the specified ASPathName, using the PDFileSpecNewFromASPathProc() of the specified file system's file specification handler.
	PDFileSpec PDFileSpecNewFromASPathEx(PDDoc pdDoc, ASFileSys fileSys, ASPathName path, ASFileSys relPathFileSys, ASPathName relativeToThisPath) Creates a new file specification from the specified ASPathName, using the PDFileSpecNewFromASPathProc() of the specified file system's file specification handler.

Typedefs Detail

PDFileSpec

Product availability: All

Platform availability: All

Syntax

typedef OPAQUE_64_BITS PDFileSpec;

The PDF file specification object. It is used to specify a file in an action (see PDAction). A file specification in a PDF file can take two forms:

A single platform-independent path.
A data structure containing one or more alternative ways to locate the file on different platforms.

PDFileSpec objects can be created from ASPathName objects or from Cos objects.

File: PDExpT.h

Line: 1119

PDFileSpecHandler

Product availability: All

Platform availability: All

Syntax

typedef _t_PDFileSpecHandler PDFileSpecHandler;

File: PDExpT.h

Line: 1194

PDFileSpecHandlerRec

Product availability: All

Platform availability: All

Syntax

typedef _t_PDFileSpecHandler PDFileSpecHandlerRec;

File: PDExpT.h

Line: 1194

Structure Detail

_t_PDFileSpecHandler

Product availability: All

Platform availability: All

Syntax

struct _t_PDFileSpecHandler {

  ASSize_t size;  


 


  PDFileSpecNewFromASPathProc NewFromASPath;  


 


  PDFileSpecAcquireASPathProc AcquireASPath;  


 


  PDLaunchActionProc LaunchAction;  


 


  ASFileSys fileSys;  

}

A data structure that implements a file specification handler. It contains callbacks that implement the file specification handler's functions (converting from a file specification to an ASPathName, creating a new file specification from an ASPathName, and launching the specified file).

See Also

PDRegisterFileSpecHandlerByName

File: PDExpT.h

Line: 1179

Elements

	size	Must be `sizeof(PDFileSpecHandlerRec)`.

	fileSys	The file system that is to be used with this file specification handler.

Callbacks Detail

PDFileSpecAcquireASPathProc

Product availability: All

Platform availability: All

Syntax

ASPathName (*PDFileSpecAcquireASPathProc)(void *fileSpecHandlerObj, PDFileSpec fileSpec, ASPathName relativeToThisPath)

A callback for PDFileSpecHandler. It aquires the ASPath corresponding to a file specification.

See Also

PDFileSpecAcquireASPath

File: PDExpT.h

Line: 1158

PDFileSpecNewFromASPathProc

Product availability: All

Platform availability: All

Syntax

PDFileSpec (*PDFileSpecNewFromASPathProc)(void *fileSpecHandlerObj, PDDoc pdDoc, ASPathName path, ASPathName relativeToThisPath)

A callback for PDFileSpecHandler. It creates a file specification from an ASPath.

See Also

PDFileSpecNewFromASPath

File: PDExpT.h

Line: 1143

Method Detail

PDFileSpecAcquireASPath

()

Product availability: All

Platform availability: All

Syntax





ASPathName PDFileSpecAcquireASPath(PDFileSpec fileSpec, ASPathName relativeToThisPath)

Acquires an ASPathName for the specified file specification and relative path.

Parameters

	`fileSpec` —	IN/OUT The file specification for which an ASPathName is acquired.

	`relativeToThisPath` —	IN/OUT A path name relative to which the `fileSpec` is interpreted. If it is `NULL`, `fileSpec` is assumed to be an absolute, not a relative, path.

Returns

The ASPathName corresponding to fileSpec.

After you are done using the ASPathName, you must free it using ASFileSysReleasePath().

See Also

ASFileSysReleasePath

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 5186

PDFileSpecAcquireASPathEx

()

Product availability: All

Platform availability: All

Syntax





ASPathName PDFileSpecAcquireASPathEx(PDFileSpec fileSpec, ASFileSys relPathFileSys, ASPathName relativeToThisPath, ASFileSys* retFileSys, ASBool pathMustExist)

Acquires an ASPathName for the specified file specification and relative path.

Parameters

	`fileSpec` —	IN/OUT The file specification for which an ASPathName is acquired.

	`relPathFileSys` —	The file system that owns `relativeToThisPath`.

	`relativeToThisPath` —	IN/OUT A path name relative to which the `fileSpec` is interpreted. If it is `NULL`, `fileSpec` is assumed to be an absolute, not a relative, path. If it is not `NULL` and `fileSys` and `relPathFileSys` are not the same, then an attempt is made to fabricate a `relPathName` in terms of `fileSys`, and if that is not possible, `NULL` is used.

	`retFileSys` —	IN/OUT The file system that owns the returned ASPathName.

	`pathMustExist` —	IN/OUT If it is `true` and the result ASPathName does not exist, then the return value is `NULL`.

Returns

The ASPathName corresponding to fileSpec.

After you are done using the ASPathName, you must free it using ASFileSysReleasePath().

See Also

ASFileSysReleasePath

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h

Line: 11278

PDFileSpecFromCosObj

()

Product availability: All

Platform availability: All

Syntax





PDFileSpec PDFileSpecFromCosObj(CosObj obj)

Converts an appropriate string or dictionary Cos object to a file specification. This method does not copy the object, but is instead the logical equivalent of a type cast.

Parameters

obj —

IN/OUT The Cos object to convert to a file specification.

Returns

The file specification corresponding to obj.

See Also

PDFileSpecGetCosObj
PDFileSpecIsValid

Exceptions

pdErrBadFileSpec is raised if the file specification is not valid, as determined by PDFileSpecIsValid().

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 5155

PDFileSpecGetCosObj

()

Product availability: All

Platform availability: All

Syntax





CosObj PDFileSpecGetCosObj(PDFileSpec fileSpec)

Gets the Cos object associated with a file specification. This method does not copy the object, but is instead the logical equivalent of a type cast.

Parameters

fileSpec —

IN/OUT The file specification whose Cos object is obtained.

Returns

The string or dictionary Cos object corresponding to the file specification.

See Also

PDFileSpecFromCosObj

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 5200

PDFileSpecGetDIPath

()

Product availability: All

Platform availability: All

Syntax





ASInt32 PDFileSpecGetDIPath(PDFileSpec fileSpec, char* buffer, ASInt32 bufLen)

Gets the device-independent path name from a file specification.

Parameters

	`fileSpec` —	IN/OUT The file specification whose device-independent path name is obtained.

	`buffer` —	IN/OUT (Filled by the method) `NULL`-terminated device- independent path name. If `buffer` is `NULL`, the method simply returns the length of the path name.

	`bufLen` —	IN/OUT The length of `buffer` in bytes. If the device- independent path name is longer than this, only the first `bufLen - 1` bytes are copied into `buffer`, plus a `NULL` at the end of the buffer.

Returns

The number of characters (excluding the NULL) copied into buffer.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 5258

PDFileSpecGetDIPathEx

()

Product availability: All

Platform availability: All

Syntax





void PDFileSpecGetDIPathEx(PDFileSpec fileSpec, ASText diPath)

Gets the device-independent path name from a file specification.

Parameters

	`fileSpec` —	IN The file specification whose device-independent path name is obtained.

	`diPath` —	IN/OUT An existing ASText object whose content is set to the path name obtained from from `fileSpec`.

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h

Line: 11291

PDFileSpecGetDoc

()

Product availability: All

Platform availability: All

Syntax





PDDoc PDFileSpecGetDoc(PDFileSpec fileSpec)

Gets the PDDoc that contains fileSpec.

Parameters

fileSpec —

IN/OUT A PDFileSpec in a document.

Returns

A PDDoc or NULL if the file specification CosObj is not in a document.

Since

PI_PDMODEL_VERSION >= 0x00020002

File: PDProcs.h

Line: 5476

PDFileSpecGetFileSys

()

Product availability: All

Platform availability: All

Syntax





ASFileSys PDFileSpecGetFileSys(PDFileSpec fileSpec)

Gets the file system that services the specified file specification.

Parameters

fileSpec —

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

Returns

The file system that services fileSpec.

See Also

PDFileSpecGetFileSysName

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 5167

PDFileSpecGetFileSysName

()

Product availability: All

Platform availability: All

Syntax





ASAtom PDFileSpecGetFileSysName(PDFileSpec fileSpec)

Gets the name of the file system that a PDFileSpec belongs to. For a simple fileSpec (string form), the name of the file system is the name of the document's file system if the CosObj that is the fileSpec is contained in a document. For a complex fileSpec (dictionary form) with an FS key, the name of the file system is the atom associated with the FS key.

The file system returned by PDFileSpecGetFileSys() is the file system that has registered a PDFileSpecHandler() for the file specification's file system name (if there is one), and is not necessarily the same as ASFileGetFileSysByName(PDFileSpecGetFileSysName(fileSpec)); .

Parameters

fileSpec —

A PDFileSpec.

Returns

An ASAtom representing the file system of fileSpec.

See Also

PDFileSpecGetFileSys

Since

PI_PDMODEL_VERSION >= 0x00020002

File: PDProcs.h

Line: 5496

PDFileSpecIsValid

()

Product availability: All

Platform availability: All

Syntax





ASBool PDFileSpecIsValid(PDFileSpec fileSpec)

Tests whether a file specification is valid. This is intended only to ensure that the file specification has not been deleted, not to ensure that all necessary information is present and valid.

Parameters

fileSpec —

The file specification whose validity is tested.

Returns

true if fileSpec is valid, false otherwise.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 5212

PDFileSpecNewFromASPath

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDFileSpec PDFileSpecNewFromASPath(PDDoc pdDoc, ASFileSys fileSys, ASPathName path, ASPathName relativeToThisPath)

Creates a new file specification from the specified ASPathName, using the PDFileSpecNewFromASPathProc() of the specified file system's file specification handler.

Parameters

	`pdDoc` —	The document in which the new file specification will be used.

	`fileSys` —	A pointer to an ASFileSysRec specifying the file system responsible for the newly created file specification.

	`path` —	The path to convert into a file specification.

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

Returns

The newly created file spec, or an invalid file spec if the ASPathName cannot be converted to a PDFileSpec (use PDFileSpecIsValid() to test whether the conversion was successful).

See Also

PDFileSpecIsValid

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 5139

PDFileSpecNewFromASPathEx

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDFileSpec PDFileSpecNewFromASPathEx(PDDoc pdDoc, ASFileSys fileSys, ASPathName path, ASFileSys relPathFileSys, ASPathName relativeToThisPath)

Creates a new file specification from the specified ASPathName, using the PDFileSpecNewFromASPathProc() of the specified file system's file specification handler.

Parameters

	`pdDoc` —	The document in which the new file specification will be used.

	`fileSys` —	A pointer to an ASFileSysRec specifying the file system responsible for the newly created file specification.

	`path` —	The path to convert into a file specification.

	`relPathFileSys` —	The file system that owns `relativeToThisPath`.

	`relativeToThisPath` —	A path name relative to which the `fileSpec` is interpreted. If it is `NULL`, `fileSpec` is assumed to be an absolute, not a relative, path. If it is not `NULL` and `fileSys` and `relPathFileSys` are not the same, then an attempt is made to fabricate a `relPathName` in terms of `fileSys`, and if that is not possible, `NULL` is used.

Returns

The newly created file specification, or an invalid file specification if the ASPathName cannot be converted to a PDFileSpec (use PDFileSpecIsValid() to test whether the conversion was successful).

See Also

PDFileSpecIsValid

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h

Line: 11252

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

	ASSize_t size;

	PDFileSpecNewFromASPathProc NewFromASPath;

	PDFileSpecAcquireASPathProc AcquireASPath;

	PDLaunchActionProc LaunchAction;

	ASFileSys fileSys;

Layer	PD_Layer
Object	PDFileSpec