[Cronet] Integrate CrNet functionality into Cronet on iOS.

components/cronet/ios/Cronet.h

 // 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 "cronet_c_for_grpc.h"
 
+// A block, that takes a request, and returns YES if the request should
+// be handled.
+typedef BOOL (^RequestFilterBlock)(NSURLRequest* request);
+
 // Interface for installing Cronet.
 CRONET_EXPORT
 @interface Cronet : NSObject
 
 // 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;
 
 // Adds hint that host supports QUIC on altPort. This method only has any effect
 // before |start| is called.
 + (void)addQuicHint:(NSString*)host port:(int)port altPort:(int)altPort;
 
-// |userAgent| is expected to be of the form Product/Version.
-// Example: Foo/3.0.0.0
+// |userAgent| is expected to be the user agent value sent to remote.

[kapishnikov, 2016/10/19 18:28:53]

Not sure about the use of 'expected' here. Maybe better: "Sets the user-agent
string to be sent with the requests"?

[mef, 2016/10/19 20:12:58]

Done.

+// 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

[kapishnikov, 2016/10/19 18:28:53]

partial -> |partial|

[mef, 2016/10/19 20:12:58]

Done.

+// 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)setPartialUserAgent:(NSString*)userAgent;
++ (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;
 
+// Set the block used to determine whether or not Cronet should handle the

[kapishnikov, 2016/10/19 18:28:53]

Set->Sets

[mef, 2016/10/19 20:12:58]

Done.

+// request. If this is not set, Cronet will handle all requests. Cronet retains

[kapishnikov, 2016/10/19 18:28:53]

this->'the block'

[mef, 2016/10/19 20:12:58]

Done.

+// 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 NSURLConnection and NSURLRequests issued by the app,

[kapishnikov, 2016/10/19 18:28:53]

Since
1) NSURLRequest is merely a value objects that represents a URL and
2) NSURLSession is not part of NSURLConnection,
I think it is more correct to say that: "Once registered, Cronet intercepts and
handles all requests made through  NSURLConnection and shared NSURLSession.'

[mef, 2016/10/19 20:12:58]

Done.

+// including requests done through 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;
+
 // Starts net-internals logging to a file named |fileName| in the application
 // temporary 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.
 + (void)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;
 
 // Get a pointer to global instance of cronet_engine for GRPC C API.
 + (cronet_engine*)getGlobalEngine;
 
+// Returns differences in metrics collected by Cronet since the last call to
+// getGlobalMetricsDeltas, serialized as a
+// <a href=https://developers.google.com/protocol-buffers>protobuf</a>.

[kapishnikov, 2016/10/19 18:28:53]

Xcode uses markup to specify links: see
https://developer.apple.com/library/content/documentation/Xcode/Reference/xco...

[mef, 2016/10/19 20:12:58]

Done.

+//
+// 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.
+// differences in metrics collected by Cronet, since the last call

[kapishnikov, 2016/10/19 18:28:53]

I think this line should not be here.

[mef, 2016/10/19 20:12:58]

Done.

++ (NSData*)getGlobalMetricsDeltas;
+
+// Sets Host Resolver Rules for testing.
+// This method only has any effect before |start| is 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;

[kapishnikov, 2016/10/19 18:28:53]

I remember we discussed moving these methods to TestCronet class that would
inherit from Cronet class. If this idea is viable, maybe we should do it in a
next CL.

[mef, 2016/10/19 20:12:58]

Yes, I would like to revisit that idea if we can create two frameworks.

+
 @end