文字セットの指定Specifying a Character Set

DllImportAttribute.CharSet フィールドは文字列のマーシャリングを制御し、DLL の関数名をプラットフォーム呼び出しが見つけるしくみを決定します。The DllImportAttribute.CharSet field controls string marshaling and determines how platform invoke finds function names in a DLL. このトピックでは、両方の動作について説明します。This topic describes both behaviors.

一部の API は、文字列引数、ナロー (ANSI) とワイド (Unicode) を受け取る 2 種類の関数をエクスポートします。Some APIs export two versions of functions that take string arguments: narrow (ANSI) and wide (Unicode). たとえば、Windows API には、MessageBox 関数の次のエントリ ポイント名が含まれています。The Windows API, for instance, includes the following entry-point names for the MessageBox function:

  • MessageBoxAMessageBoxA

    1 バイト文字の ANSI 書式設定を提供します。エントリ ポイント名に "A" が追加されます。Provides 1-byte character ANSI formatting, distinguished by an "A" appended to the entry-point name. MessageBoxA を呼び出すと、常に ANSI 形式で文字列がマーシャリングされます。Calls to MessageBoxA always marshal strings in ANSI format.

  • MessageBoxWMessageBoxW

    2 バイト文字の Unicode 書式設定を提供します。エントリ ポイント名に "W" が追加されます。Provides 2-byte character Unicode formatting, distinguished by a "W" appended to the entry-point name. MessageBoxW を呼び出すと、常に Unicode 形式で文字列がマーシャリングされます。Calls to MessageBoxW always marshal strings in Unicode format.

文字列のマーシャリングと名前の一致String Marshaling and Name Matching

CharSet フィールドは次の値を受け取ります。The CharSet field accepts the following values:

Ansi (既定値)Ansi (default value)

  • 文字列のマーシャリングString marshaling

    プラットフォーム呼び出しは、その管理対象形式 (Unicode) から ANSI 形式に文字列をマーシャリングします。Platform invoke marshals strings from their managed format (Unicode) to ANSI format.

  • 名前の一致Name matching

    DllImportAttribute.ExactSpelling フィールドが true の場合 (Visual Basic ではこれが既定値)、プラットフォーム呼び出しによって指定した名前のみが検索されます。When the DllImportAttribute.ExactSpelling field is true, as it is by default in Visual Basic, platform invoke searches only for the name you specify. たとえば、MessageBox を指定した場合、プラットフォーム呼び出しは MessageBox を検索し、厳密に一致する綴りが見つからない場合、検索失敗となります。For example, if you specify MessageBox, platform invoke searches for MessageBox and fails when it cannot locate the exact spelling.

    ExactSpelling フィールドが false のとき (C++ と C# で既定)、プラットフォーム呼び出しは最初に修飾なしのエイリアスを探し (MessageBox)、見つからなければ、修飾ありの名前を探します (MessageBoxA)。When the ExactSpelling field is false, as it is by default in C++ and C#, platform invoke searches for the unmangled alias first (MessageBox), then the mangled name (MessageBoxA) if the unmangled alias is not found. ANSI の名前一致動作と Unicode の名前一致動作は異なることにご注意ください。Notice that ANSI name-matching behavior differs from Unicode name-matching behavior.

Unicode

  • 文字列のマーシャリングString marshaling

    プラットフォーム呼び出しは、その管理対象形式 (Unicode) から Unicode 形式に文字列をコピーします。Platform invoke copies strings from their managed format (Unicode) to Unicode format.

  • 名前の一致Name matching

    ExactSpelling フィールドが true の場合 (Visual Basic ではこれが既定値)、プラットフォーム呼び出しによって指定した名前のみが検索されます。When the ExactSpelling field is true, as it is by default in Visual Basic, platform invoke searches only for the name you specify. たとえば、MessageBox を指定した場合、プラットフォーム呼び出しは MessageBox を検索し、厳密に一致する綴りが見つからない場合、検索失敗となります。For example, if you specify MessageBox, platform invoke searches for MessageBox and fails if it cannot locate the exact spelling.

    ExactSpelling フィールドが false のとき (C++ と C# で既定)、プラットフォーム呼び出しは最初に修飾ありの名前を探し (MessageBoxW)、見つからなければ、修飾なしのエイリアスを探します (MessageBox)。When the ExactSpelling field is false, as it is by default in C++ and C#, platform invoke searches for the mangled name first (MessageBoxW), then the unmangled alias (MessageBox) if the mangled name is not found. Unicode の名前一致動作と ANSI の名前一致動作は異なることにご注意ください。Notice that Unicode name-matching behavior differs from ANSI name-matching behavior.

Auto

  • プラットフォーム呼び出しは、対象プラットフォームに基づき、ANSI 形式または Unicode 形式を選択します。Platform invoke chooses between ANSI and Unicode formats at run time, based on the target platform.

Visual Basic で文字セットを指定するSpecifying a Character Set in Visual Basic

次の例では MessageBox 関数を 3 回宣言しています。宣言のたびに文字セット動作が変わっています。The following example declares the MessageBox function three times, each time with different character-set behavior. Visual Basic では、文字セット動作を指定できます。宣言ステートメントにキーワードとして AnsiUnicodeAuto を追加します。You can specify character-set behavior in Visual Basic by adding the Ansi, Unicode, or Auto keyword to the declaration statement.

最初の宣言ステートメントのように、文字セット キーワードを省略した場合、DllImportAttribute.CharSet フィールドは既定で ANSI 文字セットに設定されます。If you omit the character-set keyword, as is done in the first declaration statement, the DllImportAttribute.CharSet field defaults to the ANSI character set. 例の 2 番目と 3 番目のステートメントは、キーワードで文字セットを明示的に指定しています。The second and third statements in the example explicitly specify a character set with a keyword.

Friend Class NativeMethods
    Friend Declare Function MessageBoxA Lib "user32.dll" (
        ByVal hWnd As IntPtr,
        ByVal lpText As String,
        ByVal lpCaption As String,
        ByVal uType As UInteger) As Integer

    Friend Declare Unicode Function MessageBoxW Lib "user32.dll" (
        ByVal hWnd As IntPtr,
        ByVal lpText As String,
        ByVal lpCaption As String,
        ByVal uType As UInteger) As Integer

    Friend Declare Auto Function MessageBox Lib "user32.dll" (
        ByVal hWnd As IntPtr,
        ByVal lpText As String,
        ByVal lpCaption As String,
        ByVal uType As UInteger) As Integer
End Class

C# と C++ で文字セットを指定するSpecifying a Character Set in C# and C++

DllImportAttribute.CharSet フィールドは、基礎となる文字セットとして ANSI または Unicode を識別します。The DllImportAttribute.CharSet field identifies the underlying character set as ANSI or Unicode. この文字セットは、メソッドの文字列引数をマーシャリングする方法を制御します。The character set controls how string arguments to a method should be marshaled. 次の形式の 1 つを使用し、文字セットを指示します。Use one of the following forms to indicate the character set:

[DllImport("DllName", CharSet = CharSet.Ansi)]
[DllImport("DllName", CharSet = CharSet.Unicode)]
[DllImport("DllName", CharSet = CharSet.Auto)]
[DllImport("DllName", CharSet = CharSet::Ansi)]
[DllImport("DllName", CharSet = CharSet::Unicode)]
[DllImport("DllName", CharSet = CharSet::Auto)]

次の例では、MessageBox 関数の 3 つの管理対象定義を確認できます。これにより文字セットが指定されます。The following example shows three managed definitions of the MessageBox function attributed to specify a character set. 最初の定義で、その省略により、CharSet フィールドは ANSI 文字セットに初期設定されます。In the first definition, by its omission, the CharSet field defaults to the ANSI character set.

using System;
using System.Runtime.InteropServices;

internal static class NativeMethods
{
    [DllImport("user32.dll")]
    internal static extern int MessageBoxA(
        IntPtr hWnd, string lpText, string lpCaption, uint uType);

    [DllImport("user32.dll", CharSet = CharSet.Unicode)]
    internal static extern int MessageBoxW(
        IntPtr hWnd, string lpText, string lpCaption, uint uType);

    [DllImport("user32.dll", CharSet = CharSet.Auto)]
    internal static extern int MessageBox(
        IntPtr hWnd, string lpText, string lpCaption, uint uType);
}
typedef void* HWND;

// Can use MessageBox or MessageBoxA.
[DllImport("user32")]
extern "C" int MessageBox(
    HWND hWnd, String* lpText, String* lpCaption, unsigned int uType);

// Can use MessageBox or MessageBoxW.
[DllImport("user32", CharSet = CharSet::Unicode)]
extern "C" int MessageBoxW(
    HWND hWnd, String* lpText, String* lpCaption, unsigned int uType);

// Must use MessageBox.
[DllImport("user32", CharSet = CharSet::Auto)]
extern "C" int MessageBox(
    HWND hWnd, String* lpText, String* lpCaption, unsigned int uType);

関連項目See also