src/DotNetOpenAuth/OpenId/Extensions/ExtensionBase.cs

   1 //-----------------------------------------------------------------------
   2 // <copyright file="ExtensionBase.cs" company="Andrew Arnott">
   3 //     Copyright (c) Andrew Arnott. All rights reserved.
   4 // </copyright>
   5 //-----------------------------------------------------------------------
   6
   7 namespace DotNetOpenAuth.OpenId.Extensions {
   8         using System;
   9         using System.Collections.Generic;
  10         using System.Linq;
  11         using System.Text;
  12         using DotNetOpenAuth.Messaging;
  13         using DotNetOpenAuth.OpenId.Messages;
  14
  15         /// <summary>
  16         /// A handy base class for built-in extensions.
  17         /// </summary>
  18         public class ExtensionBase : IOpenIdMessageExtension {
  19                 /// <summary>
  20                 /// Backing store for the <see cref="IOpenIdMessageExtension.TypeUri"/> property.
  21                 /// </summary>
  22                 private string typeUri;
  23
  24                 /// <summary>
  25                 /// Backing store for the <see cref="IOpenIdMessageExtension.AdditionalSupportedTypeUris"/> property.
  26                 /// </summary>
  27                 private IEnumerable<string> additionalSupportedTypeUris;
  28
  29                 /// <summary>
  30                 /// Backing store for the <see cref="IMessage.ExtraData"/> property.
  31                 /// </summary>
  32                 private Dictionary<string, string> extraData = new Dictionary<string, string>();
  33
  34                 /// <summary>
  35                 /// Initializes a new instance of the <see cref="ExtensionBase"/> class.
  36                 /// </summary>
  37                 /// <param name="version">The version of the extension.</param>
  38                 /// <param name="typeUri">The type URI to use in the OpenID message.</param>
  39                 /// <param name="additionalSupportedTypeUris">The additional supported type URIs by which this extension might be recognized.</param>
  40                 protected ExtensionBase(Version version, string typeUri, IEnumerable<string> additionalSupportedTypeUris) {
  41                         this.Version = version;
  42                         this.typeUri = typeUri;
  43                         this.additionalSupportedTypeUris = additionalSupportedTypeUris;
  44                 }
  45
  46                 #region IOpenIdProtocolMessageExtension Members
  47
  48                 /// <summary>
  49                 /// Gets the TypeURI the extension uses in the OpenID protocol and in XRDS advertisements.
  50                 /// </summary>
  51                 string IOpenIdMessageExtension.TypeUri {
  52                         get { return this.typeUri; }
  53                 }
  54
  55                 /// <summary>
  56                 /// Gets the additional TypeURIs that are supported by this extension, in preferred order.
  57                 /// May be empty if none other than <see cref="IOpenIdMessageExtension.TypeUri"/> is supported, but
  58                 /// should not be null.
  59                 /// </summary>
  60                 /// <value></value>
  61                 /// <remarks>
  62                 /// Useful for reading in messages with an older version of an extension.
  63                 /// The value in the <see cref="IOpenIdMessageExtension.TypeUri"/> property is always checked before
  64                 /// trying this list.
  65                 /// If you do support multiple versions of an extension using this method,
  66                 /// consider adding a CreateResponse method to your request extension class
  67                 /// so that the response can have the context it needs to remain compatible
  68                 /// given the version of the extension in the request message.
  69                 /// The <see cref="SimpleRegistration.ClaimsRequest.CreateResponse"/> for an example.
  70                 /// </remarks>
  71                 IEnumerable<string> IOpenIdMessageExtension.AdditionalSupportedTypeUris {
  72                         get { return this.additionalSupportedTypeUris; }
  73                 }
  74
  75                 #endregion
  76
  77                 #region IMessage Members
  78
  79                 /// <summary>
  80                 /// Gets the version of the protocol or extension this message is prepared to implement.
  81                 /// </summary>
  82                 public Version Version { get; private set; }
  83
  84                 /// <summary>
  85                 /// Gets the extra, non-standard Protocol parameters included in the message.
  86                 /// </summary>
  87                 /// <remarks>
  88                 /// Implementations of this interface should ensure that this property never returns null.
  89                 /// </remarks>
  90                 IDictionary<string, string> IMessage.ExtraData {
  91                         get { return this.extraData; }
  92                 }
  93
  94                 /// <summary>
  95                 /// Checks the message state for conformity to the protocol specification
  96                 /// and throws an exception if the message is invalid.
  97                 /// </summary>
  98                 /// <remarks>
  99                 ///     <para>Some messages have required fields, or combinations of fields that must relate to each other
 100                 /// in specialized ways.  After deserializing a message, this method checks the state of the
 101                 /// message to see if it conforms to the protocol.</para>
 102                 ///     <para>Note that this property should <i>not</i> check signatures or perform any state checks
 103                 /// outside this scope of this particular message.</para>
 104                 /// </remarks>
 105                 /// <exception cref="ProtocolException">Thrown if the message is invalid.</exception>
 106                 void IMessage.EnsureValidMessage() {
 107                         this.EnsureValidMessage();
 108                 }
 109
 110                 #endregion
 111
 112                 /// <summary>
 113                 /// Checks the message state for conformity to the protocol specification
 114                 /// and throws an exception if the message is invalid.
 115                 /// </summary>
 116                 /// <remarks>
 117                 ///     <para>Some messages have required fields, or combinations of fields that must relate to each other
 118                 /// in specialized ways.  After deserializing a message, this method checks the state of the
 119                 /// message to see if it conforms to the protocol.</para>
 120                 ///     <para>Note that this property should <i>not</i> check signatures or perform any state checks
 121                 /// outside this scope of this particular message.</para>
 122                 /// </remarks>
 123                 /// <exception cref="ProtocolException">Thrown if the message is invalid.</exception>
 124                 protected virtual void EnsureValidMessage() {
 125                 }
 126         }
 127 }