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.  May be null.</param>
  40                 protected ExtensionBase(Version version, string typeUri, IEnumerable<string> additionalSupportedTypeUris) {
  41                         this.Version = version;
  42                         this.typeUri = typeUri;
  43                         this.additionalSupportedTypeUris = additionalSupportedTypeUris ?? EmptyList<string>.Instance;
  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                 /// <remarks>
  61                 /// Useful for reading in messages with an older version of an extension.
  62                 /// The value in the <see cref="IOpenIdMessageExtension.TypeUri"/> property is always checked before
  63                 /// trying this list.
  64                 /// If you do support multiple versions of an extension using this method,
  65                 /// consider adding a CreateResponse method to your request extension class
  66                 /// so that the response can have the context it needs to remain compatible
  67                 /// given the version of the extension in the request message.
  68                 /// The <see cref="SimpleRegistration.ClaimsRequest.CreateResponse"/> for an example.
  69                 /// </remarks>
  70                 IEnumerable<string> IOpenIdMessageExtension.AdditionalSupportedTypeUris {
  71                         get { return this.AdditionalSupportedTypeUris; }
  72                 }
  73
  74                 #endregion
  75
  76                 #region IMessage Properties
  77
  78                 /// <summary>
  79                 /// Gets the version of the protocol or extension this message is prepared to implement.
  80                 /// </summary>
  81                 public Version Version { get; private set; }
  82
  83                 /// <summary>
  84                 /// Gets the extra, non-standard Protocol parameters included in the message.
  85                 /// </summary>
  86                 /// <remarks>
  87                 /// Implementations of this interface should ensure that this property never returns null.
  88                 /// </remarks>
  89                 IDictionary<string, string> IMessage.ExtraData {
  90                         get { return this.ExtraData; }
  91                 }
  92
  93                 #endregion
  94
  95                 /// <summary>
  96                 /// Gets the TypeURI the extension uses in the OpenID protocol and in XRDS advertisements.
  97                 /// </summary>
  98                 protected string TypeUri {
  99                         get { return this.typeUri; }
 100                 }
 101
 102                 /// <summary>
 103                 /// Gets the additional TypeURIs that are supported by this extension, in preferred order.
 104                 /// May be empty if none other than <see cref="IOpenIdMessageExtension.TypeUri"/> is supported, but
 105                 /// should not be null.
 106                 /// </summary>
 107                 /// <value></value>
 108                 /// <remarks>
 109                 /// Useful for reading in messages with an older version of an extension.
 110                 /// The value in the <see cref="IOpenIdMessageExtension.TypeUri"/> property is always checked before
 111                 /// trying this list.
 112                 /// If you do support multiple versions of an extension using this method,
 113                 /// consider adding a CreateResponse method to your request extension class
 114                 /// so that the response can have the context it needs to remain compatible
 115                 /// given the version of the extension in the request message.
 116                 /// The <see cref="Extensions.SimpleRegistration.ClaimsRequest.CreateResponse"/> for an example.
 117                 /// </remarks>
 118                 protected IEnumerable<string> AdditionalSupportedTypeUris {
 119                         get { return this.additionalSupportedTypeUris; }
 120                 }
 121
 122                 /// <summary>
 123                 /// Gets the extra, non-standard Protocol parameters included in the message.
 124                 /// </summary>
 125                 /// <value></value>
 126                 /// <remarks>
 127                 /// Implementations of this interface should ensure that this property never returns null.
 128                 /// </remarks>
 129                 protected IDictionary<string, string> ExtraData {
 130                         get { return this.extraData; }
 131                 }
 132
 133                 #region IMessage Methods
 134
 135                 /// <summary>
 136                 /// Checks the message state for conformity to the protocol specification
 137                 /// and throws an exception if the message is invalid.
 138                 /// </summary>
 139                 /// <remarks>
 140                 ///     <para>Some messages have required fields, or combinations of fields that must relate to each other
 141                 /// in specialized ways.  After deserializing a message, this method checks the state of the
 142                 /// message to see if it conforms to the protocol.</para>
 143                 ///     <para>Note that this property should <i>not</i> check signatures or perform any state checks
 144                 /// outside this scope of this particular message.</para>
 145                 /// </remarks>
 146                 /// <exception cref="ProtocolException">Thrown if the message is invalid.</exception>
 147                 void IMessage.EnsureValidMessage() {
 148                         this.EnsureValidMessage();
 149                 }
 150
 151                 #endregion
 152
 153                 /// <summary>
 154                 /// Checks the message state for conformity to the protocol specification
 155                 /// and throws an exception if the message is invalid.
 156                 /// </summary>
 157                 /// <remarks>
 158                 ///     <para>Some messages have required fields, or combinations of fields that must relate to each other
 159                 /// in specialized ways.  After deserializing a message, this method checks the state of the
 160                 /// message to see if it conforms to the protocol.</para>
 161                 ///     <para>Note that this property should <i>not</i> check signatures or perform any state checks
 162                 /// outside this scope of this particular message.</para>
 163                 /// </remarks>
 164                 /// <exception cref="ProtocolException">Thrown if the message is invalid.</exception>
 165                 protected virtual void EnsureValidMessage() {
 166                 }
 167         }
 168 }