Função WPUQueueApc (ws2spi.h)

  • Artigo

A função WPUQueueApc enfileira uma APC (chamada de procedimento assíncrona) para o thread especificado para facilitar a invocação de rotinas de conclusão de E/S sobrepostas.

Sintaxe

int WPUQueueApc(
  [in]  LPWSATHREADID lpThreadId,
  [in]  LPWSAUSERAPC  lpfnUserApc,
  [in]  DWORD_PTR     dwContext,
  [out] LPINT         lpErrno
);

Parâmetros

[in] lpThreadId

Ponteiro para uma estrutura WSATHREADID que identifica o contexto do thread. Um ponteiro para essa estrutura é fornecido ao provedor de serviços pelo Ws2_32.dll como um parâmetro de entrada para uma operação sobreposta. O provedor deve armazenar a estrutura WSATHREADID localmente e fornecer um ponteiro para esse repositório local. A cópia local do WSATHREADID não é mais necessária quando WPUQueueApc retorna.

[in] lpfnUserApc

Ponteiro para a função APC a ser chamada.

[in] dwContext

Valor de contexto de 32 bits que é fornecido posteriormente como um parâmetro de entrada para a função APC.

[out] lpErrno

Ponteiro para o código de erro.

Valor retornado

Se nenhum erro ocorrer, WPUQueueApc retornará zero e enfileirará a rotina de conclusão do thread especificado. Caso contrário, ele retornará SOCKET_ERROR e um código de erro específico estará disponível no lpErrno.

Código do erro Significado
WSAEFAULT
 O parâmetro dwThreadId não especifica um thread válido.
 
 

Comentários

Essa função enfileira uma função APC no thread especificado. No Windows, isso será feito usando uma APC (chamada de procedimento assíncrona) no modo de usuário. O APC só será executado quando o thread especificado for bloqueado em uma espera alertável e um retorno de chamada será feito diretamente. Essa chamada é segura para uso em um contexto de interrupção.

LPWSAUSERAPC é definido da seguinte maneira:

typedef void ( CALLBACK FAR * LPWSAUSERAPC )( DWORD dwContext );

Como o mecanismo APC dá suporte apenas a um único valor de contexto, o próprio lpfnUserApc não pode ser a rotina de conclusão especificada pelo cliente, o que envolve mais parâmetros. Em vez disso, o provedor de serviços deve fornecer um ponteiro para sua própria função APC que usa o valor dwContext fornecido para acessar as informações de resultado necessárias para a operação sobreposta e, em seguida, invoca a rotina de conclusão especificada pelo cliente.

Para provedores de serviços em que um componente de modo de usuário implementa E/S sobreposta, um uso típico do mecanismo de APC é o seguinte.

    - Quando a operação de E/S é concluída, o provedor aloca um buffer pequeno e o empacota com um ponteiro para o procedimento de conclusão fornecido pelo cliente e os valores de parâmetro a serem passados para o procedimento. - Ele enfileira um APC, especificando o ponteiro para o buffer como o valor dwContext e seu próprio procedimento intermediário como o procedimento de destino lpfnUserApc. - Quando o thread de destino eventualmente entra no estado de espera alertável, o procedimento intermediário do provedor de serviços é chamado no contexto de thread adequado. – O procedimento intermediário simplesmente descompacta parâmetros, desaloca o buffer e chama o procedimento de conclusão fornecido pelo cliente.

Requisitos

   
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho ws2spi.h

Confira também

WSATHREADID

LPWSPIoctl

LPWSPRecv

LPWSPRecvFrom

LPWSPSend

LPWSPSendTo