System.Runtime.InteropServices.GCHandle Structure

public struct GCHandle

Base Types

Object
  ValueType
    GCHandle

Assembly

mscorlib

Library

RuntimeInfrastructure

Summary

Provides a means for referencing a managed object from unmanaged memory.

Description

Use a GCHandle when an object reference is required to be accessible from unmanaged memory.

The GCHandleType enumeration describes the possible GCHandle types.

[Note: If the type of the GCHandle is System.Runtime.InteropServices.GCHandleType.Normal, then it is an opaque handle, and the address of the object it references cannot be resolved through it.]

See Also

System.Runtime.InteropServices Namespace

Members

GCHandle Methods

GCHandle.AddrOfPinnedObject Method
GCHandle.Alloc(System.Object) Method
GCHandle.Alloc(System.Object, System.Runtime.InteropServices.GCHandleType) Method
GCHandle.Free Method
System.Runtime.InteropServices.GCHandle GCHandle.op_Explicit(System.IntPtr) Method
System.IntPtr GCHandle.op_Explicit(System.Runtime.InteropServices.GCHandle) Method

GCHandle Properties

GCHandle.IsAllocated Property
GCHandle.Target Property

GCHandle.AddrOfPinnedObject Method

public IntPtr AddrOfPinnedObject();

Summary

Returns the address of an object being referred to by a System.Runtime.InteropServices.GCHandleType.Pinned handle.

Return Value

A IntPtr containing the address of the of the System.Runtime.InteropServices.GCHandleType.Pinned object as a IntPtr .

Exceptions

Exception TypeCondition
InvalidOperationExceptionThe handle type is not System.Runtime.InteropServices.GCHandleType.Pinned .

See Also

System.Runtime.InteropServices.GCHandle Structure, System.Runtime.InteropServices Namespace

GCHandle.Alloc(System.Object) Method

public static GCHandle Alloc(object value);

Summary

Allocates a System.Runtime.InteropServices.GCHandleType.Normal handle for the specified object.

Parameters

value
The object for which the GCHandle is created. Can be null .

Return Value

A new GCHandle instance that protects the object from garbage collection.

Description

A System.Runtime.InteropServices.GCHandleType.Normal handle ensures the object will not be collected by the garbage collector.

If the value parameter is null , this method returns a valid GCHandle. [Note: The target of the handle can be changed via the System.Runtime.InteropServices.GCHandle.Target property.]

See Also

System.Runtime.InteropServices.GCHandle Structure, System.Runtime.InteropServices Namespace

GCHandle.Alloc(System.Object, System.Runtime.InteropServices.GCHandleType) Method

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

Summary

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

Parameters

value
The object for which the GCHandle is created. Can be null .
type
A GCHandleType value that specifies the type of GCHandle to create.

Return Value

A new GCHandle instance that protects the object.

Description

If the value parameter is null , this method returns a valid GCHandle. [Note: The target of the handle can be changed via the System.Runtime.InteropServices.GCHandle.Target property.]

See Also

System.Runtime.InteropServices.GCHandle Structure, System.Runtime.InteropServices Namespace

GCHandle.Free Method

public void Free();

Summary

Frees a GCHandle.

Exceptions

Exception TypeCondition
InvalidOperationExceptionThe handle has already been freed or was never initialized.

Description

The caller is required to provide synchronization to prevent multiple threads from executing this method simultaneously for a given handle.

See Also

System.Runtime.InteropServices.GCHandle Structure, System.Runtime.InteropServices Namespace

System.Runtime.InteropServices.GCHandle GCHandle.op_Explicit(System.IntPtr) Method

public static explicit operator GCHandle(IntPtr value);

Summary

Convert a IntPtr to a GCHandle instance.

Parameters

value
The IntPtr to be converted.

Return Value

A GCHandle .

Description

GCHandle instances are stored using an internal integer representation. This method allows you to retrieve a GCHandle from its integer representation.

See Also

System.Runtime.InteropServices.GCHandle Structure, System.Runtime.InteropServices Namespace

System.IntPtr GCHandle.op_Explicit(System.Runtime.InteropServices.GCHandle) Method

public static explicit operator IntPtr(GCHandle value);

Summary

Converts a GCHandle instance to a IntPtr.

Parameters

value
The GCHandle to be converted.

Return Value

A IntPtr representation of the specified GCHandle .

Description

GCHandle instances are stored using an internal integer representation. This method allows you to retrieve that representation.

See Also

System.Runtime.InteropServices.GCHandle Structure, System.Runtime.InteropServices Namespace

GCHandle.IsAllocated Property

public bool IsAllocated { get; }

Summary

Gets a Boolean value indicating whether the current GCHandle instance is allocated.

Property Value

true if the handle is allocated; otherwise, false .

Description

This property is read-only.

Use this method to determine whether the GCHandle is still available.

[Note: When the garbage collector collects the object, the handle could still be resurrected in the finalizer.]

See Also

System.Runtime.InteropServices.GCHandle Structure, System.Runtime.InteropServices Namespace

GCHandle.Target Property

public object Target { get; set; }

Summary

Gets or sets a reference to the object the current GCHandle instance represents.

Property Value

The object this handle represents.

Exceptions

Exception TypeCondition
InvalidOperationExceptionThe current GCHandle instance has already been freed or was never initialized.

See Also

System.Runtime.InteropServices.GCHandle Structure, System.Runtime.InteropServices Namespace