DllImportAttribute.PreserveSig フィールド

.NET Framework クラス ライブラリ リファレンス

DllImportAttribute.PreserveSig フィールド

戻り値が HRESULT または retval であるアンマネージ メソッドを直接変換するか、戻り値 HRESULT または retval を自動的に例外に変換するかを示します。

名前空間: System.Runtime.InteropServices
アセンブリ: mscorlib (mscorlib.dll 内)
構文

Visual Basic (宣言)

Public PreserveSig As Boolean

Visual Basic (使用法)

Dim instance As DllImportAttribute
Dim value As Boolean

value = instance.PreserveSig

instance.PreserveSig = value

C#

public bool PreserveSig

C++

public:
bool PreserveSig

J#

public boolean PreserveSig

JScript

public var PreserveSig : boolean

解説

PreserveSig フィールドに true を設定すると、HRESULT 値または retval 値でアンマネージ シグネチャが直接変換されます。false を設定すると、HRESULT 値または retval 値が自動的に例外に変換されます。既定では、PreserveSig フィールドは true です。

true の場合、結果として生成されるメソッド シグネチャは HRESULT 値を含む整数値を返します。この場合、アプリケーション内で戻り値を手動で検査し、その結果に応じて対応する必要があります。

PreserveSig フィールドに false を設定すると、結果として生成されるメソッド シグネチャに含まれる戻り値の型は、整数型 (HRESULT) ではなく void 型になります。アンマネージ メソッドが HRESULT を生成した場合、ランタイムは戻り値 S_OK (または 0) を自動的に無視し、例外をスローしません。S_OK 以外の HRESULT の場合、ランタイムはその HRESULT に対応する例外を自動的にスローします。DllImportAttribute 属性は、HRESULT を返すメソッドに対してこの変換を実行するだけです。

アプリケーションのエラー報告構造に例外が適している場合は、既定のエラー報告動作を HRESULT から例外に変更できます。ただし、HRESULT を使用する方が望ましい場合は、HRESULT エラー報告を使用します。

このフィールドは PreserveSigAttribute と似ていますが、PreserveSig フィールドとは異なり、この属性の既定値は false です。

場合によっては、Visual Basic の開発者は、マネージ コードで DLL 関数を定義する際、Declare ステートメントを使用する代わりに、DllImportAttribute を使用します。PreserveSig フィールドの設定は、このような事例の 1 つです。

使用例

DllImportAttribute を使用して PreserveSig フィールドに true を設定し、アンマネージ SHAutoComplete 関数をインポートした後、PreserveSig フィールドを再度 false に設定するコード例を次に示します。このコード例では、SHAutoComplete 関数によって HRESULT エラーが 1 度生成され、次に例外が生成されます。

Visual Basic

Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Runtime.InteropServices



Module Win32
    ' The SHAutoComplete function allows you 
    ' to add auto-compete functionality to your
    ' Windows Forms text boxes. In .NET Framework 
    ' 1.1 and earlier, you can use SHAutoComplete.
    ' Later versions have this ability built in without
    ' requiring platform invoke.
    ' See the MSDN documentation of the 
    ' SHAutoComplete function for the 
    ' complete set of flags.

    Public Enum SHAutoCompleteFlags
        SHACF_DEFAULT = &H0
        SHACF_FILESYSTEM = &H1
    End Enum 'SHAutoCompleteFlags


    ' Use the DllImportAttribute to import the SHAutoComplete function.
 
    ' Set the PreserveSig to false to specify exception errors.
    <DllImportAttribute("shlwapi.dll", EntryPoint:="SHAutoComplete",
 ExactSpelling:=True, PreserveSig:=False)> _
    Public Sub SHAutoComplete(ByVal
 hwndEdit As IntPtr, ByVal dwFlags As
 SHAutoCompleteFlags)
    End Sub


    ' Use the DllImportAttribute to import the SHAutoComplete function.
 
    ' Use the default value of the PreserveSig field to specify HRESULT
 errors.
    <DllImportAttribute("shlwapi.dll", EntryPoint:="SHAutoComplete",
 ExactSpelling:=True)> _
    Public Function SHAutoCompleteHRESULT(ByVal
 hwndEdit As IntPtr, ByVal dwFlags As
 SHAutoCompleteFlags) As Integer
    End Function
End Module



Module Program

    Sub Main()
        Run()

    End Sub


    Sub Run()
        ' Create a null (nothing in Visual Basic) IntPtr
        ' to pass to the SHAutoComplete method.  Doing so
        ' creates a failure and demonstrates the two ways  
        ' that the PreserveSig property allows you to handle 
        ' failures.  
        ' Normally, you would pass a handle to a managed
        ' Windows Forms text box.
        Dim iPtr As New
 IntPtr(0)

        ' Call the SHAutoComplete function using exceptions.
        Try
            Console.WriteLine("Calling the SHAutoComplete method
 with the PreserveSig field set to false.")

            Win32.SHAutoComplete(iPtr, Win32.SHAutoCompleteFlags.SHACF_DEFAULT)
        Catch e As Exception
            Console.WriteLine("Exception handled: "
 + e.Message)
        End Try

        Console.WriteLine("Calling the SHAutoComplete method with
 the PreserveSig field set to true.")

        ' Call the SHAutoComplete function using HRESULTS.
        Dim HRESULT As Integer
 = Win32.SHAutoCompleteHRESULT(iPtr, Win32.SHAutoCompleteFlags.SHACF_DEFAULT)

        Console.WriteLine("HRESULT handled: " + HRESULT.ToString())

    End Sub
End Module

C#

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Runtime.InteropServices;

internal class Win32
{
    // The SHAutoComplete function allows you 
    // to add auto-compete functionality to your
    // Windows Forms text boxes. In .NET Framework 
    // 1.1 and earlier, you can use SHAutoComplete.
    // Later versions have this ability built in without
    // requiring platform invoke.

    // See the MSDN documentation of the 
    // SHAutoComplete function for the 
    // complete set of flags.
    public enum SHAutoCompleteFlags
    {
        SHACF_DEFAULT = 0x00000000,
        SHACF_FILESYSTEM = 0x00000001
    }

    // Use the DllImportAttribute to import the SHAutoComplete function.
 
    // Set the PreserveSig to false to specify exception errors.
    [DllImportAttribute("shlwapi.dll", EntryPoint = "SHAutoComplete",
 ExactSpelling = true, PreserveSig = false)]
    public static extern void
 SHAutoComplete(IntPtr hwndEdit, SHAutoCompleteFlags dwFlags);

    // Use the DllImportAttribute to import the SHAutoComplete function.
 
    // Use the default value of the PreserveSig field to specify HRESULT
 errors.
    [DllImportAttribute("shlwapi.dll", EntryPoint = "SHAutoComplete",
 ExactSpelling = true)]
    public static extern int
 SHAutoCompleteHRESULT(IntPtr hwndEdit, SHAutoCompleteFlags dwFlags);
}


static class Program
{
    static void Main()
    {
        Run();
    }

    static void Run()
    {
        // Create a null (nothing in Visual Basic) IntPtr
        // to pass to the SHAutoComplete method.  Doing so
        // creates a failure and demonstrates the two ways  
        // that the PreserveSig property allows you to handle 
        // failures.  
        // Normally, you would pass a handle to a managed
        // Windows Forms text box.
        IntPtr iPtr = new IntPtr(0);

        // Call the SHAutoComplete function using exceptions.
        try
        {
            Console.WriteLine("Calling the SHAutoComplete method with the PreserveSig
 field set to false.");

            Win32.SHAutoComplete(iPtr, Win32.SHAutoCompleteFlags.SHACF_DEFAULT);
        }
        catch (Exception e)
        {
            Console.WriteLine("Exception handled: " + e.Message);
        }

        Console.WriteLine("Calling the SHAutoComplete method with the PreserveSig
 field set to true.");

        // Call the SHAutoComplete function using HRESULTS.
        int HRESULT = Win32.SHAutoCompleteHRESULT(iPtr, Win32.SHAutoCompleteFlags.SHACF_DEFAULT);

        Console.WriteLine("HRESULT handled: " + HRESULT.ToString());


    }
}

プラットフォーム

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

開発プラットフォームの中には、.NET Framework によってサポートされていないバージョンがあります。サポートされているバージョンについては、「システム要件」を参照してください。

バージョン情報

.NET Framework
サポート対象 : 2.0、1.1、1.0
.NET Compact Framework
サポート対象 : 2.0

参照

関連項目
DllImportAttribute クラス
DllImportAttribute メンバ
System.Runtime.InteropServices 名前空間
PreserveSigAttribute