88dcc20001423e75f40a4f31b1fdc97416ff5d67
[platform/upstream/grpc.git] / src / objective-c / GRPCClient / GRPCCallLegacy.h
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