SafeFileHandle Class
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
Represents a wrapper class for a file handle.
System.Runtime.ConstrainedExecution.CriticalFinalizerObject
System.Runtime.InteropServices.SafeHandle
Microsoft.Win32.SafeHandles.SafeHandleZeroOrMinusOneIsInvalid
Microsoft.Win32.SafeHandles.SafeFileHandle
Namespace: Microsoft.Win32.SafeHandles
Assembly: mscorlib (in mscorlib.dll)
The SafeFileHandle type exposes the following members.
| Name | Description | |
|---|---|---|
|
IsClosed | Gets a value indicating whether the handle is closed. (Inherited from SafeHandle.) |
|
IsInvalid | Gets a value that indicates whether the handle is invalid. (Inherited from SafeHandleZeroOrMinusOneIsInvalid.) |
| Name | Description | |
|---|---|---|
|
Close | Marks the handle for releasing and freeing resources. (Inherited from SafeHandle.) |
|
DangerousAddRef | Manually increments the reference counter on SafeHandle instances. (Inherited from SafeHandle.) |
|
DangerousGetHandle | Returns the value of the handle field. (Inherited from SafeHandle.) |
|
DangerousRelease | Manually decrements the reference counter on a SafeHandle instance. (Inherited from SafeHandle.) |
|
Dispose() | Releases all resources used by the SafeHandle class. (Inherited from SafeHandle.) |
|
Dispose(Boolean) | Releases the unmanaged resources used by the SafeHandle class specifying whether to perform a normal dispose operation. (Inherited from SafeHandle.) |
|
Equals(Object) | Determines whether the specified Object is equal to the current Object. (Inherited from Object.) |
|
Finalize | Frees all resources associated with the handle. (Inherited from SafeHandle.) |
|
GetHashCode | Serves as a hash function for a particular type. (Inherited from Object.) |
|
GetType | Gets the Type of the current instance. (Inherited from Object.) |
|
MemberwiseClone | Creates a shallow copy of the current Object. (Inherited from Object.) |
|
ReleaseHandle | When overridden in a derived class, executes the code required to free the handle. (Inherited from SafeHandle.) |
|
SetHandle | Sets the handle to the specified pre-existing handle. (Inherited from SafeHandle.) |
|
SetHandleAsInvalid | Marks a handle as no longer used. (Inherited from SafeHandle.) |
|
ToString | Returns a string that represents the current object. (Inherited from Object.) |
This class is derived from SafeHandleZeroOrMinusOneIsInvalid. A value of 0 or -1 is an invalid file handle.
The following code example demonstrates how to open a file using the SafeFileHandle class and the unmanaged CreateFile function.
using System; using Microsoft.Win32.SafeHandles; using System.Runtime.InteropServices; using System.ComponentModel; class SafeHandlesExample { static void Main() { try { UnmanagedFileLoader loader = new UnmanagedFileLoader("example.xml"); } catch (Exception e) { Console.WriteLine(e); } Console.ReadLine(); } } class UnmanagedFileLoader { public const short FILE_ATTRIBUTE_NORMAL = 0x80; public const short INVALID_HANDLE_VALUE = -1; public const uint GENERIC_READ = 0x80000000; public const uint GENERIC_WRITE = 0x40000000; public const uint CREATE_NEW = 1; public const uint CREATE_ALWAYS = 2; public const uint OPEN_EXISTING = 3; // Use interop to call the CreateFile function. // For more information about CreateFile, // see the unmanaged MSDN reference library. [DllImport("kernel32.dll", SetLastError = true, CharSet=CharSet.Unicode)] static extern SafeFileHandle CreateFile(string lpFileName, uint dwDesiredAccess, uint dwShareMode, IntPtr lpSecurityAttributes, uint dwCreationDisposition, uint dwFlagsAndAttributes, IntPtr hTemplateFile); private SafeFileHandle handleValue = null; public UnmanagedFileLoader(string Path) { Load(Path); } public void Load(string Path) { if (Path == null || Path.Length == 0) { throw new ArgumentNullException("Path"); } // Try to open the file. handleValue = CreateFile(Path, GENERIC_WRITE, 0, IntPtr.Zero, OPEN_EXISTING, 0, IntPtr.Zero); // If the handle is invalid, // get the last Win32 error // and throw a Win32Exception. if (handleValue.IsInvalid) { Marshal.ThrowExceptionForHR(Marshal.GetHRForLastWin32Error()); } } public SafeFileHandle Handle { get { // If the handle is valid, // return it. if (!handleValue.IsInvalid) { return handleValue; } else { return null; } } } }
-
SecurityCriticalAttribute
requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.
Windows 8 Consumer Preview, Windows Server 8 Beta, Windows 7, Windows Server 2008 SP2, Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.