AS_Layer.HFT_and_HFT_Server (Acrobat)

	Define
	ASExtensionMgrGetHFT
	HFTCallReplacedEntry
	HFTEntryReplaceable A flag that specifies whether an HFT entry is replaceable: If the flag is set, the new entry can be replaced. Clients should generally use this value, allowing other clients to subsequently replace the method again. If the flag is not set, the new entry cannot be replaced.
	HFT_ERROR_NO_VERSION
	kHFT_IN_BETA_FLAG

	Typedef
	HFT An object that describes a set of exported functions. It is an array of function pointers, where the first element is unused.
	HFTData
	HFTDataRec
	HFTEntry An HFTEntry may be cast to a pointer to a function whose prototype must be provided by the HFT's description file.
	HFTLocations
	HFTServer Each HFT is serviced by an HFT server. The HFT server is responsible for handling requests to obtain or destroy its HFT. An HFTServer is an object that manages several versions of an HFT for different clients which may have been compiled with different versions of the HFT's API.

	Structure
	_t_HFTData A data structure to pass to an HFT server to create a new HFT. New in Acrobat 6.0.
	_t_HFTLocations

	Callback
	HFTServerDestroyProc A callback for an HFT server. This destroys the specified HFT (for example, by calling HFTServerDestroy()).
	HFTServerProvideHFTProc A callback for an HFT server. This returns an HFT with the specified version number. If the HFT has not yet been created, create and return it. If the HFT already exists, do not create a new copy of it; simply return the existing copy.

	Method
	HFT ASExtensionMgrGetHFT(ASAtom name, ASVersion version) Gets the specified version of the Host Function Table (HFT) that has the specified name. If you want to get one of the Acrobat viewer's built-in HFTs, use the predefined global variables for the HFT Values instead of this method.
	void HFTDestroy(HFT hft) Destroys an existing HFT by freeing all the HFT's memory. Call this method only if you are absolutely sure that neither your plug-in nor any other plug-in will use the HFT again. Because this is usually impossible to know, plug-ins should not destroy HFTs. It is even dangerous to destroy an HFT at unload time, because the order in which plug-ins are unloaded is not specified.
	HFTEntry HFTGetReplacedEntry(HFT hft, Selector sel, HFTEntry oldEntry) Gets the HFTEntry that was replaced by the specified HFTEntry in the specified entry. Plug-ins should generally not use this method directly, but use the CALL_REPLACED_PROC macro instead.
	ASVersion HFTGetVersion(HFT hft) Returns the version of the HFT, if available.
	ASBool HFTIsValid(HFT hft) Tests whether an HFT is valid.
	HFT HFTNew(HFTServer hftServer, ASTCount numSelectors) Obsolete. See HFTNewEx(). Creates a new HFT by calling the specified HFT server's HFTServerProvideHFTProc().
	HFT HFTNewEx(HFTServer hftServer, HFTData data) Extends HFTNew() with version information in Acrobat 6. Creates a new HFT by calling the specified HFT server's HFTServerProvideHFTProc().
	void HFTReplaceEntry(HFT hft, Selector sel, HFTEntry newEntry, ASFlagBits flags) Replaces the specified entry in the specified HFT. This allows a plug-in to override and replace certain methods in Acrobat's API. See Replaceable Methods for a list of replaceable methods. This method can be used from anywhere in the plug-in, but it makes the most sense for most plug-ins to replace methods in the importReplaceAndRegisterCallback() procedure. Plug-ins register their HFTs in the export callback, but the code to populate the function table is only executed when the first client requests the HFT.
	void HFTReplaceEntryEx(HFT hft, Selector sel, HFTEntry newEntry, ASExtension extension, ASFlagBits flags) A new version of HFTReplaceEntry() that adds the extension argument.
	void HFTServerDestroy(HFTServer hftServer) Destroys an HFT server. Call this method only if the HFT will not be used again.
	HFTServer HFTServerNew(const char* name, HFTServerProvideHFTProc serverProc, HFTServerDestroyProc destroyProc, void* clientData) Creates a new Host Function Table (HFT) server. An HFT server is responsible for creating an instance of an HFT with the specified version number, and destroying the HFT.
	void HFTUnreplaceEntry(HFT hft, Selector sel, HFTEntry oldEntry, ASExtension extension) Removes the oldEntry item from hft at sel if the extension fields match. It allows HFT replacements to be undone in cases such as with the DigSig plug-in, which replaces a method that Acrobat could use after DigSig unloads.

Defines Detail

ASExtensionMgrGetHFT

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax


#define ASExtensionMgrGetHFT ASGetHFTByNameAndVersion

File: CorCalls.h

Line: 356

HFT_ERROR_NO_VERSION

Product availability: All

Platform availability: All

Syntax


#define HFT_ERROR_NO_VERSION (0xFFFFFFFF)

File: ASExpT.h

Line: 559

HFTCallReplacedEntry

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define HFTCallReplacedEntry (*((sel##PROTO)(HFTGetReplacedEntry((hft), sel, (oldProc)))))

File: ASCalls.h

Line: 524

HFTEntryReplaceable

Product availability: All

Platform availability: All

Syntax


#define HFTEntryReplaceable (0x00000001)

Description

A flag that specifies whether an HFT entry is replaceable:

If the flag is set, the new entry can be replaced. Clients should generally use this value, allowing other clients to subsequently replace the method again.
If the flag is not set, the new entry cannot be replaced.

See Also

HFTReplaceEntry

File: CoreExpT.h

Line: 177

kHFT_IN_BETA_FLAG

Product availability: All

Platform availability: All

Syntax


#define kHFT_IN_BETA_FLAG 0x80000000

File: CoreExpT.h

Line: 164

Typedefs Detail

HFT

Product availability: All

Platform availability: All

Syntax

typedef HFTEntry HFT;

An object that describes a set of exported functions. It is an array of function pointers, where the first element is unused.

File: CoreExpT.h

Line: 161

HFTData

Product availability: All

Platform availability: All

Syntax

typedef HFTDataRec HFTData;

File: ASExpT.h

Line: 581

HFTDataRec

Product availability: All

Platform availability: All

Syntax

typedef _t_HFTData HFTDataRec;

File: ASExpT.h

Line: 580

HFTEntry

Product availability: All

Platform availability: All

Syntax

typedef void* HFTEntry;

An HFTEntry may be cast to a pointer to a function whose prototype must be provided by the HFT's description file.

File: CoreExpT.h

Line: 150

HFTLocations

Product availability: All

Platform availability: All

Syntax

typedef _t_HFTLocations HFTLocations;

File: PDFLInitHFT.h

Line: 86

HFTServer

Product availability: All

Platform availability: All

Syntax

typedef struct _t_HFTServer* HFTServer;

Each HFT is serviced by an HFT server. The HFT server is responsible for handling requests to obtain or destroy its HFT. An HFTServer is an object that manages several versions of an HFT for different clients which may have been compiled with different versions of the HFT's API.

See Also

HFTServerNew
HFTServerDestroy

File: ASExpT.h

Line: 589

Structure Detail

_t_HFTData

Product availability: All

Platform availability: All

Syntax

struct _t_HFTData {

  ASUns32 size;  


 


  ASCount numSelectors;  


 


  ASVersion version;  


 


  const void* hftProcs;  

}

A data structure to pass to an HFT server to create a new HFT. New in Acrobat 6.0.

See Also

HFTNewEx

File: ASExpT.h

Line: 567

Elements

	size	Set to `sizeof(HFTDataRec)`

	numSelectors	The number of entries in the new HFT. This determines the number of methods that the HFT can contain; each method occupies one entry.

	version	The version number.

	hftProcs	Optional. This should point to an HFT array of function pointers.

_t_HFTLocations

Product availability: All

Platform availability: All

Syntax

struct _t_HFTLocations {

  ASUns8 dummy;  

}

File: PDFLInitHFT.h

Line: 36

Callbacks Detail

HFTServerDestroyProc

Product availability: All

Platform availability: All

Syntax

void (*HFTServerDestroyProc)(HFTServer hftServer, void *rock)

A callback for an HFT server. This destroys the specified HFT (for example, by calling HFTServerDestroy()).

See Also

HFTServerNew
HFTDestroy

File: ASExpT.h

Line: 616

HFTServerProvideHFTProc

Product availability: All

Platform availability: All

Syntax

HFT (*HFTServerProvideHFTProc)(HFTServer hftServer, ASVersion version, void *rock)

A callback for an HFT server. This returns an HFT with the specified version number. If the HFT has not yet been created, create and return it. If the HFT already exists, do not create a new copy of it; simply return the existing copy.

See Also

HFTServerNew

File: ASExpT.h

Line: 606

Method Detail

ASExtensionMgrGetHFT

()

Product availability: All

Platform availability: All

Syntax





HFT ASExtensionMgrGetHFT(ASAtom name, ASVersion version)

Gets the specified version of the Host Function Table (HFT) that has the specified name. If you want to get one of the Acrobat viewer's built-in HFTs, use the predefined global variables for the HFT Values instead of this method.

Parameters

	`name` —	The name of the HFT to obtain.

	`version` —	The version number of the HFT to obtain.

Returns

The specified HFT, or NULL if the HFT does not exist.

See Also

HFTReplaceEntry
HFTReplaceEntryEx

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: CorProcs.h

Line: 218

HFTDestroy

()

Product availability: All

Platform availability: All

Syntax





void HFTDestroy(HFT hft)

Destroys an existing HFT by freeing all the HFT's memory. Call this method only if you are absolutely sure that neither your plug-in nor any other plug-in will use the HFT again. Because this is usually impossible to know, plug-ins should not destroy HFTs. It is even dangerous to destroy an HFT at unload time, because the order in which plug-ins are unloaded is not specified.

Parameters

hft —

The HFT to destroy.

See Also

HFTNew

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 235

HFTGetReplacedEntry

()

Product availability: All

Platform availability: All

Syntax





HFTEntry HFTGetReplacedEntry(HFT hft, Selector sel, HFTEntry oldEntry)

Gets the HFTEntry that was replaced by the specified HFTEntry in the specified entry. Plug-ins should generally not use this method directly, but use the CALL_REPLACED_PROC macro instead.

It is necessary to specify both a selector (the index of an entry in the HFT's table of callback pointers) and an HFTEntry (a callback pointer) because a method may be replaced several times, and the various replacement methods are kept in a linked list. The selector determines which linked list is examined, and the HFTEntry determines the entry in the linked list to return.

Parameters

	`hft` —	The HFT in which a replaced entry is retrieved. See HFTReplaceEntry() for more information.

	`sel` —	The selector whose previous value is obtained. See HFTReplaceEntry() for more information.

	`oldEntry` —	The HFTEntry for which the previous value is obtained.

Returns

The entry present prior to being replaced. NULL is returned if the entry has not been replaced.

See Also

ASExtensionMgrGetHFT
CALL_REPLACED_PROC

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 309

HFTGetVersion

()

Product availability: All

Platform availability: All

Syntax





ASVersion HFTGetVersion(HFT hft)

Returns the version of the HFT, if available.

Parameters

hft —

The HFT whose version is obtained.

Returns

The version number if the HFT is valid and the version is available, HFT_ERROR_NO_VERSION otherwise.

See Also

HFTNewEx

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2469

HFTIsValid

()

Product availability: All

Platform availability: All

Syntax





ASBool HFTIsValid(HFT hft)

Tests whether an HFT is valid.

Parameters

hft —

IN/OUT The HFT to test.

Returns

true if hft is valid, false otherwise.

Since

PI_ACROSUPPORT_VERSION >= 0x00040000

File: ASProcs.h

Line: 1555

HFTNew

()

Product availability: All

Platform availability: All

Syntax





HFT HFTNew(HFTServer hftServer, ASTCount numSelectors)

Obsolete. See HFTNewEx(). Creates a new HFT by calling the specified HFT server's HFTServerProvideHFTProc().

Parameters

	`hftServer` —	The HFT server for the HFT being created. The HFT server must have been created previously using HFTServerNew().

	`numSelectors` —	The number of entries in the new HFT. This determines the number of methods that the HFT can contain; each method occupies one entry.

Returns

The newly created HFT.

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 221

HFTNewEx

()

Product availability: All

Platform availability: All

Syntax





HFT HFTNewEx(HFTServer hftServer, HFTData data)

Extends HFTNew() with version information in Acrobat 6. Creates a new HFT by calling the specified HFT server's HFTServerProvideHFTProc().

Parameters

hftServer —

The HFT server for the HFT being created. The HFT server must have been created previously using HFTServerNew().

data —

The data to pass to the server, which includes:

The number of entries in the new HFT, which determines the number of methods that the HFT can contain. Each method occupies one entry.
The HFT version.

Returns

The newly created HFT.

See Also

HFTNew
ASExtensionMgrGetHFT
HFTDestroy

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2494

HFTReplaceEntry

()

Product availability: All

Platform availability: All

Syntax





void HFTReplaceEntry(HFT hft, Selector sel, HFTEntry newEntry, ASFlagBits flags)

Replaces the specified entry in the specified HFT. This allows a plug-in to override and replace certain methods in Acrobat's API. See Replaceable Methods for a list of replaceable methods. This method can be used from anywhere in the plug-in, but it makes the most sense for most plug-ins to replace methods in the importReplaceAndRegisterCallback() procedure. Plug-ins register their HFTs in the export callback, but the code to populate the function table is only executed when the first client requests the HFT.

Plug-ins can use the REPLACE macro instead of calling HFTReplaceEntry() directly.

All plug-ins, and Acrobat itself, share a single copy of each HFT. As a result, when a plug-in replaces the implementation of a method, all other plug-ins and Acrobat also use the new implementation of that method. In addition, once a method's implementation has been replaced, there is no way to remove the new implementation without restarting Acrobat.

Parameters

	`hft` —	The HFT in which a method is replaced. Use ASExtensionMgrGetHFT() to get the HFT, given its name. For the HFTs built into the Acrobat viewer, global variables containing the HFTs have been defined, so you can skip calling ASExtensionMgrGetHFT() for these HFTs.

	`sel` —	The entry in the HFT to replace, derived from the method's name by appending `SEL`. For example, to replace AVAlert, `sel` must be `AVAlertSEL`.

	`newEntry` —	The function to replace the current one. The function pointer must be converted to an HFTEntry using the ASCallbackCreateReplacement() macro.

	`flags` —	The new entry's properties. Currently, only HFTEntryReplaceable is defined.

Exceptions

xmErrCannotReplaceSelector

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 282

HFTReplaceEntryEx

()

Product availability: All

Platform availability: All

Syntax





void HFTReplaceEntryEx(HFT hft, Selector sel, HFTEntry newEntry, ASExtension extension, ASFlagBits flags)

A new version of HFTReplaceEntry() that adds the extension argument.

Plug-ins can use the REPLACE macro instead of calling HFTReplaceEntryEx directly.

Parameters

	`hft` —	The HFT in which a method is replaced. Use ASExtensionMgrGetHFT() to get the HFT, given its name. For the HFTs built into the Acrobat viewer, global variables containing the HFTs have been defined, so you can skip calling ASExtensionMgrGetHFT() for these HFTs.

	`sel` —	The entry in the HFT to replace, derived from the method's name by appending `SEL`. For example, to replace AVAlert, `sel` must be `AVAlertSEL`.

	`newEntry` —	The function to replace the current one. The function pointer must be converted to an HFTEntry using the ASCallbackCreateReplacement() macro.

	`extension` —	Plug-ins should pass in `gExtensionID` for this parameter (see the code for the Acrobat 5.0 version of the REPLACE macro). This parameter is stored by Acrobat so that any entries that were replaced by a plug-in can be unreplaced in the event that the plug-in unloads.

	`flags` —	The new entry's properties. Currently, only `HFTEntryReplaceable` is defined.

Exceptions

xmErrCannotReplaceSelector

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 2071

HFTServerDestroy

()

Product availability: All

Platform availability: All

Syntax





void HFTServerDestroy(HFTServer hftServer)

Destroys an HFT server. Call this method only if the HFT will not be used again.

Parameters

hftServer —

IN/OUT The HFT server to destroy.

See Also

HFTServerNew

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 203

HFTServerNew

()

Product availability: All

Platform availability: All

Syntax





HFTServer HFTServerNew(const char* name, HFTServerProvideHFTProc serverProc, HFTServerDestroyProc destroyProc, void* clientData)

Creates a new Host Function Table (HFT) server. An HFT server is responsible for creating an instance of an HFT with the specified version number, and destroying the HFT.

Parameters

	`name` —	The new HFT server's name.

	`serverProc` —	(Required) A user-supplied callback that provides an HFT when given a version number. This procedure is called by ASExtensionMgrGetHFT() when another plug-in imports the HFT.

	`destroyProc` —	(Optional) A user-supplied callback that destroys the specified HFT (this generally means deallocating the memory associated with the HFT). This procedure is called by HFTDestroy().

	`clientData` —	A pointer to user-supplied data to pass to the HFT server.

Returns

The newly created HFT server.

See Also

HFTServerDestroy
HFTNewEx

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 193

HFTUnreplaceEntry

()

Product availability: All

Platform availability: All

Syntax





void HFTUnreplaceEntry(HFT hft, Selector sel, HFTEntry oldEntry, ASExtension extension)

Removes the oldEntry item from hft at sel if the extension fields match. It allows HFT replacements to be undone in cases such as with the DigSig plug-in, which replaces a method that Acrobat could use after DigSig unloads.

Parameters

	`hft` —	The HFT in which a method is un-replaced. Use ASExtensionMgrGetHFT() to get the HFT, given its name. For the HFTs built into the Acrobat viewer, global variables containing the HFTs have been defined, so you can skip calling ASExtensionMgrGetHFT() for these HFTs.

	`sel` —	The entry in the HFT to un-replace, derived from the method's name by appending `SEL`. For example, to replace AVAlert, `sel` must be `AVAlertSEL`.

	`oldEntry` —	The old function to be replaced. The function pointer must be converted to an HFTEntry using the ASCallbackCreateReplacement() macro.

	`extension` —	An object of type ASExtension.

Since

PI_ACROSUPPORT_VERSION >= 0x00050000

File: ASProcs.h

Line: 2098

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

	ASUns32 size;

	ASCount numSelectors;

	ASVersion version;

	const void* hftProcs;

Layer	AS_Layer
Object	HFT_and_HFT_Server