Handle Suite Callbacks (deprecated Standard Suite)

The standard Handle Suite is deprecated, please use the Handle Suite Callbacks defined with the Adobe Plug-in Component Architecture (PICA). More...

Data Structures
struct	HandleProcs
Defines
#define	kCurrentHandleProcsVersion   1
	The current version of the handle suite.
#define	kCurrentHandleProcsCount   ((sizeof(HandleProcs) - offsetof(HandleProcs, newProc)) / sizeof(void *))
	Current number of routines in the Handle Suite.
Typedefs
typedef struct HandleProcs	HandleProcs
Handle Suite Callbacks
typedef MACPASCAL Handle(*	NewPIHandleProc )(int32 size)
	Allocates a handle of the indicated size.
typedef MACPASCAL void(*	DisposePIHandleProc )(Handle h)
	Disposes of the indicated handle.
typedef MACPASCAL void(*	DisposeRegularHandlePIHandleProc )(Handle h)
	Disposes of the indicated handle.
typedef MACPASCAL int32(*	GetPIHandleSizeProc )(Handle h)
	Gets the size of the indicated handle.
typedef MACPASCAL OSErr(*	SetPIHandleSizeProc )(Handle h, int32 newSize)
	Attempts to resize the indicated handle.
typedef MACPASCAL Ptr(*	LockPIHandleProc )(Handle h, Boolean moveHigh)
	Locks and dereferences the handle.
typedef MACPASCAL void(*	UnlockPIHandleProc )(Handle h)
	Unlocks the handle.
typedef MACPASCAL void(*	RecoverSpaceProc )(int32 size)
	Recovers space from disposed handles not disposed of by invoking the DisposePIHandleProc callback.

---

Detailed Description

The standard Handle Suite is deprecated, please use the Handle Suite Callbacks defined with the Adobe Plug-in Component Architecture (PICA).

The following suite of routines is used primarily for cross-platform support. Although you can allocate handles directly using the Mac OS Toolbox, these callbacks are recommended, instead. When you use these callbacks, Photoshop accounts for these handles in its virtual memory space calculations.

The use of the Handle structure throughout the API poses a problem under Windows, where a direct equivalent does not exist. To facilitate Windows plug-ins, Photoshop implements a handle model that is very similar to handles under the Mac OS.

In general, the Buffer suite routines are more effective for memory allocation than the Handle suite. The Buffer suite may have access to memory unavailable to the Handle suite. You should use the Handle suite, however, if the data you are managing is a Mac OS handle.

For more information, please see Using Buffer and Handle Suites.

The standard Handle Suite is found as a pointer in the parameter blocks of the plug-in modules. You can access the routines within the Buffer Suite in the following manner:

    // The structure to hold the data, we'll create a handle for this.
    typedef struct Data
    {
        FilterColor color;
        FilterColor colorArray[4];
        Boolean queryForParameters;
        BufferID dissolveBufferID;
        Ptr dissolveBuffer;
        VRect proxyRect;
        real32 scaleFactor;
        BufferID proxyBufferID;
        Ptr proxyBuffer;
        int32 proxyWidth;
        int32 proxyHeight;
        int32 proxyPlaneSize;
    } Data;

    FilterRecord *gFilterRecord = NULL; 

    DLLExport MACPASCAL void PluginMain(const int16 selector,
                                        FilterRecordPtr filterRecord,
                                        intptr_t* data,
                                        int16* result)
    {
      // The parameter block that contains the suite is found in filterRecord. 
      gFilterRecord = filterRecord;
      ...
    }

    // This function uses one of the Handle Suite routines
    void CreateDataHandle(void)
    {
        // Get the Handle Suite, and call the
        // newProc routine to allocate the memory for the handle.
        Handle h = gFilterRecord->handleProcs->newProc(sizeof(Data));
        ...
    }

---

Define Documentation

#define kCurrentHandleProcsVersion   1

The current version of the handle suite.

#define kCurrentHandleProcsCount   ((sizeof(HandleProcs) - offsetof(HandleProcs, newProc)) / sizeof(void *))

Current number of routines in the Handle Suite.

---

Typedef Documentation

typedef MACPASCAL Handle(* NewPIHandleProc)(int32 size)

Allocates a handle of the indicated size.

Parameters:

size	The size of the handle to allocate

Returns:

The new handle; NULL if the handle could not be allocated.

typedef MACPASCAL void(* DisposePIHandleProc)(Handle h)

Disposes of the indicated handle.

Parameters:

h	The handle to dispose of.

typedef MACPASCAL void(* DisposeRegularHandlePIHandleProc)(Handle h)

Disposes of the indicated handle.

Parameters:

h	The handle to dispose of.

typedef MACPASCAL int32(* GetPIHandleSizeProc)(Handle h)

Gets the size of the indicated handle.

Parameters:

h	The handle to get the size of.

Returns:

The size of the handle.

typedef MACPASCAL OSErr(* SetPIHandleSizeProc)(Handle h, int32 newSize)

Attempts to resize the indicated handle.

Parameters:

h	The handle to resize.
newSize	The new size for the handle.

Returns:

noErr if successful; an error code if unsuccessful.

typedef MACPASCAL Ptr(* LockPIHandleProc)(Handle h, Boolean moveHigh)

Locks and dereferences the handle.

Parameters:

h	The handle to lock.
moveHigh	Flag to indicate whether to move the handle to the high end of memory before locking it.

Returns:

a pointer to the containing data

typedef MACPASCAL void(* UnlockPIHandleProc)(Handle h)

Unlocks the handle.

Unlike the routines for buffers, the lock and unlock calls for handles are not reference counted. A single unlock call unlocks the handle no matter how many times it has been locked.

Parameters:

h	The handle to unlock.

typedef MACPASCAL void(* RecoverSpaceProc)(int32 size)

Recovers space from disposed handles not disposed of by invoking the DisposePIHandleProc callback.

All handles allocated through the Handle suite have their space accounted for in estimates by Photoshop of how much image data it can make resident at one time.

If you obtain a handle through the Handle suite or some other mechanism in Photoshop, you should dispose of it using the DisposePIHandleProc callback. If you dispose of it in some other way (e.g., use the handle as the parameter to AddResource and then close the resource file), then you can use this call to tell Photoshop to decrease its handle memory pool estimate.

Parameters:

size	Amount of space to recover.

typedef struct HandleProcs HandleProcs

The set of routines available in the Handle suite.