saml/binding/SAMLArtifact.h

   1 /*
   2  *  Copyright 2001-2010 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file saml/binding/SAMLArtifact.h
  19  *
  20  * Base class for SAML 1.x and 2.0 artifacts.
  21  */
  22
  23 #ifndef __saml_artifact_h__
  24 #define __saml_artifact_h__
  25
  26 #include <saml/base.h>
  27
  28 #include <string>
  29 #include <xmltooling/exceptions.h>
  30
  31 namespace opensaml {
  32
  33 #if defined (_MSC_VER)
  34     #pragma warning( push )
  35     #pragma warning( disable : 4251 )
  36 #endif
  37
  38     /**
  39      * Base class for SAML 1.x and 2.0 artifacts.
  40      */
  41     class SAML_API SAMLArtifact
  42     {
  43         SAMLArtifact& operator=(const SAMLArtifact& src);
  44     public:
  45         virtual ~SAMLArtifact();
  46
  47         /**
  48          * Returns artifact encoded into null-terminated base64 for transmission.
  49          */
  50         virtual std::string encode() const;
  51
  52         /**
  53          * Builds a duplicate, independent artifact of the same type.
  54          *
  55          * @return the new artifact
  56          */
  57         virtual SAMLArtifact* clone() const=0;
  58
  59         /**
  60          * Returns all of the raw binary data that makes up the artifact.
  61          * The result is NOT null-terminated.
  62          *
  63          * @return the binary artifact data
  64          */
  65         virtual std::string getBytes() const;
  66
  67         /**
  68          * Returns the binary type code of the artifact.
  69          * The result MAY contain embedded null characters.
  70          *
  71          * @return the binary type code
  72          */
  73         virtual std::string getTypeCode() const;
  74
  75         /**
  76          * Returns the binary artifact data following the type code.
  77          * The result MAY contain embedded null characters.
  78          *
  79          * @return the binary artifact data
  80          */
  81         virtual std::string getRemainingArtifact() const;
  82
  83         /**
  84          * Returns a string that identifies the source of the artifact.
  85          * The exact form this takes depends on the type but should match
  86          * the syntax needed for metadata lookup.
  87          *
  88          * @return null-terminated source string
  89          */
  90         virtual std::string getSource() const=0;
  91
  92         /**
  93          * Returns the binary data that references the message (2.0) or assertion (1.x)
  94          * The exact form this takes depends on the type.
  95          * The result MAY contain embedded null characters.
  96          *
  97          * @return the binary reference data
  98          */
  99         virtual std::string getMessageHandle() const=0;
 100
 101         /** Length of type code */
 102         static const unsigned int TYPECODE_LENGTH;
 103
 104         /**
 105          * Parses a base64-encoded null-terminated string into an artifact,
 106          * if the type is known.
 107          *
 108          * @param s base64-encoded artifact
 109          * @return the decoded artifact
 110          */
 111         static SAMLArtifact* parse(const char* s);
 112
 113         /**
 114          * Parses a base64-encoded null-terminated string into an artifact,
 115          * if the type is known.
 116          *
 117          * @param s base64-encoded artifact
 118          * @return the decoded artifact
 119          */
 120         static SAMLArtifact* parse(const XMLCh* s);
 121
 122         /**
 123          * Converts binary data to hex notation.
 124          *
 125          * @param s the bytes to convert
 126          * @return  the data in hex form, 2 characters per byte
 127          */
 128         static std::string toHex(const std::string& s);
 129
 130     protected:
 131         SAMLArtifact();
 132
 133         /**
 134          * Decodes a base64-encoded artifact into its raw form.
 135          *
 136          * @param s NULL-terminated base64-encoded string
 137          */
 138         SAMLArtifact(const char* s);
 139
 140         SAMLArtifact(const SAMLArtifact& src);
 141
 142         /** Raw binary data that makes up an artifact. */
 143         std::string m_raw;
 144     };
 145
 146 #if defined (_MSC_VER)
 147     #pragma warning( pop )
 148 #endif
 149
 150     DECL_XMLTOOLING_EXCEPTION(ArtifactException,SAML_EXCEPTIONAPI(SAML_API),opensaml,xmltooling::XMLToolingException,Exceptions related to artifact parsing);
 151
 152     /**
 153      * Registers SAMLArtifact subclasses into the runtime.
 154      */
 155     void SAML_API registerSAMLArtifacts();
 156 };
 157
 158 #endif /* __saml_artifact_h__ */