服务代理

服务代理是服务的客户端代理。 服务代理使应用程序能够通过通道以方法调用的形式发送和接收消息。

服务代理根据需要创建、打开、用于调用服务，并在不再需要时关闭。 或者，应用程序可以重复使用服务代理来重复连接到同一服务，而无需花费多次初始化服务代理所需的时间和资源。 下图演示了服务代理的可能状态流，以及从一种状态到另一种状态的函数调用或事件。

这些服务代理状态在 WS_SERVICE_PROXY_STATE 枚举中枚举。

如上图和以下代码所示，服务代理是通过调用 WsCreateServiceProxy 函数创建的。 作为此调用的参数，WWSAPI 提供以下枚举：

• WS_CHANNEL_TYPE
• WS_CHANNEL_BINDING

它还接受使用以下数据类型的可选参数：

• WS_PROXY_PROPERTY_ID
• WS_SECURITY_DESCRIPTION

创建服务代理后， WsCreateServiceProxy 函数通过 out 参数返回对服务代理 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);

创建服务代理后，应用程序可以通过调用 WsOpenServiceProxy 函数，传递包含要连接到的服务终结点的网络地址的 地址结构的地址 ，打开服务代理以与服务进行通信。

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);

打开服务代理后，应用程序可以使用它调用服务。

hr = Add(
    serviceProxy, 
    1, 
    2, 
    &result, 
    NULL, 
    0, 
    NULL, 
    error);

当应用程序不再需要服务代理时，它会通过调用 WsCloseServiceProxy 函数关闭服务代理 。 它还通过调用 WsFreeServiceProxy 释放关联的内存。

hr = WsCloseServiceProxy(
    serviceProxy, 
    NULL, 
    error);

hr = WsFreeServiceProxy(
    serviceProxy, 
    error);

重用服务代理

或者，在调用 WsCloseServiceProxy 后，应用程序可以通过调用 WsResetServiceProxy 函数重用服务代理。

hr = WsResetServiceProxy(
    serviceProxy, 
    error);

有关如何在不同上下文中使用服务代理的详细信息，请参阅以下主题：

• 服务代理和会话
• 服务操作
• 客户端服务操作
• HttpCalculatorClientExample

安全性

使用 WWSAPI 服务代理 API 时，应仔细注意以下应用程序设计注意事项：

• 除了基本配置文件 2.0 验证和 XML 序列化之外，服务代理不会对数据执行任何验证。 应用程序负责验证在调用过程中接收的参数中包含的数据。
• 通过使用 WS_PROXY_PROPERTY_ID 枚举值 WS_PROXY_PROPERTY_MAX_PENDING_CALLS在服务代理上配置最大挂起调用数，可针对运行缓慢的服务器提供保护。 默认最大值为 100。 应用程序在修改默认值时必须小心。
• 除了用于与服务器通信的 WS_SECURITY_DESCRIPTION 结构中指定的安全保证外，服务代理不提供任何安全保障。
• 在服务代理上修改 消息 和 通道 默认值时，请小心。 在修改任何相关属性之前，请阅读与消息和通道相关的安全注意事项。
• 服务代理会加密它在内存中保留的所有凭据。

以下 API 元素与服务代理相关。

回调	说明
WS_PROXY_MESSAGE_CALLBACK	在即将通过 发送输入消息的标头或刚收到输出消息标头时调用。

 

枚举	描述
WS_CALL_PROPERTY_ID	枚举用于在客户端服务操作上配置调用的可选参数。
WS_PROXY_PROPERTY_ID	枚举用于配置服务代理的可选参数。
WS_SERVICE_PROXY_STATE	服务代理的状态。

 

函数	说明
WsAbandonCall	放弃对指定服务代理的指定调用。
WsAbortServiceProxy	取消指定服务代理上所有挂起的输入和输出。
WsCall	仅限内部。 将参数序列化为消息，并通过通道发送该消息。
WsCloseServiceProxy	关闭服务代理进行通信。
WsCreateServiceProxy	创建服务代理。
WsFreeServiceProxy	释放与服务代理关联的内存。
WsGetServiceProxyProperty	检索指定的服务代理属性。
WsOpenServiceProxy	打开服务终结点的服务代理。
WsResetServiceProxy	重置服务代理。

 

Handle	说明
WS_SERVICE_PROXY	用于引用服务代理的不透明类型。

 

结构	说明
WS_CALL_PROPERTY	指定调用属性。
WS_PROXY_PROPERTY。	指定代理属性。