服務 Proxy
服務 Proxy 是服務的用戶端 Proxy。 服務 Proxy 可讓應用程式透過通道傳送和接收訊息做為方法呼叫。
服務 Proxy 會視需要建立、開啟、用來呼叫服務,並在不再需要時關閉。 或者,應用程式可能會重複使用服務 Proxy 來重複連線到相同的服務,而不需要花費一次時間和資源來初始化服務 Proxy。 下圖說明服務 Proxy 的可能狀態流程,以及從某個狀態到另一個狀態的函式呼叫或事件。
這些服務 Proxy 狀態會在 WS_SERVICE_PROXY_STATE 列舉中列舉。
如上圖和下列程式碼所說明,服務 Proxy 是由 WsCreateServiceProxy 函式的呼叫所建立。 作為此呼叫的參數,WWSAPI 提供下列列舉:
它也接受使用下列資料類型的選擇性參數:
建立服務 Proxy 之後, WsCreateServiceProxy 函式會透過 out 參數傳回服務 Proxy 的參考WS_SERVICE_PROXY。
WS_SERVICE_PROXY* serviceProxy = NULL;
hr = WsCreateServiceProxy (
WS_TCP_CHANNEL_BINDING,
WS_CHANNEL_TYPE_DUPLEX_SESSION,
NULL,
NULL,
0,
NULL,
0,
&serviceProxy,
error);
建立服務 Proxy 之後,應用程式可以呼叫 WsOpenServiceProxy 函式,傳遞包含要連線之服務端點網路位址的 位址 結構,以開啟服務通訊的服務 Proxy。
WS_ENDPOINT_ADDRESS address = {0};
address.uri.chars = "net.tcp://localhost/example";
address.uri.length = wcslen("net.tcp://localhost/example";);
hr = WsOpenServiceProxy(serviceProxy, &address, NULL, error);
當服務 Proxy 已開啟時,應用程式可以使用它來呼叫服務。
hr = Add(
serviceProxy,
1,
2,
&result,
NULL,
0,
NULL,
error);
當應用程式不再需要服務 Proxy 時,它會呼叫 WsCloseServiceProxy 函式來關閉服務 Proxy。 它也會藉由呼叫 WsFreeServiceProxy釋放相關聯的記憶體。
hr = WsCloseServiceProxy(
serviceProxy,
NULL,
error);
hr = WsFreeServiceProxy(
serviceProxy,
error);
或者,在呼叫 WsCloseServiceProxy 之後,應用程式可以藉由呼叫 WsResetServiceProxy 函式來重複使用服務 Proxy。
hr = WsResetServiceProxy(
serviceProxy,
error);
如需如何在不同內容中使用服務 Proxy 的詳細資訊,請參閱下列主題:
當您使用 WWSAPI 服務 Proxy API 時,應仔細注意下列應用程式設計考慮:
- 服務 Proxy 不會對基本設定檔 2.0 驗證和 XML 序列化以外的資料執行任何驗證。 應用程式必須負責驗證其回傳做為呼叫一部分的參數中包含的資料。
- 藉由使用 WS_PROXY_PROPERTY_ID 列舉值 WS_PROXY_PROPERTY_MAX_PENDING_CALLS,設定服務 Proxy 上擱置的呼叫數目上限,可保護執行緩慢的伺服器。 預設最大值為 100。 修改預設值時,應用程式必須小心。
- 除了用來與伺服器通訊 之WS_SECURITY_DESCRIPTION 結構中指定的安全性保證之外,服務 Proxy 不會提供任何安全性保證。
- 在服務 Proxy 上修改 訊息 和 通道 預設值時,請小心。 在您修改任何相關屬性之前,請先閱讀與訊息和通道相關聯的安全性考慮。
- 服務 Proxy 會加密它保留在記憶體中的所有認證。
下列 API 元素與服務 Proxy 相關。
回呼 | 描述 |
---|---|
WS_PROXY_MESSAGE_CALLBACK | 當輸入訊息的標頭即將透過 或剛收到輸出訊息標頭時叫用。 |
列舉型別 | 描述 |
---|---|
WS_CALL_PROPERTY_ID | 列舉在用戶端服務作業上設定呼叫的選擇性參數。 |
WS_PROXY_PROPERTY_ID | 列舉設定服務 Proxy 的選擇性參數。 |
WS_SERVICE_PROXY_STATE | 服務 Proxy 的狀態。 |
函式 | 描述 |
---|---|
WsAbandonCall | 放棄指定服務 Proxy 上的指定呼叫。 |
WsAbortServiceProxy | 取消指定之服務 Proxy 上所有暫止的輸入和輸出。 |
WsCall | 僅供內部使用。 將引數序列化為訊息,並透過通道傳送引數。 |
WsCloseServiceProxy | 關閉服務 Proxy 以進行通訊。 |
WsCreateServiceProxy | 建立服務 Proxy。 |
WsFreeServiceProxy | 釋放與服務 Proxy 相關聯的記憶體。 |
WsGetServiceProxyProperty | 擷取指定的服務 Proxy 屬性。 |
WsOpenServiceProxy | 開啟服務 Proxy 至服務端點。 |
WsResetServiceProxy | 重設服務 Proxy。 |
Handle | 描述 |
---|---|
WS_SERVICE_PROXY | 用來參考服務 Proxy 的不透明類型。 |
結構 | 描述 |
---|---|
WS_CALL_PROPERTY | 指定呼叫屬性。 |
WS_PROXY_PROPERTY。 | 指定 Proxy 屬性。 |