1 /* 2 * 3 * Copyright 2015 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 /** 20 * \mainpage notitle 21 * 22 * The gRPC protocol is an RPC protocol on top of HTTP2. 23 * 24 * While the most common type of RPC receives only one request message and returns only one response 25 * message, the protocol also supports RPCs that return multiple individual messages in a streaming 26 * fashion, RPCs that accept a stream of request messages, or RPCs with both streaming requests and 27 * responses. 28 * 29 * Conceptually, each gRPC call consists of a bidirectional stream of binary messages, with RPCs of 30 * the "non-streaming type" sending only one message in the corresponding direction (the protocol 31 * doesn't make any distinction). 32 * 33 * Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs can be multiplexed 34 * transparently on the same TCP connection. 35 */ 36 37 #import <Foundation/Foundation.h> 38 39 #import "GRPCCallOptions.h" 40 #import "GRPCDispatchable.h" 41 #import "GRPCTypes.h" 42 43 // The legacy header is included for backwards compatibility. Some V1 API users are still using 44 // GRPCCall by importing GRPCCall.h header so we need this import. 45 #import "GRPCCallLegacy.h" 46 47 NS_ASSUME_NONNULL_BEGIN 48 49 /** An object can implement this protocol to receive responses from server from a call. */ 50 @protocol GRPCResponseHandler <NSObject, GRPCDispatchable> 51 52 @optional 53 54 /** 55 * Issued when initial metadata is received from the server. 56 */ 57 - (void)didReceiveInitialMetadata:(nullable NSDictionary *)initialMetadata; 58 59 /** 60 * Issued when a message is received from the server. The message is the raw data received from the 61 * server, with decompression and without proto deserialization. 62 * 63 * <b> This method is deprecated and does not work with interceptors.</b> To use GRPCCall2 interface 64 * with interceptor, please implement GRPCResponseHandler::didReceiveData method and leave this 65 * method unimplemented. If this method and didReceiveRawMessage are implemented at the same time, 66 * implementation of this method will be ignored. 67 */ 68 - (void)didReceiveRawMessage:(nullable NSData *)message; 69 70 /** 71 * Issued when gRPC message is received from the server. The data is always decompressed with gRPC 72 * or HTTP compression algorithm specified in the response header. \p data could be any type as 73 * transport layer and interceptors may modify the type of the data (e.g. a Protobuf interceptor may 74 * consume NSData typed data and issue GPBMessage typed data to user). Users should interpret \p 75 * data according to the configuration of their calls. Interceptor authors should not assume the 76 * type of \p data unless an agreement is made on how it should be used in a particular call 77 * setting. 78 */ 79 - (void)didReceiveData:(id)data; 80 81 /** 82 * Issued when a call finished. If the call finished successfully, \p error is nil and \p 83 * trailingMetadata consists any trailing metadata received from the server. Otherwise, \p error 84 * is non-nil and contains the corresponding error information, including gRPC error codes and 85 * error descriptions. 86 */ 87 - (void)didCloseWithTrailingMetadata:(nullable NSDictionary *)trailingMetadata 88 error:(nullable NSError *)error; 89 90 /** 91 * Issued when flow control is enabled for the call and a message written with GRPCCall2::writeData 92 * is passed to gRPC core with SEND_MESSAGE operation. 93 */ 94 - (void)didWriteData; 95 96 @end 97 98 /** 99 * HTTP request parameters. If Protobuf is used, these parameters are automatically generated by 100 * Protobuf. If directly using the GRPCCall2 class, users should specify these parameters manually. 101 */ 102 @interface GRPCRequestOptions : NSObject <NSCopying> 103 104 - (instancetype)init NS_UNAVAILABLE; 105 106 + (instancetype)new NS_UNAVAILABLE; 107 108 /** Initialize with all properties. */ 109 - (instancetype)initWithHost:(NSString *)host 110 path:(NSString *)path 111 safety:(GRPCCallSafety)safety NS_DESIGNATED_INITIALIZER; 112 113 /** The host serving the RPC service. */ 114 @property(copy, readonly) NSString *host; 115 /** The path to the RPC call. */ 116 @property(copy, readonly) NSString *path; 117 /** 118 * Specify whether the call is idempotent or cachable. gRPC may select different HTTP verbs for the 119 * call based on this information. The default verb used by gRPC is POST. 120 */ 121 @property(readonly) GRPCCallSafety safety; 122 123 @end 124 125 #pragma mark GRPCCall 126 127 /** 128 * A GRPCCall2 object represents an RPC call. 129 */ 130 @interface GRPCCall2 : NSObject 131 132 - (instancetype)init NS_UNAVAILABLE; 133 134 + (instancetype)new NS_UNAVAILABLE; 135 136 /** 137 * Designated initializer for a call. 138 * \param requestOptions Protobuf generated parameters for the call. 139 * \param responseHandler The object to which responses should be issued. 140 * \param callOptions Options for the call. 141 */ 142 - (instancetype)initWithRequestOptions:(GRPCRequestOptions *)requestOptions 143 responseHandler:(id<GRPCResponseHandler>)responseHandler 144 callOptions:(nullable GRPCCallOptions *)callOptions 145 NS_DESIGNATED_INITIALIZER; 146 /** 147 * Convenience initializer for a call that uses default call options (see GRPCCallOptions.m for 148 * the default options). 149 */ 150 - (instancetype)initWithRequestOptions:(GRPCRequestOptions *)requestOptions 151 responseHandler:(id<GRPCResponseHandler>)responseHandler; 152 153 /** 154 * Starts the call. This function must only be called once for each instance. 155 */ 156 - (void)start; 157 158 /** 159 * Cancel the request of this call at best effort. It attempts to notify the server that the RPC 160 * should be cancelled, and issue didCloseWithTrailingMetadata:error: callback with error code 161 * CANCELED if no other error code has already been issued. 162 */ 163 - (void)cancel; 164 165 /** 166 * Send a message to the server. The data is subject to marshaller serialization and compression 167 * (marshaller is work in progress). 168 */ 169 - (void)writeData:(id)data; 170 171 /** 172 * Finish the RPC request and half-close the call. The server may still send messages and/or 173 * trailers to the client. The method must only be called once and after start is called. 174 */ 175 - (void)finish; 176 177 /** 178 * Tell gRPC to receive the next N gRPC messages. 179 * 180 * This method should only be used when flow control is enabled. When flow control is not enabled, 181 * this method is a no-op. 182 */ 183 - (void)receiveNextMessages:(NSUInteger)numberOfMessages; 184 185 /** 186 * Get a copy of the original call options. 187 */ 188 @property(readonly, copy) GRPCCallOptions *callOptions; 189 190 /** Get a copy of the original request options. */ 191 @property(readonly, copy) GRPCRequestOptions *requestOptions; 192 193 @end 194 195 NS_ASSUME_NONNULL_END 196