Partilhar via

Especificar um conjunto de caracteres

  • Artigo

O DllImportAttribute.CharSet campo controla a organização de cadeia de caracteres e determina como a invocação de plataforma localiza nomes de função em uma DLL. Este tópico descreve ambos os comportamentos.

Algumas APIs exportam duas versões de funções que usam argumentos de cadeia de caracteres: narrow (ANSI) e wide (Unicode). A API do Windows, por exemplo, inclui os seguintes nomes de ponto de entrada para a função MessageBox :

  • MessageBoxA

    Fornece formatação ANSI de caractere de 1 byte, distinguida por um "A" anexado ao nome do ponto de entrada. Chamadas para MessageBoxA sempre marshal strings no formato ANSI.

  • MessageBoxW

    Fornece formatação Unicode de caracteres de 2 bytes, distinguida por um "W" anexado ao nome do ponto de entrada. Chamadas para MessageBoxW sempre marshal strings em formato Unicode.

Marshalling de cadeias de caracteres e correspondência de nomes

O CharSet campo aceita os seguintes valores:

Ansi (valor padrão)

  • Marshalling de cordas

    A plataforma invoca cadeias de caracteres de marechais de seu formato gerenciado (Unicode) para o formato ANSI.

  • Correspondência de nomes

    Quando o DllImportAttribute.ExactSpelling campo é true, como é por padrão no Visual Basic, a plataforma invoca pesquisas apenas para o nome que você especificar. Por exemplo, se você especificar MessageBox, a plataforma invocará pesquisas por MessageBox e falhará quando não conseguir localizar a ortografia exata.

    Quando o ExactSpelling campo é false, como é por padrão em C++ e C#, a plataforma invoca a pesquisa primeiro o alias não manipulado (MessageBox) e, em seguida, o nome manipulado (MessageBoxA) se o alias não manipulado não for encontrado. Observe que o comportamento de correspondência de nome ANSI difere do comportamento de correspondência de nome Unicode.

Unicode

  • Marshalling de cordas

    A plataforma invoca cópias de cadeias de caracteres de seu formato gerenciado (Unicode) para o formato Unicode.

  • Correspondência de nomes

    Quando o ExactSpelling campo é true, como é por padrão no Visual Basic, a plataforma invoca pesquisas apenas para o nome que você especificar. Por exemplo, se você especificar MessageBox, a plataforma invocará pesquisas por MessageBox e falhará se não conseguir localizar a ortografia exata.

    Quando o ExactSpelling campo é false, como é por padrão em C++ e C#, a plataforma invoca primeiro o nome mutilado (MessageBoxW) e, em seguida, o alias não manipulado (MessageBox) se o nome distorcido não for encontrado. Observe que o comportamento de correspondência de nome Unicode difere do comportamento de correspondência de nome ANSI.

Auto

  • A invocação da plataforma escolhe entre os formatos ANSI e Unicode em tempo de execução, com base na plataforma de destino.

Especificar um conjunto de caracteres no Visual Basic

Você pode especificar o comportamento do conjunto de caracteres no Visual Basic adicionando a AnsiUnicode, ou Auto palavra-chave à instrução de declaração. Se você omitir a palavra-chave do conjunto de caracteres, o campo assumirá DllImportAttribute.CharSet como padrão o conjunto de caracteres ANSI.

O exemplo a seguir declara a função MessageBox três vezes, cada vez com comportamento de conjunto de caracteres diferente. A primeira instrução omite a palavra-chave do conjunto de caracteres, portanto, o padrão do conjunto de caracteres é ANSI. A segunda e terceira instruções especificam explicitamente um conjunto de caracteres com uma palavra-chave.

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

Especificar um conjunto de caracteres em C# e C++

O DllImportAttribute.CharSet campo identifica o conjunto de caracteres subjacente como ANSI ou Unicode. O conjunto de caracteres controla como os argumentos de cadeia de caracteres para um método devem ser empacotados. Use um dos seguintes formulários para indicar o conjunto de caracteres:

[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)]

O exemplo a seguir mostra três definições gerenciadas da função MessageBox atribuída para especificar um conjunto de caracteres. Na primeira definição, por sua omissão, o CharSet campo assume como padrão o conjunto de caracteres ANSI.

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);

Consulte também