Convenciones para Prototipos de función

  • Artículo

Windows SDK proporciona prototipos de función en versiones genéricas, páginas de códigos de Windows y Unicode . Los prototipos se pueden compilar para generar prototipos de página de códigos de Windows o prototipos unicode. Los tres prototipos se describen en este tema y se ilustran mediante ejemplos de código para la función SetWindowText .

A continuación se muestra un ejemplo de un prototipo genérico:

BOOL SetWindowText(
  HWND hwnd,
  LPCTSTR lpText
);

El archivo de encabezado proporciona el nombre de función genérico implementado como una macro.

#ifdef UNICODE
#define SetWindowText SetWindowTextW
#else
#define SetWindowText SetWindowTextA
#endif // !UNICODE

El preprocesador expande la macro en la página de códigos de Windows o en el nombre de la función Unicode. La letra "A" (ANSI) o "W" (Unicode) se agrega al final del nombre de la función genérica, según corresponda. A continuación, el archivo de encabezado proporciona dos prototipos específicos, uno para las páginas de códigos de Windows y otro para Unicode, como se muestra en los ejemplos siguientes.

BOOL SetWindowTextA(
  HWND hwnd,
  LPCSTR lpText
);

BOOL SetWindowTextW(
  HWND hwnd,
  LPCWSTR lpText
);

Como se explica en Tipos de datos de Windows para cadenas, el prototipo de función genérica usa el tipo de datos LPCTSTR para el parámetro de texto. Sin embargo, el prototipo de la página de códigos de Windows utiliza el tipo LPCSTR, y el prototipo Unicode utiliza LPCWSTR.

Para todas las características con argumentos de texto, las aplicaciones deben utilizar normalmente los prototipos genéricos de la función. Si una aplicación define "UNICODE" antes de las instrucciones #include para los archivos de encabezado o durante la compilación, las instrucciones se compilarán en funciones Unicode.

Nota

Las nuevas aplicaciones de Windows deben usar Unicode para evitar las incoherencias de páginas de códigos variadas y para facilitar la localización. Deben escribirse con funciones genéricas y deben definir UNICODE para compilar las funciones en funciones Unicode. En los pocos lugares donde una aplicación debe trabajar con datos de caracteres de 8 bits, puede hacer uso explícito de las funciones para las páginas de códigos de Windows.

 

La aplicación debe utilizar siempre un prototipo genérico de la función con cadena y tipos de caracteres genéricos. Todos los nombres de funciones que terminen con una “W” mayúscula utilizan Unicode, es decir, carácter, parámetros anchos. Algunas funciones solo existen en versiones Unicode y solo se pueden usar con los tipos de datos adecuados. Por ejemplo, LCIDToLocaleName y LocaleNameToLCID solo tienen versiones Unicode.

La sección Requisitos de la documentación de referencia de cada función Unicode y juego de caracteres proporciona información sobre las versiones de función implementadas por los sistemas operativos compatibles. Si se incluye una línea que comienza con "Unicode", la función tiene versiones independientes de página de códigos Unicode y Windows.

Nota

Cuando una función tiene un parámetro de longitud para una cadena de caracteres, la longitud debe documentarse como un recuento de valores TCHAR en la cadena. Este tipo de datos hace referencia a bytes para las versiones de página de códigos de Windows de la función o palabras de 16 bits para versiones Unicode. Sin embargo, las funciones que requieren o devuelven punteros a bloques de memoria sin tipo, como la función GlobalAlloc , generalmente toman un tamaño en bytes, independientemente del prototipo que se use. Si la asignación de memoria sin tipo es para una cadena, la aplicación debe multiplicar el número de caracteres por sizeof(TCHAR). Para obtener más información, consulte Uso de tipos de datos genéricos.

 

Unicode en la API de Windows