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.

See also:
System.Runtime.InteropServices Namespace

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.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.

Return to top


Top of page

Copyright (c) 2002 Microsoft Corporation. All rights reserved.