CreatePersistentUdpPortReservation 函式 (iphlpapi.h)

發行項
02/28/2024

CreatePersistentUdpPortReservation 函式會針對本機電腦上的 UDP 埠連續區塊建立持續性 UDP 埠保留。

語法

IPHLPAPI_DLL_LINKAGE ULONG CreatePersistentUdpPortReservation(
  [in]  USHORT   StartPort,
  [in]  USHORT   NumberOfPorts,
  [out] PULONG64 Token
);

參數

[in] StartPort

以網路位元組順序起始的UDP埠號碼。

[in] NumberOfPorts

要保留的 UDP 連接埠號碼數目。

[out] Token

如果函式成功，則會傳回的埠保留令牌指標。

傳回值

如果函式成功，傳回值會NO_ERROR。

如果函式失敗，傳回值就是下列其中一個錯誤碼。

傳回碼	Description
ERROR_ACCESS_DENIED	存取遭到拒絕。此錯誤會在數種狀況下傳回：使用者缺少本機電腦上的必要系統管理許可權，或應用程式未在增強殼層中執行，因為內建系統管理員 (RunAs 系統管理員) 。
ERROR_INVALID_PARAMETER	無效的參數已傳遞至函式。如果在 StartPort 或 NumberOfPorts 參數中傳遞零，就會傳回此錯誤。如果 NumberOfPorts 參數太大，視可配置埠區塊的 StartPort 參數而定，埠配置區塊超過可配置的埠上限，也會傳回此錯誤。
ERROR_SHARING_VIOLATION	由於已有另一個處理序正在使用該檔案，所以此處理序無法存取該檔案。如果使用 StartPort 和 NumberOfPorts 參數所指定的 UDP 連接埠區塊中的 UDP 連接埠，就會傳回此錯誤。如果 StartPort 和 NumberOfPorts 參數所指定之 UDP 埠區塊的持續性保留符合或重疊已建立之 UDP 埠區塊的持續性保留，也會傳回此錯誤。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

CreatePersistentUdpPortReservation 函式是在 Windows Vista 和更新版本上定義。

CreatePersistentUdpPortReservation 函式可用來新增 UDP 埠區塊的持續性保留。

需要保留埠的應用程式和服務分為兩個類別。第一個類別包含需要特定埠作為作業一部分的元件。這類元件通常會偏好在應用程式指令清單中指定其安裝時間 (所需的埠，例如) 。第二個類別包含需要在運行時間使用任何可用埠或埠區塊的元件。

這兩個類別對應至特定和通配符埠保留要求。特定保留要求可能是持續性或運行時間，而通配符埠保留要求只有在運行時間才支援。

CreatePersistentUdpPortReservation 函式可讓您的應用程式或服務持續保留 UDP 埠區塊。持續性 TCP 保留會記錄在 Windows 中 UDP 模組的永續性存放區中。

呼叫端會指定需要多少埠，以及是否需要特定範圍，以取得永續性埠保留。如果可以滿足要求， CreatePersistentUdpPortReservation 函式會傳回唯一不透明ULONG64令牌，後續會識別保留。呼叫 DeletePersistentUdpPortReservation 函式，即可釋放持續性UDP埠保留。請注意，每次重新啟動系統時，給定持續性 UDP 埠保留的令牌可能會變更。

Windows 不會針對使用這些函式取得的持續性保留實作元件間安全性。這表示，如果元件被授與取得任何持續性埠保留的能力，該元件會自動取得取用系統上任何其他元件所授與之任何持續性埠保留的能力。運行時間保留會強制執行進程層級安全性，但這類控件無法擴充至使用 CreatePersistentTcpPortReservation 或 CreatePersistentUdpPortReservation 函式所建立的持續性保留。

取得永續性 UDP 埠保留之後，應用程式就可以透過開啟 UDP 套接字，從 UDP 埠保留要求埠指派，然後呼叫 WSAIoctl 函式來指定 SIO_ASSOCIATE_PORT_RESERVATION IOCTL，並在對套接字上的系結函式發出呼叫之前傳遞保留令牌。

SIO_ACQUIRE_PORT_RESERVATION IOCTL 可用來要求 TCP 或 UDP 連接埠區塊的運行時間保留。針對運行時間埠保留，埠集區會要求從授與保留套接字的進程取用保留。只有在呼叫 SIO_ACQUIRE_PORT_RESERVATION IOCTL 的套接字存留期之後，運行時間埠保留才會持續。相反地，使用 CreatePersistentUdpPortReservation 函式建立的持續性埠保留，可能會由任何能夠取得持續性保留的程式取用。

CreatePersistentUdpPortReservation 函式只能由以 Administrators 群組成員身分登入的使用者呼叫。如果 CreatePersistentUdpPortReservation 是由不是 Administrators 群組成員的使用者呼叫，則函式呼叫將會失敗，並 傳回ERROR_ACCESS_DENIED 。此函式也可能因為 Windows Vista 和更新版本上的用戶帳戶控制 (UAC) 而失敗。如果包含此函式的應用程式是由使用者以系統管理員以外的系統管理員群組成員身分登入來執行，除非應用程式已在指令清單檔中標示為 requestedExecutionLevel 設定為 requireAdministrator，否則此呼叫將會失敗。如果應用程式缺少此指令清單檔，則身為系統管理員以外的 Administrators 群組成員登入的使用者，就必須在增強殼層中執行應用程式，因為內建系統管理員 (RunAs 系統管理員) ，此函式才能成功。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	iphlpapi.h
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll