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     namespace saml2p {
  36         class SAML_API Status;
  37     };
  38     namespace saml2md {
  39         class SAML_API EntityDescriptor;
  40         class SAML_API RoleDescriptor;
  41     };
  42
  43     DECL_XMLTOOLING_EXCEPTION(SecurityPolicyException,SAML_EXCEPTIONAPI(SAML_API),opensaml,xmltooling::XMLToolingException,Exceptions in security policy processing);
  44     DECL_XMLTOOLING_EXCEPTION(BindingException,SAML_EXCEPTIONAPI(SAML_API),opensaml,xmltooling::XMLToolingException,Exceptions in SAML binding processing);
  45     DECL_XMLTOOLING_EXCEPTION(ProfileException,SAML_EXCEPTIONAPI(SAML_API),opensaml,xmltooling::ValidationException,Exceptions in SAML profile processing);
  46     DECL_XMLTOOLING_EXCEPTION(FatalProfileException,SAML_EXCEPTIONAPI(SAML_API),opensaml,ProfileException,Fatal exceptions in SAML profile processing);
  47     DECL_XMLTOOLING_EXCEPTION(RetryableProfileException,SAML_EXCEPTIONAPI(SAML_API),opensaml,ProfileException,Non-fatal exceptions in SAML profile processing);
  48
  49     /**
  50      * Attaches metadata-derived information as exception properties and optionally
  51      * rethrows the object. The following named properties are attached, when possible:
  52      *
  53      *  <dl>
  54      *  <dt>entityID</dt>       <dd>The unique ID of the entity</dd>
  55      *  <dt>errorURL</dt>       <dd>The error support URL of a random role</dd>
  56      *  <dt>contactName</dt>    <dd>A formatted support or technical contact name</dd>
  57      *  <dt>contactEmail</dt>   <dd>A contact email address</dd>
  58      *  <dt>statusCode</dt>     <dd>Top-level status code from Status object</dd>
  59      *  <dt>statusCode2</dt>    <dd>Second-level status code from Status object</dd>
  60      *  <dt>statusMessage</dt>  <dd>StatusMessage from Status object</dd>
  61      *  </dl>
  62      *
  63      * @param e         pointer to exception object
  64      * @param entity    pointer to entity
  65      * @param status    pointer to Status from message
  66      * @param rethrow   true iff the exception should be rethrown
  67      */
  68     void SAML_API annotateException(
  69         xmltooling::XMLToolingException* e,
  70         const saml2md::EntityDescriptor* entity,
  71         const saml2p::Status* status=nullptr,
  72         bool rethrow=true
  73         );
  74
  75     /**
  76      * Attaches metadata-derived information as exception properties and optionally
  77      * rethrows the object. The following named properties are attached, when possible:
  78      *
  79      *  <dl>
  80      *  <dt>entityID</dt>       <dd>The unique ID of the entity</dd>
  81      *  <dt>errorURL</dt>       <dd>The error support URL of the role</dd>
  82      *  <dt>contactName</dt>    <dd>A formatted support or technical contact name</dd>
  83      *  <dt>contactEmail</dt>   <dd>A contact email address</dd>
  84      *  <dt>statusCode</dt>     <dd>Top-level status code from Status object</dd>
  85      *  <dt>statusCode2</dt>    <dd>Second-level status code from Status object</dd>
  86      *  </dl>
  87      *
  88      * @param e         pointer to exception object
  89      * @param entity    pointer to role
  90      * @param status    pointer to Status from message
  91      * @param rethrow   true iff the exception should be rethrown
  92      */
  93     void SAML_API annotateException(
  94         xmltooling::XMLToolingException* e,
  95         const saml2md::RoleDescriptor* role,
  96         const saml2p::Status* status=nullptr,
  97         bool rethrow=true
  98         );
  99 };
 100
 101 #endif /* __saml_exceptions_h__ */