Función CreatePersistentUdpPortReservation (iphlpapi.h)

Artículo
03/14/2023

La función CreatePersistentUdpPortReservation crea una reserva de puertos UDP persistente para un bloque consecutivo de puertos UDP en el equipo local.

Sintaxis

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

Parámetros

[in] StartPort

Número de puerto UDP inicial en orden de bytes de red.

[in] NumberOfPorts

Número de números de puerto UDP que se van a reservar.

[out] Token

Puntero a un token de reserva de puerto que se devuelve si la función se realiza correctamente.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es NO_ERROR.

Si se produce un error en la función, el valor devuelto es uno de los siguientes códigos de error.

Código devuelto	Descripción
ERROR_ACCESS_DENIED	Acceso denegado. Este error se devuelve en varias condiciones que incluyen lo siguiente: el usuario carece de los privilegios administrativos necesarios en el equipo local o la aplicación no se ejecuta en un shell mejorado como administrador integrado (administrador de RunAs).
ERROR_INVALID_PARAMETER	Se pasó un parámetro no válido a la función. Este error se devuelve si se pasa cero en los parámetros StartPort o NumberOfPorts . Este error también se devuelve si el parámetro NumberOfPorts es demasiado grande un bloque de puertos según el parámetro StartPort que el bloque asignado de puertos superaría el puerto máximo que se puede asignar.
ERROR_SHARING_VIOLATION	El proceso no puede obtener acceso al archivo porque otro proceso lo está utilizando. Este error se devuelve si ya se está usando un puerto UDP en el bloque de puertos UDP especificados por los parámetros StartPort y NumberOfPorts . Este error también se devuelve si una reserva persistente para un bloque de puertos UDP especificado por los parámetros StartPort y NumberOfPorts coincide o se superpone a una reserva persistente para un bloque de puertos UDP que ya se crearon.
Otros	Use FormatMessage para obtener la cadena de mensaje del error devuelto.

Comentarios

La función CreatePersistentUdpPortReservation se define en Windows Vista y versiones posteriores.

La función CreatePersistentUdpPortReservation se usa para agregar una reserva persistente para un bloque de puertos UDP.

Las aplicaciones y los servicios que necesitan reservar puertos se dividen en dos categorías. La primera categoría incluye componentes que necesitan un puerto determinado como parte de su operación. Por lo general, estos componentes prefieren especificar su puerto necesario en el momento de la instalación (por ejemplo, en un manifiesto de aplicación). La segunda categoría incluye componentes que necesitan cualquier puerto o bloque de puertos disponibles en tiempo de ejecución.

Estas dos categorías corresponden a solicitudes de reserva de puertos comodín y específicas. Las solicitudes de reserva específicas pueden ser persistentes o en tiempo de ejecución, mientras que las solicitudes de reserva de puerto comodín solo se admiten en tiempo de ejecución.

La función CreatePersistentUdpPortReservation proporciona la posibilidad de que una aplicación o servicio reserve persistentemente un bloque de puertos UDP. Las reservas TCP persistentes se registran en un almacén persistente para el módulo UDP en Windows.

Un llamador obtiene una reserva de puerto persistente especificando cuántos puertos son necesarios y si se necesita un intervalo específico. Si se puede satisfacer la solicitud, la función CreatePersistentUdpPortReservation devuelve un token de ULONG64 opaco único, que posteriormente identifica la reserva. Se puede liberar una reserva de puertos UDP persistente mediante una llamada a la función DeletePersistentUdpPortReservation . Tenga en cuenta que el token de una reserva de puertos UDP persistente determinada puede cambiar cada vez que se reinicia el sistema.

Windows no implementa la seguridad entre componentes para las reservas persistentes obtenidas mediante estas funciones. Esto significa que, si se concede a un componente la capacidad de obtener reservas de puertos persistentes, ese componente obtiene automáticamente la capacidad de consumir cualquier reserva de puerto persistente concedida a cualquier otro componente del sistema. La seguridad de nivel de proceso se aplica para las reservas en tiempo de ejecución, pero este control no se puede extender a las reservas persistentes creadas mediante el creado mediante la función CreatePersistentTcpPortReservation o CreatePersistentUdpPortReservation .

Una vez que se ha obtenido una reserva de puertos UDP persistente, una aplicación puede solicitar asignaciones de puertos de la reserva de puertos UDP abriendo un socket UDP y llamando a la función WSAIoctl especificando el SIO_ASSOCIATE_PORT_RESERVATION IOCTL y pasando el token de reserva antes de emitir una llamada a la función bind en el socket.

El SIO_ACQUIRE_PORT_RESERVATION IOCTL se puede usar para solicitar una reserva en tiempo de ejecución para un bloque de puertos TCP o UDP. Para las reservas de puertos en tiempo de ejecución, el grupo de puertos requiere que las reservas se consuman desde el proceso en cuyo socket se concedió la reserva. Las reservas de puertos en tiempo de ejecución solo duran mientras dure el socket en el que se llamó al SIO_ACQUIRE_PORT_RESERVATION IOCTL. En cambio, las reservas de puertos persistentes creadas mediante la función CreatePersistentUdpPortReservation pueden consumirse en cualquier proceso con la capacidad de obtener reservas persistentes.

Un usuario que ha iniciado sesión como miembro del grupo Administradores solo puede llamar a la función CreatePersistentUdpPortReservation . Si un usuario llama a CreatePersistentUdpPortReservation que no es miembro del grupo Administradores, se producirá un error en la llamada a la función y se devolverá ERROR_ACCESS_DENIED . Esta función también puede producir un error debido al control de cuentas de usuario (UAC) en Windows Vista y versiones posteriores. Si un usuario inicia sesión como miembro del grupo Administradores que no sea el administrador integrado, esta llamada producirá un error a menos que la aplicación se haya marcado en el archivo de manifiesto con un valor requestedExecutionLevel establecido en requireAdministrator. Si la aplicación carece de este archivo de manifiesto, un usuario que inició sesión como miembro del grupo Administradores que no sea el administrador integrado debe ejecutar la aplicación en un shell mejorado como administrador integrado (administrador de RunAs) para que esta función se realice correctamente.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	iphlpapi.h
Library	Iphlpapi.lib
Archivo DLL	Iphlpapi.dll