Service Proxy

A service proxy is the client side proxy for a service. The service proxy enables applications to send and receive messages over a channel as method calls.

Service proxies are created as needed, opened, used to call a service, and closed when no longer needed. Alternatively, an application may reuse a service proxy to connect repeatedly to the same service without the expenditure of time and resources required for initialising a service proxy more than once. The following diagram illustrates the flow of the possible states of the service proxy and the function calls or events that lead from one state to another.

These service proxy states are enumerated in the WS_SERVICE_PROXY_STATE enumeration.

As the preceding diagram and the following code illustrate, a service proxy is created by a call to the WsCreateServiceProxy function. As parameters for this call, WWSAPI provides the following enumerations:

• WS_CHANNEL_TYPE
• WS_CHANNEL_BINDING

It also accepts optional parameters using the following data types:

• WS_PROXY_PROPERTY_ID
• WS_SECURITY_DESCRIPTION

When the service proxy has been created, the WsCreateServiceProxy function returns a reference to the service proxy, WS_SERVICE_PROXY, through an out parameter.

WS_SERVICE_PROXY* serviceProxy = NULL;
hr = WsCreateServiceProxy (
    WS_TCP_CHANNEL_BINDING, 
    WS_CHANNEL_TYPE_DUPLEX_SESSION, 
    NULL, 
    NULL, 
    0, 
    NULL,
    0,
    &serviceProxy, 
    error);

When the service proxy has been created, the application can open the service proxy for communication to a service by calling the WsOpenServiceProxy function, passing an address structure containing the network address of the service endpoint to connect to.

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

When the service proxy has been opened, the application can use it to make calls to the service.

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

When the application no longer needs the service proxy, it closes the service proxy by calling the WsCloseServiceProxy function. It also frees the associated memory by calling WsFreeServiceProxy.

hr = WsCloseServiceProxy(
    serviceProxy, 
    NULL, 
    error);

hr = WsFreeServiceProxy(
    serviceProxy, 
    error);

Reusing the Service Proxy

Alternatively, after calling WsCloseServiceProxy an application can reuse the service proxy by calling the WsResetServiceProxy function.

hr = WsResetServiceProxy(
    serviceProxy, 
    error);

For more information on how service proxies are used in different contexts, see the following topics:

• Service Proxy and Sessions
• Service Operation
• Client Side Service Operations
• HttpCalculatorClientExample

Security

Following application design considerations should be carefully noted when you use the WWSAPI service proxy API:

• The service proxy will not perform any validation of the data beyond Basic Profile 2.0 validation and XML serialization. It is the responsibility of the application to validate the data contained in the parameters it receives back as part of the call.
• Configuring the maximum number of pending calls on the service proxy, by using the WS_PROXY_PROPERTY_ID enumeration value WS_PROXY_PROPERTY_MAX_PENDING_CALLS, provides protection against a slow running server. The default maximum is 100. Applications must be careful in modifying the defaults.
• The service proxy provides no security guarantees beyond those specified in the WS_SECURITY_DESCRIPTION structure used to communicate with the server.
• Take care when you modifying message and channel defaults on the service proxy. Read the security considerations associated with messages and channels before you modify any of the related properties.
• Service proxy encrypts all credentials that it keeps in memory.

The following API elements relate to service proxies.