Add short name to encoders/decoders for endpoint generation.

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

diff --git a/saml/binding/MessageEncoder.h b/saml/binding/MessageEncoder.h
index 1bc8e1c..96c30b3 100644 (file)
--- a/saml/binding/MessageEncoder.h
+++ b/saml/binding/MessageEncoder.h
@@ -1,5 +1,5 @@
 /*
- *  Copyright 2001-2007 Internet2
+ *  Copyright 2001-2010 Internet2
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,10 +25,11 @@
 
 #include <saml/base.h>
 
-#include <istream>
-#include <xmltooling/XMLObject.h>
-#include <xmltooling/io/GenericResponse.h>
-#include <xmltooling/security/Credential.h>
+namespace xmltooling {
+    class XMLTOOL_API Credential;
+    class XMLTOOL_API GenericResponse;
+    class XMLTOOL_API XMLObject;
+};
 
 namespace opensaml {
 
@@ -36,6 +37,9 @@ namespace opensaml {
     namespace saml2p {
         class SAML_API SAML2Artifact;
     };
+    namespace saml2md {
+        class SAML_API EntityDescriptor;
+    };
 
     /**
      * Interface to SAML protocol binding message encoders.
@@ -44,16 +48,35 @@ namespace opensaml {
     {
         MAKE_NONCOPYABLE(MessageEncoder);
     public:
-        virtual ~MessageEncoder() {}
+        virtual ~MessageEncoder();
 
         /**
          * Indicates whether the encoding format requires that messages be as compact as possible.
          *
          * @return  true iff the encoding has size constraints
          */
-        virtual bool isCompact() const {
-            return false;
-        }
+        virtual bool isCompact() const;
+
+        /**
+         * Indicates whether a web browser or similar user agent will receive the message.
+         *
+         * @return true iff the message will be handled by a user agent
+         */
+        virtual bool isUserAgentPresent() const;
+
+        /**
+         * Returns identifier for the protocol family associated with the encoder.
+         *
+         * @return  a protocol family identifier, or nullptr
+         */
+        virtual const XMLCh* getProtocolFamily() const;
+
+        /**
+         * Returns a shorthand name for the binding/encoding supported by the encoder.
+         *
+         * @return  a short name for the binding/encoding, or nullptr
+         */
+        virtual const char* getShortName() const;
 
         /**
          * Interface to caller-supplied artifact generation mechanism.
@@ -68,9 +91,9 @@ namespace opensaml {
         class SAML_API ArtifactGenerator {
             MAKE_NONCOPYABLE(ArtifactGenerator);
         protected:
-            ArtifactGenerator() {}
+            ArtifactGenerator();
         public:
-            virtual ~ArtifactGenerator() {}
+            virtual ~ArtifactGenerator();
             
             /**
              * Generate a SAML 1.x artifact suitable for consumption by the relying party.
@@ -78,7 +101,7 @@ namespace opensaml {
              * @param relyingParty  the party that will recieve the artifact
              * @return a SAML 1.x artifact with a random assertion handle
              */
-            virtual SAMLArtifact* generateSAML1Artifact(const char* relyingParty) const=0;
+            virtual SAMLArtifact* generateSAML1Artifact(const saml2md::EntityDescriptor* relyingParty) const=0;
 
             /**
              * Generate a SAML 2.0 artifact suitable for consumption by the relying party.
@@ -86,21 +109,10 @@ namespace opensaml {
              * @param relyingParty  the party that will recieve the artifact
              * @return a SAML 2.0 artifact with a random message handle
              */
-            virtual saml2p::SAML2Artifact* generateSAML2Artifact(const char* relyingParty) const=0;
+            virtual saml2p::SAML2Artifact* generateSAML2Artifact(const saml2md::EntityDescriptor* relyingParty) const=0;
         };
 
         /**
-         * Provides an ArtifactGenerator implementation for the MessageEncoder to use.
-         * The implementation's lifetime must be longer than the lifetime of this object. 
-         * This method must be externally synchronized. 
-         * 
-         * @param artifactGenerator   an ArtifactGenerator implementation to use
-         */
-        void setArtifactGenerator(ArtifactGenerator* artifactGenerator) {
-            m_artifactGenerator = artifactGenerator;
-        }
-        
-        /**
          * Encodes an XML object/message into a binding- and transport-specific response.
          * The XML content cannot have a parent object, and any existing references to
          * the content will be invalidated if the encode method returns successfully.
@@ -115,8 +127,9 @@ namespace opensaml {
          * @param genericResponse   reference to interface for sending transport response      
          * @param xmlObject         XML message to encode
          * @param destination       destination URL for message
-         * @param recipientID       optional entityID of message recipient
+         * @param recipient         optional message recipient
          * @param relayState        optional RelayState value to accompany message
+         * @param artifactGenerator optional interface for generation of artifacts
          * @param credential        optional Credential to supply signing key
          * @param signatureAlg      optional signature algorithm identifier
          * @param digestAlg         optional reference digest algorithm identifier
@@ -125,18 +138,16 @@ namespace opensaml {
             xmltooling::GenericResponse& genericResponse,
             xmltooling::XMLObject* xmlObject,
             const char* destination,
-            const char* recipientID=NULL,
-            const char* relayState=NULL,
-            const xmltooling::Credential* credential=NULL,
-            const XMLCh* signatureAlg=NULL,
-            const XMLCh* digestAlg=NULL
+            const saml2md::EntityDescriptor* recipient=nullptr,
+            const char* relayState=nullptr,
+            const ArtifactGenerator* artifactGenerator=nullptr,
+            const xmltooling::Credential* credential=nullptr,
+            const XMLCh* signatureAlg=nullptr,
+            const XMLCh* digestAlg=nullptr
             ) const=0;
 
     protected:
-        MessageEncoder() : m_artifactGenerator(NULL) {}
-        
-        /** Pointer to an ArtifactGenerator implementation. */
-        const ArtifactGenerator* m_artifactGenerator;
+        MessageEncoder();
     };
 
     /**