Função WPUCompleteOverlappedRequest (ws2spi.h)
A função WPUCompleteOverlappedRequest executa uma notificação de conclusão de E/S sobreposta para operações de E/S sobrepostas.
Sintaxe
int WPUCompleteOverlappedRequest(
[in] SOCKET s,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] DWORD dwError,
[in] DWORD cbTransferred,
[out] LPINT lpErrno
);
Parâmetros
[in] s
O soquete do provedor de serviços criado por WPUCreateSocketHandle.
[in] lpOverlapped
Um ponteiro para uma estrutura WSAOVERLAPPED associada à operação de E/S sobreposta cuja conclusão deve ser notificada.
[in] dwError
A conclusão status da operação de E/S sobreposta cuja conclusão deve ser notificada.
[in] cbTransferred
O número de bytes transferidos de ou para buffers de cliente (a direção da transferência depende da natureza de envio ou recebimento da operação de E/S sobreposta cuja conclusão deve ser notificada).
[out] lpErrno
Um ponteiro para o código de erro resultante da execução dessa função.
Retornar valor
Se nenhum erro ocorrer, WPUCompleteOverlappedRequest retornará zero e notificará a conclusão da operação de E/S sobreposta de acordo com o mecanismo selecionado pelo cliente (sinaliza um evento encontrado na estrutura WSAOVERLAPPED referenciada por lpOverlapped e/ou enfileira um relatório de conclusão status à porta de conclusão associada ao soquete se uma porta de conclusão estiver associada). Caso contrário, WPUCompleteOverlappedRequest retornará SOCKET_ERROR e um código de erro específico estará disponível em lpErrno.
| Código do erro | Significado |
|---|---|
| O soquete passado no parâmetro s não é um soquete criado por WPUCreateSocketHandle. |
Comentários
A função WPUCompleteOverlappedRequest executa uma notificação de conclusão de E/S sobreposta para operações de E/S sobrepostas em que o mecanismo de conclusão especificado pelo cliente é algo diferente do modo de usuário – APC (chamada de procedimento assíncrono). Essa função só pode ser usada para identificadores de soquete criados por WPUCreateSocketHandle.
Se o cliente selecionar um APC no modo de usuário como o método de notificação, o provedor de serviços deverá usar WPUQueueApc ou outra função de sistema operacional apropriada para executar a notificação de conclusão. Se a APC do modo de usuário não for selecionada pelo cliente, um provedor de serviços que não implementa diretamente a funcionalidade IFS não poderá determinar se o cliente associou ou não uma porta de conclusão ao identificador de soquete. Portanto, ele não pode determinar se o método de notificação de conclusão deve estar enfileirando um registro de conclusão status em uma porta de conclusão ou sinalizando um evento encontrado na estrutura WSAOVERLAPPED. A arquitetura do Windows Socket 2 controla qualquer associação de porta de conclusão com um soquete criado por WPUCreateSocketHandle e pode tomar uma decisão correta entre a notificação baseada em porta de conclusão ou a notificação baseada em evento.
Quando WPUCompleteOverlappedRequest enfileira uma indicação de conclusão, ele define o membro InternalHigh da estrutura WSAOVERLAPPED para a contagem de bytes transferidos. Em seguida, ele define o membro Interno como algum valor dependente do sistema operacional diferente do valor especial WSS_OPERATION_IN_PROGRESS. Pode haver um pequeno atraso após o retorno de WPUCompleteOverlappedRequest antes que esses valores apareçam, pois o processamento pode ocorrer de forma assíncrona. No entanto, o valor InternalHigh (contagem de bytes) tem a garantia de ser definido pelo momento em que Interno é definido.
WPUCompleteOverlappedRequest funciona conforme indicado (executa a notificação de conclusão conforme solicitado pelo cliente) se o identificador de soquete foi ou não associado a uma porta de conclusão.
Interação com WSPGetOverlappedResult
O comportamento de WPUCompleteOverlappedRequest coloca algumas restrições sobre como um provedor de serviços implementa WSPGetOverlappedResult , pois apenas os membros Offset e OffsetHigh da estrutura WSAOVERLAPPED são controlados exclusivamente pelo provedor de serviços, mas três valores (contagem de bytes, sinalizadores e erro) devem ser recuperados da estrutura por WSPGetOverlappedResult. Um provedor de serviços pode fazer isso da maneira que escolher, desde que interaja com o comportamento de WPUCompleteOverlappedRequest corretamente. No entanto, uma implementação típica é a seguinte:
- No início do processamento sobreposto, o provedor de serviços define Interno como WSS_OPERATION_IN_PROGRESS.
- Quando a operação de E/S for concluída, o provedor definirá OffsetHigh como o código de erro do Windows Socket 2 resultante da operação, definirá Offset para os sinalizadores resultantes da operação de E/S e chamará WPUCompleteOverlappedRequest, passando a contagem de bytes de transferência como um dos parâmetros. O WPUCompleteOverlappedRequest eventualmente define InternalHigh como a contagem de bytes de transferência e define Interno como um valor diferente de WSS_OPERATION_IN_PROGRESS.
- Quando WSPGetOverlappedResult é chamado, o provedor de serviços verifica Interno. Se for WSS_OPERATION_IN_PROGRESS, o provedor aguardará o identificador de evento no membro hEvent ou retornará um erro, com base na configuração do sinalizador FWAIT de WSPGetOverlappedResult. Se não estiver em andamento ou após a conclusão da espera, o provedor retornará os valores de InternalHigh, OffsetHigh e Offset como a contagem de transferência, o código de erro do resultado da operação e os sinalizadores, respectivamente.
Requisitos
| Requisito | Valor |
|---|---|
| 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 |