Поделиться через

Использование API сервера служб развертывания Windows

  • Статья

В средах, где невозможно использовать стандартное решение служб развертывания Windows (WDS), сервер WDS предоставляет API, который позволяет разработчикам создавать подключаемые модули, называемые поставщиками, для обработки запросов среды выполнения предварительной загрузки (PXE). При написании поставщиков PXE для WDS разработчикам следует придерживаться следующих рекомендаций.

Установка роли WDS на сервере

  • Службы развертывания Windows (WDS) — это пересмотренная версия служб удаленной установки (RIS). Для реализации PXE-сервера и поставщиков WDS потребуется роль сервера WDS.
  • WDS заменяет RIS в качестве стандартного компонента, начиная с Windows Server 2008 и Windows Server 2003 с пакетом обновления 2 (SP2).
  • Необходимо обновить сервер RIS до WDS в Windows Server 2003 с пакетом обновления 1 (SP1). Вы можете установить роль сервера WDS с помощью пакет автоматической установки Windows (WAIK).

Регистрация поставщиков

  • Зарегистрируйте библиотеку динамической компоновки поставщика (DLL) во время ее установки и вставьте поставщика в упорядоченный список зарегистрированных поставщиков.

    Примечание

    При установке нового или измененного поставщика необходимо перезапустить службу PXE WDS, чтобы изменения вступили в силу.

     

  • Используйте функцию PxeProviderRegister , чтобы зарегистрировать поставщик и добавить его в список. Используйте функцию PxeProviderUnRegister , чтобы отменить регистрацию зарегистрированного поставщика и удалить его из списка.

  • Укажите последовательность поставщика в упорядоченном списке. Индекс поставщика в списке не может быть гарантирован, так как другой поставщик может быть позже зарегистрирован до него. Чтобы вставить поставщик в список до или после другого зарегистрированного поставщика, сначала используйте функцию PxeProviderQueryIndex , чтобы получить индекс зарегистрированного поставщика, а затем зарегистрируйте новый поставщик, указав большее или меньшее значение индекса.

  • При установке могут храниться сведения о конфигурации поставщика в разделе реестра, возвращаемом при регистрации поставщика. Адрес раздела реестра получается phProviderKeyобъекта PxeProviderRegister. Поставщик получает дескриптор того же ключа, что и параметр hProviderKey для обратного вызова PxeProviderInitialize . Поставщик должен хранить адрес этого ключа.

  • Всегда устанавливайте библиотеку динамической компоновки поставщика (DLL) в папке Program Files сервера.

Initialize

  • Включите библиотеку DLL, которая экспортирует функцию обратного вызова PxeProviderInitialize в поставщик. Для каждого поставщика требуется обратный вызов PxeProviderInitialize . Когда служба WDS загружает поставщик, она вызывает функцию PxeProviderInitialize поставщика и передает дескриптор тому же ключу, который используется для хранения сведений о конфигурации во время регистрации поставщика.
  • Когда обратный вызов PxeProviderInitialize возвращается и завершается успешно, поставщик должен быть полностью инициализирован и готов к обработке запросов.
  • Регистрируйте каждый обратный вызов в поставщике во время обработки функции PxeProviderInitialize . Обратные вызовы должны быть зарегистрированы с помощью функции PxeRegisterCallback .
  • Инициализируйте все внутренние ресурсы поставщика в рамках обработки его функции PxeProviderInitialize .

Завершить работу

  • Реализуйте обратный вызов PxeProviderShutdown . Каждый поставщик должен иметь обратный вызов PxeProviderShutdown.
  • Функция обратного вызова PxeProviderShutdown должна полностью завершить работу поставщика и освободить все его ресурсы.
  • После возврата обратного вызова PxeProviderShutdown дескриптор hProvider , переданный функции PxeProviderInitialize , становится недействительным и не должен использоваться для вызова WDS.
  • Зарегистрируйте обратный вызов PxeProviderShutdown , вызвав функцию PxeRegisterCallback с PXE_CALLBACK_SHUTDOWN во время обработки обратного вызова PxeProviderInitialize . Не вызывайте обратный вызов PxeProviderShutdown , если функция PxeProviderInitialize завершается сбоем.

Обработка пакета запроса

Реализуйте обратный вызов PxeProviderRecvRequest для поставщика. Каждый поставщик должен иметь обратный вызов PxeProviderRecvRequest . Когда служба WDS получает запрос, она вызывает обратный вызов PxeProviderRecvRequest для первого поставщика в списке зарегистрированных поставщиков.

  • Если поставщик будет обрабатывать этот запрос синхронно, функция PxeProviderRecvRequest должна вернуть значение ERROR_SUCCESS. Если и только в том случае, если поставщик будет обрабатывать этот запрос асинхронно, обратный вызов PxeProviderRecvRequest должен возвращать ERROR_IO_PENDING и вызывать функцию PxeAsyncRecvDone при обработке запроса.

  • Обратный вызов PxeProviderRecvRequest и функция PxeAsyncRecvDone возвращают адрес перечисления PXE_BOOT_ACTION , описывающего действия, предпринятые поставщиком для обработки запроса.

    Существует четыре способа обработки запроса поставщиком:

    • Поставщик отвечает клиенту стандартным пакетом ответа DHCP, содержащим путь к программе загрузки сети. Возврат значения PXE_BA_NBP для перечисления означает, что поставщик успешно обработал пакет запроса и выполнил запрос, отправив пакет ответа, вызвав функции PxePacketAllocate и PxeSendReply .
    • Поставщик отвечает клиенту с пользовательским пакетом ответа, который не соответствует DHCP. Возврат значения PXE_BA_CUSTOM для перечисления означает, что поставщик успешно обработал пакет запроса и выполнил запрос, отправив пользовательский пакет ответа, вызвав функции PxePacketAllocate и PxeSendReply .
    • Поставщик определяет, что запрос следует игнорировать. Возврат значения PXE_BA_IGNORE для перечисления означает, что поставщик отпустил все ресурсы, связанные с запросом, и запрос не передается следующему поставщику в списке зарегистрированных поставщиков. Поставщики могут использовать этот параметр, если обнаруживают, что пакет запроса является недопустимым.
    • Поставщик отклоняет обслуживание запроса. Возвращая значение PXE_BA_REJECT для перечисления, система передает запрос следующему поставщику в списке зарегистрированных поставщиков. Если этот поставщик был последним в списке, он освобождает все ресурсы, связанные с запросом, и запрос игнорируется.
    • Зарегистрируйте обратный вызов PxeProviderRecvRequest , вызвав функцию PxeRegisterCallback с PXE_CALLBACK_RECV_REQUEST во время обработки обратного вызова PxeProviderInitialize .

Создание пакета ответа

  • Используйте API для записи поставщиков для обработки ЗАПРОСОВ DHCP и создания пакетов ответа.
  • Функция PxeProviderSetAttribute указывает атрибуты, используемые поставщиком для фильтрации пакетов. Атрибуты поставщика можно указать таким образом, чтобы поставщик видел все пакеты, поставщик видел только пакеты DHCP, или поставщик видел только пакеты DHCP, указывающие параметр идентификатора класса поставщика DHCP (60) как "PXEClient".
  • Функция PxeDhcpIsValid проверяет, является ли пакет допустимым пакетом DHCP. Поставщики могут использовать функцию PxeDhcpIsValid, чтобы проверка, является ли пакет от клиента DHCP-пакетом, если для фильтра, заданного с помощью функции PxeProviderSetAttribute, задано получение всех пакетов, чтобы определить, является ли указанный пакет допустимым DHCP-пакетом.
  • Функция PxeDhcpInitialize инициализирует ответный пакет как пакет ответа DHCP, основанный на информации в пакете, полученном от клиента. Функция PxeProviderInitialize принимает адрес допустимого dhcp-пакета, полученного от клиента в обратном вызове PxeProviderRecvRequest . Функция PxeDhcpInitialize принимает указатель на пакет ответа, выделенный с помощью функции PxePacketAllocate .
  • Функция PxeDhcpGetOptionValue извлекает значение параметра из пакета DHCP. Функция PxeDhcpGetVendorOptionValue извлекает значение параметра из поля Сведения о поставщике (43) пакета DHCP.
  • Затем поставщик может заполнить пакет ответа информацией и использовать функцию PxeSendReply для отправки пакета ответа клиенту. Функция PxeDhcpAppendOption добавляет параметр DHCP к пакету ответа.
  • Поставщик, который отвечает на клиентские запросы, отправляя пакет, должен выделить пакет ответа с помощью функции PxePacketAllocate . Затем поставщик может заполнить пакет ответа информацией и использовать функцию PxeSendReply для отправки пакета ответа клиенту.
  • Если выделенная память больше не нужна, поставщик должен освободить ее с помощью функции PxePacketFree .

Перечисление зарегистрированных поставщиков

  • Используйте API для записи поставщиков, которые перечисляют и проверка других зарегистрированных поставщиков в списке.
  • Функция PxeGetServerInfo возвращает сведения о PXE-сервере. Функция PxeGetServerInfo возвращает BOOL , указывающее, включена ли трассировка для сервера. Значение TRUE указывает, что трассировка включена.
  • Функция PxeProviderEnumFirst запускает перечисление поставщиков в списке зарегистрированных поставщиков. Функция PxeProviderEnumFirst запускает перечисление и возвращает адрес дескриптора, который следует использовать при вызове функции PxeProviderEnumNext . Функция PxeProviderEnumNext возвращает структуру PXE_PROVIDER , содержащую сведения о поставщике. Функция PxeProviderFreeInfo освобождает память, выделенную для структуры PXE_PROVIDER функцией PxeProviderEnumNext . Функция PxeProviderEnumClose закрывает перечисление поставщиков в списке зарегистрированных поставщиков.

Обработка кодов элементов управления службой

  • При получении сообщения об управлении службой служба WDS вызывает обратный вызов PxeProviderServiceControl .
  • Поставщик может определить функцию обратного вызова PxeProviderServiceControl для обработки сообщений управления службой.
  • Зарегистрируйте обратный вызов PxeProviderServiceControl , вызвав функцию PxeRegisterCallback с PXE_CALLBACK_SERVICE_CONTROL во время обработки обратного вызова PxeProviderInitialize .

Добавление записей трассировки в журнал PXE

  • Функция PxeTrace добавляет запись трассировки в журнал PXE. WDSPXE предоставляет трассировку, чтобы помочь администраторам в устранении неполадок. Поставщики могут регистрируют записи трассировки разных уровней серьезности. Администраторы могут настроить WDSPXE только для записей журнала для определенных уровней серьезности.

Сведения об API служб развертывания Windows

Использование API клиента служб развертывания Windows