Errores

  • Artículo

En esta sección se describen los errores que pueden emitir las funciones de Servicios web de Windows como resultado de un error en la ejecución del comando.

Parámetros out

Como regla general, el valor de los parámetros out no se modifica si se produce un error en una función.

Hay algunas instancias en las que se modifican los parámetros out si se produce un error en la función. Estos casos se indican explícitamente en la documentación de cada parámetro. Si la documentación no menciona nada sobre la modificación de los parámetros en caso de error, puede asumir con seguridad que la función no los modificará.

Códigos de error

Todos los códigos de error devueltos son HRESULT. Esta API define un conjunto de HRESULT en el intervalo FACILITY_WEBSERVICES, pero también devuelve errores definidos en otras partes de la API de Windows.

Consulte la documentación de las API específicas para obtener información sobre qué códigos de error se devuelven. La lista no pretende ser exhaustiva para cada API, sino más bien una lista de códigos de error para los que hay escenarios comunes para su control explícito. Un autor de llamada siempre debe asumir que otros códigos de error son posibles desde cualquier API.

Esta API define un número relativamente pequeño de códigos de error, que corresponden a escenarios en los que un programa querrá tomar medidas basándose en el error. Los códigos de error por sí solos pueden no ser suficientes para determinar qué ha ido mal o para proporcionar una buena descripción del problema al usuario. La mejor forma de entender el problema es utilizar errores enriquecidos, como se describe a continuación.

Errores enriquecidos

Además de devolver un código de error, un autor de llamada puede solicitar información de error enriquecida para cualquier llamada API pasando un objeto que no sea NULLWS_ERROR. Para crear un objeto de error, use WsCreateError. Si se produce un error, la API que provocó el error rellenará el objeto de error con contexto adicional sobre la situación del error. Si no hay ningún error, el objeto de error no se modifica. Pasar un objeto de error NULL indica que el autor de llamada no está interesado en la información de error enriquecida. Las llamadas (incluidas las devoluciones de llamada) deben estar preparadas para controlar objetos de error NULL.

Tenga en cuenta que el mismo objeto de error se puede usar para varias llamadas API, pero solo se puede usar para una llamada API a la vez (ya que es un solo subproceso). Cada vez que se produce un error, la información de error se anexa al objeto de error. A medida que se desarrolla una cadena de llamadas, varias funciones pueden añadir información al objeto de error para proporcionar contexto adicional sobre el error. Para borrar el contenido del objeto de error antes de reutilizarlo (después de producirse un error), use WsResetError. Si no se produce ningún error, no es necesario restablecer el objeto de error antes de reutilizarlo.

La información de error enriquecida consta de lo siguiente:

Errores

Consulte Errores para obtener información sobre cómo se relacionan los errores.

Información de error confidencial del idioma

Al crear un objeto de error, se especifica el identificador de idioma del idioma al que debe traducirse la información de error. Esto se usa al agregar información de error al objeto de error.

Este valor de idioma se puede recuperar o establecer mediante WS_ERROR_PROPERTY_LANGID.

Códigos de error canónicos

Esta API proporciona un conjunto canónico de códigos de error (WS_E_*) que permiten usar diferentes tecnologías de comunicación sin tener que depender de los códigos de error específicos de la implementación subyacente específica. Para obtener una lista completa de estos códigos de error, consulte Valores devueltos de Servicios web de Windows.

Esto permite, por ejemplo, que un programa compruebe el código de error WS_E_ENDPOINT_NOT_FOUND si usa TCP, UDP o HTTP, y realice alguna acción (como intentar usar un punto de conexión diferente).

Cuando se asigna un código de error específico de implementación a un error canónico, el código de error original se guarda en el objeto de error y se puede acceder a él con fines de diagnóstico. Consulte WS_ERROR_PROPERTY_ORIGINAL_ERROR_CODE para obtener más información.

Uso de API no válido

Los siguientes códigos de error están reservados para el uso de la API no válido y no se devolverán en otras circunstancias. Si se devuelve alguno de estos errores, puede indicar un error de aplicación.

  • WS_E_INVALID_OPERATION
  • E_INVALIDARG

Las enumeraciones siguientes forman parte del seguimiento:

Los siguientes códigos de error forman parte del seguimiento:

  • 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

Las funciones siguientes forman parte del seguimiento:

El controlador siguiente forma parte del seguimiento:

La estructura siguiente forma parte del seguimiento:

Seguridad

Hay varias consideraciones de seguridad que el usuario del objeto de error debe tener en cuenta:

  • El objeto de error puede contener datos que no son de confianza. Ejemplos de esto son: el WS_FAULT y las cadenas de error, que se pueden almacenar en el objeto de error en función de la información recibida a través de un canal que no es de confianza. El usuario del objeto de error debe tener cuidado al inspeccionar la información del objeto de error y tomar decisiones basadas en sus valores.
  • Un usuario del objeto de error debe llamar a WsResetError después de inspeccionar la información sobre el error. Si no lo hace, puede provocar la acumulación de memoria.
  • Un usuario del objeto de error debe tener mucho cuidado al usar el valor WS_FULL_FAULT_DISCLOSURE de la enumeración WS_FAULT_DISCLOSURE, ya que el error generado podría contener información privada que se acumuló como parte del proceso de registro de errores.