Функция NdisRegisterProtocol (ndis.h)

Статья
08/07/2023

Примечание NDIS 5. X является нерекомендуемым и заменен NDIS 6. x. Сведения о разработке новых драйверов NDIS см. в статье Сетевые драйверы, начиная с Windows Vista. Сведения о переносе NDIS 5. x драйверы для NDIS 6. x, см. раздел Перенос драйверов NDIS 5.x в NDIS 6.0.

NdisRegisterProtocol регистрирует точки входа и имя protocolXxx драйвера NDIS в библиотеке NDIS при инициализации драйвера.

Синтаксис

void NdisRegisterProtocol(
  [out] PNDIS_STATUS                   Status,
  [out] PNDIS_HANDLE                   NdisProtocolHandle,
  [in]  PNDIS_PROTOCOL_CHARACTERISTICS ProtocolCharacteristics,
  [in]  UINT                           CharacteristicsLength
);

Параметры

[out] Status

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

NDIS_STATUS_SUCCESS
Библиотека NDIS зарегистрировала вызывающий объект в качестве драйвера протокола.
NDIS_STATUS_BAD_CHARACTERISTICS
Параметр CharacteristicsLength слишком мал для параметра MajorNdisVersion, указанного в буфере в разделе ProtocolCharacteristics.
NDIS_STATUS_BAD_VERSION
Параметр MajorNdisVersion, указанный в буфере в параметре ProtocolCharacteristics , недопустим.
NDIS_STATUS_RESOURCES
Нехватка ресурсов, возможно, памяти, не позволила библиотеке NDIS зарегистрировать вызывающий объект.

[out] NdisProtocolHandle

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

[in] ProtocolCharacteristics

Указатель на структуру NDIS_PROTOCOL_CHARACTERISTICS, настроенную вызывающим элементом. Структура в ProtocolCharacteristics определяется следующим образом:

        typedef struct _NDIS_PROTOCOL_CHARACTERISTICS {
            UCHAR MajorNdisVersion;
            UCHAR MinorNdisVersion;
            UINT Reserved;
            OPEN_ADAPTER_COMPLETE_HANDLER OpenAdapterCompleteHandler;
            CLOSE_ADAPTER_COMPLETE_HANDLER CloseAdapterCompleteHandler;
            SEND_COMPLETE_HANDLER SendCompleteHandler;
            TRANSFER_DATA_COMPLETE_HANDLER TransferDataCompleteHandler;
            RESET_COMPLETE_HANDLER ResetCompleteHandler;
            REQUEST_COMPLETE_HANDLER RequestCompleteHandler;
            RECEIVE_HANDLER ReceiveHandler;
            RECEIVE_COMPLETE_HANDLER ReceiveCompleteHandler;
            STATUS_HANDLER StatusHandler;
            STATUS_COMPLETE_HANDLER StatusCompleteHandler;
            NDIS_STRING Name;
        //
        // MajorNdisVersion must be set to 0x04 or 0x05
        // with any of the following members.
        //
            RECEIVE_PACKET_HANDLER ReceivePacketHandler;
            BIND_HANDLER BindAdapterHandler;
            UNBIND_HANDLER UnbindAdapterHandler;
            PNP_EVENT_HANDLER PnPEventHandler;
            UNLOAD_PROTOCOL_HANDLER UnloadHandler;
        //
        // MajorNdisVersion must be set to 0x05 
        // with any of the following members.
        //
            CO_SEND_COMPLETE_HANDLER CoSendCompleteHandler;
            CO_STATUS_HANDLER CoStatusHandler;
            CO_RECEIVE_PACKET_HANDLER CoReceivePacketHandler;
            CO_AF_REGISTER_NOTIFY_HANDLER CoAfRegisterNotifyHandler;
        } NDIS_PROTOCOL_CHARACTERISTICS, *PNDIS_PROTOCOL_CHARACTERISTICS;

Драйвер должен инициализировать эту структуру нулями, прежде чем настраивать следующие элементы:

MajorNdisVersion
Указывает основную версию библиотеки NDIS, используемой драйвером. Текущее значение 0x05, хотя библиотека NDIS продолжает поддерживать существующие драйверы, разработанные для NDIS версии 4.0. NDIS больше не поддерживает протоколы версии 3.0.
MinorNdisVersion
Указывает дополнительную версию NDIS. Текущее значение — 0x00.
Reserved
Этот элемент зарезервирован для использования системой.
OpenAdapterCompleteHandler
Указывает точку входа функции ProtocolOpenAdapterComplete вызывающего объекта.
CloseAdapterCompleteHandler
Указывает точку входа функции ProtocolCloseAdapterComplete вызывающего объекта.
SendCompleteHandler
Указывает точку входа функции ProtocolSendComplete вызывающего объекта, если она есть.
TransferDataCompleteHandler
Указывает точку входа функции ProtocolTransferDataComplete вызывающего объекта, если она есть.
ResetCompleteHandler
Указывает точку входа функции ProtocolResetComplete вызывающего объекта.
RequestCompleteHandler
Указывает точку входа функции ProtocolRequestComplete вызывающего объекта.
ReceiveHandler
Указывает точку входа функции ProtocolReceive вызывающего объекта, если она есть.
ReceiveCompleteHandler
Указывает точку входа функции ProtocolReceiveComplete вызывающего объекта.
StatusHandler
Указывает точку входа функции ProtocolStatus вызывающего объекта, если она есть.
StatusCompleteHandler
Указывает точку входа функции ProtocolStatusComplete вызывающего объекта.
имя;
Тип NDIS_STRING, содержащий инициализированную инициализированную строку счетчика в системной кодировке по умолчанию, именующую драйвер. Для драйверов Windows 2000 и более поздних версий эта строка содержит символы Юникода. То есть для Windows 2000 и более поздних версий NDIS определяет тип NDIS_STRING как тип UNICODE_STRING . Эта строка должна соответствовать строке, указанной в реестре (в разделе Службы) при установке протокола.

NdisRegisterProtocol преобразует предоставленную строку в верхний регистр, поэтому модуль записи драйвера протокола не может предположить, что изменение регистра уже зарегистрированного имени протокола создает уникальное имя драйвера.
ReceivePacketHandler
Указывает точку входа функции ProtocolReceivePacket вызывающего объекта , если она имеется, или ЗНАЧЕНИЕ NULL. Протоколы, которые привязываются к любому драйверу сетевого адаптера, который поддерживает многопакетные указания получения, должны предоставлять функцию ProtocolReceivePacket для повышения их производительности. Однако протокол, который привязывается исключительно к минипортам, ориентированным на подключение, также может присвоить этому члену значение NULL.
BindAdapterHandler
Указывает точку входа функции ProtocolBindAdapter вызывающего объекта. Вызывающие элементы, задающие значение в элементе MajorNdisVersion 0x05 или 0x04, должны предоставлять функцию ProtocolBindAdapter и поддерживать Plug and Play. Промежуточные драйверы NDIS также должны предоставлять функцию ProtocolBindAdapter , которая позволяет этим промежуточным драйверам вызывать NdisIMRegisterLayeredMiniport и откладывать полную инициализацию драйвера до инициализации базовых драйверов сетевой карты.
UnbindAdapterHandler
Указывает точку входа функции ProtocolUnbindAdapter вызывающего объекта. Драйверы NDIS, предоставляющие функцию ProtocolBindAdapter , также должны предоставлять функцию ProtocolUnbindAdapter .
PnPEventHandler
Указывает точку входа функции ProtocolPnPEvent вызывающего объекта, если она есть.
UnloadHandler
Указывает точку входа функции ProtocolUnbind вызывающего объекта, если она имеется, или значение NULL.
CoSendCompleteHandler
Указывает точку входа функции ProtocolCoSendComplete вызывающего объекта, которую должен предоставить клиент или диспетчер вызовов, ориентированный на подключение. Клиент, ориентированный на подключение, предоставляет функцию ProtocolSendComplete , если он также привязывается к минипортам без подключения.
CoStatusHandlerCoStatusHandler
Указывает точку входа функции ProtocolCoStatus вызывающего объекта, которую должен предоставить клиент или диспетчер вызовов, ориентированный на подключение. Клиент, ориентированный на подключение, предоставляет функцию ProtocolStatus, если он также привязывается к минипортам без подключения.
CoReceivePacketHandler
Указывает точку входа функции ProtocolCoReceivePacket вызывающего объекта, которую должен предоставить клиент или диспетчер вызовов, ориентированный на подключение. Клиент, ориентированный на подключение, предоставляет функцию ProtocolReceivePacket и (или) функции ProtocolReceive и ProtocolTransferDataComplete , если он также привязывается к минипортам без подключения.
CoAfRegisterNotifyHandler
Указывает точку входа функции ProtocolAfRegisterNotify вызывающего объекта, которую должен предоставить клиент, ориентированный на подключение.

[in] CharacteristicsLength

Задает размер структуры в байтах в разделе ProtocolCharacteristics. Если директива сборки -DNDIS50=1 или -DNDIS40=1 указана в файле источников перед #includeNdis.h , параметру sizeof(NDIS_PROTOCOL_CHARACTERISTICS) автоматически присваивается соответствующее значение. Если ни указана ни та или иная директива, NDIS предполагает, что используется структура характеристик версии 3.0.

Значения, заданные в элементах MajorNdisVersion и MinorNdisVersion структуры характеристик, должны соответствовать директиве build или должны быть 0x03 и 0x00 соответственно.

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

None

Remarks

Драйвер протокола должен указать MajorNdisVersion 0x05 (текущая версия) или 0x04. NDIS больше не поддерживает протоколы V.30 и поэтому не загружает протокол, указывающий MajorNdisVersion 0x03.

Все протоколы должны поддерживать Plug and Play (PnP). Поэтому протокол должен указывать точки входа для BindAdapterHandler и UnbindAdapterHandler. NDIS не загружает протокол, указывающий значение NULL для этих обработчиков.

Для достижения максимальной производительности любой протокол, который будет выполняться над драйвером сетевого адаптера без подключения, поддерживающим получение нескольких пакетов, должен предоставлять функцию ProtocolReceivePacket . Такой драйвер протокола также должен предоставлять функцию ProtocolReceive . Любой драйвер сетевого адаптера без подключения, поддерживающий отправку с несколькими пакетами, также может указывать на получение нескольких пакетов.

Все протоколы, ориентированные на подключение, будь то клиенты или диспетчеры вызовов, должны регистрировать функцию ProtocolCoReceivePacket . Клиентские протоколы, которые также привязываются к драйверам сетевого адаптера без подключения, также предоставляют функции ProtocolReceivePacket и ProtocolReceive . Протоколы, ориентированные на подключение, должны регистрировать дополнительные точки входа, ориентированные на подключение, с помощью NDIS путем вызова NdisClOpenAddressFamily для клиентов или NdisCmRegisterAddressFamily для диспетчеров вызовов из функций ProtocolBindAdapter .

После успешного вызова NdisRegisterProtocol драйвер не может изменить предоставленный набор функций ProtocolXxx .

Успешно зарегистрированный драйвер должен сохранить дескриптор, возвращенный в NdisProtocolHandle. Это обязательный параметр для других функций NdisXxx , которые драйвер вызывает впоследствии.

После успешного вызова NdisRegisterProtocol функция DriverEntry протокола с поддержкой PnP или протокола, ориентированного на подключение, возвращает управление, так как функция ProtocolBindAdapter такого драйвера будет вызываться впоследствии один или несколько раз для настройки привязок к базовым сетевым картам. В противном случае драйвер протокола может вызвать NdisOpenAdapter , чтобы настроить привязку к базовому драйверу сетевого адаптера или выполнить слой выше любого драйвера NDIS, который зарегистрировал набор функций NDIS MiniportXxx .

Целевая платформа: универсальная
Версия: не поддерживается для драйверов NDIS 6.0 в Windows Vista. Вместо этого используйте NdisRegisterProtocolDriver. Поддерживается для драйверов NDIS 5.1 в Windows Vista и Windows XP.

Требования

Требование	Значение
Заголовок	ndis.h (включая Ndis.h)
Библиотека	Ndis.lib
IRQL	PASSIVE_LEVEL