Función SHAnsiToUnicode (shlwapi.h)

2023-03-15

[Esta función está disponible a través de Windows XP y Windows Server 2003. Es posible que se modifique o no esté disponible en versiones posteriores de Windows.

Convierte una cadena de la página de códigos ANSI en la página de códigos Unicode.

Sintaxis

int SHAnsiToUnicode(
  [in]  PCSTR pszSrc,
  [out] PWSTR pwszDst,
        int   cwchBuf
);

Parámetros

[in] pszSrc

Tipo: PCSTR

Puntero a una cadena ANSI terminada en null que se va a convertir en Unicode.

[out] pwszDst

Tipo: PWSTR

Puntero a un búfer que, cuando esta función devuelve correctamente, recibe la cadena especificada por pszSrc, después de que los caracteres ANSI se hayan convertido en Unicode (WCHAR). El búfer debe ser lo suficientemente grande como para contener el número de caracteres Unicode especificados por el parámetro cwchBuf , incluido un carácter nulo de terminación.

cwchBuf

Tipo: int

Número de caracteres Unicode que puede contener el búfer al que apunta pwszDst. Este parámetro debe ser mayor que cero.

Valor devuelto

Tipo: int

Devuelve el número de caracteres Unicode escritos en pwszDst, incluido el carácter nulo de terminación. Devuelve 0 si no se realiza correctamente.

Comentarios

Advertencia de seguridad: El uso incorrecto de esta función puede poner en peligro la seguridad de la aplicación. Por ejemplo, si el búfer pwszDst no es lo suficientemente grande como para contener el número de caracteres especificados por cwchBuf, puede producirse una saturación del búfer. Las saturaciones de búfer pueden provocar un ataque de denegación de servicio contra una aplicación si se produce una infracción de acceso. En el peor de los casos, una saturación de búfer podría permitir que un atacante inserte código ejecutable en el proceso, especialmente si pwszDst es un búfer basado en pila. Al copiar una cadena completa, tenga en cuenta que sizeof devuelve el número de bytes, que no es el valor correcto que se va a usar para el parámetro cwchBuf . En su lugar, use sizeof(pwszDst)/sizeof(WCHAR). Tenga en cuenta que esta técnica supone que pwszDst es una matriz, no un puntero.

Si el búfer pwszDst no es lo suficientemente grande como para contener toda la cadena de salida convertida, la cadena se trunca para ajustarse al búfer. No hay ninguna manera de detectar que la cadena de devolución se ha truncado. La cadena siempre termina en null, incluso si se ha truncado. Esto garantiza que no se copien más de caracteres cwchBuf en pwszDst. No se intenta evitar truncar la cadena en medio de un par suplente Unicode.

Si los búferes pszSrc y pwszDst se superponen, el comportamiento de la función no está definido.

Nota No suponga que la función no ha cambiado ninguno de los caracteres del búfer de salida que siguen al carácter nulo de terminación de la cadena. El contenido del búfer de salida que sigue al carácter NULO de terminación de la cadena no está definido, hasta el último carácter del búfer e incluye el último carácter del búfer.

SHAnsiToTChar se define como el mismo que SHAnsiToUnicode.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server, Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shlwapi.h
Archivo DLL	Shlwapi.dll (versión 5.0 o posterior)