Метод IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface (bits10_3.h)

Статья
07/16/2024

Сертификаты сервера отправляются при открытии подключения HTTPS. Используйте этот метод, чтобы задать обратный вызов для проверки этих сертификатов сервера.

Синтаксис

HRESULT SetServerCertificateValidationInterface(
  IUnknown *certValidationCallback
);

Параметры

certValidationCallback

Тип: IUnknown*

Указатель на объект, реализующий IBackgroundCopyServerCertificateValidationCallback. Чтобы удалить текущий указатель интерфейса обратного вызова, задайте для этого параметра значение nullptr.

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

Тип: HRESULT

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

Возвращаемое значение	Описание
E_NOINTERFACE	Вы передаете указатель интерфейса, который не может запрашиваться для IBackgroundCopyServerCertificateValidationCallback.
BG_E_READ_ONLY_WHEN_JOB_ACTIVE	Состояние задания должно быть ПРИОСТАНОВЛЕНо, чтобы задать обратный вызов.

Замечания

Используйте этот метод, если вы хотите выполнить собственные проверки на сертификате сервера.

Вызовите этот метод только при реализации интерфейса IBackgroundCopyServerCertificateValidationCallback.

Интерфейс проверки становится недействительным при завершении работы приложения; BITS не поддерживает запись интерфейса проверки. В результате процесс инициализации приложения должен вызывать SetServerCertificateValidationInterface для существующих заданий, для которых требуется получать запросы на проверку сертификатов.

Если несколько вызовов приложений SetServerCertificateValidationInterface, чтобы задать интерфейс уведомлений для задания, последнее приложение для вызова — это тот, который получит уведомления. Другие приложения не будут получать уведомления.

Если во время проверки сертификата обнаружены какие-либо ошибки сертификата, подключение прервано, а пользовательский обратный вызов никогда не вызывается. Логику проверки ОС можно настроить с помощью вызова IBackgroundCopyJobHttpOptions::SetSecurityFlags. Например, можно игнорировать ожидаемые ошибки проверки сертификата.

Если проверка ОС проходит, перед завершением подтверждения TLS вызывается метод IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate перед завершением подтверждения TLS и перед отправкой HTTP-запроса.

Если метод проверки отклоняет сертификат, задание перейдет в BG_JOB_STATE_TRANSIENT_ERROR с контекстом ошибки задания BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK и ошибкой HRESULT из обратного вызова. Если обратный вызов не удалось вызвать (например, так как BITS требуется для проверки сертификата сервера после завершения программы), код ошибки задания будет BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. После следующего запуска приложения он может исправить эту ошибку, задав обратный вызов проверки еще раз и повторив задание.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 10 версии 1809 [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2016 [только классические приложения]
заголовка	bits10_3.h (include Bits.h)
библиотеки	Bits.lib
DLL	Bits.dll

См. также

IBackgroundCopyServerCertificateValidationCallback

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