There are times when a developer will need to use 4D Handles instead of C/C++ based handles. An example of this would be when working with Picts and BLOBs. These data types in 4D return a PA_Handle which is defined as a char** in PublicTypes.h. You should not use 4D's Handle calls to replace basic memory management calls such as malloc, NewHandle, etc. These should only be used for 4D structures.

To create a new 4D Handle the developer can call the command PA_NewHandle. Since we are dealing with calls that allocate memory you should always check the return value from PA_NewHandle to make sure there was enough memory to create the new handle.

For example:

aHandle = PA_NewHandle(1024);
if ( aHandle == 0L )
{
// error occurred
}
else
// continue with your code


Once you have finished with using the handle you need to dispose of the handle. To do this, simply call the PA_DisposeHandle command. To extend our example above, we now have:

aHandle = PA_NewHandle(1024);
if ( aHandle == 0L )
{
// error occurred
}
else
// work with the new handle
PA_DisposeHandle(aHandle); // we are finished and need to free memory

If we need to move memory around with our Handles we must Lock the handle before moving the data to prevent the data from changing or being touched by other processes. To lock a Handle we call PA_LockHandle. To free the handle again call PA_UnlockHandle.

For Example:

aHandle = PA_NewHandle(1024);
if ( aHandle == 0L )
{
//error occurred
}
else
{
ptr = PA_LockHandle(aHandle); //ptr is a char*
//copy the handle or some other function
PA_UnlockHandle(aHandle);
}

You should always unlock a handle when finished to prevent memory fragmentation.

For more information on 4D Handles refer to the "4D Plug-in API Reference.pdf" starting on page 85.