| // Copyright 2016 The Chromium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| #import <Foundation/Foundation.h> |
| |
| #include "bidirectional_stream_c.h" |
| #include "cronet.idl_c.h" |
| #include "cronet_c.h" |
| #include "cronet_export.h" |
| |
| // Type of HTTP cache; public interface to private implementation defined in |
| // URLRequestContextConfig class. |
| typedef NS_ENUM(NSInteger, CRNHttpCacheType) { |
| // Disabled HTTP cache. Some data may still be temporarily stored in memory. |
| CRNHttpCacheTypeDisabled, |
| // Enable on-disk HTTP cache, including HTTP data. |
| CRNHttpCacheTypeDisk, |
| // Enable in-memory cache, including HTTP data. |
| CRNHttpCacheTypeMemory, |
| }; |
| |
| /// Cronet error domain name. |
| FOUNDATION_EXPORT GRPC_SUPPORT_EXPORT NSString* const CRNCronetErrorDomain; |
| |
| /// Enum of Cronet NSError codes. |
| NS_ENUM(NSInteger){ |
| CRNErrorInvalidArgument = 1001, CRNErrorUnsupportedConfig = 1002, |
| }; |
| |
| /// The corresponding value is a String object that contains the name of |
| /// an invalid argument inside the NSError userInfo dictionary. |
| FOUNDATION_EXPORT GRPC_SUPPORT_EXPORT NSString* const CRNInvalidArgumentKey; |
| |
| // A block, that takes a request, and returns YES if the request should |
| // be handled. |
| typedef BOOL (^RequestFilterBlock)(NSURLRequest* request); |
| |
| // Interface for installing Cronet. |
| // TODO(gcasto): Should this macro be separate from the one defined in |
| // bidirectional_stream_c.h? |
| GRPC_SUPPORT_EXPORT |
| @interface Cronet : NSObject |
| |
| // Sets the HTTP Accept-Language header. This method only has any effect before |
| // |start| is called. |
| + (void)setAcceptLanguages:(NSString*)acceptLanguages; |
| |
| // Sets whether HTTP/2 should be supported by CronetEngine. This method only has |
| // any effect before |start| is called. |
| + (void)setHttp2Enabled:(BOOL)http2Enabled; |
| |
| // Sets whether QUIC should be supported by CronetEngine. This method only has |
| // any effect before |start| is called. |
| + (void)setQuicEnabled:(BOOL)quicEnabled; |
| |
| // Sets whether Brotli should be supported by CronetEngine. This method only has |
| // any effect before |start| is called. |
| + (void)setBrotliEnabled:(BOOL)brotliEnabled; |
| |
| // Sets whether Metrics should be collected by CronetEngine. This method only |
| // has any effect before |start| is called. |
| + (void)setMetricsEnabled:(BOOL)metricsEnabled; |
| |
| // Set HTTP Cache type to be used by CronetEngine. This method only has any |
| // effect before |start| is called. See HttpCacheType enum for available |
| // options. |
| + (void)setHttpCacheType:(CRNHttpCacheType)httpCacheType; |
| |
| // Adds hint that host supports QUIC on altPort. This method only has any effect |
| // before |start| is called. Returns NO if it fails to add hint (because the |
| // host is invalid). |
| + (BOOL)addQuicHint:(NSString*)host port:(int)port altPort:(int)altPort; |
| |
| // Set experimental Cronet options. Argument is a JSON string; see |
| // |URLRequestContextConfig| for more details. This method only has |
| // any effect before |start| is called. |
| + (void)setExperimentalOptions:(NSString*)experimentalOptions; |
| |
| // Sets the User-Agent request header string to be sent with all requests. |
| // If |partial| is set to YES, then actual user agent value is based on device |
| // model, OS version, and |userAgent| argument. For example "Foo/3.0.0.0" is |
| // sent as "Mozilla/5.0 (iPhone; CPU iPhone OS 9_3 like Mac OS X) |
| // AppleWebKit/601.1 (KHTML, like Gecko) Foo/3.0.0.0 Mobile/15G31 |
| // Safari/601.1.46". |
| // If |partial| is set to NO, then |userAgent| value is complete value sent to |
| // the remote. For Example: "Foo/3.0.0.0" is sent as "Foo/3.0.0.0". |
| // |
| // This method only has any effect before |start| is called. |
| + (void)setUserAgent:(NSString*)userAgent partial:(BOOL)partial; |
| |
| // Sets SSLKEYLogFileName to export SSL key for Wireshark decryption of packet |
| // captures. This method only has any effect before |start| is called. |
| + (void)setSslKeyLogFileName:(NSString*)sslKeyLogFileName; |
| |
| /// Pins a set of public keys for a given host. This method only has any effect |
| /// before |start| is called. By pinning a set of public keys, |pinHashes|, |
| /// communication with |host| is required to authenticate with a certificate |
| /// with a public key from the set of pinned ones. |
| /// An app can pin the public key of the root certificate, any of the |
| /// intermediate certificates or the end-entry certificate. Authentication will |
| /// fail and secure communication will not be established if none of the public |
| /// keys is present in the host's certificate chain, even if the host attempts |
| /// to authenticate with a certificate allowed by the device's trusted store of |
| /// certificates. |
| /// |
| /// Calling this method multiple times with the same host name overrides the |
| /// previously set pins for the host. |
| /// |
| /// More information about the public key pinning can be found in |
| /// [RFC 7469](https://tools.ietf.org/html/rfc7469). |
| /// |
| /// @param host name of the host to which the public keys should be pinned. |
| /// A host that consists only of digits and the dot character |
| /// is treated as invalid. |
| /// @param pinHashes a set of pins. Each pin is the SHA-256 cryptographic |
| /// hash of the DER-encoded ASN.1 representation of the |
| /// Subject Public Key Info (SPKI) of the host's X.509 |
| /// certificate. Although, the method does not mandate the |
| /// presence of the backup pin that can be used if the control |
| /// of the primary private key has been lost, it is highly |
| /// recommended to supply one. |
| /// @param includeSubdomains indicates whether the pinning policy should be |
| /// applied to subdomains of |host|. |
| /// @param expirationDate specifies the expiration date for the pins. |
| /// @param outError on return, if the pin cannot be added, a pointer to an |
| /// error object that encapsulates the reason for the error. |
| /// @return returns |YES| if the pins were added successfully; |NO|, otherwise. |
| + (BOOL)addPublicKeyPinsForHost:(NSString*)host |
| pinHashes:(NSSet<NSData*>*)pinHashes |
| includeSubdomains:(BOOL)includeSubdomains |
| expirationDate:(NSDate*)expirationDate |
| error:(NSError**)outError; |
| |
| // Sets the block used to determine whether or not Cronet should handle the |
| // request. If the block is not set, Cronet will handle all requests. Cronet |
| // retains strong reference to the block, which can be released by calling this |
| // method with nil block. |
| + (void)setRequestFilterBlock:(RequestFilterBlock)block; |
| |
| // Starts CronetEngine. It is recommended to call this method on the application |
| // main thread. If the method is called on any thread other than the main one, |
| // the method will internally try to execute synchronously using the main GCD |
| // queue. Please make sure that the main thread is not blocked by a job |
| // that calls this method; otherwise, a deadlock can occur. |
| + (void)start; |
| |
| // Registers Cronet as HttpProtocol Handler. Once registered, Cronet intercepts |
| // and handles all requests made through NSURLConnection and shared |
| // NSURLSession. |
| // This method must be called after |start|. |
| + (void)registerHttpProtocolHandler; |
| |
| // Unregister Cronet as HttpProtocol Handler. This means that Cronet will stop |
| // intercepting requests, however, it won't tear down the Cronet environment. |
| // This method must be called after |start|. |
| + (void)unregisterHttpProtocolHandler; |
| |
| // Installs Cronet into NSURLSessionConfiguration so that all |
| // NSURLSessions created with this configuration will use the Cronet stack. |
| // Note that all Cronet settings are global and are shared between |
| // all NSURLSessions & NSURLConnections that use the Cronet stack. |
| // This method must be called after |start|. |
| + (void)installIntoSessionConfiguration:(NSURLSessionConfiguration*)config; |
| |
| // Returns the absolute path that startNetLogToFile:fileName will actually |
| // write to. |
| + (NSString*)getNetLogPathForFile:(NSString*)fileName; |
| |
| // Starts net-internals logging to a file named |fileName|. Where fileName is |
| // relative to the application documents directory. |fileName| must not be |
| // empty. Log level is determined by |logBytes| - if YES then LOG_ALL otherwise |
| // LOG_ALL_BUT_BYTES. If the file exists it is truncated before starting. If |
| // actively logging the call is ignored. |
| + (BOOL)startNetLogToFile:(NSString*)fileName logBytes:(BOOL)logBytes; |
| |
| // Stop net-internals logging and flush file to disk. If a logging session is |
| // not in progress this call is ignored. |
| + (void)stopNetLog; |
| |
| // Returns the full user-agent that the stack uses. |
| // This is the exact string servers will see. |
| + (NSString*)getUserAgent; |
| |
| // Sets priority of the network thread. The |priority| should be a |
| // floating point number between 0.0 to 1.0, where 1.0 is highest priority. |
| // This method can be called multiple times before or after |start| method. |
| + (void)setNetworkThreadPriority:(double)priority; |
| |
| // Get a pointer to global instance of cronet_engine for GRPC C API. |
| + (stream_engine*)getGlobalEngine; |
| |
| // Returns differences in metrics collected by Cronet since the last call to |
| // getGlobalMetricsDeltas, serialized as a [protobuf] |
| // (https://developers.google.com/protocol-buffers). |
| // |
| // Cronet starts collecting these metrics after the first call to |
| // getGlobalMetricsDeltras, so the first call returns no |
| // useful data as no metrics have yet been collected. |
| + (NSData*)getGlobalMetricsDeltas; |
| |
| // Sets Host Resolver Rules for testing. |
| // This method must be called after |start| has been called. |
| + (void)setHostResolverRulesForTesting:(NSString*)hostResolverRulesForTesting; |
| |
| // Enables TestCertVerifier which accepts all certificates for testing. |
| // This method only has any effect before |start| is called. |
| + (void)enableTestCertVerifierForTesting; |
| |
| @end |