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 #import <Foundation/Foundation.h> 20 21 // import legacy header for compatibility with users using the ProtoRPC interface 22 #import "ProtoRPCLegacy.h" 23 24 #import "ProtoMethod.h" 25 26 NS_ASSUME_NONNULL_BEGIN 27 28 @class GRPCRequestOptions; 29 @class GRPCCallOptions; 30 @class GPBMessage; 31 32 /** An object can implement this protocol to receive responses from server from a call. */ 33 @protocol GRPCProtoResponseHandler <NSObject> 34 35 @required 36 37 /** 38 * All the responses must be issued to a user-provided dispatch queue. This property specifies the 39 * dispatch queue to be used for issuing the notifications. 40 */ 41 @property(atomic, readonly) dispatch_queue_t dispatchQueue; 42 43 @optional 44 45 /** 46 * Issued when initial metadata is received from the server. 47 */ 48 - (void)didReceiveInitialMetadata:(nullable NSDictionary *)initialMetadata; 49 50 /** 51 * Issued when a message is received from the server. The message is the deserialized proto object. 52 */ 53 - (void)didReceiveProtoMessage:(nullable GPBMessage *)message; 54 55 /** 56 * Issued when a call finished. If the call finished successfully, \p error is nil and \p 57 * trainingMetadata consists any trailing metadata received from the server. Otherwise, \p error 58 * is non-nil and contains the corresponding error information, including gRPC error codes and 59 * error descriptions. 60 */ 61 - (void)didCloseWithTrailingMetadata:(nullable NSDictionary *)trailingMetadata 62 error:(nullable NSError *)error; 63 64 /** 65 * Issued when flow control is enabled for the call and a message (written with writeMessage: method 66 * of GRPCStreamingProtoCall or the initializer of GRPCUnaryProtoCall) is passed to gRPC core with 67 * SEND_MESSAGE operation. 68 */ 69 - (void)didWriteMessage; 70 71 @end 72 73 /** 74 * A convenience class of objects that act as response handlers of calls. Issues 75 * response to a single handler when the response is completed. 76 * 77 * The object is stateful and should not be reused for multiple calls. If multiple calls share the 78 * same response handling logic, create separate GRPCUnaryResponseHandler objects for each call. 79 */ 80 @interface GRPCUnaryResponseHandler<ResponseType> : NSObject <GRPCProtoResponseHandler> 81 82 /** 83 * Creates a responsehandler object with a unary call handler. 84 * 85 * responseHandler: The unary handler to be called when the call is completed. 86 * responseDispatchQueue: the dispatch queue on which the response handler 87 * should be issued. If it's nil, the handler will use the main queue. 88 */ 89 - (nullable instancetype)initWithResponseHandler:(void (^)(ResponseType, NSError *))handler 90 responseDispatchQueue:(nullable dispatch_queue_t)dispatchQueue; 91 92 /** Response headers received during the call. */ 93 @property(readonly, nullable) NSDictionary *responseHeaders; 94 95 /** Response trailers received during the call. */ 96 @property(readonly, nullable) NSDictionary *responseTrailers; 97 98 @end 99 100 /** A unary-request RPC call with Protobuf. */ 101 @interface GRPCUnaryProtoCall : NSObject 102 103 - (instancetype)init NS_UNAVAILABLE; 104 105 + (instancetype)new NS_UNAVAILABLE; 106 107 /** 108 * Users should not use this initializer directly. Call objects will be created, initialized, and 109 * returned to users by methods of the generated service. 110 */ 111 - (nullable instancetype)initWithRequestOptions:(GRPCRequestOptions *)requestOptions 112 message:(GPBMessage *)message 113 responseHandler:(id<GRPCProtoResponseHandler>)handler 114 callOptions:(nullable GRPCCallOptions *)callOptions 115 responseClass:(Class)responseClass NS_DESIGNATED_INITIALIZER; 116 117 /** 118 * Start the call. This function must only be called once for each instance. 119 */ 120 - (void)start; 121 122 /** 123 * Cancel the request of this call at best effort. It attempts to notify the server that the RPC 124 * should be cancelled, and issue didCloseWithTrailingMetadata:error: callback with error code 125 * CANCELED if no other error code has already been issued. 126 */ 127 - (void)cancel; 128 129 @end 130 131 /** A client-streaming RPC call with Protobuf. */ 132 @interface GRPCStreamingProtoCall : NSObject 133 134 - (instancetype)init NS_UNAVAILABLE; 135 136 + (instancetype)new NS_UNAVAILABLE; 137 138 /** 139 * Users should not use this initializer directly. Call objects will be created, initialized, and 140 * returned to users by methods of the generated service. 141 */ 142 - (nullable instancetype)initWithRequestOptions:(GRPCRequestOptions *)requestOptions 143 responseHandler:(id<GRPCProtoResponseHandler>)handler 144 callOptions:(nullable GRPCCallOptions *)callOptions 145 responseClass:(Class)responseClass NS_DESIGNATED_INITIALIZER; 146 147 /** 148 * Start the call. This function must only be called once for each instance. 149 */ 150 - (void)start; 151 152 /** 153 * Cancel the request of this call at best effort. It attempts to notify the server that the RPC 154 * should be cancelled, and issue didCloseWithTrailingMetadata:error: callback with error code 155 * CANCELED if no other error code has already been issued. 156 */ 157 - (void)cancel; 158 159 /** 160 * Send a message to the server. The message should be a Protobuf message which will be serialized 161 * internally. 162 */ 163 - (void)writeMessage:(GPBMessage *)message; 164 165 /** 166 * Finish the RPC request and half-close the call. The server may still send messages and/or 167 * trailers to the client. 168 */ 169 - (void)finish; 170 171 /** 172 * Tell gRPC to receive another message. 173 * 174 * This method should only be used when flow control is enabled. If flow control is enabled, gRPC 175 * will only receive additional messages after the user indicates so by using either 176 * receiveNextMessage: or receiveNextMessages: methods. If flow control is not enabled, messages 177 * will be automatically received after the previous one is delivered. 178 */ 179 - (void)receiveNextMessage; 180 181 /** 182 * Tell gRPC to receive another N message. 183 * 184 * This method should only be used when flow control is enabled. If flow control is enabled, the 185 * messages received from the server are buffered in gRPC until the user want to receive the next 186 * message. If flow control is not enabled, messages will be automatically received after the 187 * previous one is delivered. 188 */ 189 - (void)receiveNextMessages:(NSUInteger)numberOfMessages; 190 191 @end 192 193 NS_ASSUME_NONNULL_END 194