1 /* 2 * 3 * Copyright 2019 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 #import <RxLibrary/GRXWriter.h> 20 #import "GRPCTypes.h" 21 22 #pragma clang diagnostic push 23 #pragma clang diagnostic ignored "-Wnullability-completeness" 24 25 /** 26 * This is the legacy interface of this gRPC library. This API is deprecated and users should use 27 * GRPCCall2 in GRPCCall.h. This API exists solely for the purpose of backwards compatibility. 28 * Represents a single gRPC remote call. 29 */ 30 @interface GRPCCall : GRXWriter 31 32 - (instancetype)init NS_UNAVAILABLE; 33 34 /** 35 * The container of the request headers of an RPC conforms to this protocol, which is a subset of 36 * NSMutableDictionary's interface. It will become a NSMutableDictionary later on. 37 * The keys of this container are the header names, which per the HTTP standard are case- 38 * insensitive. They are stored in lowercase (which is how HTTP/2 mandates them on the wire), and 39 * can only consist of ASCII characters. 40 * A header value is a NSString object (with only ASCII characters), unless the header name has the 41 * suffix "-bin", in which case the value has to be a NSData object. 42 */ 43 /** 44 * These HTTP headers will be passed to the server as part of this call. Each HTTP header is a 45 * name-value pair with string names and either string or binary values. 46 * 47 * The passed dictionary has to use NSString keys, corresponding to the header names. The value 48 * associated to each can be a NSString object or a NSData object. E.g.: 49 * 50 * call.requestHeaders = @{@"authorization": @"Bearer ..."}; 51 * 52 * call.requestHeaders[@"my-header-bin"] = someData; 53 * 54 * After the call is started, trying to modify this property is an error. 55 * 56 * The property is initialized to an empty NSMutableDictionary. 57 */ 58 @property(atomic, readonly) NSMutableDictionary *requestHeaders; 59 60 /** 61 * This dictionary is populated with the HTTP headers received from the server. This happens before 62 * any response message is received from the server. It has the same structure as the request 63 * headers dictionary: Keys are NSString header names; names ending with the suffix "-bin" have a 64 * NSData value; the others have a NSString value. 65 * 66 * The value of this property is nil until all response headers are received, and will change before 67 * any of -writeValue: or -writesFinishedWithError: are sent to the writeable. 68 */ 69 @property(atomic, readonly) NSDictionary *responseHeaders; 70 71 /** 72 * Same as responseHeaders, but populated with the HTTP trailers received from the server before the 73 * call finishes. 74 * 75 * The value of this property is nil until all response trailers are received, and will change 76 * before -writesFinishedWithError: is sent to the writeable. 77 */ 78 @property(atomic, readonly) NSDictionary *responseTrailers; 79 80 /** 81 * The request writer has to write NSData objects into the provided Writeable. The server will 82 * receive each of those separately and in order as distinct messages. 83 * A gRPC call might not complete until the request writer finishes. On the other hand, the request 84 * finishing doesn't necessarily make the call to finish, as the server might continue sending 85 * messages to the response side of the call indefinitely (depending on the semantics of the 86 * specific remote method called). 87 * To finish a call right away, invoke cancel. 88 * host parameter should not contain the scheme (http:// or https://), only the name or IP addr 89 * and the port number, for example @"localhost:5050". 90 */ 91 - (instancetype)initWithHost:(NSString *)host 92 path:(NSString *)path 93 requestsWriter:(GRXWriter *)requestWriter; 94 95 /** 96 * Finishes the request side of this call, notifies the server that the RPC should be cancelled, and 97 * finishes the response side of the call with an error of code CANCELED. 98 */ 99 - (void)cancel; 100 101 /** 102 * The following methods are deprecated. 103 */ 104 + (void)setCallSafety:(GRPCCallSafety)callSafety host:(NSString *)host path:(NSString *)path; 105 @property(atomic, copy, readwrite) NSString *serverName; 106 @property NSTimeInterval timeout; 107 - (void)setResponseDispatchQueue:(dispatch_queue_t)queue; 108 109 @end 110 111 #pragma mark Backwards compatibiity 112 113 /** This protocol is kept for backwards compatibility with existing code. */ 114 DEPRECATED_MSG_ATTRIBUTE("Use NSDictionary or NSMutableDictionary instead.") 115 @protocol GRPCRequestHeaders <NSObject> 116 @property(nonatomic, readonly) NSUInteger count; 117 118 - (id)objectForKeyedSubscript:(id)key; 119 - (void)setObject:(id)obj forKeyedSubscript:(id)key; 120 121 - (void)removeAllObjects; 122 - (void)removeObjectForKey:(id)key; 123 @end 124 125 #pragma clang diagnostic push 126 #pragma clang diagnostic ignored "-Wdeprecated" 127 /** This is only needed for backwards-compatibility. */ 128 @interface NSMutableDictionary (GRPCRequestHeaders) <GRPCRequestHeaders> 129 @end 130 #pragma clang diagnostic pop 131 #pragma clang diagnostic pop 132