Criando um cliente

A criação de um cliente para serviços Web é muito simplificada no WWSAPI pelo Service Model API e pela ferramenta WsUtil.exe. O modelo de serviço fornece uma API que permite ao cliente enviar e receber mensagens através de um canal como chamadas de método C. A ferramenta WsUtil gera cabeçalhos e auxiliares para implementar o cliente. Esses cabeçalhos incluem os tipos e protótipos de função para funções C que representam os serviços oferecidos pelo serviço Web de destino. Os auxiliares são usados para criar o proxy de serviço, que contém as informações de associação e endereço de ponto de extremidade para o serviço.

Usando WsUtil para gerar cabeçalhos e auxiliares

Para gerar os cabeçalhos e auxiliares, o WsUtil abre e lê os arquivos de metadados para o serviço de destino — arquivos wsdl e xsd — e os converte em cabeçalhos; portanto, é necessário recuperar os arquivos de metadados para o serviço de destino com antecedência, por exemplo, usando SvcUtil, uma parte do Windows Communication Foundation. Por razões de segurança, é imperativo que as suas cópias desses ficheiros sejam fidedignas. (Para obter mais informações, consulte a seção "Segurança" do tópico WsUtil Compiler Tool.)

Para executar WsUtil, use a seguinte sintaxe de linha de comando se os arquivos WSDL e XSD para o serviço estiverem em seu próprio diretório: WsUtil.exe *.wsdl *.xsd. Como alternativa, você pode especificar os arquivos pelo nome completo.

WsUtil geralmente gera dois arquivos para cada arquivo de metadados: um cabeçalho e um arquivo C. Adicione estes ficheiros ao seu projeto de codificação e use declarações #include para incluí-los no código para o seu cliente. (Os arquivos XSD representam tipos e os arquivos WSDL representam operações.)

Criando o proxy de serviço

O cabeçalho gerado por WsUtil contém uma rotina auxiliar para criar o proxy de serviço com a associação necessária. Essa rotina está incluída na seção "Rotinas auxiliares de política" do arquivo de cabeçalho gerado. Por exemplo, o cabeçalho gerado para o serviço de calculadora ilustrado no exemplo httpcalculatorclientexample conterá o seguinte protótipo de função.

HRESULT BasicHttpBinding_ICalculator_CreateServiceProxy(
    __in_opt WS_HTTP_BINDING_TEMPLATE* templateValue,
    __in_ecount_opt(proxyPropertyCount) const WS_PROXY_PROPERTY* proxyProperties,
    __in const ULONG proxyPropertyCount,
    __deref_out_opt WS_SERVICE_PROXY** _serviceProxy,
    __in_opt WS_ERROR* error);

Incorpore esse auxiliar em seu código e passe um identificador de WS_SERVICE_PROXY para receber o identificador para o proxy de serviço criado. No cenário mais simples, no qual apenas um identificador de proxy de serviço e um objeto de erro são passados para a função, a chamada tem a seguinte aparência.

hr = BasicHttpBinding_ICalculator_CreateServiceProxy(
            NULL,
            NULL,
            0,
            &serviceProxy,
            error);

Para criar o segmento de endereço do serviço proxy, chame WsOpenServiceProxy com um identificador do serviço proxy e um ponteiro para um WS_ENDPOINT_ADDRESS que contém o endereço do endpoint do serviço ao qual pretende se conectar.

Implementando o cliente com protótipos de função

Os cabeçalhos gerados a partir dos arquivos WSDL do serviço também contêm protótipos de função C que representam os serviços disponíveis no serviço Web e específicos para a vinculação necessária. Por exemplo, um cabeçalho gerado para o serviço de calculadora ilustrado em HttpCalculatorServiceExample conterá o seguinte protótipo para a operação de multiplicação desse serviço.

HRESULT BasicHttpBinding_ICalculator_Multiply(
    __in WS_SERVICE_PROXY* _serviceProxy,
    __in double n1,
    __in double n2,
    __out double* MultiplyResult,
    __in WS_HEAP* _heap,
    __in_ecount_opt(_callPropertyCount) const WS_CALL_PROPERTY* _callProperties,
    __in const ULONG _callPropertyCount,
    __in_opt const WS_ASYNC_CONTEXT* _asyncContext,
    __in_opt WS_ERROR* _error);

Você pode copiar os protótipos e usá-los como modelos para codificar as chamadas de função em seu cliente, em cada caso passando o identificador para o proxy de serviço. Após terminar de usar o proxy de serviço, chame WsCloseServiceProxy.