Visão geral de marshaling no C++/CLI

  • Artigo

No modo misto, às vezes você deve fazer marshaling dos dados entre tipos nativos e gerenciados. A biblioteca de marshaling ajuda você a fazer marshaling e converter dados de maneira simples. A biblioteca de marshaling consiste em um conjunto de funções e uma classe marshal_context que executa marshaling para tipos comuns. A biblioteca é definida nesses cabeçalhos no diretório include/msclr para sua edição do Visual Studio:

parâmetro Descrição
marshal.h Classe marshal_context e funções de marshaling sem contexto
marshal_atl.h Funções para marshaling de tipos ATL
marshal_cppstd.h Funções para marshaling de tipos C++ padrão
marshal_windows.h Funções para marshaling de tipos Windows

O caminho padrão para a pasta msclr é semelhante ao seguinte, dependendo de qual edição você tem e do número de build:

C:\\Program Files (x86)\\Microsoft Visual Studio\\Preview\\Enterprise\\VC\\Tools\\MSVC\\14.15.26528\\include\\msclr

Você pode usar a biblioteca de marshaling com ou sem uma classe marshal_context. Algumas conversões exigem um contexto. Outras conversões podem ser implementadas usando a função marshal_as. A seguinte tabela lista as conversões compatíveis atuais, se elas exigem ou não um contexto e qual arquivo de marshal você precisa incluir:

Tipo From Tipo To Método marshal Incluir arquivo
System::String^ const char * marshal_context marshal.h
const char * System::String^ marshal_as marshal.h
char * System::String^ marshal_as marshal.h
System::String^ const wchar_t* marshal_context marshal.h
const wchar_t* System::String^ marshal_as marshal.h
wchar_t * System::String^ marshal_as marshal.h
System::IntPtr HANDLE marshal_as marshal_windows.h
HANDLE System::IntPtr marshal_as marshal_windows.h
System::String^ BSTR marshal_context marshal_windows.h
BSTR System::String^ marshal_as marshal.h
System::String^ bstr_t marshal_as marshal_windows.h
bstr_t System::String^ marshal_as marshal_windows.h
System::String^ std::string marshal_as marshal_cppstd.h
std::string System::String^ marshal_as marshal_cppstd.h
System::String^ std::wstring marshal_as marshal_cppstd.h
std::wstring System::String^ marshal_as marshal_cppstd.h
System::String^ CStringT<char> marshal_as marshal_atl.h
CStringT<char> System::String^ marshal_as marshal_atl.h
System::String^ CStringT<wchar_t> marshal_as marshal_atl.h
CStringT<wchar_t> System::String^ marshal_as marshal_atl.h
System::String^ CComBSTR marshal_as marshal_atl.h
CComBSTR System::String^ marshal_as marshal_atl.h

O marshaling requer um contexto somente quando você faz marshal de tipos de dados gerenciados para nativos e o tipo nativo para o qual você está convertendo não tem um destruidor para limpeza automática. O contexto de marshaling destrói o tipo de dados nativo alocado no destruidor dele. Portanto, as conversões que exigem um contexto serão válidas somente até que o contexto seja excluído. Para salvar quaisquer valores que passem por marshaling, você precisa copiar os valores para as suas variáveis.

Observação

Se você tiver NULLs inseridos em sua cadeia de caracteres, o resultado do marshaling da cadeia de caracteres não será garantido. Os NULLs inseridos podem fazer com que a cadeia de caracteres seja truncada ou elas podem ser preservadas.

Este exemplo mostra como incluir o diretório msclr em uma declaração de cabeçalho de inclusão:

#include "msclr\marshal_cppstd.h"

A biblioteca de marshaling é extensível para que você possa adicionar seus tipos de marshaling. Para obter mais informações sobre como estender a biblioteca de marshaling, confira Como estender a biblioteca de marshaling.

Confira também

Biblioteca de suporte do C++
Como estender a biblioteca de marshaling