Type: System.Runtime.InteropServices.GCHandle

System.Runtime.InteropServices.GCHandle Structure

Assembly: Mscorlib.dll
Namespace: System.Runtime.InteropServices

Summary: Provides a means for accessing a managed object from unmanaged memory.

C# Syntax:


        public struct GCHandle

Remarks

Use a GCHandle when an object reference must be accessible from unmanaged code. The GCHandle can be used to obtain the address of the object or, from managed code, to obtain a new object reference.

See GCHandleType for more information about the different GCHandleType values used by the common language runtime.

System.Runtime.InteropServices.GCHandle Member List:

Public Properties

IsAllocated	Read-only Gets a value indicating whether the handle is allocated.
Target	Read-write Gets and sets the object this handle represents.

Public Methods

AddrOfPinnedObject	Retrieves the address of an object in a GCHandleType.Pinned handle.
Alloc	Overloaded: `Alloc(object value)` Allocates a GCHandleType.Normal handle for the specified object.
Alloc	Overloaded: `Alloc(object value, GCHandleType type)` Allocates a handle of the specified type for the specified object.
Equals (inherited from System.ValueType)	See base class member description: System.ValueType.Equals Indicates whether this instance and a specified object are equal.
Free	Releases a GCHandle.
GetHashCode (inherited from System.ValueType)	See base class member description: System.ValueType.GetHashCode Returns the hash code for this instance.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
ToString (inherited from System.ValueType)	See base class member description: System.ValueType.ToString Returns the fully qualified type name of this instance.

Public Operators and Type Conversions

op_Explicit (convert System.Runtime.InteropServices.GCHandle to System.IntPtr)	Overloaded: `op_Explicit(GCHandle value)` A GCHandle is stored using an internal integer representation. This method can be used to retrieve the integer value from a GCHandle.
op_Explicit (convert System.IntPtr to System.Runtime.InteropServices.GCHandle)	Overloaded: `op_Explicit(IntPtr value)` A GCHandle is stored using an internal integer representation. This method allows you to retrieve a GCHandle from an integer value.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

System.Object

System.ValueType

System.Runtime.InteropServices.GCHandle

System.Runtime.InteropServices.GCHandle Member Details

Property: IsAllocated (read-only)

Summary: Gets a value indicating whether the handle is allocated.

C# Syntax:


            public bool IsAllocated {get;}

Remarks

Use this method when using GCHandleType.Weak handles to determine if the GCHandle is still available. When the garbage collector collects the object, the GCHandleType.Weak handle could still be resurrected in the finalizer. In this case, the handle is not allocated (it is lost when the garbage collector attempts to collect the object) even though the target object is valid.

Return to top

Property: Target (read-write)

Summary: Gets and sets the object this handle represents.

C# Syntax:


            public object Target {get; set;}

Exceptions

Exception Type	Condition
InvalidOperationException	The handle was freed, or never initialized.

.NET Framework Security:

SecurityPermission for operating with unmanaged code. Associated enumeration: SecurityPermissionFlag.UnmanagedCode.

Return to top

Method: AddrOfPinnedObject()

Summary: Retrieves the address of an object in a GCHandleType.Pinned handle.

C# Syntax:


            public IntPtr AddrOfPinnedObject();

Return Value:: Returns the address of the of the Pinned object as an IntPtr.

Exceptions

Exception Type	Condition
InvalidOperationException	The handle is any type other than GCHandleType.Pinned.

Remarks

This method is used to get a stable pointer to the object. Pinning an object prevents the garbage collector from moving it around in memory, thereby reducing the efficiency of the garbage collector.

.NET Framework Security:

SecurityPermission for operating with unmanaged code. Associated enumeration: SecurityPermissionFlag.UnmanagedCode.

Return to top

Overloaded Method: Alloc(
object value
)

Summary: Allocates a GCHandleType.Normal handle for the specified object.

C# Syntax:


            public static GCHandle Alloc(
   object value
);

Parameters:

value

The object that uses the GCHandle.

Return Value:: Returns a new GCHandle that protects the object from garbage collection. This GCHandle must be released with GCHandle.Free when it is no longer needed.

Remarks

GCHandleType.Normal handles are opaque, meaning that you cannot resolve the address of the object it contains through the handle.

.NET Framework Security:

SecurityPermission for operating with unmanaged code. Associated enumeration: SecurityPermissionFlag.UnmanagedCode.

Return to top

Overloaded Method: Alloc(
object value,
GCHandleType type
)

Summary: Allocates a handle of the specified type for the specified object.

C# Syntax:


            public static GCHandle Alloc(
   object value,
   GCHandleType type
);

Parameters:

value

The object that uses the GCHandle.

type

The type of GCHandle to create.

Return Value:: Returns a new GCHandle of the specified type. This GCHandle must be released with GCHandle.Free when it is no longer needed.

.NET Framework Security:

SecurityPermission for operating with unmanaged code. Associated enumeration: SecurityPermissionFlag.UnmanagedCode.

Return to top

Method: Equals(
object obj
)

Inherited
See base class member description: System.ValueType.Equals

Summary: Indicates whether this instance and a specified object are equal.

C# Syntax:


            public override bool Equals(
   object obj
);

Parameters:

obj

Another object to compare to.

Return Value:: true if obj and this instance are the same type and represent the same value; otherwise, false.

Return to top

Method: Finalize()

Inherited
See base class member description: System.Object.Finalize

C# Syntax:


            ~GCHandle();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: Free()

Summary: Releases a GCHandle.

C# Syntax:


            public void Free();

Exceptions

Exception Type	Condition
InvalidOperationException	The handle was freed or never initialized.

Remarks

The caller must ensure that for a given handle, Free is called only once.

.NET Framework Security:

SecurityPermission for operating with unmanaged code. Associated enumeration: SecurityPermissionFlag.UnmanagedCode.

Return to top

Method: GetHashCode()

Inherited
See base class member description: System.ValueType.GetHashCode

Summary: Returns the hash code for this instance.

C# Syntax:


            public override int GetHashCode();

Return Value:: A 32-bit signed integer that is the hash code for this instance.

Remarks

The ValueType.GetHashCode method applies to types derived from ValueType. One or more fields of the derived type is used to calculate the return value. If one or more of those fields contains a mutable value, the return value might be unpredictable, and unsuitable for use as a key in a hash table.

For more information, see Object.GetHashCode, and Hashtable.

Return to top

Method: GetType()

Inherited
See base class member description: System.Object.GetType

C# Syntax:


            public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: MemberwiseClone()

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:


            protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Overloaded Method: op_Explicit System.IntPtr(
GCHandle value
)

Summary: A GCHandle is stored using an internal integer representation. This method can be used to retrieve the integer value from a GCHandle.

C# Syntax:


            public static operator explicit IntPtr(
   GCHandle value
);

Parameters:

value

The handle for which the integer is required.

Return Value:: Returns the integer value.

.NET Framework Security:

SecurityPermission for operating with unmanaged code. Associated enumeration: SecurityPermissionFlag.UnmanagedCode.

Return to top

Overloaded Method: op_Explicit System.Runtime.InteropServices.GCHandle(
IntPtr value
)

Summary: A GCHandle is stored using an internal integer representation. This method allows you to retrieve a GCHandle from an integer value.

C# Syntax:


            public static operator explicit GCHandle(
   IntPtr value
);

Parameters:

value

The handle for which the conversion is required.

Return Value:: Returns the GCHandle.

.NET Framework Security:

SecurityPermission for operating with unmanaged code. Associated enumeration: SecurityPermissionFlag.UnmanagedCode.

Return to top

Method: ToString()

Inherited
See base class member description: System.ValueType.ToString

Summary: Returns the fully qualified type name of this instance.

C# Syntax:


            public override string ToString();

Return Value:: A String containing a fully qualified type name.