HandleRef Struct
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Wraps a managed object holding a handle to a resource that is passed to unmanaged code using platform invoke.
public value class HandleRefpublic readonly struct HandleRefpublic struct HandleRef[System.Runtime.InteropServices.ComVisible(true)]
public struct HandleReftype HandleRef = struct[<System.Runtime.InteropServices.ComVisible(true)>]
type HandleRef = structPublic Structure HandleRef- Inheritance
- Attributes
Remarks
Important
Starting with the .NET Framework 2.0, the functionality of the HandleRef class has been replaced by the SafeHandle class and its derived classes, as well as by the CriticalHandle class.
If you use platform invoke to call a managed object, and the object is not referenced elsewhere after the platform invoke call, it is possible for the garbage collector to finalize the managed object. This action releases the resource and invalidates the handle, causing the platform invoke call to fail. Wrapping a handle with HandleRef guarantees that the managed object is not garbage collected until the platform invoke call completes. For a description of platform invoke services, see Consuming Unmanaged DLL Functions.
The HandleRef value type, like GCHandle, is a special type recognized by the interop marshaler. A normal, nonpinned GCHandle also prevents untimely garbage collection, yet HandleRef provides better performance. Although using HandleRef to keep an object alive for the duration of a platform invoke call is preferred, you can also use the GC.KeepAlive method for the same purpose.
The HandleRef constructor takes two parameters: an Object representing the wrapper, and an IntPtr representing the unmanaged handle. The interop marshaler passes only the handle to unmanaged code, and guarantees that the wrapper (passed as the first parameter to the constructor of the HandleRef) remains alive for the duration of the call.
Constructors
| HandleRef(Object, IntPtr) |
Initializes a new instance of the HandleRef class with the object to wrap and a handle to the resource used by unmanaged code. |
Properties
| Handle |
Gets the handle to a resource. |
| Wrapper |
Gets the object holding the handle to a resource. |
Methods
| ToIntPtr(HandleRef) |
Returns the internal integer representation of a HandleRef object. |
Operators
| Explicit(HandleRef to IntPtr) |
Returns the handle to a resource of the specified HandleRef object. |
