Part IV in Visual C#

Encoder PDF417 in Visual C# Part IV

public abstract Boolean IsInvalid { get { // A derived class overrides this property. // The implementation should return true if the handle's value doesn't // represent a resource (this usually means that the handle is 0 or -1) } } // These three methods have to do with security and reference counting; // I'll talk about them at the end of this section public void DangerousAddRef(ref Boolean success) {...} public IntPtr DangerousGetHandle() {...} public void DangerousRelease() {...} }

The first thing to notice about the SafeHandle class is that it is derived from CriticalFinalizerObject; this ensures it gets the CLR s special treatment . The second thing to notice is that the class is abstract; it is expected that another class will be derived from SafeHandle, and this class will override the protected constructor, the abstract method ReleaseHandle, and the abstract IsInvalid property get accessor method . In Windows, most handles are invalid if they have a value of 0 or -1 . The Microsoft.Win32.SafeHandles namespace contains another helper class called SafeHandleZeroOrMinusOneIsInvalid, which looks like this:

public abstract class SafeHandleZeroOrMinusOneIsInvalid : SafeHandle { protected SafeHandleZeroOrMinusOneIsInvalid(Boolean ownsHandle) : base(IntPtr.Zero, ownsHandle) { } public override Boolean IsInvalid { get { if (base.handle == IntPtr.Zero) return true; if (base.handle == (IntPtr) (-1)) return true; return false; } } }

Again, you ll notice that the SafeHandleZeroOrMinusOneIsInvalid class is abstract, and therefore, another class must be derived from this one to override the protected constructor and the abstract method ReleaseHandle . The .NET Framework provides just a few public classes derived from SafeHandleZeroOrMinusOneIsInvalid, including SafeFileHandle, SafeRegistryHandle, SafeWaitHandle, and SafeBuffer . Here is what the SafeFileHandle class looks like:

public sealed class SafeFileHandle : SafeHandleZeroOrMinusOneIsInvalid { public SafeFileHandle(IntPtr preexistingHandle, Boolean ownsHandle) : base(ownsHandle) { base.SetHandle(preexistingHandle); }

21

Automatic Memory Management (Garbage Collection)

protected override Boolean ReleaseHandle() { // Tell Windows that we want the native resource closed. return Win32Native.CloseHandle(base.handle); } }

The SafeWaitHandle class is implemented similarly to the SafeFileHandle class shown above . The only reason why there are different classes with similar implementations is to achieve type safety; the compiler won t let you use a file handle as an argument to a method that expects a wait handle, and vice versa . The SafeRegistryHandle class s ReleaseHandle method calls the Win32 RegCloseKey function . It would be nice if the .NET Framework included additional classes that wrap various native resources . For example, one could imagine classes such as SafeProcessHandle, SafeThreadHandle, SafeTokenHandle, SafeFileMappingHandle, SafeViewOfFileHandle (its ReleaseHandle method would call the Win32 UnmapViewOfFile function), SafeLibraryHandle (its ReleaseHandle method would call the Win32 FreeLibrary function), SafeLocalAllocHandle (its ReleaseHandle method would call the Win32 LocalFree function), and so on . All of the classes just listed (and more) actually do ship with the Framework Class Library (FCL) . However, these classes are not publicly exposed; they are all internal to MSCorLib .dll or System .dll . Microsoft didn t expose these classes publicly because they didn t want to do full testing of them, and they didn t want to have to take the time to document them . However, if you need any of these classes for your own work, I d recommend that you use a tool such as ILDasm .exe or some IL decompiler tool to extract the code for these classes and integrate that code into your own project s source code . All of these classes are trivial to implement, and writing them yourself from scratch would also be quite easy .

As already shown, the SafeHandle-derived classes are extremely useful because they ensure that the native resource is freed when a garbage collection occurs . In addition to what we ve already discussed, SafeHandle offers two more capabilities . First, the CLR gives SafeHandlederived types special treatment when used in scenarios in which you are interoperating with unmanaged code . For example, let s examine the following code:

using System; using System.Runtime.InteropServices; using Microsoft.Win32.SafeHandles; internal static class SomeType { [DllImport("Kernel32", CharSet=CharSet.Unicode, EntryPoint="CreateEvent")] // This prototype is not robust private static extern IntPtr CreateEventBad( IntPtr pSecurityAttributes, Boolean manualReset, Boolean initialState, String name);