Compartilhar via

Errors

  • Artigo

Esta seção descreve o erro que pode ser um problema das funções dos Serviços Web do Windows como resultado de uma falha na execução do comando.

Parâmetros de saída

Como regra geral, o valor dos parâmetros externos não será modificado se uma função falhar.

Há algumas instâncias em que os parâmetros externos são modificados se a função falhar. Esses casos são explicitamente chamados na documentação de cada parâmetro. Se a documentação não mencionar nada sobre a modificação de parâmetros em caso de falha, você poderá assumir com segurança que a função não os modificará.

Códigos de erro

Todos os códigos de retorno de erro são HRESULTs. Essa API define um conjunto de HRESULTs no intervalo de FACILITY_WEBSERVICES, mas também retorna erros definidos em outro lugar na API do Windows.

Confira a documentação de API específica para saber quais códigos de erro são retornados. A lista não se destina a ser exaustiva para cada API, mas sim uma lista de códigos de erro para os quais há cenários comuns para tratamento explícito. Um chamador sempre deve assumir que outros códigos de erro são possíveis de qualquer API.

Essa API define um número relativamente pequeno de códigos de erro, que correspondem a cenários em que um programa deseja executar uma ação com base no erro. Somente códigos de erro podem não ser suficientes para determinar o que deu errado ou para fornecer uma boa descrição do problema ao usuário. A melhor compreensão do problema vem do uso de Erros avançados, conforme descrito abaixo.

Erros avançados

Além de retornar um código de erro, um chamador pode, opcionalmente, solicitar informações de erro avançadas para qualquer chamada à API passando um objeto não NULLWS_ERROR. Para criar um objeto de erro, use WsCreateError. Se houver um erro, a API que causou o erro preencherá o objeto de erro com contexto adicional sobre a situação de erro. Se não houver erro, o objeto de erro não será modificado. Passar um objeto de erro NULL indica que o chamador não está interessado em informações de erro avançadas. Os callees (incluindo retornos de chamada) devem estar preparados para lidar com objetos de erro NULL.

Observe que o mesmo objeto de erro pode ser usado para várias chamadas à API, mas pode ser usado apenas para uma chamada de API por vez (já que é de thread único). Sempre que ocorre um erro, as informações de erro são acrescentadas ao objeto de erro. À medida que uma cadeia de chamadas se desenrola, várias funções podem adicionar informações ao objeto de erro para fornecer contexto adicional sobre o erro. Para limpar o conteúdo do objeto de erro antes de reutilizá-lo (após ocorrer um erro), use WsResetError. Se nenhum erro ocorrer, não será necessário redefinir o objeto de erro antes de reutilizá-lo.

Informações de erro avançadas consistem no seguinte:

Falhas e erros

Confira Falhas para obter informações sobre como erros e falhas se relacionam.

Informações de erro confidenciais do idioma

Ao criar um objeto de erro, o LANGID da tradução de idioma desejada para informações de erro é especificado. Isso é usado ao adicionar informações de erro ao objeto de erro.

Esse valor de idioma pode ser recuperado ou definido usando WS_ERROR_PROPERTY_LANGID.

Códigos de erro Canonical

Essa API fornece um conjunto canônico de códigos de erro (WS_E_*) que permitem que diferentes tecnologias de comunicação sejam usadas sem precisar depender dos códigos de erro específicos da implementação subjacente específica. Para obter uma lista completa desses códigos de erro, confira Valores retornados dos serviços Web do Windows.

Isso permite, por exemplo, que um programa verifique se o código de erro WS_E_ENDPOINT_NOT_FOUND está usando TCP, UDP ou HTTP e execute alguma ação (como tentar usar um ponto de extremidade diferente).

Quando um código de erro específico de implementação é mapeado para um erro canônico, o código de erro original é salvo no objeto de erro e ainda pode ser acessado para fins de diagnóstico. Confira WS_ERROR_PROPERTY_ORIGINAL_ERROR_CODE para obter mais informações.

Uso inválido de API

Os códigos de erro a seguir são reservados para uso inválido da API e não serão retornados em outras circunstâncias. Se algum desses erros for retornado, pode ser uma indicação de um bug do aplicativo.

  • WS_E_INVALID_OPERATION
  • E_INVALIDARG

As seguintes enumerações fazem parte do rastreamento:

Os seguintes códigos de erro fazem parte do rastreamento:

  • CERT_E_CN_NO_MATCH
  • CERT_E_EXPIRED
  • CERT_E_UNTRUSTEDROOT
  • CERT_E_WRONG_USAGE
  • CRYPT_E_REVOCATION_OFFLINE
  • E_INVALIDARG
  • E_OUTOFMEMORY
  • WS_E_ADDRESS_IN_USE
  • WS_E_ADDRESS_NOT_AVAILABLE
  • WS_E_ENDPOINT_ACCESS_DENIED
  • WS_E_ENDPOINT_ACTION_NOT_SUPPORTED
  • WS_E_ENDPOINT_DISCONNECTED
  • WS_E_ENDPOINT_FAILURE
  • WS_E_ENDPOINT_FAULT_RECEIVED
  • WS_E_ENDPOINT_NOT_AVAILABLE
  • WS_E_ENDPOINT_NOT_FOUND
  • WS_E_ENDPOINT_TOO_BUSY
  • WS_E_ENDPOINT_UNREACHABLE
  • WS_E_INVALID_ENDPOINT_URL
  • WS_E_INVALID_FORMAT
  • WS_E_INVALID_OPERATION
  • WS_E_NOT_SUPPORTED
  • WS_E_NO_TRANSLATION_AVAILABLE
  • WS_E_NUMERIC_OVERFLOW
  • WS_E_OBJECT_FAULTED
  • WS_E_OPERATION_ABANDONED
  • WS_E_OPERATION_ABORTED
  • WS_E_OPERATION_TIMED_OUT
  • WS_E_OTHER
  • WS_E_PROXY_ACCESS_DENIED
  • WS_E_PROXY_FAILURE
  • WS_E_PROXY_REQUIRES_BASIC_AUTH
  • WS_E_PROXY_REQUIRES_DIGEST_AUTH
  • WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH
  • WS_E_PROXY_REQUIRES_NTLM_AUTH
  • WS_E_QUOTA_EXCEEDED
  • WS_E_SECURITY_SYSTEM_FAILURE
  • WS_E_SECURITY_TOKEN_EXPIRED
  • WS_E_SECURITY_VERIFICATION_FAILURE
  • WS_E_SERVER_REQUIRES_BASIC_AUTH
  • WS_E_SERVER_REQUIRES_DIGEST_AUTH
  • WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH
  • WS_E_SERVER_REQUIRES_NTLM_AUTH
  • WS_S_ASYNC
  • WS_S_END

As seguintes funções fazem parte do rastreamento:

O identificador a seguir faz parte do rastreamento:

A seguinte estrutura faz parte do rastreamento:

Segurança

Há várias considerações de segurança que o usuário do objeto de erro deve estar ciente:

  • O objeto de erro pode conter dados não confiáveis. Exemplos disso são: o WS_FAULT e as cadeias de caracteres de erro, que podem ser armazenadas no objeto de erro com base nas informações recebidas em um canal não confiável. O usuário do objeto de erro deve ter cuidado ao inspecionar as informações no objeto de erro e tomar decisões com base em seus valores.
  • Um usuário do objeto de erro deve chamar WsResetError depois de inspecionar as informações sobre o erro. Não fazer isso pode levar ao acúmulo de memória.
  • Um usuário do objeto de erro deve ter muito cuidado ao usar o valor WS_FULL_FAULT_DISCLOSURE da enumeração WS_FAULT_DISCLOSURE, pois a falha gerada pode conter informações privadas que foram acumuladas como parte do processo de gravação de erros.