CloneHandle

Last Updated2019-05-29
Created At2007-01-01

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.

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.

native Handle CloneHandle(Handle hndl, Handle plugin = INVALID_HANDLE)

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 Handle on success, INVALID_HANDLE if not cloneable.

Error

Invalid handles will cause a run time error.