RpcServerRegisterIf2 函式 (rpcdce.h)

發行項
03/05/2024

RpcServerRegisterIf2 函式會向 RPC 運行時間連結庫註冊介面。

語法

RPC_STATUS RpcServerRegisterIf2(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  unsigned int       MaxRpcSize,
  RPC_IF_CALLBACK_FN *IfCallbackFn
);

參數

IfSpec

MIDL 產生的結構，表示要註冊的介面。

MgrTypeUuid

要與 MgrEpv 參數產生關聯的類型 UUID 指標。指定 null 參數值 (或 nil UUID) 會向 nil 類型 UUID 註冊 IfSpec。

MgrEpv

管理員例程的進入點向量 (EPV) 。若要使用 MIDL 產生的預設 EPV，請指定 Null 值。如需詳細資訊，請參閱 RPC_MGR_EPV。

Flags

標誌。如需旗標值的清單，請參閱介面註冊旗標。

MaxCalls

伺服器可以在 自動接聽 介面上接受的並行遠端過程調用要求數目上限。 MaxCalls 參數僅適用於自動接聽介面，而且不會自動接聽的介面會忽略。 RPC 執行時間連結庫會盡最大努力確保伺服器不允許比 MaxCalls 中指定的呼叫數目更多的並行呼叫要求。實際數目可能更大，而且每個通訊協定序列可能會有所不同。

其他介面上的呼叫是由 RpcServerListen 函數調用中指定的全進程 MaxCalls 參數值所控管。

如果並行呼叫數目不相關，您可以使用 RPC_C_LISTEN_MAX_CALLS_DEFAULT 來指定預設值，以達到稍微更好的伺服器端效能。這樣做可減輕 RPC 運行時間環境強制執行不必要的限制。

MaxRpcSize

傳入數據區塊的大小上限，以位元組為單位。此參數可用來協助防止惡意拒絕服務攻擊。如果遠端過程調用的數據區塊大於 MaxRpcSize，RPC 運行時間連結庫會拒絕呼叫，並將RPC_S_ACCESS_DENIED錯誤傳送至用戶端。針對此參數指定不帶正負號的 int) (值 -1，會移除傳入數據區塊的大小限制。此參數不會影響透過 ncalrpc 通訊協議進行的呼叫。

IfCallbackFn

無回呼的安全性回呼函式或 NULL 。每個已註冊的介面都可以有不同的回呼函式。請參閱＜備註＞。

傳回值

成功時傳回RPC_S_OK。

注意如需有效錯誤碼的清單，請參閱 RPC 傳回值。

備註

RpcServerRegisterIf2 函式的參數和效果會擴充 RpcServerRegisterIf 函式的參數和效果。差別在於註冊 自動接聽 介面和指定安全性回呼函式的能力。

伺服器應用程式程式代碼會呼叫 RpcServerRegisterIf2 來註冊介面。若要註冊介面，伺服器會提供下列資訊：

介面規格
介面規格是 MIDL 編譯程式所產生的數據結構。
管理員類型 UUID 和管理員 EPV
管理員類型 UUID 和管理員 EPV 會決定當伺服器收到來自客戶端的遠端過程調用要求時，所執行的管理員例程。針對伺服器所提供之介面的每個實作，它必須註冊個別的管理員 EPV。

請注意，指定非 nil 的管理員類型 UUID 時，伺服器也必須呼叫 RpcObjectSetType 來註冊此非 nil 類型的物件。

指定RPC_IF_AUTOLISTEN旗標會將介面標示為 自動接聽 介面。運行時間會在介面註冊后立即開始接聽呼叫，並在介面取消註冊時停止接聽。此介面的 RpcServerUnregisterIf 呼叫會等候此介面上所有擱置呼叫完成。對 RpcServerListen 和 RpcMgmtStopServerListening 函式的呼叫不會影響介面，也不會呼叫 RpcServerUnregisterIf 函式並將 IfSpec 設定為 NULL 值。這可讓 DLL 註冊 RPC 介面，或從登錄中移除它們，而不需變更主要應用程式的 RPC 狀態。

指定安全性回呼函式可讓伺服器應用程式限制個別客戶端對接口的存取。也就是說，根據預設，安全性是選擇性的;即使伺服器已呼叫 RpcServerRegisterAuthInfo 函式，伺服器運行時間還是會分派不安全的呼叫。如果伺服器只想要接受已驗證的用戶端，介面回呼函式必須呼叫 RpcBindingInqAuthClient、 RpcGetAuthorizationContextForClient 或 RpcServerInqCallAttributes 函式來擷取安全性層級，或嘗試使用 RpcImpersonateClient 函式模擬用戶端。它也可以指定介面旗標的RPC_IF_ALLOW_SECURE_ONLY旗標，以拒絕未經驗證的呼叫。

當伺服器應用程式為其介面指定安全性回呼函式 () 時，RPC 運行時間會自動拒絕呼叫，而不需要該介面的驗證資訊。此外，運行時間會記錄每個用戶端所使用的介面。當用戶端對目前通訊會話期間未使用的介面進行 RPC 時，RPC 運行時間連結庫會呼叫介面的安全性回呼函式。指定RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH旗標可防止自動拒絕未經驗證的用戶端。請注意，在所謂的 NULL 安全性會話上呼叫可以有驗證資訊，即使它們來自匿名用戶端也一樣。因此，單獨存在回呼並不足以防止匿名用戶端連線。安全性回呼函式必須檢查該函式，或者必須使用RPC_IF_ALLOW_SECURE_ONLY旗標。 RPC_IF_ALLOW_SECURE_ONLY只會在 Windows XP 和更新版本的 Windows 上拒絕 Null 會話呼叫。

如需回呼函式的簽章，請參閱 RPC_IF_CALLBACK_FN。

如果允許用戶端在此介面中呼叫方法，回呼函式應該會傳回RPC_S_OK。任何其他傳回碼都會造成用戶端收到例外狀況RPC_S_ACCESS_DENIED。

在某些情況下，RPC 運行時間可能會針對每個介面呼叫每個用戶端多次的安全性回呼函式。請確定您的回呼函式可以處理這種可能性。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	rpcdce.h (包含 Rpc.h)
程式庫	Rpcrt4.lib
Dll	Rpcrt4.dll