Cálculo de referencias predeterminado para cadenas

Las clases System.String y System.Text.StringBuilder tienen un comportamiento de cálculo de referencias similar.

Las referencias de cadenas se calculan como un tipo BSTR de estilo COM o como una matriz de caracteres que termina en una referencia null (Nothing en Visual Basic). Las referencias de los caracteres con la cadena pueden calcularse como Unicode o ANSI, o en función de la plataforma: Unicode en Microsoft Windows NT, Windows 2000 y Windows XP; ANSI en Windows 98 y Windows Millennium (Windows Me).

En este tema se ofrece la siguiente información sobre el cálculo de referencias de tipos de cadena:

• Cadenas utilizadas en interfaces

• Cadenas utilizadas en invocación de plataforma

• Cadenas utilizadas en estructuras

• Búferes de cadenas de longitud fija

Cadenas utilizadas en interfaces

En la tabla siguiente se muestran las opciones de cálculo de referencias para el tipo de datos String cuando se calculan las referencias como un argumento de método para código no administrado. El atributo MarshalAsAttribute proporciona varios valores de la enumeración UnmanagedType para calcular las referencias de cadenas a interfaces COM.

Esta tabla se aplica a las cadenas. Sin embargo, para StringBuilder, las únicas opciones que se permiten son UnmanagedType.LPStr y UnmanagedType.LPWStr.

En el ejemplo siguiente se muestran las cadenas declaradas en la interfaz IStringWorker.

public interface IStringWorker {
void PassString1(String s);
void PassString2([MarshalAs(UnmanagedType.BStr)]String s);
void PassString3([MarshalAs(UnmanagedType.LPStr)]String s);
void PassString4([MarshalAs(UnmanagedType.LPWStr)]String s);
void PassStringRef1(ref String s);
void PassStringRef2([MarshalAs(UnmanagedType.BStr)]ref String s);
void PassStringRef3([MarshalAs(UnmanagedType.LPStr)]ref String s);
void PassStringRef4([MarshalAs(UnmanagedType.LPWStr)]ref String s);
);

En el ejemplo siguiente se muestra la interfaz correspondiente descrita en una biblioteca de tipos.

[…]
interface IStringWorker : IDispatch {
HRESULT PassString1([in] BSTR s);
HRESULT PassString2([in] BSTR s);
HRESULT PassString3([in] LPStr s);
HRESULT PassString4([in] LPWStr s);
HRESULT PassStringRef1([in, out] BSTR *s);
HRESULT PassStringRef2([in, out] BSTR *s);
HRESULT PassStringRef3([in, out] LPStr *s);
HRESULT PassStringRef4([in, out] LPWStr *s);
);

Cadenas utilizadas en invocación de plataforma

La invocación de plataforma copia argumentos de cadena y convierte el formato de .NET Framework (Unicode) al formato no administrado de la plataforma. Las cadenas son inmutables y no se copian de la memoria no administrada a la memoria administrada al volver de la llamada.

En la tabla siguiente se muestran las opciones de cálculo de referencias para cadenas cuando las referencias se calculan como un argumento de método de una llamada de invocación de plataforma. El atributo MarshalAsAttribute proporciona varios valores de la enumeración UnmanagedType para calcular las referencias de cadenas.

Esta tabla se aplica a las cadenas. Sin embargo, para StringBuilder, las únicas opciones que se permiten son LPStr, LPTStr y LPWStr.

En la definición de tipo siguiente se muestra el uso correcto de MarshalAsAttribute en llamadas de invocación de plataforma.

Class StringLibAPI    
Public Declare Auto Sub PassLPStr Lib "StringLib.Dll" _
(<MarshalAs(UnmanagedType.LPStr)> s As String)    
Public Declare Auto Sub PassLPWStr Lib "StringLib.Dll" _
(<MarshalAs(UnmanagedType.LPWStr)> s As String)    
Public Declare Auto Sub PassLPTStr Lib "StringLib.Dll" _
(<MarshalAs(UnmanagedType.LPTStr)> s As String)    
Public Declare Auto Sub PassBStr Lib "StringLib.Dll" _
(<MarshalAs(UnmanagedType.BStr)> s As String)    
Public Declare Auto Sub PassAnsiBStr Lib "StringLib.Dll" _
(<MarshalAs(UnmanagedType.AnsiBStr)> s As String)    
Public Declare Auto Sub PassTBStr Lib "StringLib.Dll" _
(<MarshalAs(UnmanagedType.TBStr)> s As String)
End Class

class StringLibAPI {
[DllImport("StringLib.Dll")]
public static extern void PassLPStr([MarshalAs(UnmanagedType.LPStr)]
String s);
[DllImport("StringLib.Dll")]
public static extern void 
PassLPWStr([MarshalAs(UnmanagedType.LPWStr)]String s);
[DllImport("StringLib.Dll")]
public static extern void 
PassLPTStr([MarshalAs(UnmanagedType.LPTStr)]String s);
[DllImport("StringLib.Dll")]
public static extern void PassBStr([MarshalAs(UnmanagedType.BStr)]
String s);
[DllImport("StringLib.Dll")]
public static extern void 
PassAnsiBStr([MarshalAs(UnmanagedType.AnsiBStr)]String s);
[DllImport("StringLib.Dll")]
public static extern void PassTBStr([MarshalAs(UnmanagedType.TBStr)]
String s);
}

Cadenas utilizadas en estructuras

Las cadenas son miembros válidos de las estructuras; sin embargo, los búferes StringBuilder no son válidos en las estructuras. En la tabla siguiente se muestran las opciones de cálculo de referencias para el tipo de datos String cuando se calculan las referencias del tipo como un campo. El atributo MarshalAsAttribute proporciona varios valores de la enumeración UnmanagedType para calcular las referencias de cadenas a un campo.

El tipo ByValTStr se utiliza para matrices insertadas de caracteres de longitud fija que aparecen dentro de una estructura. Otros tipos se aplican a referencias de cadena que se encuentran en estructuras que contienen punteros a cadenas.

El argumento CharSet del atributo StructLayoutAttribute que se aplica a la estructura contenedora determina el formato de los caracteres de cadena en las estructuras. Las siguientes estructuras de ejemplo contienen referencias de cadena y cadenas en línea, así como caracteres ANSI, Unicode y dependientes de la plataforma.

Representación de biblioteca de tipos

struct StringInfoA {
   char *    f1;
   char      f2[256];
};
struct StringInfoW {
   WCHAR *   f1;
   WCHAR     f2[256];
   BSTR      f3;
};
struct StringInfoT {
   TCHAR *   f1;
   TCHAR     f2[256];
};

En el ejemplo de código siguiente se muestra cómo utilizar el atributo MarshalAsAttribute para definir la misma estructura en diferentes formatos.

<StructLayout(LayoutKind.Sequential, CharSet := CharSet.Ansi)> _
Structure StringInfoA
<MarshalAs(UnmanagedType.LPStr)> Public f1 As String
<MarshalAs(UnmanagedType.ByValTStr, SizeConst := 256)> _
Public f2 As String
End Structure
<StructLayout(LayoutKind.Sequential, CharSet := CharSet.Unicode)> _
Structure StringInfoW
<MarshalAs(UnmanagedType.LPWStr)> Public f1 As String
<MarshalAs(UnmanagedType.ByValTStr, SizeConst := 256)> _
Public f2 As String
<MarshalAs(UnmanagedType.BStr)> Public f3 As String
End Structure
<StructLayout(LayoutKind.Sequential, CharSet := CharSet.Auto)> _
Structure StringInfoT
<MarshalAs(UnmanagedType.LPTStr)> Public f1 As String
<MarshalAs(UnmanagedType.ByValTStr, SizeConst := 256)> _
Public f2 As String
End Structure

[StructLayout(LayoutKind.Sequential, CharSet=CharSet.Ansi)]
struct StringInfoA {
   [MarshalAs(UnmanagedType.LPStr)] public String f1;
   [MarshalAs(UnmanagedType.ByValTStr, SizeConst=256)] public String f2;
}
[StructLayout(LayoutKind.Sequential, CharSet=CharSet.Unicode)]
struct StringInfoW {
   [MarshalAs(UnmanagedType.LPWStr)] public String f1;
   [MarshalAs(UnmanagedType.ByValTStr, SizeConst=256)] public String f2;
   [MarshalAs(UnmanagedType.BStr)] public String f3;
}
[StructLayout(LayoutKind.Sequential, CharSet=CharSet.Auto)]
struct StringInfoT {
   [MarshalAs(UnmanagedType.LPTStr)] public String f1;
   [MarshalAs(UnmanagedType.ByValTStr, SizeConst=256)] public String f2;
}

Búferes de cadenas de longitud fija

En algunas circunstancias, para manipular un búfer de caracteres de longitud fija se debe pasar a código no administrado. No basta sólo con pasar una cadena en este caso, ya que el destinatario de la llamada no puede modificar el contenido del búfer pasado. Aunque se pase la cadena por referencia, no hay modo de inicializar el búfer con un tamaño determinado.

La solución consiste en pasar un búfer StringBuilder como argumento en lugar de una cadena. El destinatario de la llamada puede desreferenciar un generador StringBuilder y modificarlo, siempre que no supere la capacidad del generador StringBuilder. También puede inicializarse con una longitud fija. Por ejemplo, si inicializa un búfer StringBuilder para una capacidad de N, el contador de referencias proporcionará un búfer de caracteres con el tamaño N+1. El incremento en uno se debe a que la cadena no administrada tiene un terminador null, a diferencia de StringBuilder, que no lo tiene.

Por ejemplo, la función GetWindowText de la API Win32 de Microsoft (definida en Windows.h) es un búfer de caracteres de longitud fija que debe pasarse a código no administrado para que pueda manipularse. LpString apunta a un búfer asignado a un llamador de tamaño nMaxCount. Se espera que el llamador asigne el búfer y establezca el argumento nMaxCount al tamaño del búfer asignado. En el código siguiente se muestra la declaración de la función GetWindowText tal y como se define en Windows.h.

int GetWindowText(
HWND hWnd,        // Handle to window or control.
LPTStr lpString,  // Text buffer.
int nMaxCount     // Maximum number of characters to copy.
);

El destinatario de la llamada puede desreferenciar un generador StringBuilder y modificarlo, siempre que no supere la capacidad del generador StringBuilder. En el ejemplo de código siguiente se muestra cómo puede inicializarse StringBuilder con una longitud fija.

Public Class Win32API
Public Declare Auto Sub GetWindowText Lib "User32.Dll" _
(h As Integer, s As StringBuilder, nMaxCount As Integer)
End Class
Public Class Window
   Friend h As Integer ' Friend handle to Window.
   Public Function GetText() As String
      Dim sb As New StringBuilder(256)
      Win32API.GetWindowText(h, sb, sb.Capacity + 1)
   Return sb.ToString()
   End Function
End Class

public class Win32API {
[DllImport("User32.Dll")]
public static extern void GetWindowText(int h, StringBuilder s, 
int nMaxCount);
}
public class Window {
   internal int h;        // Internal handle to Window.
   public String GetText() {
      StringBuilder sb = new StringBuilder(256);
      Win32API.GetWindowText(h, sb, sb.Capacity + 1);
   return sb.ToString();
   }
}

Vea también

Conceptos

Tipos que pueden o que no pueden representarse como bits o bytes

Atributos direccionales

Copiar y fijar

Otros recursos

Comportamiento del cálculo de referencias predeterminado