CloneHandle Function

Clones a Handle. When passing handles in between plugins, caching handles can result in accidental invalidation when one plugin releases the Handle, or is its owner is unloaded from memory. To prevent this, the Handle may be "cloned" with a new owner.

Handle CloneHandle(Handle hndl, Handle plugin)

Parameters

Handle hndl

Handle to clone/duplicate.

Handle plugin

Optional Handle to another plugin to mark as the new owner. If no owner is passed, the owner becomes the calling plugin.

Return Value

Handle on success, INVALID_HANDLE if not cloneable.

Errors

Invalid handles will cause a run time error.

Notes

Usually, you will be cloning Handles for other plugins. This means that if you clone the Handle without specifying the new owner, it will assume the identity of your original calling plugin, which is not very useful. You should either specify that the receiving plugin should clone the handle on its own, or you should explicitly clone the Handle using the receiving plugin's identity Handle.