saml/exceptions.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file saml/exceptions.h
  23  *
  24  * Exception classes
  25  */
  26
  27 #ifndef __saml_exceptions_h__
  28 #define __saml_exceptions_h__
  29
  30 #include <saml/base.h>
  31 #include <xmltooling/exceptions.h>
  32
  33 namespace opensaml {
  34
  35     class SAML_API Status;
  36
  37     namespace saml2md {
  38         class SAML_API EntityDescriptor;
  39         class SAML_API RoleDescriptor;
  40     };
  41
  42     DECL_XMLTOOLING_EXCEPTION(SecurityPolicyException,SAML_EXCEPTIONAPI(SAML_API),opensaml,xmltooling::XMLToolingException,Exceptions in security policy processing);
  43     DECL_XMLTOOLING_EXCEPTION(BindingException,SAML_EXCEPTIONAPI(SAML_API),opensaml,xmltooling::XMLToolingException,Exceptions in SAML binding processing);
  44     DECL_XMLTOOLING_EXCEPTION(ProfileException,SAML_EXCEPTIONAPI(SAML_API),opensaml,xmltooling::ValidationException,Exceptions in SAML profile processing);
  45     DECL_XMLTOOLING_EXCEPTION(FatalProfileException,SAML_EXCEPTIONAPI(SAML_API),opensaml,ProfileException,Fatal exceptions in SAML profile processing);
  46     DECL_XMLTOOLING_EXCEPTION(RetryableProfileException,SAML_EXCEPTIONAPI(SAML_API),opensaml,ProfileException,Non-fatal exceptions in SAML profile processing);
  47
  48     /**
  49      * Attaches metadata-derived information as exception properties and optionally
  50      * rethrows the object. The following named properties are attached, when possible:
  51      *
  52      *  <dl>
  53      *  <dt>entityID</dt>       <dd>The unique ID of the entity</dd>
  54      *  <dt>errorURL</dt>       <dd>The error support URL of a random role</dd>
  55      *  <dt>contactName</dt>    <dd>A formatted support or technical contact name</dd>
  56      *  <dt>contactEmail</dt>   <dd>A contact email address</dd>
  57      *  <dt>statusCode</dt>     <dd>Top-level status code from Status object</dd>
  58      *  <dt>statusCode2</dt>    <dd>Second-level status code from Status object</dd>
  59      *  <dt>statusMessage</dt>  <dd>StatusMessage from Status object</dd>
  60      *  </dl>
  61      *
  62      * @param e         pointer to exception object
  63      * @param entity    pointer to entity
  64      * @param status    pointer to Status from message
  65      * @param rethrow   true iff the exception should be rethrown
  66      */
  67     void SAML_API annotateException(
  68         xmltooling::XMLToolingException* e,
  69         const saml2md::EntityDescriptor* entity,
  70         const Status* status=nullptr,
  71         bool rethrow=true
  72         );
  73
  74     /**
  75      * Attaches metadata-derived information as exception properties and optionally
  76      * rethrows the object. The following named properties are attached, when possible:
  77      *
  78      *  <dl>
  79      *  <dt>entityID</dt>       <dd>The unique ID of the entity</dd>
  80      *  <dt>errorURL</dt>       <dd>The error support URL of the role</dd>
  81      *  <dt>contactName</dt>    <dd>A formatted support or technical contact name</dd>
  82      *  <dt>contactEmail</dt>   <dd>A contact email address</dd>
  83      *  <dt>statusCode</dt>     <dd>Top-level status code from Status object</dd>
  84      *  <dt>statusCode2</dt>    <dd>Second-level status code from Status object</dd>
  85      *  </dl>
  86      *
  87      * @param e         pointer to exception object
  88      * @param entity    pointer to role
  89      * @param status    pointer to Status from message
  90      * @param rethrow   true iff the exception should be rethrown
  91      */
  92     void SAML_API annotateException(
  93         xmltooling::XMLToolingException* e,
  94         const saml2md::RoleDescriptor* role,
  95         const Status* status=nullptr,
  96         bool rethrow=true
  97         );
  98
  99 };
 100
 101 #endif /* __saml_exceptions_h__ */