diff options
Diffstat (limited to 'src/objective-c/GRPCClient/GRPCCall.h')
| -rw-r--r-- | src/objective-c/GRPCClient/GRPCCall.h | 60 |
1 files changed, 36 insertions, 24 deletions
diff --git a/src/objective-c/GRPCClient/GRPCCall.h b/src/objective-c/GRPCClient/GRPCCall.h index 81b409b9ff..33aae10747 100644 --- a/src/objective-c/GRPCClient/GRPCCall.h +++ b/src/objective-c/GRPCClient/GRPCCall.h @@ -31,43 +31,55 @@ * */ +// The gRPC protocol is an RPC protocol on top of HTTP2. +// +// While the most common type of RPC receives only one request message and returns only one response +// message, the protocol also supports RPCs that return multiple individual messages in a streaming +// fashion, RPCs that accept a stream of request messages, or RPCs with both streaming requests and +// responses. +// +// Conceptually, each gRPC call consists of a bidirectional stream of binary messages, with RPCs of +// the "non-streaming type" sending only one message in the corresponding direction (the protocol +// doesn't make any distinction). +// +// Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs can be multiplexed +// transparently on the same TCP connection. + #import <Foundation/Foundation.h> -#import <gRPC/GRXWriter.h> +#import <RxLibrary/GRXWriter.h> @class GRPCMethodName; -@class GRPCCall; +// Key used in |NSError|'s |userInfo| dictionary to store the response metadata sent by the server. +extern id const kGRPCStatusMetadataKey; -// The gRPC protocol is an RPC protocol on top of HTTP2. -// -// While the most common type of RPC receives only one request message and -// returns only one response message, the protocol also supports RPCs that -// return multiple individual messages in a streaming fashion, RPCs that -// accept a stream of request messages, or RPCs with both streaming requests -// and responses. -// -// Conceptually, each gRPC call consists of a bidirectional stream of binary -// messages, with RPCs of the "non-streaming type" sending only one message in -// the corresponding direction (the protocol doesn't make any distinction). -// -// Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs -// can be multiplexed transparently on the same TCP connection. +// Represents a single gRPC remote call. @interface GRPCCall : NSObject<GRXWriter> -// These HTTP2 headers will be passed to the server as part of this call. Each -// HTTP2 header is a name-value pair with string names and either string or binary values. +// These HTTP headers will be passed to the server as part of this call. Each HTTP header is a +// name-value pair with string names and either string or binary values. +// // The passed dictionary has to use NSString keys, corresponding to the header names. The // value associated to each can be a NSString object or a NSData object. E.g.: // -// call.requestMetadata = @{ -// @"Authorization": @"Bearer ...", -// @"SomeBinaryHeader": someData -// }; +// call.requestMetadata = @{@"Authorization": @"Bearer ..."}; +// +// call.requestMetadata[@"SomeBinaryHeader"] = someData; // // After the call is started, modifying this won't have any effect. -@property(nonatomic, readwrite) NSMutableDictionary *requestMetadata; +// +// For convenience, the property is initialized to an empty NSMutableDictionary, and the setter +// accepts (and copies) both mutable and immutable dictionaries. +- (NSMutableDictionary *)requestMetadata; // nonatomic +- (void)setRequestMetadata:(NSDictionary *)requestMetadata; // nonatomic, copy -// This isn't populated until the first event is delivered to the handler. +// This dictionary is populated with the HTTP headers received from the server. When the RPC ends, +// the HTTP trailers received are added to the dictionary too. It has the same structure as the +// request metadata dictionary. +// +// The first time this object calls |writeValue| on the writeable passed to |startWithWriteable|, +// the |responseMetadata| dictionary already contains the response headers. When it calls +// |writesFinishedWithError|, the dictionary contains both the response headers and trailers. @property(atomic, readonly) NSDictionary *responseMetadata; // The request writer has to write NSData objects into the provided Writeable. The server will |