Partager via

Erreurs

  • Article

Cette section décrit les erreurs qui peuvent être générées par les fonctions des services Web Windows après l’échec de l’exécution de la commande.

Paramètres de sortie

En règle générale, la valeur des paramètres de sortie n’est pas modifiée en cas d’échec d’une fonction.

Il existe quelques cas où les paramètres de sortie sont modifiés en cas d’échec de la fonction. Ces cas sont explicitement appelés dans la documentation pour chaque paramètre. Si la documentation ne mentionne rien sur la modification des paramètres de sortie en cas d’échec, vous pouvez supposer sans problème que la fonction ne les modifiera pas.

Codes d’erreur

Tous les codes de retour d’erreur sont des valeurs HRESULT. Cette API définit un ensemble de valeurs HRESULT dans la plage de FACILITY_WEBSERVICES, mais elle retourne également des erreurs définies ailleurs dans l’API Windows.

Consultez la documentation relative à l’API spécifique pour en savoir plus sur les codes d’erreur retournés. La liste n’est pas destinée à être exhaustive pour chaque API. Il s’agit plutôt d’une liste de codes d’erreur pour lesquels il existe des scénarios courants de gestion explicite. Un appelant doit toujours partir du principe que d’autres codes d’erreur sont possibles à partir de n’importe quelle API.

Cette API définit un nombre relativement faible de codes d’erreur, qui correspondent à des scénarios dans lesquels un programme souhaite entreprendre une action en fonction de l’erreur. Les codes d’erreur à eux seuls ne sont peut-être pas suffisants pour déterminer ce qui s’est passé, ou pour fournir une bonne description du problème à l’utilisateur. Pour mieux comprendre le problème, vous devez utiliser la fonctionnalité relative aux erreurs détaillées, comme indiqué ci-dessous.

Erreurs détaillées

En plus de retourner un code d’erreur, un appelant peut éventuellement demander des informations d’erreur détaillées pour un appel d’API en passant un objet WS_ERROR non NULL. Pour créer un objet d’erreur, utilisez WsCreateError. En cas d’erreur, l’API qui en est à l’origine remplit l’objet d’erreur avec un contexte supplémentaire sur la situation d’erreur. En l’absence d’erreur, l’objet d’erreur n’est pas modifié. Le passage d’un objet d’erreur NULL indique que l’appelant n’est pas intéressé par des informations d’erreur détaillées. Les appelés (notamment les rappels) doivent être prêts à gérer les objets d’erreur NULL.

Notez que le même objet d’erreur peut être utilisé pour plusieurs appels d’API, mais qu’il ne peut être utilisé que pour un seul appel d’API à la fois (car il s’agit d’un seul thread). Chaque fois qu’une erreur se produit, les informations d’erreur sont ajoutées à l’objet d’erreur. Au fur et à mesure qu’une chaîne d’appels se déroule, plusieurs fonctions peuvent ajouter des informations à l’objet d’erreur pour fournir un contexte supplémentaire sur l’erreur. Pour effacer le contenu de l’objet d’erreur avant de le réutiliser (après une erreur), utilisez WsResetError. Si aucune erreur ne se produit, il n’est pas nécessaire de réinitialiser l’objet d’erreur avant de le réutiliser.

Les informations d’erreur détaillées se composent des éléments suivants :

  • Ensemble de valeurs de propriétés, qui fournissent des informations supplémentaires sur l’erreur, le cas échéant. Consultez WS_ERROR_PROPERTY.
  • Zéro ou plusieurs chaînes d’erreur. Les chaînes sont ajoutées à l’aide de WsAddErrorString, et peuvent être interrogées à l’aide de WsGetErrorString. Vous pouvez interroger le nombre de chaînes à l’aide de WS_ERROR_PROPERTY_STRING_COUNT.

Défaillances et erreurs

Pour plus d’informations sur la relation entre les erreurs et les défaillances, consultez Défaillances.

Informations sur les erreurs en fonction de la langue

Quand vous créez un objet d’erreur, le LANGID de la traduction dans la langue souhaitée pour les informations d’erreur est spécifié. Il est utilisé au moment de l’ajout des informations d’erreur à l’objet d’erreur.

Cette valeur spécifique à la langue peut être récupérée ou définie à l’aide de WS_ERROR_PROPERTY_LANGID.

Codes d’erreur canoniques

Cette API fournit un ensemble canonique de codes d’erreur (WS_E_*) qui permettent d’utiliser différentes technologies de communication sans avoir à dépendre des codes d’erreur spécifiques de l’implémentation sous-jacente particulière. Pour obtenir la liste complète de ces codes d’erreur, consultez Valeurs de retour des services Web Windows.

Cela permet notamment à un programme de rechercher le code d’erreur WS_E_ENDPOINT_NOT_FOUND, que TCP, UDP ou HTTP soit utilisé, et d’effectuer certaines actions (par exemple tenter d’utiliser un autre point de terminaison).

Quand un code d’erreur spécifique à l’implémentation est mappé à une erreur canonique, le code d’erreur d’origine est enregistré dans l’objet d’erreur, et est toujours accessible à des fins de diagnostic. Pour plus d’informations, consultez WS_ERROR_PROPERTY_ORIGINAL_ERROR_CODE.

Utilisation d’API non valide

Les codes d’erreur suivants sont réservés à une utilisation d’API non valide. Ils ne sont pas retournés dans d’autres circonstances. Si l’une de ces erreurs est retournée, cela peut indiquer un bogue d’application.

  • WS_E_INVALID_OPERATION
  • E_INVALIDARG

Les énumérations suivantes font partie du suivi :

Les codes d’erreur suivants font partie du suivi :

  • 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

Les fonctions suivantes font partie du suivi :

Le descripteur suivant fait partie du suivi :

La structure suivante fait partie du suivi :

Sécurité

L’utilisateur de l’objet d’erreur doit prendre en compte un certain nombre de considérations relatives à la sécurité :

  • L’objet d’erreur peut contenir des données non approuvées. Par exemple : WS_FAULT et les chaînes d’erreur peuvent être stockés dans l’objet d’erreur en fonction des informations reçues sur un canal non approuvé. L’utilisateur de l’objet d’erreur doit être prudent quand il inspecte les informations de l’objet d’erreur, et qu’il prend des décisions basées sur ses valeurs.
  • Un utilisateur de l’objet d’erreur doit appeler WsResetError après avoir inspecté les informations relatives à l’erreur. Dans le cas contraire, cela peut entraîner une accumulation de mémoire.
  • L’utilisateur de l’objet d’erreur doit être très prudent quand il utilise la valeur WS_FULL_FAULT_DISCLOSURE de l’énumération WS_FAULT_DISCLOSURE, car l’erreur générée peut contenir des informations privées, accumulées dans le cadre du processus d’enregistrement d’erreur.