RpcBindingBind 函式 (rpcasync.h)

RpcBindingBind 函式會連絡 RPC 伺服器並系結至該伺服器。

語法

RPC_STATUS RpcBindingBind(
  [in, optional] PRPC_ASYNC_STATE   pAsync,
  [in]           RPC_BINDING_HANDLE Binding,
  [in]           RPC_IF_HANDLE      IfSpec
);

參數

[in, optional] pAsync

包含異步呼叫資訊的 RPC_ASYNC_STATE 結構的指標。 此狀態資訊包含完成系結作業時用來發出訊號的完成方法。

[in] Binding

RPC_BINDING_HANDLE 結構，其中包含先前呼叫 RpcBindingCreate 所建立的系結句柄。

[in] IfSpec

RPC_IF_HANDLE 值，這個值會指定要對此系結句柄進行呼叫的介面。

傳回值

此函式會在成功時傳回RPC_S_OK;否則會傳回RPC_S_* 錯誤碼。 如需這些錯誤碼的相關信息，請參閱 RPC 傳回值。

備註

RpcBindingBind 會連絡 RPC 伺服器，並使用先前呼叫 RpcBindingCreate 所傳回的系結句柄來系結至該伺服器。 使用此方法建立的系結句柄稱為「快速」系結句柄。

如果 pAsync 參數的值不是 NULL，則系結將會是異步的，而且可以在提供的異步狀態上呼叫 RpcAsyncCancelCall 和 RpcAsyncGetCallStatus 。 異步狀態資訊中指定的完成方法，用來向呼叫端發出系結已完成的訊號。 完成通知時，可以使用新系結的系結句柄進行呼叫。

bind 方法不會判斷可以使用系結句柄進行哪些呼叫—如果系結是同步的，仍然可以對系結句柄進行異步呼叫，反之亦然。 bind 方法會決定成功系結的通知如何發出訊號，特別是在異步系結的情況下。

由於此 API 會與 RPC 伺服器交換訊息，因此系結作業可能需要很長的時間，因為有一些獨立因素，包括網路流量和伺服器封鎖。 如果系結是同步的，系結作業可以在伺服器遭到封鎖時封鎖。

系結完成之後，在系結句柄上所進行的呼叫語意與任何其他系結句柄上的呼叫相同，但有四個值得注意的差異，如下所示：

• 此系結句柄上的所有呼叫都必須在 IfSpec 中指定的介面上進行。 系結句柄會唯一系結至這個介面。 介面本身可以在系結句柄終結之前卸除，但系結句柄中會快取介面的詳細資訊，而且如果在不同介面的相同系結句柄上呼叫，結果就會未定義。
• 系結句柄上不允許 RPC 回呼。 如果 RPC 伺服器嘗試使用具有 [callback] 屬性的方法進行回呼，則會拒絕呼叫，並出現錯誤狀態代碼RPC_S_CANNOT_SUPPORT。
• 透過傳統系結句柄，RPC 會在卸除連線時，嘗試以透明方式重新連線到伺服器。 針對快速系結句柄，RPC 不會嘗試以透明方式重新連線到伺服器;相反地，它會傳回下列其中一個錯誤：RPC_S_SERVER_UNAVAILABLE、RPC_S_CALL_FAILED和RPC_C_CALL_FAILED_DNE。 如果因為拒絕的認證而中斷連線，則會傳回RPC_S_ACCESS_DENIED;如果伺服器因為記憶體不足而發生暫時性錯誤，則會傳回RPC_S_OUT_OF_MEMORY。 任何其他連線錯誤都是伺服器例程傳回的封送處理或取消封送處理錯誤的結果。在遺失連線的情況下，呼叫的必須藉由呼叫 RpcBindingUnbind 解除系結，然後重新系結至 RpcBindingBind 的另一個呼叫。

如果 RpcBindingBind 的呼叫失敗，則系結句柄不會繫結至伺服器，而且呼叫端可以嘗試再次與相同 API 的另一個呼叫系結，或釋放系結句柄。 由於失敗的系結作業不會將系結句柄移至系結狀態，因此不能呼叫 RpcBindingUnbind 。

在系結作業發出完成訊號之前，必須呼叫某些函式，特別是：

• RpcBindingFree
• RpcBindingReset
• RpcBindingSetAuthInfo 和 RpcBindingSetAuthInfoEx
• RpcBindingSetObject
• RpcBindingSetOption
• RpcMgmtSetComTimeout

規格需求

另請參閱

RpcBindingCreate

RpcBindingUnbind