Función ProcessSocketNotifications (winsock2.h)

  • Artículo

Asocia un conjunto de sockets a un puerto de finalización y recupera las notificaciones que ya están pendientes en ese puerto. Una vez asociado, el puerto de finalización recibe las notificaciones de estado del socket que se especificaron. Solo se admiten sockets de proveedor de Microsoft Winsock .

Para reducir la sobrecarga de llamadas del sistema, puede registrarse para recibir notificaciones y recuperarlas en una sola llamada a ProcessSocketNotifications. Como alternativa, puede recuperarlas explícitamente llamando a las funciones de puerto de finalización de E/S habituales, como GetQueuedCompletionStatus. Las notificaciones recuperadas mediante ProcessSocketNotifications son las mismas que las recuperadas mediante GetQueuedCompletionStatusEx, que podrían incluir paquetes de notificación distintos de los cambios de estado del socket.

Las marcas de evento de notificación son el valor entero de los campos dwNumberOfBytesTransferred de las estructuras de OVERLAPPED_ENTRY devueltas. Esto es similar al uso de JOBOBJECT_ASSOCIATE_COMPLETION_PORT, que también usa el campo dwNumberOfBytesTransferred para enviar mensajes enteros. Llame a la función SocketNotificationRetrieveEvents para obtenerlos.

Un identificador de socket solo se puede registrar en un IOCP cada vez. Al volver a registrar un identificador de socket registrado anteriormente, se sobrescribe el registro existente. Antes de cerrar un identificador usado para el registro, debe quitar explícitamente el registro y esperar a la notificación de SOCK_NOTIFY_EVENT_REMOVE (vea Comentarios en este tema).

Para obtener más información y ejemplos de código, consulte Notificaciones de estado de socket winsock.

Sintaxis

DWORD WSAAPI ProcessSocketNotifications(
  HANDLE                   completionPort,
  UINT32                   registrationCount,
  SOCK_NOTIFY_REGISTRATION *registrationInfos,
  UINT32                   timeoutMs,
  ULONG                    completionCount,
  OVERLAPPED_ENTRY         *completionPortEntries,
  UINT32                   *receivedEntryCount
);

Parámetros

completionPort

Tipo: _In_ HANDLE

Identificador de un puerto de finalización de E/S creado mediante la función CreateIoCompletionPort . El puerto se usará en el parámetro CompletionPort de la función PostQueuedCompletionStatus cuando se envíen mensajes en nombre del socket.

registrationCount

Tipo: _In_ UINT32

Número de registros proporcionados por registrationInfos.

registrationInfos

Tipo: _Inout_updates_opt_(registrationCount) SOCK_NOTIFY_REGISTRATION*

Puntero a una matriz de estructuras de SOCK_NOTIFY_REGISTRATION que definen los parámetros de registro de notificaciones. Estos incluyen el socket de interés, los eventos de notificación de interés y las marcas de operación. Si se ejecuta correctamente, debe inspeccionar los elementos para saber si el registro se procesó correctamente. Este argumento debe ser NULL si registrationCount es 0.

timeoutMs

Tipo: _In_ UINT32

El tiempo en milisegundos que está dispuesto a esperar a que aparezca un paquete de finalización en el puerto de finalización. Si un paquete de finalización no aparece dentro del tiempo especificado, la función agota el tiempo de espera y devuelve ERROR_TIMEOUT.

Si timeoutMs es INFINITE (0xFFFFFFFF), la función nunca agotará el tiempo de espera. Si los timeoutMs son 0 y no hay ninguna operación de E/S para quitar la cola, la función agotará el tiempo de espera inmediatamente.

El valor de timeoutMs debe ser 0 si completionCount es 0.

completionCount

Tipo: _In_ ULONG

Número máximo de estructuras de OVERLAPPED_ENTRY que se van a quitar. Si se especifica 0, solo se procesarán las operaciones de registro.

completionPortEntries

Tipo: _Out_writes_to_opt_(completionCount, *receivedEntryCount) OVERLAPPED_ENTRY*

En la entrada, apunta a una matriz preasignada de estructuras OVERLAPPED_ENTRY. La matriz no debe superponerse con la matriz registrationInfos . El valor de completionPortEntries debe ser NULL si completionCount es 0.

En la salida, recibe una matriz de estructuras OVERLAPPED_ENTRY que contienen las entradas. ReceivedEntryCount proporciona el número de elementos de matriz. Los campos dwNumberOfBytesTransferred de las estructuras son máscaras enteras de eventos recibidos. Los campos lpOverlapped están reservados y no se deben usar como punteros.

receivedEntryCount

Tipo: _Out_opt_ UINT32*

Puntero a una variable que recibe el número de entradas quitadas. Debe ser NULL si completionCount es 0.

Valor devuelto

Si se ejecuta correctamente, devuelve ERROR_SUCCESS. Si la función se realizó correctamente y proporcionó un valor de completionCount distinto de 0, pero no apareció ningún paquete de finalización dentro del tiempo especificado, devuelve WAIT_TIMEOUT. De lo contrario, devuelve un código de error WSAE* adecuado.

Si se devuelve ERROR_SUCCESS o WAIT_TIMEOUT , debe inspeccionar los resultados de registro de la información de registro individual. De lo contrario, se produjo un error en toda la operación y no se produjo ningún cambio.

Comentarios

Consulte SocketNotificationRetrieveEvents para conocer los eventos que son posibles cuando se recibe una notificación.

Requisitos

   
Cliente mínimo compatible Compilación 20348 de Windows 10
Servidor mínimo compatible Compilación 20348 de Windows 10
Encabezado winsock2.h
Library Ws2_32.lib
Archivo DLL Ws2_32.dll

Consulte también