PFN_WSK_GET_NAME_INFO回呼函式 (wsk.h)

發行項
03/05/2024

WskGetNameInfo 函式提供從傳輸位址到主機名的通訊協議獨立轉譯。

語法

PFN_WSK_GET_NAME_INFO PfnWskGetNameInfo;

NTSTATUS PfnWskGetNameInfo(
  [in]            PWSK_CLIENT Client,
  [in]            PSOCKADDR SockAddr,
  [in]            ULONG SockAddrLength,
  [out, optional] PUNICODE_STRING NodeName,
  [out, optional] PUNICODE_STRING ServiceName,
  [in]            ULONG Flags,
  [in, optional]  PEPROCESS OwningProcess,
  [in, optional]  PETHREAD OwningThread,
  [in, out]       PIRP Irp
)
{...}

參數

[in] Client

[in]透過的 WskProviderNpi 參數傳回之WSK_CLIENT結構的指標 WskCaptureProviderNPI 函式。

[in] SockAddr

[in] SOCKADDR 結構的指標，其中包含套接字的IP位址和埠號碼。

[in] SockAddrLength

[in]指定 SockAddr 參數所指向之緩衝區的長度，以位元組為單位。 SockAddrLength 的值不應超過SOCKADDR_STORAGE結構的大小。

[out, optional] NodeName

[out]UNICODE_STRING 結構的選擇性指標，其中包含代表主機 (節點) 名稱的 Unicode 字串。成功時，Unicode 主機名預設會寫入為完整域名， (FQDN) 。呼叫端必須提供足以保存 Unicode 主機名的UNICODE_STRING緩衝區，其中包含終止的 NULL 字元。如果 NodeBuffer 參數為 NULL，則呼叫端不想要接收主機名字符串。 NodeBuffer 和 ServiceBuffer 不得同時為 NULL。

[out, optional] ServiceName

[out] UNICODE_STRING 結構的選擇性指標，其中包含 Unicode 字串，代表與埠號碼相關聯的服務名稱。呼叫端必須提供足以保存 Unicode 服務名稱的UNICODE_STRING緩衝區，其中包含終止的 NULL 字元。如果 NodeBuffer 參數為 NULL，則呼叫端不想要接收服務名稱字串。 NodeBuffer 和 ServiceBuffer 不得同時為 NULL。

[in] Flags

[in]ULONG 值，用來自定義此函式的處理。

下列旗標可供使用：

NI_DGRAM

表示服務是數據報服務。此旗標對於為 UDP 和 TCP 服務提供不同埠號碼的少數服務是必要的。

NI_NAMEREQD

表示 DNS 無法解析的主機名會導致錯誤。

NI_NOFQDN

導致本機主機只有其相對辨別名稱 (RDN) 在 NodeName 參數中傳回。

NI_NUMERICHOST

表示函式會傳回主機名的數值形式，而不是其名稱，而是反向 DNS 查閱。如果 DNS 無法解析主機名，也會傳回主機名的數值形式。

NI_NUMERICSERV

表示函式會傳回服務的埠號碼，而不是其名稱。此外，如果找不到IP位址的主機名， (127.0.0.2，例如) ，則會以IP位址的形式傳回主機名。

[in, optional] OwningProcess

[in]函式從中擷取安全性內容之進程的選擇性指標。此安全性內容表示函式處理名稱解析要求的用戶帳戶內容。

如果此參數為 NULL，函式會在預先定義的本機帳戶內容中處理名稱解析要求，且具有最低許可權。

如果此參數不是 NULL ，而且模擬令牌對呼叫線程有效，則此函式會失敗並傳回STATUS_INVALID_PARAMETER。

[in, optional] OwningThread

[in]函式從中擷取安全性內容的線程選擇性指標。只有當 OwningProcess 不是 NULL 時，此參數才可以是非 NULL。否則，此函式會失敗並傳回STATUS_INVALID_PARAMETER。

如果此參數不是 NULL ，而且模擬令牌對呼叫線程有效，則此函式會失敗並傳回STATUS_INVALID_PARAMETER。

[in, out] Irp

[in/out]I/O 要求封包的指標 (IRP) ，以異步方式完成要求。完成要求之後， Irp ->Iostatus.Information 會保留傳回的狀態代碼。

傳回值

WskGetNameInfo 會傳回下列其中一個 NTSTATUS 代碼：

傳回碼	Description
STATUS_INVALID_PARAMETER	指定了無效的參數。
STATUS_NO_MATCH	無法解析主機名。
STATUS_SUCCESS	語言函式已順利完成。如果 WSK 應用程式在中指定 IRP 的指標 Irp 參數會以成功狀態完成 IRP。
STATUS_PENDING	WSK 子系統無法立即完成函式。 WSK 子系統會在完成控制作業之後完成 IRP。控制作業的狀態將會在 IRP 的 [IoStatus.Status ] 字段中傳回。
其他狀態代碼	發生錯誤。 IRP 將會以失敗狀態完成。

備註

OwningProcess 參數指向的進程，或 OwningThread 進程指向的線程，表示此函式的安全性內容。安全性內容所表示的用戶帳戶表示函式名稱解析要求的內容。

規格需求

需求	值
最低支援的用戶端	可在 Windows 7 和更新版本的 Windows 作業系統中使用。
目標平台	Universal
標頭	wsk.h (包含 Wsk.h)
IRQL	PASSIVE_LEVEL