IHttpFilter IHttpFilter IHttpFilter IHttpFilter Interface

Definition

An interface used to implement custom filters for an HttpClient instance.

public : interface IHttpFilterpublic interface IHttpFilterPublic Interface IHttpFilter// You can use this interface in JavaScript.
Inheritance
IClosableIDisposableIDisposableIDisposable
IHttpFilterIHttpFilterIHttpFilterIHttpFilter
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited methods

Remarks

The IHttpFilter interface is used to develop custom filters for an HttpClient instance. Custom filters are implemented in the SendRequestAsync method on their IHttpFilter interface.

Classes in the Windows.Web.Http namespace support the use of filters based on the classes in the Windows.Web.Http.Filters namespace. The HttpClient class in the Windows.Web.Http namespace provides a base class for sending HTTP requests and receiving HTTP responses. Filters provide a handler mechanism to help with common HTTP service issues. Simple filters can be chained together in a sequence to handle more complex HTTP service issues.

An HTTP filter is a black box which takes an HTTP request message and produces an HTTP response message. How the filter gets an HTTP response is determined by the filter developer. An app can create the response immediately, it can send the request over TCP to a server, it can even send multiple requests to a server (or to more than one server) before it generates a response message. Since it is unspecified how a filter gets to a response message, a filter can pass the request message to another filter (called the inner filter), thus delegating the creation of a response message to the inner filter.

Filters commonly add or change headers, handle authorization (possibly using the WebAuthenticationBroker ), or allow or disallow a request based on network conditions. Filters usually make changes and then pass the request to an inner filter, which is typically set when a filter is constructed.

This approach allows filters to be only responsible for a specific aspect of an HTTP request execution and delegate other aspects to other filters. A filter can implement caching, authentication, redirects, cookies, actual communication with the server, or a combination of these. The bottom-most (base) filter will usually be the one that does actual communication with the network.

Developers can write their own filters for site-specific issues. An example is that some site uses the 503 (Service Unavailable) response to indicate that the request should be retried. A custom filter could be implemented to detect this behavior and respond accordingly. Another example could deal with methods in the Windows.Web.Http and Windows.Web.Http.Filters namespaces that send data over the network throw exceptions due to network failures (network connectivity is lost in airplane mode, for example). A custom filter could change catch network exception and convert them to an HTTP status code.

Methods

SendRequestAsync(HttpRequestMessage) SendRequestAsync(HttpRequestMessage) SendRequestAsync(HttpRequestMessage) SendRequestAsync(HttpRequestMessage)

Send an HTTP request on the IHttpFilter instance as an asynchronous operation.

public : IAsyncOperationWithProgress<HttpResponseMessage, HttpProgress> SendRequestAsync(HttpRequestMessage request)public IAsyncOperationWithProgress<HttpResponseMessage, HttpProgress> SendRequestAsync(HttpRequestMessage request)Public Function SendRequestAsync(request As HttpRequestMessage) As IAsyncOperationWithProgress( Of HttpResponseMessage, HttpProgress )// You can use this method in JavaScript.
Parameters
Returns

Remarks

Custom filters are implemented in the SendRequestAsync method on their IHttpFilter interface.

Classes in the Windows.Web.Http namespace support the use of filters based on the classes in the Windows.Web.Http.Filters namespace. The HttpClient class in the Windows.Web.Http namespace provides a base class for sending HTTP requests and receiving HTTP responses. Filters provide a handler mechanism to help with common HTTP service issues. Simple filters can be chained together in a sequence to handle more complex HTTP service issues.

An HTTP filter is a black box which takes an HTTP request message and produces an HTTP response message. How the filter gets an HTTP response is determined by the filter developer. An app can create the response immediately, it can send the request over TCP to a server, it can even send multiple requests to a server (or to more than one server) before it generates a response message. Since it is unspecified how a filter gets to a response message, a filter can pass the request message to another filter (called the inner filter), thus delegating the creation of a response message to the inner filter.

Filters commonly add or change headers, handle authorization (possibly using the WebAuthenticationBroker ), or allow or disallow a request based on network conditions. Filters usually make changes and then pass the request to an inner filter, which is typically set when a filter is constructed.

This approach allows filters to be only responsible for a specific aspect of an HTTP request execution and delegate other aspects to other filters. A filter can implement caching, authentication, redirects, cookies, actual communication with the server, or a combination of these. The bottom-most (base) filter will usually be the one that does actual communication with the network.

Below are some exceptions that this function throws.

E_INVALIDARG

The request parameter was a null reference (Nothing in Visual Basic).

E_ILLEGAL_METHOD_CALL

The request message was already sent by the IHttpFilter instance.

See Also

  • IClosable IDisposable IDisposable IDisposable