Функция CreatePersistentUdpPortReservation (iphlpapi.h)

Статья
03/14/2023

Функция CreatePersistentUdpPortReservation создает постоянное резервирование портов UDP для последовательного блока UDP-портов на локальном компьютере.

Синтаксис

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

Параметры

[in] StartPort

Начальный номер порта UDP в порядке сетевых байтов.

[in] NumberOfPorts

Число зарезервированных портов UDP.

[out] Token

Указатель на маркер резервирования портов, который возвращается в случае успешного выполнения функции.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение будет NO_ERROR.

Если функция завершается сбоем, возвращаемое значение представляет собой один из следующих кодов ошибок.

Код возврата	Описание
ERROR_ACCESS_DENIED	Отказано в доступе". Эта ошибка возвращается при нескольких условиях, которые включают следующее: у пользователя отсутствуют необходимые права администратора на локальном компьютере или приложение не выполняется в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени).
ERROR_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если в параметрах StartPort или NumberOfPorts передается ноль. Эта ошибка также возвращается, если параметр NumberOfPorts слишком велик, в зависимости от параметра StartPort , что выделенный блок портов превысит максимальное количество выделенных портов.
ERROR_SHARING_VIOLATION	The process cannot access the file because it is being used by another process. Эта ошибка возвращается, если UDP-порт в блоке портов UDP, указанных параметрами StartPort и NumberOfPorts , уже используется. Эта ошибка также возвращается, если постоянное резервирование для блока портов UDP, указанных параметрами StartPort и NumberOfPorts , соответствует или перекрывает постоянное резервирование для уже созданного блока портов UDP.
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки.

Приложения и службы, которым необходимо зарезервировать порты, делятся на две категории. К первой категории относятся компоненты, которым требуется определенный порт в рамках операции. Такие компоненты обычно предпочитают указывать необходимый порт во время установки (например, в манифесте приложения). Вторая категория включает компоненты, которым требуется любой доступный порт или блок портов во время выполнения.

Эти две категории соответствуют конкретным запросам на резервирование портов и с подстановочными знаками. Определенные запросы на резервирование могут быть постоянными или выполняться во время выполнения, а запросы на резервирование портов с подстановочными знаками поддерживаются только во время выполнения.

Функция CreatePersistentUdpPortReservation позволяет приложению или службе постоянно резервировать блок портов UDP. Постоянные резервирования TCP записываются в постоянное хранилище для модуля UDP в Windows.

Вызывающий объект получает постоянное резервирование портов, указывая, сколько портов требуется и требуется ли определенный диапазон. Если запрос может быть удовлетворен, функция CreatePersistentUdpPortReservation возвращает уникальный непрозрачный маркер ULONG64, который впоследствии идентифицирует резервирование. Постоянное резервирование портов UDP может быть освобождено путем вызова функции DeletePersistentUdpPortReservation . Обратите внимание, что маркер для заданного постоянного резервирования портов UDP может изменяться при каждом перезапуске системы.

Windows не реализует межкомпонентную безопасность для постоянных резервирований, полученных с помощью этих функций. Это означает, что если компоненту предоставляется возможность получать любые постоянные резервирования портов, этот компонент автоматически получает возможность использовать любые постоянные резервирования портов, предоставленные любому другому компоненту в системе. Безопасность на уровне процесса применяется для резервирований среды выполнения, но такое управление нельзя распространить на постоянные резервирования, созданные с помощью функции CreatePersistentTcpPortReservation или CreatePersistentUdpPortReservation .

После получения постоянного резервирования портов UDP приложение может запросить назначения портов из резервирования портов UDP, открыв сокет UDP, а затем вызвав функцию WSAIoctl , указав SIO_ASSOCIATE_PORT_RESERVATION IOCTL и передав маркер резервирования перед вызовом функции bind в сокете.

IOCTL SIO_ACQUIRE_PORT_RESERVATION можно использовать для запроса резервирования среды выполнения для блока портов TCP или UDP. Для резервирования портов среды выполнения пул портов требует, чтобы резервирования были использованы из процесса, в сокете которого было предоставлено резервирование. Резервирование портов среды выполнения длится только до времени существования сокета, в котором был вызван SIO_ACQUIRE_PORT_RESERVATION IOCTL. Напротив, резервирования постоянных портов, созданные с помощью функции CreatePersistentUdpPortReservation , могут использоваться любым процессом с возможностью получения постоянных резервирований.

Функция CreatePersistentUdpPortReservation может вызываться только пользователем, вошедшего в систему как член группы Администраторы. Если метод CreatePersistentUdpPortReservation вызывается пользователем, не включаемым в группу Администраторы, вызов функции завершится ошибкой, и возвращается ERROR_ACCESS_DENIED . Эта функция также может завершиться ошибкой из-за контроля учетных записей (UAC) в Windows Vista и более поздних версиях. Если приложение, содержащее эту функцию, выполняется пользователем, вошедшего в систему как участник группы администраторов, отличный от встроенного администратора, этот вызов завершится ошибкой, если приложение не было отмечено в файле манифеста параметром requestedExecutionLevel , для которого задано значение requireAdministrator. Если в приложении отсутствует этот файл манифеста, пользователь, вошедший в группу администраторов, отличный от встроенного администратора, должен выполнять приложение в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени) для успешного выполнения этой функции.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	iphlpapi.h
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll