Código de controle SIO_ASSOCIATE_PORT_RESERVATION

Artigo
06/13/2023

Descrição

O código de controle SIO_ASSOCIATE_PORT_RESERVATION associa um soquete a uma reserva persistente ou de runtime para um bloco de TCP ou UDP identificado pelo token de reserva de porta. Esse IOCTL deve ser emitido antes que o soquete seja associado. Se e quando o soquete estiver associado, a porta atribuída a ele será selecionada na reserva de porta identificada pelo token fornecido. Se nenhuma porta estiver disponível na reserva especificada , a chamada de função de associação falhará.

Para executar essa operação, chame a função WSAIoctl ou WSPIoctl com os parâmetros a seguir.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RESERVATION_TOKEN
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  NULL,           // lpvOutBuffer is a pointer to the output buffer
  0,              // cbOutBuffer is the size, in bytes, of the output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RESERVATION_TOKEN
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  NULL,           // lpvOutBuffer is a pointer to the output buffer
  0,              // cbOutBuffer is the size, in bytes, of the output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parâmetros

s

Um descritor que identifica um soquete.

Dwiocontrolcode

O código de controle da operação. Use SIO_ASSOCIATE_PORT_RESERVATION para esta operação.

Lpvinbuffer

Um ponteiro para o buffer de entrada. Esse parâmetro contém um ponteiro para uma estrutura INET_PORT_RESERVATION_TOKEN com o token para a reserva de porta TCP ou UDP a ser associada ao soquete.

Cbinbuffer

O tamanho, em bytes, do buffer de entrada. Esse parâmetro deve ter pelo menos o tamanho da estrutura INET_PORT_RESERVATION_TOKEN .

Lpvoutbuffer

Um ponteiro para o buffer de saída. Esse parâmetro não é usado para essa operação.

cbOutBuffer

O tamanho, em bytes, do buffer de saída. Esse parâmetro deve ser definido como zero.

Lpcbbytesreturned

Um ponteiro para uma variável que recebe o tamanho, em bytes, dos dados armazenados no buffer de saída.

Se o buffer de saída for muito pequeno, a chamada falhará, WSAGetLastError retornará WSAEINVAL e o parâmetro lpcbBytesReturned apontará para um valor DWORD igual a zero.

Se lpOverlapped for NULL, o valor DWORD apontado pelo parâmetro lpcbBytesReturned retornado em uma chamada bem-sucedida não poderá ser zero.

Se o parâmetro lpOverlapped não for NULL para soquetes sobrepostos, as operações que não puderem ser concluídas imediatamente serão iniciadas e a conclusão será indicada posteriormente. O valor DWORD apontado pelo parâmetro lpcbBytesReturned retornado pode ser zero, pois o tamanho dos dados armazenados não pode ser determinado até que a operação sobreposta seja concluída. A conclusão final status pode ser recuperada quando o método de conclusão apropriado é sinalizado quando a operação é concluída.

lpvOverlapped

Um ponteiro para uma estrutura WSAOVERLAPPED .

Se o soquete s tiver sido criado sem o atributo sobreposto, o parâmetro lpOverlapped será ignorado.

Se s tiver sido aberto com o atributo sobreposto e o parâmetro lpOverlapped não for NULL, a operação será executada como uma operação sobreposta (assíncrona). Nesse caso, o parâmetro lpOverlapped deve apontar para uma estrutura WSAOVERLAPPED válida.

Para operações sobrepostas, a função WSAIoctl ou WSPIoctl retorna imediatamente e o método de conclusão apropriado é sinalizado quando a operação é concluída. Caso contrário, a função não retornará até que a operação seja concluída ou ocorra um erro.

Lpcompletionroutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Um ponteiro para a rotina de conclusão chamado quando a operação foi concluída (ignorado para soquetes não sobrepostos).

lpThreadId

Um ponteiro para uma estrutura WSATHREADID a ser usada pelo provedor em uma chamada subsequente para WPUQueueApc. O provedor deve armazenar a estrutura WSATHREADID referenciada (não o ponteiro para o mesmo) até que a função WPUQueueApc retorne.

Nota Esse parâmetro se aplica somente à função WSPIoctl .

Lperrno

Um ponteiro para o código de erro.

Nota Esse parâmetro se aplica somente à função WSPIoctl .

Valor retornado

Se a operação for concluída com êxito, a função WSAIoctl ou WSPIoctl retornará zero.

Se a operação falhar ou estiver pendente, a função WSAIoctl ou WSPIoctl retornará SOCKET_ERROR. Para obter informações de erro estendidas, chame WSAGetLastError.

Código do erro	Significado
WSA_IO_PENDING	A operação de E/S sobreposta está em andamento. Esse valor será retornado se uma operação sobreposta tiver sido iniciada com êxito e a conclusão for indicada posteriormente.
WSA_OPERATION_ABORTED	A operação de E/S foi anulada devido ao encerramento de um thread ou a uma solicitação de aplicativo. Esse erro será retornado se uma operação sobreposta tiver sido cancelada devido ao fechamento do soquete ou à execução do SIO_FLUSH comando IOCTL .
WSAEACCES	Foi feita uma tentativa de acessar um soquete de forma proibida por suas permissões de acesso. Esse erro é retornado sob várias condições para reservas de porta persistentes que incluem o seguinte: o usuário não tem os privilégios administrativos necessários no computador local ou o aplicativo não está em execução em um shell avançado como o Administrador interno (`RunAs administrator`).
WSAEFAULT	O sistema detectou um endereço de ponteiro inválido ao tentar usar um argumento de ponteiro em uma chamada. Esse erro é retornado do parâmetro lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped ou lpCompletionRoutine não está totalmente contido em uma parte válida do espaço de endereço do usuário.
WSAEINPROGRESS	Uma operação de bloqueio está atualmente em execução. Esse erro será retornado se a função for invocada quando um retorno de chamada estiver em andamento.
WSAEINTR	Uma operação de bloqueio foi interrompida por uma chamada para WSACancelBlockingCall. Esse erro será retornado se uma operação de bloqueio tiver sido interrompida.
WSAEINVAL	Foi fornecido um argumento inválido. Esse erro será retornado se o parâmetro dwIoControlCode não for um comando válido ou se um parâmetro de entrada especificado não for aceitável ou se o comando não for aplicável ao tipo de soquete especificado.
WSAENETDOWN	Uma operação de soquete encontrou uma rede inoperante. Esse erro será retornado se o subsistema de rede falhar.
WSAENOTSOCK	Uma operação foi tentada em algo que não é um soquete. Esse erro será retornado se o descritor s não for um soquete.
WSAEOPNOTSUPP	Não há suporte para a tentativa de operação para o tipo de objeto referenciado. Esse erro será retornado se não houver suporte para o comando IOCTL especificado. Esse erro também será retornado se o SIO_ASSOCIATE_PORT_RESERVATION IOCTL não tiver suporte do provedor de transporte. Esse erro também é retornado quando uma tentativa de usar o SIO_ASSOCIATE_PORT_RESERVATION IOCTL é feita em um soquete diferente de UDP ou TCP.

Comentários

O SIO_ASSOCIATE_PORT_RESERVATION IOCTL é compatível com o Windows Vista e versões posteriores do sistema operacional.

Aplicativos e serviços que precisam reservar portas se enquadram em duas categorias. A primeira categoria inclui componentes que precisam de uma porta específica como parte de sua operação. Esses componentes geralmente preferem especificar a porta necessária no momento da instalação (em um manifesto do aplicativo, por exemplo). A segunda categoria inclui componentes que precisam de qualquer porta disponível ou bloco de portas em runtime. Essas duas categorias correspondem a solicitações de reserva de porta curinga e específicas. Solicitações de reserva específicas podem ser persistentes ou runtime, enquanto as solicitações de reserva de porta curinga só têm suporte no runtime.

O SIO_ASSOCIATE_PORT_RESERVATION IOCTL é usado para associar uma reserva de porta TCP ou UDP a uma reserva persistente ou de runtime.

A função CreatePersistentTcpPortReservation ou CreatePersistentUdpPortReservation fornece a capacidade de um aplicativo ou serviço reservar um bloco persistente de portas TCP ou UDP. As reservas de porta persistentes são registradas em um repositório persistente para o módulo TCP ou UDP no Windows. Observe que o token de uma determinada reserva de porta persistente pode ser alterado sempre que o sistema é reiniciado.

Depois que uma reserva de porta TCP ou UDP persistente tiver sido obtida, um aplicativo poderá solicitar atribuições de porta da reserva de porta abrindo um soquete TCP ou UDP e, em seguida, chamando a função WSAIoctl especificando o SIO_ASSOCIATE_PORT_RESERVATION IOCTL e passando o token de reserva antes de emitir uma chamada para a função de associação no soquete.

O SIO_ACQUIRE_PORT_RESERVATION IOCTL pode ser usado para solicitar uma reserva de runtime para um bloco de portas TCP ou UDP. Para reservas de porta de runtime, o pool de portas exige que as reservas sejam consumidas do processo em cujo soquete a reserva foi concedida. As reservas de porta de runtime duram apenas o tempo de vida do soquete no qual o SIO_ACQUIRE_PORT_RESERVATION IOCTL foi chamado. Por outro lado, as reservas de porta persistentes criadas usando a função CreatePersistentTcpPortReservation ou CreatePersistentUdpPortReservation podem ser consumidas por qualquer processo com a capacidade de obter reservas persistentes.

Depois que uma reserva de porta TCP ou UDP de runtime tiver sido obtida, um aplicativo poderá solicitar atribuições de porta da reserva de porta abrindo um soquete TCP ou UDP e, em seguida, chamando a função WSAIoctl especificando o SIO_ASSOCIATE_PORT_RESERVATION IOCTL e passando o token de reserva antes de emitir uma chamada para a função de associação no soquete.

Se os parâmetros lpOverlapped e lpCompletionRoutine forem NULL, o soquete nessa função será tratado como um soquete não sobreposto. Para um soquete não sobreposto, os parâmetros lpOverlapped e lpCompletionRoutine são ignorados, exceto que a função pode bloquear se o soquete s estiver no modo de bloqueio. Se o soquete s estiver no modo sem bloqueio, essa função ainda será bloqueada, pois esse IOCTL específico não dá suporte ao modo sem bloqueio.

Para soquetes sobrepostos, as operações que não podem ser concluídas imediatamente serão iniciadas e a conclusão será indicada posteriormente.

Qualquer IOCTL pode ser bloqueada indefinidamente, dependendo da implementação do provedor de serviços. Se o aplicativo não puder tolerar o bloqueio em uma chamada de função WSAIoctl ou WSPIoctl , a E/S sobreposta será aconselhada para IOCTLs que são especialmente propensas a bloquear.

O SIO_ASSOCIATE_PORT_RESERVATION IOCTL pode falhar com WSAEINTR ou WSA_OPERATION_ABORTED nos seguintes casos:

A solicitação é cancelada pelo Gerenciador de E/S.
O soquete está fechado.

O SIO_ASSOCIATE_PORT_RESERVATION IOCTL passado para a função WSAIoctl ou WSPIoctl para uma reserva de porta persistente só pode ser usado em um aplicativo quando o usuário está conectado como membro do grupo Administradores. Se SIO_ASSOCIATE_PORT_RESERVATION IOCTL for usado em um aplicativo quando o usuário não for membro do grupo Administradores, a chamada de função falhará e WSAEACCES será retornado. O uso do SIO_ASSOCIATE_PORT_RESERVATION IOCTL também pode falhar devido ao UAC (controle de conta de usuário) no Windows Vista e posterior. Se um aplicativo que usa esse IOCTL com uma reserva de porta persistente for executado por um usuário conectado como um membro do grupo Administradores diferente do Administrador interno, essa chamada falhará, a menos que o aplicativo tenha sido marcado no arquivo de manifesto com um requestedExecutionLevel definido como requireAdministrator. Se o aplicativo não tiver esse arquivo de manifesto, um usuário conectado como membro do grupo Administradores diferente do Administrador interno deverá executar o aplicativo em um shell aprimorado como o Administrador interno (RunAs administrator) para que essa função tenha êxito.