DevWiki/websocket-sharp
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix some xml doc comments for HttpListener.cs

Browse Source
This commit is contained in:
sta 2014-04-23 21:13:36 +09:00
parent 03d5926492
commit 83bf1f8608
1 changed files with 87 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
websocket-sharp/Net/HttpListener.cs
View File

@ -33,7 +33,7 @@
#region Authors #region Authors
/* /*
* Authors: * Authors:
* Gonzalo Paniagua Javier <gonzalo@novell.com> * - Gonzalo Paniagua Javier <gonzalo@novell.com>
*/ */
#endregion #endregion
@ -44,7 +44,7 @@ using System.Security.Cryptography.X509Certificates;
using System.Security.Principal; using System.Security.Principal;
using System.Threading; using System.Threading;
// TODO: logging // TODO: Logging.
namespace WebSocketSharp.Net namespace WebSocketSharp.Net
{ {
/// <summary> /// <summary>
@ -104,12 +104,12 @@ namespace WebSocketSharp.Net
/// Gets or sets the scheme used to authenticate the clients. /// Gets or sets the scheme used to authenticate the clients.
/// </summary> /// </summary>
/// <value> /// <value>
/// One of the <see cref="WebSocketSharp.Net.AuthenticationSchemes"/> values /// One of the <see cref="WebSocketSharp.Net.AuthenticationSchemes"/> enum values,
/// that indicates the scheme used to authenticate the clients. The default /// represents the scheme used to authenticate the clients. The default value is
/// value is <see cref="WebSocketSharp.Net.AuthenticationSchemes.Anonymous"/>. /// <see cref="WebSocketSharp.Net.AuthenticationSchemes.Anonymous"/>.
/// </value> /// </value>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public AuthenticationSchemes AuthenticationSchemes { public AuthenticationSchemes AuthenticationSchemes {
get { get {
@ -124,16 +124,14 @@ namespace WebSocketSharp.Net
} }
/// <summary> /// <summary>
/// Gets or sets the delegate called to determine the scheme used to /// Gets or sets the delegate called to determine the scheme used to authenticate clients.
/// authenticate clients.
/// </summary> /// </summary>
/// <value> /// <value>
/// A <see cref="AuthenticationSchemeSelector"/> delegate that invokes the /// A <see cref="AuthenticationSchemeSelector"/> delegate that invokes the method(s) used to
/// method(s) used to select an authentication scheme. The default value is /// select an authentication scheme. The default value is <see langword="null"/>.
/// <see langword="null"/>.
/// </value> /// </value>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public AuthenticationSchemeSelector AuthenticationSchemeSelectorDelegate { public AuthenticationSchemeSelector AuthenticationSchemeSelectorDelegate {
get { get {
@ -148,29 +146,29 @@ namespace WebSocketSharp.Net
} }
/// <summary> /// <summary>
/// Gets or sets the path to the folder stored the certificate files used to /// Gets or sets the path to the folder in which stores the certificate files used to
/// authenticate the server on the secure connection. /// authenticate the server on the secure connection.
/// </summary> /// </summary>
/// <remarks> /// <remarks>
/// This property represents the path to the folder stored the certificate /// This property represents the path to the folder in which stores the certificate files
/// files associated with the port number of each added URI prefix. A set of /// associated with each port number of added URI prefixes. A set of the certificate files
/// the certificate files is a pair of the <c>'port number'.cer</c> (DER) and /// is a pair of the <c>'port number'.cer</c> (DER) and <c>'port number'.key</c>
/// <c>'port number'.key</c> (DER, RSA Private Key). /// (DER, RSA Private Key).
/// </remarks> /// </remarks>
/// <value> /// <value>
/// A <see cref="string"/> that contains the path to the certificate folder. /// A <see cref="string"/> that represents the path to the folder in which stores the
/// The default value is the result of <c>Environment.GetFolderPath</c> /// certificate files. The default value is result of <c>System.Environment.GetFolderPath
/// (<see cref="Environment.SpecialFolder.ApplicationData"/>). /// (<see cref="Environment.SpecialFolder.ApplicationData"/>)</c>.
/// </value> /// </value>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public string CertificateFolderPath { public string CertificateFolderPath {
get { get {
CheckDisposed (); CheckDisposed ();
return _certFolderPath == null || _certFolderPath.Length == 0 return _certFolderPath == null || _certFolderPath.Length == 0
? (_certFolderPath = Environment.GetFolderPath ( ? (_certFolderPath =
Environment.SpecialFolder.ApplicationData)) Environment.GetFolderPath (Environment.SpecialFolder.ApplicationData))
: _certFolderPath; : _certFolderPath;
} }
@ -181,16 +179,16 @@ namespace WebSocketSharp.Net
} }
/// <summary> /// <summary>
/// Gets or sets the default certificate used to authenticate the server on /// Gets or sets the default certificate used to authenticate the server on the secure
/// the secure connection. /// connection.
/// </summary> /// </summary>
/// <value> /// <value>
/// A <see cref="X509Certificate2"/> used to authenticate the server if the /// A <see cref="X509Certificate2"/> used to authenticate the server if the certificate
/// certificate associated with the port number of each added URI prefix is /// files aren't found in the <see cref="CertificateFolderPath"/>. The default value is
/// not found in the <see cref="CertificateFolderPath"/>. /// <see langword="null"/>.
/// </value> /// </value>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public X509Certificate2 DefaultCertificate { public X509Certificate2 DefaultCertificate {
get { get {
@ -205,16 +203,15 @@ namespace WebSocketSharp.Net
} }
/// <summary> /// <summary>
/// Gets or sets a value indicating whether the <see cref="HttpListener"/> /// Gets or sets a value indicating whether the listener returns exceptions that occur when
/// returns exceptions that occur when sending the response to the client. /// sending the response to the client.
/// </summary> /// </summary>
/// <value> /// <value>
/// <c>true</c> if the <see cref="HttpListener"/> doesn't return exceptions /// <c>true</c> if the listener doesn't return exceptions that occur when sending the response
/// that occur when sending the response to the client; otherwise, /// to the client; otherwise, <c>false</c>. The default value is <c>false</c>.
/// <c>false</c>. The default value is <c>false</c>.
/// </value> /// </value>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public bool IgnoreWriteExceptions { public bool IgnoreWriteExceptions {
get { get {
@ -229,12 +226,10 @@ namespace WebSocketSharp.Net
} }
/// <summary> /// <summary>
/// Gets a value indicating whether the <see cref="HttpListener"/> has been /// Gets a value indicating whether the listener has been started.
/// started.
/// </summary> /// </summary>
/// <value> /// <value>
/// <c>true</c> if the <see cref="HttpListener"/> has been started; otherwise, /// <c>true</c> if the listener has been started; otherwise, <c>false</c>.
/// <c>false</c>.
/// </value> /// </value>
public bool IsListening { public bool IsListening {
get { get {
@ -243,8 +238,7 @@ namespace WebSocketSharp.Net
} }
/// <summary> /// <summary>
/// Gets a value indicating whether the <see cref="HttpListener"/> can be /// Gets a value indicating whether the listener can be used with the current operating system.
/// used with the current operating system.
/// </summary> /// </summary>
/// <value> /// <value>
/// <c>true</c>. /// <c>true</c>.
@ -256,14 +250,13 @@ namespace WebSocketSharp.Net
} }
/// <summary> /// <summary>
/// Gets the URI prefixes handled by the <see cref="HttpListener"/>. /// Gets the URI prefixes handled by the listener.
/// </summary> /// </summary>
/// <value> /// <value>
/// A <see cref="HttpListenerPrefixCollection"/> that contains the URI /// A <see cref="HttpListenerPrefixCollection"/> that contains the URI prefixes.
/// prefixes.
/// </value> /// </value>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public HttpListenerPrefixCollection Prefixes { public HttpListenerPrefixCollection Prefixes {
get { get {
@ -273,15 +266,14 @@ namespace WebSocketSharp.Net
} }
/// <summary> /// <summary>
/// Gets or sets the name of the realm associated with the /// Gets or sets the name of the realm associated with the listener.
/// <see cref="HttpListener"/>.
/// </summary> /// </summary>
/// <value> /// <value>
/// A <see cref="string"/> that contains the name of the realm. The default /// A <see cref="string"/> that represents the name of the realm. The default value is
/// value is <c>SECRET AREA</c>. /// <c>SECRET AREA</c>.
/// </value> /// </value>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public string Realm { public string Realm {
get { get {
@ -324,16 +316,16 @@ namespace WebSocketSharp.Net
} }
/// <summary> /// <summary>
/// Gets or sets the delegate called to find the credentials for an identity /// Gets or sets the delegate called to find the credentials for an identity used to
/// used to authenticate a client. /// authenticate a client.
/// </summary> /// </summary>
/// <value> /// <value>
/// A Func&lt;<see cref="IIdentity"/>, <see cref="NetworkCredential"/>&gt; /// A <c>Func&lt;<see cref="IIdentity"/>, <see cref="NetworkCredential"/>&gt;</c> delegate
/// delegate that references the method(s) used to find the credentials. The /// that invokes the method(s) used to find the credentials. The default value is a function
/// default value is a function that only returns <see langword="null"/>. /// that only returns <see langword="null"/>.
/// </value> /// </value>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public Func<IIdentity, NetworkCredential> UserCredentialsFinder { public Func<IIdentity, NetworkCredential> UserCredentialsFinder {
get { get {
@ -369,7 +361,7 @@ namespace WebSocketSharp.Net
if (_connections.Count == 0) if (_connections.Count == 0)
return; return;
// Need to copy this since closing will call RemoveConnection // Need to copy this since closing will call RemoveConnection.
var keys = _connections.Keys; var keys = _connections.Keys;
var conns = new HttpConnection [keys.Count]; var conns = new HttpConnection [keys.Count];
keys.CopyTo (conns, 0); keys.CopyTo (conns, 0);
@ -385,7 +377,7 @@ namespace WebSocketSharp.Net
if (_registry.Count == 0) if (_registry.Count == 0)
return; return;
// Need to copy this since closing will call UnregisterContext // Need to copy this since closing will call UnregisterContext.
var keys = _registry.Keys; var keys = _registry.Keys;
var all = new HttpListenerContext [keys.Count]; var all = new HttpListenerContext [keys.Count];
keys.CopyTo (all, 0); keys.CopyTo (all, 0);
@ -402,9 +394,8 @@ namespace WebSocketSharp.Net
return; return;
var ex = new ObjectDisposedException (GetType ().ToString ()); var ex = new ObjectDisposedException (GetType ().ToString ());
foreach (var ares in _waitQueue) { foreach (var ares in _waitQueue)
ares.Complete (ex); ares.Complete (ex);
}
_waitQueue.Clear (); _waitQueue.Clear ();
} }
@ -416,7 +407,7 @@ namespace WebSocketSharp.Net
cleanup (force); cleanup (force);
} }
// Must be called with a lock on _contextQueue // Must be called with a lock on _contextQueue.
private HttpListenerContext getContextFromQueue () private HttpListenerContext getContextFromQueue ()
{ {
if (_contextQueue.Count == 0) if (_contextQueue.Count == 0)
@ -457,14 +448,12 @@ namespace WebSocketSharp.Net
{ {
CheckDisposed (); CheckDisposed ();
if (_prefixes.Count == 0) if (_prefixes.Count == 0)
throw new InvalidOperationException ( throw new InvalidOperationException ("Please, call AddPrefix before using this method.");
"Please, call AddPrefix before using this method.");
if (!_listening) if (!_listening)
throw new InvalidOperationException ( throw new InvalidOperationException ("Please, call Start before using this method.");
"Please, call Start before using this method.");
// Lock _waitQueue early to avoid race conditions // Lock _waitQueue early to avoid race conditions.
lock (((ICollection) _waitQueue).SyncRoot) { lock (((ICollection) _waitQueue).SyncRoot) {
lock (((ICollection) _contextQueue).SyncRoot) { lock (((ICollection) _contextQueue).SyncRoot) {
var context = getContextFromQueue (); var context = getContextFromQueue ();
@ -512,8 +501,7 @@ namespace WebSocketSharp.Net
_connections.Remove (connection); _connections.Remove (connection);
} }
internal AuthenticationSchemes SelectAuthenticationScheme ( internal AuthenticationSchemes SelectAuthenticationScheme (HttpListenerContext context)
HttpListenerContext context)
{ {
return AuthenticationSchemeSelectorDelegate != null return AuthenticationSchemeSelectorDelegate != null
? AuthenticationSchemeSelectorDelegate (context.Request) ? AuthenticationSchemeSelectorDelegate (context.Request)
@ -537,7 +525,7 @@ namespace WebSocketSharp.Net
#region Public Methods #region Public Methods
/// <summary> /// <summary>
/// Shuts down the <see cref="HttpListener"/> immediately. /// Shuts down the listener immediately.
/// </summary> /// </summary>
public void Abort () public void Abort ()
{ {
@ -552,17 +540,15 @@ namespace WebSocketSharp.Net
/// Begins getting an incoming request information asynchronously. /// Begins getting an incoming request information asynchronously.
/// </summary> /// </summary>
/// <remarks> /// <remarks>
/// This asynchronous operation must be completed by calling the /// This asynchronous operation must be completed by calling the <c>EndGetContext</c> method.
/// <c>EndGetContext</c> method. Typically, that method is invoked by the /// Typically, that method is invoked by the <paramref name="callback"/> delegate.
/// <paramref name="callback"/> delegate.
/// </remarks> /// </remarks>
/// <returns> /// <returns>
/// An <see cref="IAsyncResult"/> that contains the status of the /// An <see cref="IAsyncResult"/> that represents the status of the asynchronous operation.
/// asynchronous operation.
/// </returns> /// </returns>
/// <param name="callback"> /// <param name="callback">
/// An <see cref="AsyncCallback"/> delegate that references the method(s) /// An <see cref="AsyncCallback"/> delegate that references the method(s) to invoke
/// called when the asynchronous operation completes. /// when the asynchronous operation completes.
/// </param> /// </param>
/// <param name="state"> /// <param name="state">
/// An <see cref="object"/> that contains a user defined object to pass to /// An <see cref="object"/> that contains a user defined object to pass to
@ -570,19 +556,17 @@ namespace WebSocketSharp.Net
/// </param> /// </param>
/// <exception cref="InvalidOperationException"> /// <exception cref="InvalidOperationException">
/// <para> /// <para>
/// The <see cref="HttpListener"/> does not have any URI prefixes to listen /// This listener doesn't have any URI prefixes to listen on.
/// on.
/// </para> /// </para>
/// <para> /// <para>
/// -or- /// -or-
/// </para> /// </para>
/// <para> /// <para>
/// The <see cref="HttpListener"/> has not been started or is stopped /// This listener hasn't been started or is stopped currently.
/// currently.
/// </para> /// </para>
/// </exception> /// </exception>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public IAsyncResult BeginGetContext (AsyncCallback callback, Object state) public IAsyncResult BeginGetContext (AsyncCallback callback, Object state)
{ {
@ -590,7 +574,7 @@ namespace WebSocketSharp.Net
} }
/// <summary> /// <summary>
/// Shuts down the <see cref="HttpListener"/>. /// Shuts down the listener.
/// </summary> /// </summary>
public void Close () public void Close ()
{ {
@ -605,30 +589,26 @@ namespace WebSocketSharp.Net
/// Ends an asynchronous operation to get an incoming request information. /// Ends an asynchronous operation to get an incoming request information.
/// </summary> /// </summary>
/// <remarks> /// <remarks>
/// This method completes an asynchronous operation started by calling the /// This method completes an asynchronous operation started by calling
/// <c>BeginGetContext</c> method. /// the <c>BeginGetContext</c> method.
/// </remarks> /// </remarks>
/// <returns> /// <returns>
/// A <see cref="HttpListenerContext"/> that contains a client's request /// A <see cref="HttpListenerContext"/> that contains a request information.
/// information.
/// </returns> /// </returns>
/// <param name="asyncResult"> /// <param name="asyncResult">
/// An <see cref="IAsyncResult"/> obtained by calling the /// An <see cref="IAsyncResult"/> obtained by calling the <c>BeginGetContext</c> method.
/// <c>BeginGetContext</c> method.
/// </param> /// </param>
/// <exception cref="ArgumentException">
/// <paramref name="asyncResult"/> was not obtained by calling the
/// <c>BeginGetContext</c> method.
/// </exception>
/// <exception cref="ArgumentNullException"> /// <exception cref="ArgumentNullException">
/// <paramref name="asyncResult"/> is <see langword="null"/>. /// <paramref name="asyncResult"/> is <see langword="null"/>.
/// </exception> /// </exception>
/// <exception cref="ArgumentException">
/// <paramref name="asyncResult"/> wasn't obtained by calling the <c>BeginGetContext</c> method.
/// </exception>
/// <exception cref="InvalidOperationException"> /// <exception cref="InvalidOperationException">
/// This method was already called for the specified /// This method was already called for the specified <paramref name="asyncResult"/>.
/// <paramref name="asyncResult"/>.
/// </exception> /// </exception>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public HttpListenerContext EndGetContext (IAsyncResult asyncResult) public HttpListenerContext EndGetContext (IAsyncResult asyncResult)
{ {
@ -654,9 +634,9 @@ namespace WebSocketSharp.Net
} }
var context = ares.GetContext (); var context = ares.GetContext ();
var authScheme = SelectAuthenticationScheme (context); var scheme = SelectAuthenticationScheme (context);
if (authScheme != AuthenticationSchemes.Anonymous) if (scheme != AuthenticationSchemes.Anonymous)
context.SetUser (authScheme, Realm, UserCredentialsFinder); context.SetUser (scheme, Realm, UserCredentialsFinder);
return context; // This will throw on error. return context; // This will throw on error.
} }
@ -665,28 +645,25 @@ namespace WebSocketSharp.Net
/// Gets an incoming request information. /// Gets an incoming request information.
/// </summary> /// </summary>
/// <remarks> /// <remarks>
/// This method waits for an incoming request and returns the request /// This method waits for an incoming request and returns a request information
/// information when received the request. /// when the listener receives a request.
/// </remarks> /// </remarks>
/// <returns> /// <returns>
/// A <see cref="HttpListenerContext"/> that contains a client's request /// A <see cref="HttpListenerContext"/> that contains a request information.
/// information.
/// </returns> /// </returns>
/// <exception cref="InvalidOperationException"> /// <exception cref="InvalidOperationException">
/// <para> /// <para>
/// The <see cref="HttpListener"/> does not have any URI prefixes to listen /// This listener doesn't have any URI prefixes to listen on.
/// on.
/// </para> /// </para>
/// <para> /// <para>
/// -or- /// -or-
/// </para> /// </para>
/// <para> /// <para>
/// The <see cref="HttpListener"/> has not been started or is stopped /// This listener hasn't been started or is stopped currently.
/// currently.
/// </para> /// </para>
/// </exception> /// </exception>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public HttpListenerContext GetContext () public HttpListenerContext GetContext ()
{ {
@ -700,7 +677,7 @@ namespace WebSocketSharp.Net
/// Starts to receive incoming requests. /// Starts to receive incoming requests.
/// </summary> /// </summary>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public void Start () public void Start ()
{ {
@ -716,7 +693,7 @@ namespace WebSocketSharp.Net
/// Stops receiving incoming requests. /// Stops receiving incoming requests.
/// </summary> /// </summary>
/// <exception cref="ObjectDisposedException"> /// <exception cref="ObjectDisposedException">
/// This object has been closed. /// This listener has been closed.
/// </exception> /// </exception>
public void Stop () public void Stop ()
{ {
@ -734,7 +711,7 @@ namespace WebSocketSharp.Net
#region Explicit Interface Implementation #region Explicit Interface Implementation
/// <summary> /// <summary>
/// Releases all resource used by the <see cref="HttpListener"/>. /// Releases all resource used by the listener.
/// </summary> /// </summary>
void IDisposable.Dispose () void IDisposable.Dispose ()
{ {