https://issues.shibboleth.net/jira/browse/SSPCPP-181

[shibboleth/cpp-opensaml.git] / saml / binding / MessageDecoder.h

diff --git a/saml/binding/MessageDecoder.h b/saml/binding/MessageDecoder.h
index 9f3905d..479f199 100644 (file)
--- a/saml/binding/MessageDecoder.h
+++ b/saml/binding/MessageDecoder.h
@@ -1,6 +1,6 @@
 /*
- *  Copyright 2001-2007 Internet2
- * 
+ *  Copyright 2001-2009 Internet2
+ *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
@@ -16,8 +16,8 @@
 
 /**
  * @file saml/binding/MessageDecoder.h
- * 
- * Interface to SAML protocol binding message decoders. 
+ *
+ * Interface to SAML protocol binding message decoders.
  */
 
 #ifndef __saml_decoder_h__
@@ -28,7 +28,7 @@
 #include <xmltooling/io/GenericRequest.h>
 
 namespace opensaml {
-    
+
     class SAML_API SAMLArtifact;
     namespace saml1p {
         class SAML_API Response;
@@ -64,12 +64,12 @@ namespace opensaml {
 
         /**
          * Interface to caller-supplied artifact resolution mechanism.
-         * 
+         *
          * Resolving artifacts requires internally performing a SOAP-based
          * call to the artifact source, usually in a mutually authenticated fashion.
          * The potential options vary widely, so the work is encapsulated by this
          * interface, though of course other library facilities may be used.
-         * 
+         *
          * <p>A MessageDecoder implementation will invoke the supplied interface
          * when it requires an artifact be resolved.
          */
@@ -85,11 +85,11 @@ namespace opensaml {
              * Resolves one or more SAML 1.x artifacts into a response containing a set of
              * resolved Assertions. The caller is responsible for the resulting Response.
              * The supplied SecurityPolicy is used to access caller-supplied infrastructure
-             * and to pass back the result of authenticating the resolution process. 
-             * 
+             * and to pass back the result of authenticating the resolution process.
+             *
              * @param artifacts         one or more SAML 1.x artifacts
              * @param idpDescriptor     reference to IdP role of artifact issuer
-             * @param policy            reference to policy containing rules, MetadataProvider, TrustEngine, etc. 
+             * @param policy            reference to policy containing rules, MetadataProvider, TrustEngine, etc.
              * @return the corresponding SAML Assertions wrapped in a Response.
              */
             virtual saml1p::Response* resolve(
@@ -102,11 +102,11 @@ namespace opensaml {
              * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message.
              * The caller is responsible for the resulting ArtifactResponse message.
              * The supplied SecurityPolicy is used to access caller-supplied infrastructure
-             * and to pass back the result of authenticating the resolution process. 
-             * 
+             * and to pass back the result of authenticating the resolution process.
+             *
              * @param artifact          reference to a SAML 2.0 artifact
              * @param ssoDescriptor     reference to SSO role of artifact issuer (may be SP or IdP)
-             * @param policy            reference to policy containing rules, MetadataProvider, TrustEngine, etc. 
+             * @param policy            reference to policy containing rules, MetadataProvider, TrustEngine, etc.
              * @return the corresponding SAML protocol message or NULL
              */
             virtual saml2p::ArtifactResponse* resolve(
@@ -114,31 +114,39 @@ namespace opensaml {
                 const saml2md::SSODescriptorType& ssoDescriptor,
                 SecurityPolicy& policy
                 ) const=0;
+
+            /**
+             * Returns true iff the metadata provided includes a supported artifact resolution service.
+             *
+             * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP)
+             * @return true iff the artifact issuer offers endpoints supported by this resolver
+             */
+            virtual bool isSupported(const saml2md::SSODescriptorType& ssoDescriptor) const;
         };
 
         /**
          * Provides an ArtifactResolver implementation for the MessageDecoder to use.
-         * The implementation's lifetime must be longer than the lifetime of this object. 
-         * This method must be externally synchronized. 
-         * 
+         * The implementation's lifetime must be longer than the lifetime of this object.
+         * This method must be externally synchronized.
+         *
          * @param artifactResolver   an ArtifactResolver implementation to use
          */
         void setArtifactResolver(const ArtifactResolver* artifactResolver) {
             m_artifactResolver = artifactResolver;
         }
-        
+
         /**
          * Decodes a transport request into a SAML protocol message, and evaluates it
          * against a supplied SecurityPolicy. If the transport request does not contain
          * the information necessary to decode the request, NULL will be returned.
          * Errors during the decoding process will be raised as exceptions.
-         * 
+         *
          * <p>Artifact-based bindings require an ArtifactResolver be set to
          * turn an artifact into the corresponding message.
-         * 
+         *
          * @param relayState        will be set to RelayState/TARGET value accompanying message
          * @param genericRequest    reference to interface for accessing transport request to decode
-         * @param policy            reference to policy containing rules, MetadataProvider, TrustEngine, etc. 
+         * @param policy            reference to policy containing rules, MetadataProvider, TrustEngine, etc.
          * @return  the decoded message, or NULL if the decoder did not recognize the request content
          */
         virtual xmltooling::XMLObject* decode(
@@ -155,7 +163,7 @@ namespace opensaml {
 
         /**
          * Extracts policy-relevant message details.
-         * 
+         *
          * @param message   the incoming message
          * @param request   the protocol request
          * @param protocol  the protocol family in use