Função CreatePersistentUdpPortReservation (iphlpapi.h)

Artigo
03/14/2023

A função CreatePersistentUdpPortReservation cria uma reserva de porta UDP persistente para um bloco consecutivo de portas UDP no computador local.

Sintaxe

IPHLPAPI_DLL_LINKAGE ULONG CreatePersistentUdpPortReservation(
  [in]  USHORT   StartPort,
  [in]  USHORT   NumberOfPorts,
  [out] PULONG64 Token
);

Parâmetros

[in] StartPort

O número da porta UDP inicial na ordem de bytes de rede.

[in] NumberOfPorts

O número de números de porta UDP a serem reservados.

[out] Token

Um ponteiro para um token de reserva de porta retornado se a função for bem-sucedida.

Retornar valor

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um dos seguintes códigos de erro.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	Acesso negado. Esse erro é retornado sob várias condições 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 aprimorado como administrador interno (administrador de RunAs).
ERROR_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função. Esse erro será retornado se zero for passado nos parâmetros StartPort ou NumberOfPorts . Esse erro também será retornado se o parâmetro NumberOfPorts for muito grande, dependendo do parâmetro StartPort , que o bloco alocável de portas excederia a porta máxima que pode ser alocada.
ERROR_SHARING_VIOLATION	O processo não pode acessar o arquivo porque ele está sendo usado por outro processo. Esse erro será retornado se uma porta UDP no bloco de portas UDP especificadas pelos parâmetros StartPort e NumberOfPorts já estiver sendo usada. Esse erro também será retornado se uma reserva persistente para um bloco de portas UDP especificadas pelos parâmetros StartPort e NumberOfPorts corresponder ou sobrepor uma reserva persistente para um bloco de portas UDP que já foi criado.
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função CreatePersistentUdpPortReservation é definida no Windows Vista e posteriores.

A função CreatePersistentUdpPortReservation é usada para adicionar uma reserva persistente a um bloco de portas UDP.

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. As solicitações de reserva específicas podem ser persistentes ou de runtime, enquanto as solicitações de reserva de porta curinga só têm suporte no runtime.

A função CreatePersistentUdpPortReservation fornece a capacidade de um aplicativo ou serviço reservar persistentemente um bloco de portas UDP. As reservas de TCP persistentes são registradas em um repositório persistente para o módulo UDP no Windows.

Um chamador obtém uma reserva de porta persistente especificando quantas portas são necessárias e se um intervalo específico é necessário. Se a solicitação puder ser atendida, a função CreatePersistentUdpPortReservation retornará um token de ULONG64 opaco exclusivo, que identifica posteriormente a reserva. Uma reserva de porta UDP persistente pode ser liberada chamando a função DeletePersistentUdpPortReservation . Observe que o token para uma determinada reserva de porta UDP persistente pode ser alterado sempre que o sistema é reiniciado.

O Windows não implementa a segurança entre componentes para reservas persistentes obtidas usando essas funções. Isso significa que, se um componente receber a capacidade de obter quaisquer reservas de porta persistentes, esse componente obterá automaticamente a capacidade de consumir quaisquer reservas de porta persistentes concedidas a qualquer outro componente no sistema. A segurança em nível de processo é imposta para reservas de runtime, mas esse controle não pode ser estendido para reservas persistentes criadas usando o criado usando a função CreatePersistentTcpPortReservation ou CreatePersistentUdpPortReservation .

Depois que uma reserva de porta UDP persistente tiver sido obtida, um aplicativo poderá solicitar atribuições de porta da reserva de porta UDP abrindo um soquete UDP e chamando a função WSAIoctl especificando a 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 CreatePersistentUdpPortReservation podem ser consumidas por qualquer processo com a capacidade de obter reservas persistentes.

A função CreatePersistentUdpPortReservation só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se CreatePersistentUdpPortReservation for chamado por um usuário que não é membro do grupo Administradores, a chamada de função falhará e ERROR_ACCESS_DENIED será retornado. Essa função também pode falhar devido ao UAC (controle de conta de usuário) no Windows Vista e posterior. Se um aplicativo que contém essa função for executado por um usuário conectado como 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 para exigirAdministrator. 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 administrador interno (administrador RunAs) para que essa função tenha êxito.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	iphlpapi.h
Biblioteca	Iphlpapi.lib
DLL	Iphlpapi.dll