Função WSAProviderConfigChange (winsock2.h)

Artigo
08/27/2023

A função WSAProviderConfigChange notifica o aplicativo quando a configuração do provedor é alterada.

Sintaxe

INT WSAAPI WSAProviderConfigChange(
  [in, out] LPHANDLE                           lpNotificationHandle,
  [in]      LPWSAOVERLAPPED                    lpOverlapped,
  [in]      LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parâmetros

[in, out] lpNotificationHandle

Ponteiro para o identificador de notificação. Se o identificador de notificação estiver definido como NULL (o valor do identificador não o ponteiro em si), essa função retornará um identificador de notificação no local apontado por lpNotificationHandle.

[in] lpOverlapped

Ponteiro para uma estrutura WSAOVERLAPPED .

[in] lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Ponteiro para a rotina de conclusão chamada quando a notificação de alteração do provedor é recebida.

Retornar valor

Se nenhum erro ocorrer, o WSAProviderConfigChange retornará 0. Caso contrário, um valor de SOCKET_ERROR é retornado e um código de erro específico pode ser recuperado chamando WSAGetLastError. O código de erro WSA_IO_PENDING indica que a operação sobreposta foi iniciada com êxito e que a conclusão (e, portanto, o evento de alteração) será indicada posteriormente.

Código do erro	Significado
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAENETDOWN	O subsistema de rede falhou.
WSA_NOT_ENOUGH_MEMORY	Não há memória livre suficiente disponível para concluir a operação.
WSA_INVALID_HANDLE	O valor apontado pelo parâmetro lpNotificationHandle não é um identificador de notificação válido.
WSAEOPNOTSUPP	O ambiente atual do sistema operacional não dá suporte à instalação ou remoção do provedor sem reinicialização.

Comentários

A função WSAProviderConfigChange notifica o aplicativo de instalação ou remoção do provedor (transporte e namespace) em ambientes operacionais Windows que dão suporte a essa alteração de configuração sem a necessidade de uma reinicialização. Quando chamada pela primeira vez (o parâmetro lpNotificationHandle aponta para o identificador NULL ), essa função é concluída imediatamente e retorna o identificador de notificação no local apontado por lpNotificationHandle que pode ser usado em chamadas subsequentes para receber notificações de instalação e remoção do provedor. A segunda e todas as chamadas subsequentes só são concluídas quando as informações do provedor são alteradas desde o momento em que a chamada foi feita É esperado (mas não necessário) que o aplicativo use E/S sobreposta na segunda e nas chamadas subsequentes para WSAProviderConfigChange, nesse caso, a chamada será retornada imediatamente e o aplicativo será notificado sobre as alterações de configuração do provedor usando o mecanismo de conclusão escolhido por meio de parâmetros de conclusão sobrepostos especificados.

O identificador de notificação retornado por WSAProviderConfigChange é como qualquer identificador do sistema operacional regular que deve ser fechado (quando não for mais necessário) usando a chamada CloseHandle do Windows.

A seguinte sequência de ações pode ser usada para garantir que o aplicativo sempre tenha informações de configuração de protocolo atuais:

Chamar WSAProviderConfigChange
Chamar WSAEnumProtocols e/ou WSAEnumNameSpaceProviders
Sempre que WSAProviderConfigChange notifica o aplicativo de alteração de configuração do provedor (por meio de E/S de bloqueio ou sobreposta), toda a sequência de ações deve ser repetida.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8.1, Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winsock2.h
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll