функция обратного вызова NPI_PROVIDER_ATTACH_CLIENT_FN (netioddk.h)

Статья
08/07/2023

Функция обратного вызова ProviderAttachClient модуля поставщика подключает модуль поставщика к клиентскому модулю.

Синтаксис

NPI_PROVIDER_ATTACH_CLIENT_FN NpiProviderAttachClientFn;

NTSTATUS NpiProviderAttachClientFn(
  [in]  HANDLE NmrBindingHandle,
  [in]  PVOID ProviderContext,
  [in]  PNPI_REGISTRATION_INSTANCE ClientRegistrationInstance,
  [in]  PVOID ClientBindingContext,
  [in]  const VOID *ClientDispatch,
  [out] PVOID *ProviderBindingContext,
  [out] const VOID **ProviderDispatch
)
{...}

Параметры

[in] NmrBindingHandle

Дескриптор, используемый NMR для представления привязки между клиентским модулем и модулем поставщика.

[in] ProviderContext

Указатель на контекст регистрации модуля поставщика. Модуль поставщика передает этот указатель в NMR при вызове функции NmrRegisterProvider для регистрации в NMR.

[in] ClientRegistrationInstance

Указатель на NPI_REGISTRATION_INSTANCE структура. Эта структура содержит данные регистрации клиентского модуля.

[in] ClientBindingContext

Указатель на контекст клиентского модуля для привязки между клиентским модулем и модулем поставщика. Клиентский модуль использует этот контекст для отслеживания состояния привязки. Содержимое контекста привязки клиентского модуля непрозрачно для модуля поставщика. Модуль поставщика передает этот указатель клиентскому модулю при каждом вызове любой функции обратного вызова NPI клиентского модуля, для которых требуется контекст привязки клиентского модуля.

[in] ClientDispatch

Указатель на константную структуру, содержащую таблицу диспетчеризации функций обратного вызова NPI для клиентского модуля. Содержимое структуры зависит от NPI. Если NPI не определяет структуру таблицы диспетчеризации клиента, то этот указатель имеет значение NULL.

[out] ProviderBindingContext

Указатель на переменную, в которую модуль поставщика будет хранить указатель на его контекст для привязки между клиентским модулем и модулем поставщика. Модуль поставщика использует этот контекст для отслеживания состояния привязки. Содержимое контекста привязки модуля поставщика непрозрачно для клиентского модуля. Клиентский модуль передает этот указатель модулю поставщика всякий раз, когда он вызывает одну из функций NPI модуля поставщика, для которых требуется контекст привязки модуля поставщика. Модуль поставщика должен убедиться, что этот контекст остается допустимым и находится в памяти до тех пор, пока клиентский модуль подключен к модулю поставщика.

[out] ProviderDispatch

Указатель на переменную, в которую модуль поставщика будет хранить указатель на константную структуру, содержащую таблицу диспетчеризации функций NPI для модуля поставщика. Модуль поставщика должен убедиться, что эта структура остается действительной и находится в памяти, пока клиентский модуль подключен к модулю поставщика. Содержимое структуры зависит от NPI.

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

Функция обратного вызова ProviderAttachClient модуля поставщика возвращает один из следующих кодов NTSTATUS:

Код возврата	Описание
STATUS_SUCCESS	Модуль поставщика успешно подключен к клиентскому модулю.
STATUS_NOINTERFACE	Модуль поставщика не подключился к клиентскому модулю.
Другие коды состояния	Произошла ошибка.

NMR вызывает функцию обратного вызова ProviderAttachClient модуля поставщика, когда клиентский модуль вызывает функцию NmrClientAttachProvider с дескриптором, который представляет привязку между клиентским модулем и модулем поставщика.

Модуль поставщика может проверять данные регистрации клиентского модуля. Эти данные в структуре, на которую указывает параметр ClientRegistrationInstance . Модуль поставщика использует эти данные, чтобы определить, будет ли он подключаться к клиентскому модулю:

Если модуль поставщика определяет, что он будет присоединен к клиентскому модулю, функция обратного вызова ProviderAttachClient должна выполнять следующие действия:
1. Сохраните указатели, переданные в параметрах ClientBindingContext и ClientDispatch , чтобы модуль поставщика мог выполнять вызовы функций NPI клиентского модуля.
2. Сохраните дескриптор, переданный в параметре NmrBindingHandle . Модуль поставщика передает этот дескриптор в качестве параметра вФункция NmrProviderDetachClientComplete при отключении от клиентского модуля.
3. Задайте параметр ProviderBindingContext , чтобы указать структуру контекста привязки модуля поставщика для привязки между клиентским модулем и модулем поставщика.
4. Задайте параметр ProviderDispatch , чтобы он указывал на структуру, содержащую таблицу диспетчеризации модуля поставщика функций NPI .
5. Возврат STATUS_SUCCESS.
Если модуль поставщика определяет, что он не будет подключаться к клиентскому модулю, функция обратного вызова ProviderAttachClient должна возвращать STATUS_NOINTERFACE.

Если модуль поставщика подключается к клиентскому модулю и динамически выделяет память для контекста привязки, он должен освободить выделенную память, когда NMR вызывает модуль поставщика.Функция обратного вызова ProviderCleanupBindingContext после отсоединения клиентского модуля и модуля поставщика друг от друга.

NMR вызывает функцию обратного вызова ProviderAttachClient модуля поставщика в IRQL = PASSIVE_LEVEL.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows Vista и более поздних версиях операционных систем Windows.
Целевая платформа	Windows
Header	netioddk.h (включая Wsk.h)
IRQL	PASSIVE_LEVEL