NdisOpenAdapter 函式 (ndis.h)
注意 NDIS 5. x 已被取代,且由 NDIS 6 取代。 x。 如需新的 NDIS 驅動程式開發,請參閱 從 Windows Vista 開始的網路驅動程式。 如需移植 NDIS 5 的相關信息。 x 驅動程式至 NDIS 6。 x,請參閱 將 NDIS 5.x 驅動程式移植到 NDIS 6.0。
NdisOpenAdapter 會設定呼叫通訊協定與特定基礎 NIC 驅動程式或 NDIS 中繼驅動程式之間的系結。
語法
void NdisOpenAdapter(
[out] PNDIS_STATUS Status,
[out] PNDIS_STATUS OpenErrorStatus,
[out] PNDIS_HANDLE NdisBindingHandle,
[out] PUINT SelectedMediumIndex,
[in] PNDIS_MEDIUM MediumArray,
[in] UINT MediumArraySize,
[in] NDIS_HANDLE NdisProtocolHandle,
[in] NDIS_HANDLE ProtocolBindingContext,
[in] PNDIS_STRING AdapterName,
[in] UINT OpenOptions,
[in, optional] PSTRING AddressingInformation
);
參數
[out] Status
呼叫端提供的變數指標,可以是下列其中一個值,可從此函式傳回:
STATUS_SUCCESS
現在已設定要求的系結,因此呼叫端可以在後續呼叫 NdisXxx 中使用在 NdisBindingHandle 和 SelectedMediumIndex 傳回的值。NDIS_STATUS_PENDING
要求的作業是以異步方式處理,而呼叫端的 ProtocolOpenAdapterComplete 函式會在開啟完成時呼叫。NDIS_STATUS_RESOURCES
要求的作業失敗,因為 NDIS 無法配置足夠的記憶體或初始化用來追蹤開啟系結的狀態。NDIS_STATUS_ADAPTER_NOT_FOUND
要求的作業失敗,因為無法在系統物件命名空間中找到 AdapterName 的名稱。NDIS_STATUS_UNSUPPORTED_MEDIA
MediumArray 上的陣列未指定 NDIS 或基礎驅動程式所支援的任何媒體。NDIS_STATUS_CLOSING
呼叫端或在 AdapterName 指定的實體或虛擬設備正在關閉。NDIS_STATUS_OPEN_FAILED
基於上述任何特定原因,開啟嘗試失敗。 例如,NDIS 可能無法初始化所選媒體的篩選套件。
[out] OpenErrorStatus
如果 NdisOpenAdapter 在 Status 中傳回錯誤,則呼叫端提供的變數指標可包含NDIS_STATUS_XXX 錯誤,以提供詳細資訊。 例如,令牌通道 NIC 的驅動程式可能會在此變數中傳回通道錯誤。
[out] NdisBindingHandle
呼叫端提供的變數指標,其中 NDIS 會傳回句柄,代表呼叫端與 在 AdapterName 中指定的指定實體或虛擬 NIC 之間的成功系結。
[out] SelectedMediumIndex
呼叫端提供的變數指標,其中 NDIS 會傳回數位元素的索引,指定基礎 NDIS 驅動程式所使用的媒體類型。
[in] MediumArray
指定呼叫端可支援之媒體類型的NDIS_MEDIUM型別值的陣列指標。 可能的元素包含下列任何適當的子集:
NdisMedium802_3
指定乙太網路 (802.3) 網路。NdisMedium802_5
指定令牌通道 (802.5) 網路。NdisMediumFddi
指定光纖分散式數據介面 (FDDI) 網路。NdisMediumWan
指定廣域網。 此類型涵蓋各種形式的點對點和 WAN NIC,以及必須在建立系結之後,通訊協定驅動程式與基礎驅動程式之間交涉的變體位址/標頭格式。NdisMediumLocalTalk
指定 LocalTalk 網路。NdisMediumDix
指定驅動程式使用 DIX 乙太網路標頭格式的乙太網路。NdisMediumArcnetRaw
指定 ARCNET 網路。NdisMediumArcnet878_2
指定 ARCNET (878.2) 網路。NdisMediumAtm
指定 ATM 網路。 線上導向客戶端通訊協定可以自行系結至傳回此值的基礎迷你埠驅動程式。 否則,舊版通訊協定會自行系結至系統提供的 LanE 中繼驅動程式,這會根據網路管理員如何設定 LanE 驅動程式,將其中型類型回報為 NdisMedium802_3 或 NdisMedium802_5。NdisMediumWirelessWan
指定無線網路。 支援無線 LAN (WLAN) 或無線 WAN 的 NDIS 5.X 迷你埠驅動程式, (WWAN) 封包將其媒體宣告為 NdisMedium802_3 ,並將乙太網路模擬至較高層級的 NDIS 驅動程式。注意 此媒體類型無法從 Windows Vista 開始使用。
NdisMediumIrda
指定 irDA) 網路的基礎結構 (。NdisMediumCoWan
指定連線導向環境中的廣域網。NdisMedium1394
指定 IEEE 1394 (引發網路) 網路。
[in] MediumArraySize
指定 MediumArray 上的項目數目。
[in] NdisProtocolHandle
指定 NdisRegisterProtocol 傳回的句柄。
[in] ProtocolBindingContext
指定呼叫端提供的駐留內容區域的句柄,通訊協定會在建立此系結之後維護此系結的狀態。
[in] AdapterName
NDIS_STRING類型的指標,其中包含系統預設字元集中指定的計數位符串,為基礎 NDIS 驅動程式命名 NIC 或虛擬配接器。 此驅動程式會匯出一組上邊緣 ( MiniportXxx) 函式。 對於 Windows 2000 和更新版本的驅動程式,此計算字串包含 Unicode 字元。 也就是說,針對 Windows 2000 和更新版本,NDIS 會將NDIS_STRING類型定義為 UNICODE_STRING 類型。
[in] OpenOptions
指定位掩碼,其中包含呼叫端傳遞至下一個較低驅動程式的旗標,假設為 NIC 驅動程式。 目前,此參數保留供系統使用。
[in, optional] AddressingInformation
選擇性可變長度計數位符串的指標,其中包含 NIC 驅動程式可用來程式設計 netcard 的基礎 NIC 特定資訊。 此指標可以是 NULL。
如果已提供,尋址信息必須維持有效狀態,直到開啟的作業完成為止。 支援異步數據機的基礎 NIC 驅動程式可以使用這項資訊進行撥號。
傳回值
無
備註
通訊協議驅動程式會從其 ProtocolBindAdapter 函式呼叫 NdisOpenAdapter。 NDIS 不再支援從 DriverEntry 函式呼叫 NdisOpenAdapter,這是舊版 (V3.0) 通訊協定可用的選項。 NDIS 不再支援 V3.0 通訊協定。 NDIS 無法嘗試在 ProtocolBindAdapter 的內容之外呼叫 NdisOpenAdapter。
只有在 NdisOpenAdapter 傳回控件之前,AdapterName 上的字串才會保持有效狀態,即使它傳回狀態NDIS_STATUS_PENDING也一樣。
如果 NdisOpenAdapter 傳回NDIS_STATUS_PENDING,則應該忽略 NdisBindingHandle 和 SelectedMediumIndex 的變數,直到呼叫 ProtocolOpenAdapterComplete 函式為止。 由於這些變數在呼叫 ProtocolOpenAdapterComplete 之前可能會保持無效,因此它們不能位於堆棧上。 這些變數通常位於 ProtocolBindingContext 區域中,因為此句柄是 ProtocolOpenAdapterComplete 的輸入參數。
通訊協議驅動程序應該保留 在 NdisProtocolHandle 傳回的句柄。 這是驅動程序後續呼叫之其他 NdisXxx 函式的必要參數。 提供的 ProtocolBindingContext 是呼叫端 ProtocolXxx 函式的輸入參數,因此通訊協定通常會將 NdisProtocolHandle 指標傳遞至呼叫端配置內容區域中呼叫 NdisOpenAdapter 的某個變數。
呼叫端會在後續呼叫 NdisRequest 和/或 NdisCoRequest 時,使用 SelectedMediumIndex 傳回的值。 在要求封包中設定的 OID 取決於傳回 的 NdisMediumXxx。 例如,如果在 SelectedMediumIndex 傳回 NdisMediumAtm,通訊協定驅動程式會在指定 OID_ATM_ XXX 或 OID_CO_XXX 代碼時呼叫 NdisCoRequest,並在指定 OID_GEN_XXX 代碼時呼叫 NdisRequest。
如果在 SelectedMediumIndex 傳回 NdisMediumWan,通訊協定驅動程式會呼叫 NdisRequest,在查詢中指定OID_WAN_MEDIUM_SUBTYPE,以判斷基礎驅動程式所使用的 WAN 媒體類型。
如果先前發行的無線媒體OID_NETWORK_TYPE全域查詢指出驅動程式和基礎 NIC 支援一個以上的 NdisMediumWirelessWan 類型媒體,則通訊協議必須在 NDIS 設定系結之後選取其中一個支持的媒體,並在通訊協定選取標頭格式之前選取其中一個。
如需通訊協定驅動程式用來與 Just-bound NDIS 驅動程式交涉之一般和中型特定 OID 的詳細資訊,請參閱 NDIS 物件標識碼。
- 目標平臺: 通用
- 版本:Windows Vista 中不支援 NDIS 6.0 驅動程式。 請改用 NdisOpenAdapterEx。 Windows Vista 和 Windows XP 中支援 NDIS 5.1 驅動程式。
規格需求
需求 | 值 |
---|---|
標頭 | ndis.h (包含 Ndis.h) |
程式庫 | Ndis.lib |
IRQL | PASSIVE_LEVEL |
另請參閱
- ANSI_STRING
- NDIS 通訊協定驅動程式的 DriverEntry
- MiniportInitialize
- MiniportQueryInformation
- MiniportSendPackets
- MiniportSetInformation
- NdisCloseAdapter
- NdisClOpenAddressFamily
- NdisCoRequest
- NdisCmRegisterAddressFamily
- NdisIMInitializeDeviceInstance
- NdisIMRegisterLayeredMiniport
- NdisMIndicateReceivePacket
- NDIS_PACKET_OOB_DATA
- NdisRegisterProtocol
- NdisRequest
- NdisSendPackets
- ProtocolBindAdapter
- ProtocolOpenAdapterComplete
- ProtocolReceivePacket
- UNICODE_STRING