PFN_WSK_CONNECT_EX função de retorno de chamada (wsk.h)

Artigo
08/08/2023

A função WskConnectEx conecta um soquete de fluxo ou orientado a conexão a um endereço de transporte remoto.

WskConnectEx é semelhante ao WskConnect , exceto que também pode, opcionalmente, enviar um buffer de dados durante ou após a sincronização da conexão.

Sintaxe

PFN_WSK_CONNECT_EX PfnWskConnectEx;

NTSTATUS PfnWskConnectEx(
  [in]           PWSK_SOCKET Socket,
  [in]           PSOCKADDR RemoteAddress,
  [in, optional] PWSK_BUF Buffer,
                 ULONG Flags,
  [in, out]      PIRP Irp
)
{...}

Parâmetros

[in] Socket

Um ponteiro para uma estrutura WSK_SOCKET que especifica o objeto de soquete para o soquete que está sendo conectado a um endereço de transporte remoto.

[in] RemoteAddress

Um ponteiro para uma estrutura que especifica o endereço de transporte remoto ao qual conectar o soquete. Esse ponteiro deve ser um ponteiro para o tipo de estrutura SOCKADDR específico que corresponde à família de endereços especificada pelo aplicativo WSK ao criar o soquete.

[in, optional] Buffer

Um ponteiro para uma estrutura WSK_BUF , que contém os dados a serem enviados durante ou após a sincronização da conexão. O tamanho máximo permitido em bytes é de 65.535.

Flags

Esse parâmetro é reservado para uso do sistema. Um aplicativo WSK deve definir esse parâmetro como zero.

[in, out] Irp

Um ponteiro para um IRP alocado pelo chamador que o subsistema WSK usa para concluir a operação de conexão de forma assíncrona. Para obter mais informações sobre como usar IRPs com funções WSK, consulte Usando IRPs com funções de kernel Winsock.

Retornar valor

WskConnectEx retorna um dos seguintes códigos NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	O soquete foi conectado com êxito ao endereço de transporte remoto. O IRP será concluído com êxito status.
STATUS_PENDING	O subsistema WSK não pôde conectar o soquete imediatamente. O subsistema WSK concluirá o IRP depois de conectar o soquete ao endereço de transporte remoto. O status da operação de conexão será retornado no campo IoStatus.Status do IRP.
STATUS_FILE_FORCED_CLOSED	O soquete não é mais funcional. O IRP será concluído com status de falha. O aplicativo WSK deve chamar a função WskCloseSocket para fechar o soquete o mais rápido possível.
STATUS_INVALID_PARAMETER	O aplicativo WSK tentou passar um sinalizador para o parâmetro Flags (como nenhum sinalizador válido está definido no momento para WskConnectEx, isso não é permitido).
STATUS_BUFFER_OVERFLOW	O aplicativo WSK tentou passar um buffer maior que 65.535 bytes para o parâmetro Buffer .
Outros códigos de status	Ocorreu um erro. O IRP será concluído com status de falha.

Comentários

Um aplicativo WSK pode criar, associar e conectar um soquete orientado a conexão em uma única chamada de função chamando a função WskSocketConnect em vez de chamar a função WskSocket , a função WskBind e, em seguida, a função WskConnectEx . É recomendável chamar a função WskSocketConnect , a menos que o aplicativo WSK precise definir uma opção de soquete ou emitir uma operação de controle de E/S antes de associar ou conectar o soquete.

Um aplicativo WSK pode chamar a função WskConnectEx somente em um soquete de fluxo ou orientado a conexão que o aplicativo vinculou anteriormente a um endereço de transporte local chamando a função WskBind .

Para soquetes de fluxo, depois que WskConnectEx é chamado com êxito em um soquete de fluxo, o soquete é confirmado em um fluxo orientado a conexão e pode não chamar mais funções de soquete de escuta.

Se o parâmetro Buffer for usado, o chamador poderá liberar o MDL em sua estrutura de WSK_BUF assim que a solicitação de conexão for concluída.

Antes de chamar WskConnectEx com um buffer de envio fornecido, se o aplicativo WSK definir a opção TCP_FASTOPEN em um soquete WSK por meio da função WskControlSocket , o sistema enviará opcionalmente alguns ou todos os dados em um pacote SYN. Para obter mais informações, consulte a opção TCP Fastopen em IPPROTO_TCP Opções de Soquete.