Función WSAAsyncGetServByName (winsock.h)
La función WSAAsyncGetServByName recupera asincrónicamente la información del servicio que corresponde a un nombre de servicio y un puerto.
Sintaxis
HANDLE WSAAsyncGetServByName(
[in] HWND hWnd,
[in] u_int wMsg,
[in] const char *name,
[in] const char *proto,
[out] char *buf,
[in] int buflen
);
Parámetros
[in] hWnd
Identificador de la ventana que debe recibir un mensaje cuando se completa la solicitud asincrónica.
[in] wMsg
Mensaje que se va a recibir cuando se completa la solicitud asincrónica.
[in] name
Puntero a un nombre de servicio terminado en null.
[in] proto
Puntero a un nombre de protocolo. Puede ser NULL, en cuyo caso WSAAsyncGetServByName buscará la primera entrada de servicio para la que s_name o uno de los s_aliases coincide con el nombre especificado. De lo contrario, WSAAsyncGetServByName coincide con name y proto.
[out] buf
Puntero al área de datos para recibir los datos serventes . El área de datos debe ser mayor que el tamaño de una estructura servent porque Windows Sockets usa el área de datos para contener una estructura servent y todos los datos a los que hacen referencia los miembros de la estructura servent . Se recomienda un búfer de bytes MAXGETHOSTSTRUCT.
[in] buflen
Tamaño del área de datos para el parámetro buf , en bytes.
Valor devuelto
El valor devuelto especifica si la operación asincrónica se inició correctamente o no. No implica éxito o fracaso de la propia operación.
Si no se produce ningún error, WSAAsyncGetServByName devuelve un valor distinto de cero de tipo HANDLE que es el identificador de tarea asincrónico de la solicitud (no debe confundirse con un HTASK de Windows). Este valor se puede usar de dos maneras. Se puede usar para cancelar la operación mediante WSACancelAsyncRequest, o se puede usar para buscar coincidencias con las operaciones asincrónicas y los mensajes de finalización mediante el examen del parámetro de mensaje wParam .
Si no se pudo iniciar la operación asincrónica, WSAAsyncServByName devuelve un valor cero y se puede recuperar un número de error específico llamando a WSAGetLastError.
Los siguientes códigos de error se pueden establecer cuando una ventana de la aplicación recibe un mensaje. Como se ha descrito anteriormente, se pueden extraer de lParam en el mensaje de respuesta mediante la macro WSAGETASYNCERROR .
| Código de error | Significado |
|---|---|
| Error en el subsistema de red. | |
| No hay suficiente espacio en búfer disponible. | |
| El parámetro buf no está en una parte válida del espacio de direcciones del proceso. | |
| No se encontró el host de respuesta autoritativo. | |
| No se encontró el servicio no autenticado o error del servidor. | |
| Errores irrecuperables, la base de datos de servicios no es accesible. | |
| Nombre válido, sin registro de datos del tipo solicitado. |
Los errores siguientes pueden producirse en el momento de la llamada a la función e indicar que no se pudo iniciar la operación asincrónica.
| Código de error | Significado |
|---|---|
| WSANOTINITIALISED | Debe producirse una llamada WSAStartup correcta antes de usar esta función. |
| WSAENETDOWN | Error en el subsistema de red. |
| WSAEINPROGRESS | Una llamada de Bloqueo de Windows Sockets 1.1 está en curso o el proveedor de servicios sigue procesando una función de devolución de llamada. |
| WSAEWOULDBLOCK | La operación asincrónica no se puede programar en este momento debido a recursos u otras restricciones dentro de la implementación de Windows Sockets. |
Comentarios
La función WSAAsyncGetServByName es una versión asincrónica de getservbyname y se usa para recuperar la información del servicio correspondiente a un nombre de servicio. Windows Sockets inicia la operación y vuelve al autor de la llamada inmediatamente, pasando un identificador de tarea opaco y asincrónico que la aplicación puede usar para identificar la operación. Cuando se completa la operación, los resultados (si existen) se copian en el búfer proporcionado por el autor de la llamada y se envía un mensaje a la ventana de la aplicación.
Una vez completada la operación asincrónica, la ventana de la aplicación indicada por el parámetro hWnd recibe el mensaje en el parámetro wMsg . El parámetro wParam contiene el identificador de tarea asincrónico tal como lo devuelve la llamada de función original. Los 16 bits altos de lParam contienen cualquier código de error. El código de error puede ser cualquier error tal y como se define en Winsock2.h. Un código de error de cero indica que la operación asincrónica se completó correctamente.
Al finalizar correctamente, el búfer especificado en la llamada de función original contiene una estructura servent . Para acceder a los miembros de esta estructura, la dirección del búfer original debe convertirse a un puntero de estructura servent y tener acceso a ellos según corresponda.
Si el código de error es WSAENOBUFS, el tamaño del búfer especificado por buflen en la llamada original era demasiado pequeño para contener toda la información resultante. En este caso, los 16 bits bajos de lParam contienen el tamaño del búfer necesario para proporcionar toda la información necesaria. Si la aplicación decide que los datos parciales son inadecuados, puede volver a emitir la llamada de función WSAAsyncGetServByName con un búfer lo suficientemente grande como para recibir toda la información deseada (es decir, no menor que los 16 bits bajos de lParam).
Windows Sockets usa el búfer especificado para esta función para construir una estructura servent junto con el contenido de las áreas de datos a las que hacen referencia los miembros de la misma estructura servent . Para evitar el error WSAENOBUFS , la aplicación debe proporcionar un búfer de al menos MAXGETHOSTSTRUCT bytes (como se define en Winsock2.h).
El código de error y la longitud del búfer deben extraerse de lParam mediante las macros WSAGETASYNCERROR y WSAGETASYNCBUFLEN, definidas en Winsock2.h como:
#include <windows.h>
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)
El uso de estas macros maximizará la portabilidad del código fuente de la aplicación.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | winsock.h (incluya Winsock2.h) |
| Library | Ws2_32.lib |
| Archivo DLL | Ws2_32.dll |