System 2.0.0.0 4.0.0.0 System.Object System.IDisposable

Using the class, you can create a simple HTTP protocol listener that responds to HTTP requests. The listener is active for the lifetime of the object and runs within your application with its permissions.

This class is available only on computers running the Windows XP SP2 or Windows Server 2003 operating systems. If you attempt to create an object on a computer that is running an earlier operating system, the constructor throws a exception.

To use , create a new instance of the class using the constructor and use the property to gain access to the collection that holds the strings that specify which Uniform Resource Identifier (URI) prefixes the should process.

A URI prefix string is composed of a scheme (http or https), a host, an optional port, and an optional path. An example of a complete prefix string is "http://www.contoso.com:8080/customerData/". Prefixes must end in a forward slash ("/"). The object with the prefix that most closely matches a requested URI responds to the request. Multiple objects cannot add the same prefix; a exception is thrown if a adds a prefix that is already in use.

When a port is specified, the host element can be replaced with "*" to indicate that the accepts requests sent to the port if the requested URI does not match any other prefix. For example, to receive all requests sent to port 8080 when the requested URI is not handled by any , the prefix is "http://*:8080/". Similarly, to specify that the accepts all requests sent to a port, replace the host element with the "+" character, "https://+:8080". The "*" and "+" characters can be present in prefixes that include paths.

To begin listening for requests from clients, add the URI prefixes to the collection and call the method. offers both synchronous and asynchronous models for processing client requests. Requests and their associated responses are accessed using the object returned by the method or its asynchronous counterparts, the and methods.

The synchronous model is appropriate if your application should block while waiting for a client request and if you want to process only one request at a time. Using the synchronous model, call the method, which waits for a client to send a request. The method returns an object to you for processing when one occurs.

In the more complex asynchronous model, your application does not block while waiting for requests and each request is processed in its own execution thread. Use the method to specify an application-defined method to be called for each incoming request. Within that method, call the method to obtain the request, process it, and respond.

In either model, incoming requests are accessed using the property and are represented by objects. Similarly, responses are accessed using the property and are represented by objects. These objects share some functionality with the and objects, but the latter objects cannot be used in conjunction with because they implement client, not server, behaviors.

An can require client authentication. You can either specify a particular scheme to use for authentication, or you can specify a delegate that determines the scheme to use. You must require some form of authentication to obtain information about the client's identity. For additional information, see the , , and properties.

If you create an using https, you must select a Server Certificate for that listener. Otherwise, an query of this will fail with an unexpected close of the connection.

You can configure Server Certificates and other listener options by using HttpCfg.exe. See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/http/http/httpcfg_exe.asp for more details. The executable is shipped with Windows Server 2003, or can be built from source code available in the Platform SDK.

If you specify multiple authentication schemes for the , the listener will challenge clients in the following order: Negotiate, NTLM, Digest, and then Basic.

Provides a simple, programmatically controlled HTTP protocol listener. This class cannot be inherited.

- Constructor
  2.0.0.0
  4.0.0.0

  Before using the instance returned by this constructor, you must invoke its method.

  Initializes a new instance of the class.

- Method
  2.0.0.0
  4.0.0.0
  System.Void

  This method disposes of all resources held by this listener. Any pending requests are unable to complete.

  After calling this method, you will receive an if you attempt to use this .

  Shuts down the object immediately, discarding all currently queued requests.

- Property
  2.0.0.0
  4.0.0.0
  System.Net.AuthenticationSchemes To be added.

  The uses the specified scheme to authenticate all incoming requests. The and methods return an incoming client request only if the successfully authenticates the request.

  You can interrogate the identity of a successfully authenticated client by using the property.

  If you want an object to use different authentication mechanisms based on characteristics of the requests it receives (for example, the request's or property), you must implement a method that chooses the authentication scheme. For instructions about how to do this, see the property documentation.

  To set this property to enable Digest, NTLM, or Negotiate requires the , .

  Gets or sets the scheme used to authenticate clients.

- Property
  2.0.0.0
  4.0.0.0
  System.Net.AuthenticationSchemeSelector To be added.

  If you want the same authentication protocol to be used for all requests handled by a particular instance of , you do not need to set this property. To specify a protocol to be used for all client requests, use the property.

  If the client has not specified authentication information in its headers, the calls the specified delegate for each unauthenticated incoming request to determine which, if any, protocol to use to authenticate the client. The and methods return an incoming request only if the successfully authenticated the request. If a request cannot be authenticated, the automatically sends back a 401 response. You can get the identity of a successfully authenticated client using the property.

  The ability to delegate the choice of authentication protocol to an application-specific method is useful if you want an instance of to use different authentication protocols depending on the characteristics of the requests it receives (for example, the request's or property).

  To set this property to enable Digest, NTLM, or Negotiate requires the , .

  Gets or sets the delegate called to determine the protocol used to authenticate clients.

- Method
  2.0.0.0
  4.0.0.0
  System.IAsyncResult `` ``

  The method begins an asynchronous (non-blocking) call to receive incoming client requests. Before calling this method, you must call the method and add at least one Uniform Resource Identifier (URI) prefix to listen for by adding the URI strings to the returned by the property.

  The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate.

  This method does not block while the operation completes. To get an incoming request and block until the operation completes, call the method.

  For detailed information about using the asynchronous programming model, see Asynchronous Programming Overview

  Begins asynchronously retrieving an incoming request.

  An object that indicates the status of the asynchronous operation.

  An delegate that references the method to invoke when a client request is available. A user-defined object that contains information about the operation. This object is passed to the delegate when the operation completes.
- Method
  2.0.0.0
  4.0.0.0
  System.Void

  After calling this method, you can no longer use the object. To temporarily pause an object, use the method.

  This method shut downs the object without processing queued requests. Any pending requests are unable to complete.

  Shuts down the .

- Method
  2.0.0.0
  4.0.0.0
  System.Net.HttpListenerContext ``

  The method is called, usually within an application-defined callback method invoked by a delegate, to obtain the object that contains an incoming client request and its associated response. This method completes an operation previously started by calling the method. If the operation has not completed, this method blocks until it does.

  Because calling the method requires the object, this object is typically passed into a callback method by using the state object passed into the method. You can obtain this state object by using the property of the object.

  For detailed information about using the asynchronous programming model, see Asynchronous Programming Overview

  Completes an asynchronous operation to retrieve an incoming client request.

  An object that represents the client request.

  An object that was obtained when the asynchronous operation was started.
- Method
  2.0.0.0
  4.0.0.0
  System.Net.HttpListenerContext

  Before calling this method, you must call the method and add at least one URI prefix to listen for by adding the URI strings to the returned by the property. For a detailed description of prefixes, see the class overview.

  This method blocks while waiting for an incoming request. If you want incoming requests to be processed asynchronously (on separate threads) so that your application does not block, use the method.

  Waits for an incoming request and returns when one is received.

  An object that represents a client request.

- Method
  4.0.0.0
  System.Threading.Tasks.Task<System.Net.HttpListenerContext>

  This operation will not block. The returned object will complete when the incoming request has been received.

  Before calling this method, you must call the method and add at least one URI prefix to listen for by adding the URI strings to the returned by the property. For a detailed description of prefixes, see the class overview.

  Waits for an incoming request as an asynchronous operation.

  Returns .

  The task object representing the asynchronous operation. The property on the task object returns an object that represents a client request.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  Set this property to true if your application does not require that a response is successfully sent to each client.

  Gets or sets a value that specifies whether your application receives exceptions that occur when an sends the response to the client.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  To start an , call the method.

  Gets a value that indicates whether has been started.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  This class is available only on computers running the Windows XP SP2 or Windows Server 2003 operating systems.

  Gets a value that indicates whether can be used with the current operating system.

- Property
  2.0.0.0
  4.0.0.0
  System.Net.HttpListenerPrefixCollection To be added.

  The prefixes are in canonical form. For a detailed description of prefixes, see the class overview.

  Gets the Uniform Resource Identifier (URI) prefixes handled by this object.

- Property
  2.0.0.0
  4.0.0.0
  System.String To be added.

  Servers use realms to partition protected resources; each partition can have its own authentication scheme and/or authorization database. Realms are used only for basic and digest authentication. After a client successfully authenticates, the authentication is valid for all resources in a given realm. For a detailed description of realms, see RFC 2617 at http://www.ietf.org.

  An instance of has only one associated realm.

  Gets or sets the realm, or resource partition, associated with this object.

- Method
  2.0.0.0
  4.0.0.0
  System.Void

  This method must be called before you call the or method.

  After you have started an object, you can use the method to stop it.

  If this listener instance uses https, you must install and select a Server Certificate. Otherwise, an query of this will fail with an unexpected close of the connection. You can configure Server Certificates and other listener options by using HttpCfg.exe. See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/http/http/httpcfg_exe.asp for more details.

  Allows this instance to receive incoming requests.

- Method
  2.0.0.0
  4.0.0.0
  System.Void

  If this instance is already stopped, calling this method has no effect.

  After you have stopped an object, you can use the method to restart it.

  Causes this instance to stop receiving incoming requests.

- Method
  2.0.0.0
  4.0.0.0
  System.Void

  Applications should use the method instead of calling this method.

  Releases the resources held by this object.

- Property
  2.0.0.0
  4.0.0.0
  System.MonoTODO("Support for NTLM needs some loving.")
  System.Boolean To be added.

  When this property is set to true and the first request over a particular TCP connection is authenticated using NTLM, subsequent requests over the same TCP connection are processed using the authentication information () of the initial request.

  This property has no effect when NTLM is not the authentication protocol. When Negotiate is specified as the authentication protocol, this property has an effect only if NTLM is the actual protocol used for authentication.

  While setting this property to true increases performance because the does not send additional NTLM authentication challenges, there is a security risk in not requiring all requests to provide authentication information. You must determine whether the increase in performance is worth this risk.

  Gets or sets a value that controls whether, when NTLM is used, additional requests using the same Transmission Control Protocol (TCP) connection are required to authenticate.