Método Marshal.StringToHGlobalAnsi (String)

Artigo
04/23/2018

Dica

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Copia o conteúdo de um String gerenciado para a memória não gerenciada, convertendo em formato ANSI durante a cópia.

Namespace: System.Runtime.InteropServices
Assembly: mscorlib (em mscorlib.dll)

Sintaxe

[SecurityCriticalAttribute]
public static IntPtr StringToHGlobalAnsi(
    string s
)

public:
[SecurityCriticalAttribute]
static IntPtr StringToHGlobalAnsi(
    String^ s
)

[<SecurityCriticalAttribute>]
static member StringToHGlobalAnsi : 
        s:string -> nativeint

<SecurityCriticalAttribute>
Public Shared Function StringToHGlobalAnsi (
    s As String
) As IntPtr

Parâmetros

s
Type: System.String

Uma cadeia de caracteres gerenciada a ser copiada.

Valor Retornado

Type: System.IntPtr

O endereço, na memória não gerenciada, para o qual s foi copiado ou 0 se s for null.

Exceções

Exception	Condition
OutOfMemoryException	Não há memória suficiente disponível.
ArgumentOutOfRangeException	O parâmetro s excede o tamanho máximo permitido pelo sistema operacional.

Comentários

StringToHGlobalAnsié útil para empacotamento personalizado ou mistura de código gerenciado e não gerenciado. Como esse método aloca a memória não gerenciada, necessária para uma cadeia de caracteres, sempre liberar a memória chamando FreeHGlobal.StringToHGlobalAnsifornece a funcionalidade oposta do Marshal.PtrToStringAnsi.

Esse método copia caracteres nulos inseridos e inclui um caractere null de terminação.

Exemplos

O exemplo a seguir demonstra como converter o conteúdo de um gerenciado String classe a memória não gerenciada e, em seguida, descarte a memória não gerenciada quando terminar.

using System;
using System.Runtime.InteropServices;

class MainFunction
{
    static void Main()
    {
    Console.WriteLine("\nStringToGlobalAnsi\n");

    // Create a managed string.
    String  managedString = "I am a managed String";
    Console.WriteLine("1) managedString = " + managedString );

    // Marshal the managed string to unmanaged memory.
    IntPtr stringPointer = (IntPtr)Marshal.StringToHGlobalAnsi(managedString);
    Console.WriteLine("2) stringPointer = {0}", stringPointer );

    // Get the string back from unmanaged memory
    String RetrievedString = Marshal.PtrToStringAnsi( stringPointer);
    Console.WriteLine("3) Retrieved from unmanaged memory = " + RetrievedString );

    // Always free the unmanaged string.
    Marshal.FreeHGlobal(stringPointer);

    // IntPtr handle value is still the same:
    Console.WriteLine("4) stringPointer = " + stringPointer );

    // However, it contains no data after being freed:
    String RetrievedString2 = Marshal.PtrToStringAnsi( stringPointer);
    Console.WriteLine("5) RetrievedString2 = " + RetrievedString2 );
    }
}

using namespace System;
using namespace System::Runtime::InteropServices;

#include <iostream>                                                 // for printf


int main()
{
    // Create a managed string.
    String^ managedString = "Hello unmanaged world (from the managed world).";

    // Marshal the managed string to unmanaged memory.
    char* stringPointer = (char*) Marshal::StringToHGlobalAnsi(managedString ).ToPointer();

    printf("stringPointer = %s\n", stringPointer);

    // Always free the unmanaged string.
    Marshal::FreeHGlobal(IntPtr(stringPointer));

    return 0;
}

Segurança

SecurityCriticalAttribute

requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.

Informações de Versão

Plataforma Universal do Windows
Disponível desde 8
.NET Framework
Disponível desde 1.1
Biblioteca de Classes Portátil
Com suporte no: plataformas portáteis do .NET
Windows Phone
Disponível desde 8.1

Confira Também

FreeCoTaskMem
PtrToStringAnsi
Classe Marshal
Namespace System.Runtime.InteropServices

Retornar ao início

Compartilhar via