服務 Proxy

服務 Proxy 是服務的用戶端 Proxy。 服務 Proxy 可讓應用程式透過通道傳送和接收訊息做為方法呼叫。

服務 Proxy 會視需要建立、開啟、用來呼叫服務，並在不再需要時關閉。 或者，應用程式可能會重複使用服務 Proxy 來重複連線到相同的服務，而不需要花費一次時間和資源來初始化服務 Proxy。 下圖說明服務 Proxy 的可能狀態流程，以及從某個狀態到另一個狀態的函式呼叫或事件。

這些服務 Proxy 狀態會在 WS_SERVICE_PROXY_STATE 列舉中列舉。

如上圖和下列程式碼所說明，服務 Proxy 是由 WsCreateServiceProxy 函式的呼叫所建立。 作為此呼叫的參數，WWSAPI 提供下列列舉：

• WS_CHANNEL_TYPE
• WS_CHANNEL_BINDING

它也接受使用下列資料類型的選擇性參數：

• WS_PROXY_PROPERTY_ID
• WS_SECURITY_DESCRIPTION

建立服務 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);

重複使用服務 Proxy

或者，在呼叫 WsCloseServiceProxy 之後，應用程式可以藉由呼叫 WsResetServiceProxy 函式來重複使用服務 Proxy。

hr = WsResetServiceProxy(
    serviceProxy, 
    error);

如需如何在不同內容中使用服務 Proxy 的詳細資訊，請參閱下列主題：

• 服務 Proxy 和會話
• 服務作業
• 用戶端服務作業
• HttpCalculatorClientExample

安全性

當您使用 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 屬性。