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