New API for GRPCCall

1 files changed, 111 insertions, 34 deletions

diff --git a/src/objective-c/GRPCClient/GRPCCall.h b/src/objective-c/GRPCClient/GRPCCall.h
index e0ef8b1391..3f6ec75c04 100644
--- a/src/objective-c/GRPCClient/GRPCCall.h
+++ b/src/objective-c/GRPCClient/GRPCCall.h
@@ -37,6 +37,10 @@
 
 #include <AvailabilityMacros.h>
 
+#include "GRPCCallOptions.h"
+
+@class GRPCCallOptions;
+
 #pragma mark gRPC errors
 
 /** Domain of NSError objects produced by gRPC. */
@@ -140,42 +144,123 @@ typedef NS_ENUM(NSUInteger, GRPCErrorCode) {
 };
 
 /**
- * Safety remark of a gRPC method as defined in RFC 2616 Section 9.1
- */
-typedef NS_ENUM(NSUInteger, GRPCCallSafety) {
-  /** Signal that there is no guarantees on how the call affects the server state. */
-  GRPCCallSafetyDefault = 0,
-  /** Signal that the call is idempotent. gRPC is free to use PUT verb. */
-  GRPCCallSafetyIdempotentRequest = 1,
-  /** Signal that the call is cacheable and will not affect server state. gRPC is free to use GET
-     verb. */
-  GRPCCallSafetyCacheableRequest = 2,
-};
-
-/**
  * Keys used in |NSError|'s |userInfo| dictionary to store the response headers and trailers sent by
  * the server.
  */
 extern id const kGRPCHeadersKey;
 extern id const kGRPCTrailersKey;
 
+/** An object can implement this protocol to receive responses from server from a call. */
+@protocol GRPCResponseHandler
+@optional
+/** Issued when initial metadata is received from the server. */
+- (void)receivedInitialMetadata:(NSDictionary *)initialMetadata;
+/**
+ * Issued when a message is received from the server. The message may be raw data from the server
+ * (when using \a GRPCCall2 directly) or deserialized proto object (when using \a ProtoRPC).
+ */
+- (void)receivedMessage:(id)message;
+/**
+ * Issued when a call finished. If the call finished successfully, \a error is nil and \a
+ * trainingMetadata consists any trailing metadata received from the server. Otherwise, \a error
+ * is non-nil and contains the corresponding error information, including gRPC error codes and
+ * error descriptions.
+ */
+- (void)closedWithTrailingMetadata:(NSDictionary *)trailingMetadata error:(NSError *)error;
+
+/**
+ * All the responses must be issued to a user-provided dispatch queue. This property specifies the
+ * dispatch queue to be used for issuing the notifications.
+ */
+@property(atomic, readonly) dispatch_queue_t dispatchQueue;
+
+@end
+
+/**
+ * Call related parameters. These parameters are automatically specified by Protobuf. If directly
+ * using the \a GRPCCall2 class, users should specify these parameters manually.
+ */
+@interface GRPCRequestOptions : NSObject<NSCopying>
+
+- (instancetype)init NS_UNAVAILABLE;
+
+/** Initialize with all properties. */
+- (instancetype)initWithHost:(NSString *)host path:(NSString *)path safety:(GRPCCallSafety)safety;
+
+/** The host serving the RPC service. */
+@property(copy, readonly) NSString *host;
+/** The path to the RPC call. */
+@property(copy, readonly) NSString *path;
+/**
+ * Specify whether the call is idempotent or cachable. gRPC may select different HTTP verbs for the
+ * call based on this information.
+ */
+@property(readonly) GRPCCallSafety safety;
+
+@end
+
 #pragma mark GRPCCall
 
-/** Represents a single gRPC remote call. */
-@interface GRPCCall : GRXWriter
+/**
+ * A \a GRPCCall2 object represents an RPC call.
+ */
+@interface GRPCCall2 : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
 
 /**
- * The authority for the RPC. If nil, the default authority will be used. This property must be nil
- * when Cronet transport is enabled.
+ * Designated initializer for a call.
+ * \param requestOptions Protobuf generated parameters for the call.
+ * \param handler The object to which responses should be issed.
+ * \param callOptions Options for the call.
  */
-@property(atomic, copy, readwrite) NSString *serverName;
+- (instancetype)initWithRequestOptions:(GRPCRequestOptions *)requestOptions
+                               handler:(id<GRPCResponseHandler>)handler
+                           callOptions:(GRPCCallOptions *)callOptions NS_DESIGNATED_INITIALIZER;
+/**
+ * Convevience initializer for a call that uses default call options.
+ */
+- (instancetype)initWithRequestOptions:(GRPCRequestOptions *)requestOptions
+                               handler:(id<GRPCResponseHandler>)handler;
 
 /**
- * The timeout for the RPC call in seconds. If set to 0, the call will not timeout. If set to
- * positive, the gRPC call returns with status GRPCErrorCodeDeadlineExceeded if it is not completed
- * within \a timeout seconds. A negative value is not allowed.
+ * Starts the call. Can only be called once.
  */
-@property NSTimeInterval timeout;
+- (void)start;
+
+/**
+ * Cancel the request of this call at best effort; notifies the server that the RPC should be
+ * cancelled, and issue callback to the user with an error code CANCELED if the call is not
+ * finished.
+ */
+- (void)cancel;
+
+/**
+ * Send a message to the server. Data are sent as raw bytes in gRPC message frames.
+ */
+- (void)writeWithData:(NSData *)data;
+
+/**
+ * Finish the RPC request and half-close the call. The server may still send messages and/or
+ * trailers to the client.
+ */ -(void)finish;
+
+/**
+ * Get a copy of the original call options.
+ */
+@property(readonly, copy) GRPCCallOptions *callOptions;
+
+/** Get a copy of the original request options. */
+@property(readonly, copy) GRPCRequestOptions *requestOptions;
+
+@end
+
+/**
+ * This interface is deprecated. Please use \a GRPCcall2.
+ *
+ * Represents a single gRPC remote call.
+ */
+@interface GRPCCall : GRXWriter
 
 /**
  * The container of the request headers of an RPC conforms to this protocol, which is a subset of
@@ -236,7 +321,7 @@ extern id const kGRPCTrailersKey;
  */
 - (instancetype)initWithHost:(NSString *)host
                         path:(NSString *)path
-              requestsWriter:(GRXWriter *)requestsWriter NS_DESIGNATED_INITIALIZER;
+              requestsWriter:(GRXWriter *)requestWriter;
 
 /**
  * Finishes the request side of this call, notifies the server that the RPC should be cancelled, and
@@ -245,21 +330,13 @@ extern id const kGRPCTrailersKey;
 - (void)cancel;
 
 /**
- * Set the call flag for a specific host path.
- *
- * Host parameter should not contain the scheme (http:// or https://), only the name or IP addr
- * and the port number, for example @"localhost:5050".
+ * The following methods are deprecated.
  */
 + (void)setCallSafety:(GRPCCallSafety)callSafety host:(NSString *)host path:(NSString *)path;
-
-/**
- * Set the dispatch queue to be used for callbacks.
- *
- * This configuration is only effective before the call starts.
- */
+@property(atomic, copy, readwrite) NSString *serverName;
+@property NSTimeInterval timeout;
 - (void)setResponseDispatchQueue:(dispatch_queue_t)queue;
 
-// TODO(jcanizales): Let specify a deadline. As a category of GRXWriter?
 @end
 
 #pragma mark Backwards compatibiity