Compartir a través de

Función WindowsCreateStringReference (winstring.h)

  • Artículo

Crea una nueva referencia de cadena basada en la cadena especificada.

Sintaxis

HRESULT WindowsCreateStringReference(
  PCWSTR         sourceString,
  UINT32         length,
  HSTRING_HEADER *hstringHeader,
  HSTRING        *string
);

Parámetros

sourceString

Tipo: [in] PCWSTR

Cadena terminada en NULL que se usará como origen para el nuevo HSTRING.

Un valor de NULL representa la cadena vacía, si el valor de longitud es 0. Debe asignarse en el marco de pila.

length

Tipo: [in] UINT32

Longitud de sourceString, en caracteres Unicode. Debe ser 0 si sourceString es NULL. Si es mayor que 0, sourceString debe tener un carácter nulo de terminación.

hstringHeader

Tipo: [out] HSTRING_HEADER*

Puntero a una estructura que el Windows Runtime usa para identificar la cadena como una referencia de cadena o una cadena de paso rápido.

string

Tipo: [out] HSTRING*

Puntero a la cadena recién creada o NULL si se produce un error. Se sobrescribe cualquier contenido existente en la cadena . HSTRING es un tipo de identificador estándar.

Valor devuelto

Tipo: HRESULT

Esta función puede devolver uno de estos valores.

Código devuelto Descripción
S_OK
 HSTRING se creó correctamente.
E_INVALIDARG
 String ohstringHeader es NULL o string no termina en null.
E_OUTOFMEMORY
 No se pudo asignar el nuevo HSTRING.
E_POINTER
 sourceString es NULL y length es distinto de cero.

Comentarios

Use la función WindowsCreateStringReference para crear un HSTRING a partir de una cadena existente. Este tipo de HSTRING se denomina cadena de paso rápido. A diferencia de un HSTRING creado por la función WindowsCreateString, el Windows Runtime no administra la duración del búfer de respaldo en el nuevo HSTRING. El autor de la llamada asigna sourceString en el marco de pila, junto con un HSTRING_HEADER sin inicializar, para evitar una asignación de montón y eliminar el riesgo de pérdida de memoria. El autor de la llamada debe asegurarse de que sourceString y el contenido de hstringHeader permanecen sin cambios durante la vigencia del HSTRING adjunto.

No es necesario llamar a la función WindowsDeleteString para desasignar un HSTRING de paso rápido creado por la función WindowsCreateStringReference .

Para crear un HSTRING vacío, pase NULL para sourceString y 0 para la longitud.

El Windows Runtime realiza un seguimiento de una cadena de paso rápido mediante una estructura HSTRING_HEADER, que se devuelve en el parámetro out hstringHeader. No cambie el contenido del HSTRING_HEADER.

Requisitos

   
Cliente mínimo compatible Windows 8 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2012 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado winstring.h

Consulte también

WindowsCreateString

WindowsDeleteString