AndroidMessageHandler Class

Definition

Namespace:

Xamarin.Android.Net

Assembly:

Mono.Android.dll

A custom implementation of HttpMessageHandler which internally uses HttpURLConnection (or its HTTPS incarnation) to send HTTP requests.

public class AndroidMessageHandler : System.Net.Http.HttpMessageHandler

type AndroidMessageHandler = class
    inherit HttpMessageHandler

Inheritance

HttpMessageHandler

AndroidMessageHandler

Remarks

Instance of this class is used to configure HttpClient instance in the following way:

<example> var handler = new AndroidMessageHandler { UseCookies = true, AutomaticDecompression = DecompressionMethods.Deflate | DecompressionMethods.GZip, };

var httpClient = new HttpClient (handler); var response = httpClient.GetAsync ("http://example.com")?.Result as AndroidHttpResponseMessage; </example>

The class supports pre-authentication of requests albeit in a slightly "manual" way. Namely, whenever a request to a server requiring authentication is made and no authentication credentials are provided in the PreAuthenticationData property (which is usually the case on the first request), the RequestNeedsAuthorization property will return true and the RequestedAuthentication property will contain all the authentication information gathered from the server. The application must then fill in the blanks (i.e. the credentials) and re-send the request configured to perform pre-authentication. The reason for this manual process is that the underlying Java HTTP client API supports only a single, VM-wide, authentication handler which cannot be configured to handle credentials for several requests. AndroidMessageHandler, therefore, implements the authentication in managed .NET code. Message handler supports both Basic and Digest authentication. If an authentication scheme that's not supported by AndroidMessageHandler is requested by the server, the application can provide its own authentication module (AuthenticationData, PreAuthenticationData) to handle the protocol authorization.

AndroidMessageHandler also supports requests to servers with "invalid" (e.g. self-signed) SSL certificates. Since this process is a bit convoluted using the Java APIs, AndroidMessageHandler defines two ways to handle the situation. First, easier, is to store the necessary certificates (either CA or server certificates) in the TrustedCerts collection or, after deriving a custom class from AndroidMessageHandler, by overriding one or more methods provided for this purpose (ConfigureTrustManagerFactory(KeyStore), ConfigureKeyManagerFactory(KeyStore) and ConfigureKeyStore(KeyStore)). The former method should be sufficient for most use cases, the latter allows the application to provide fully customized key store, trust manager and key manager, if needed. Note that the instance of AndroidMessageHandler configured to accept an "invalid" certificate from the particular server will most likely fail to validate certificates from other servers (even if they use a certificate with a fully validated trust chain) unless you store the CA certificates from your Android system in TrustedCerts along with the self-signed certificate(s).

Constructors

Name	Description
AndroidMessageHandler()

Properties

Name	Description
AllowAutoRedirect	Gets or sets a value that indicates whether the handler should follow redirection responses. The default value is true.
AutomaticDecompression	Gets or sets the type of decompression method used by the handler for automatic decompression of the HTTP content response.
CheckCertificateRevocationList	Gets or sets a value that indicates whether the certificate revocation list is checked during validation. The default value is false.
ClientCertificateOptions	Gets or sets a value that indicates how client certificates are provided. The default value is Manual.
ClientCertificates	Gets or sets the collection of client certificates used by the handler to authenticate the client.
ConnectTimeout	Specifies the connect timeout The native Java client supports two separate timeouts - one for reading from the connection (ReadTimeout) and another for establishing the connection. This property sets the value of the latter timeout, unless it is set to Zero in which case the native Java client defaults are used. The default value is 24 hours, same as ReadTimeout.
CookieContainer	Gets or sets the cookie container used to store server cookies.
Credentials	Gets or sets authentication information used by this handler.
DefaultProxyCredentials	Gets or sets the credentials to use when authenticating with the proxy.
MaxAutomaticRedirections	Gets or sets the maximum number of allowed HTTP redirects. The default value is 50.
MaxConnectionsPerServer	Gets or sets the maximum number of concurrent connections allowed per server. The default value is MaxValue.
MaxResponseHeadersLength	Gets or sets the maximum length, in kilobytes (1024 bytes), of the response headers. The default value is 64 KB.
PreAuthenticate	Gets or sets a value that indicates whether the handler sends an Authorization header with the request. The default value is false.
PreAuthenticationData	Gets or sets the pre authentication data for the request. This property must be set by the application before the request is made. Generally the value can be taken from RequestedAuthentication after the initial request, without any authentication data, receives the authorization request from the server. The application must then store credentials in instance of AuthenticationData and assign the instance to this property before retrying the request. The property is never set by AndroidMessageHandler.
Properties	Gets or sets a custom property collection for the handler. This can be used to pass additional metadata or configuration to the underlying transport.
Proxy	Gets or sets the proxy information used by the handler.
ProxyAuthenticationRequested	Server authentication response indicates that the request to authorize comes from a proxy if this property is true. All the instances of AuthenticationData stored in the RequestedAuthentication property will have their UseProxyAuthentication preset to the same value as this property.
ReadTimeout	Specifies the connection read timeout. Since there's no way for the handler to access Timeout directly, this property should be set by the calling party to the same desired value. Value of this property will be passed to the native Java HTTP client, unless it is set to Zero The default value is 24 hours, much higher than the documented value of Timeout and the same as the value of iOS-specific NSUrlSessionHandler.
RequestedAuthentication	If the website requires authentication, this property will contain data about each scheme supported by the server after the response. Note that unauthorized request will return a valid response - you need to check the status code and and (re)configure AndroidMessageHandler instance accordingly by providing both the credentials and the authentication scheme by setting the PreAuthenticationData property. If AndroidMessageHandler is not able to detect the kind of authentication scheme it will store an instance of AuthenticationData with its Scheme property set to AuthenticationScheme.Unsupported and the application will be responsible for providing an instance of IAndroidAuthenticationModule which handles this kind of authorization scheme (AuthModule
RequestNeedsAuthorization	If true then the server requested authorization and the application must use information found in RequestedAuthentication to set the value of PreAuthenticationData
ServerCertificateCustomValidationCallback	Gets or sets a callback to validate the server certificate. When set, the callback is invoked during the TLS handshake to perform custom certificate validation.
SslProtocols	Gets or sets the TLS/SSL protocols used by the handler. The default value is Tls13 | Tls12 on Android API 29+, or Tls12 on earlier versions.
SupportsAutomaticDecompression	Gets a value indicating whether the handler supports automatic response content decompression. Always returns true for AndroidMessageHandler.
SupportsProxy	Gets a value indicating whether the handler supports proxy settings. Always returns true for AndroidMessageHandler.
SupportsRedirectConfiguration	Gets a value indicating whether the handler supports configuration settings for the AllowAutoRedirect and MaxAutomaticRedirections properties. Always returns true for AndroidMessageHandler.
TrustedCerts	If the request is to the server protected with a self-signed (or otherwise untrusted) SSL certificate, the request will fail security chain verification unless the application provides either the CA certificate of the entity which issued the server's certificate or, alternatively, provides the server public key. Whichever the case, the certificate(s) must be stored in this property in order for AndroidMessageHandler to configure the request to accept the server certificate. AndroidMessageHandler uses a custom KeyStore and TrustManagerFactory to configure the connection. If, however, the application requires finer control over the SSL configuration (e.g. it implements its own TrustManager) then it should leave this property empty and instead derive a custom class from AndroidMessageHandler and override, as needed, the ConfigureTrustManagerFactory(KeyStore), ConfigureKeyManagerFactory(KeyStore) and ConfigureKeyStore(KeyStore) methods instead
UseCookies	Gets or sets a value that indicates whether the handler uses the CookieContainer property to store server cookies and uses these cookies when sending requests. The default value is true.
UseProxy	Gets or sets a value that indicates whether the handler uses a proxy for requests. The default value is true.

Methods

Name	Description
AssertSelf()
ConfigureCustomSSLSocketFactory(HttpsURLConnection)	Configure and return a custom SSLSocketFactory for the passed HTTPS connection. If the class overriding the method returns anything but the default null, the SSL setup code will not call the ConfigureKeyManagerFactory(KeyStore) nor the ConfigureTrustManagerFactory(KeyStore) methods used to configure a custom trust manager which is then used to create a default socket factory. Deriving class must perform all the key manager and trust manager configuration to ensure proper operation of the returned socket factory.
ConfigureKeyManagerFactory(KeyStore)	Create and configure an instance of KeyManagerFactory. The keyStore parameter is set to the return value of the ConfigureKeyStore(KeyStore) method, so it might be null if the application overrode the method and provided no key store. It will not be null when the default implementation is used. The application can return null here since KeyManagerFactory is not required for the custom SSL configuration, but it might be used by the application to implement a more advanced mechanism of key management.
ConfigureKeyStore(KeyStore)	Configures the key store. The keyStore parameter is set to instance of KeyStore created using the DefaultType type and with populated with certificates provided in the TrustedCerts property. AndroidMessageHandler implementation simply returns the instance passed in the keyStore parameter
ConfigureTrustManagerFactory(KeyStore)	Create and configure an instance of TrustManagerFactory. The keyStore parameter is set to the return value of the ConfigureKeyStore(KeyStore) method, so it might be null if the application overrode the method and provided no key store. It will not be null when the default implementation is used. The application can return null from this method in which case AndroidMessageHandler will create its own instance of the trust manager factory provided that the TrustCerts list contains at least one valid certificate. If there are no valid certificates and this method returns null, no custom trust manager will be created since that would make all the HTTPS requests fail.
Dispose(Boolean)
GetJavaProxy(Uri, CancellationToken)
GetSSLHostnameVerifier(HttpsURLConnection)	Returns a custom host name verifier for a HTTPS connection. By default it returns null and thus the connection uses whatever host name verification mechanism the operating system defaults to. Override in your class to define custom host name verification behavior. The overriding class should not set the HttpsURLConnection.HostnameVerifier property directly on the passed connection
SendAsync(HttpRequestMessage, CancellationToken)	Creates, configures and processes an asynchronous request to the indicated resource.
SetupRequest(HttpRequestMessage, HttpURLConnection)	Configure the HttpURLConnection before the request is sent. This method is meant to be overriden by applications which need to perform some extra configuration steps on the connection. It is called with all the request headers set, pre-authentication performed (if applicable) but before the request body is set (e.g. for POST requests). The default implementation in AndroidMessageHandler does nothing.
WriteRequestContentToOutput(HttpRequestMessage, HttpURLConnection, CancellationToken)