1 /* 2 * 3 * Copyright 2018 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 "GRPCTypes.h" 22 23 NS_ASSUME_NONNULL_BEGIN 24 25 @protocol GRPCInterceptorFactory; 26 27 /** 28 * Immutable user configurable options for a gRPC call. 29 */ 30 @interface GRPCCallOptions : NSObject <NSCopying, NSMutableCopying> 31 32 // Call parameters 33 /** 34 * The authority for the RPC. If nil, the default authority will be used. 35 * 36 * Note: This property does not have effect on Cronet transport and will be ignored. 37 * Note: This property cannot be used to validate a self-signed server certificate. It control the 38 * :authority header field of the call and performs an extra check that server's certificate 39 * matches the :authority header. 40 */ 41 @property(copy, readonly, nullable) NSString *serverAuthority; 42 43 /** 44 * The timeout for the RPC call in seconds. If set to 0, the call will not timeout. If set to 45 * positive, the gRPC call returns with status GRPCErrorCodeDeadlineExceeded if it is not completed 46 * within \a timeout seconds. A negative value is not allowed. 47 */ 48 @property(readonly) NSTimeInterval timeout; 49 50 /** 51 * Enable flow control of a gRPC call. The option is default to NO. If set to YES, writeData: method 52 * should only be called at most once before a didWriteData callback is issued, and 53 * receiveNextMessage: must be called each time before gRPC call issues a didReceiveMessage 54 * callback. 55 */ 56 @property(readonly) BOOL flowControlEnabled; 57 58 /** 59 * An array of interceptor factories. When a call starts, interceptors are created 60 * by these factories and chained together with the same order as the factories in 61 * this array. This parameter should not be modified by any interceptor and will 62 * not take effect if done so. 63 */ 64 @property(copy, readonly) NSArray<id<GRPCInterceptorFactory>> *interceptorFactories; 65 66 // OAuth2 parameters. Users of gRPC may specify one of the following two parameters. 67 68 /** 69 * The OAuth2 access token string. The string is prefixed with "Bearer " then used as value of the 70 * request's "authorization" header field. This parameter should not be used simultaneously with 71 * \a authTokenProvider. 72 */ 73 @property(copy, readonly, nullable) NSString *oauth2AccessToken; 74 75 /** 76 * The interface to get the OAuth2 access token string. gRPC will attempt to acquire token when 77 * initiating the call. This parameter should not be used simultaneously with \a oauth2AccessToken. 78 */ 79 @property(readonly, nullable) id<GRPCAuthorizationProtocol> authTokenProvider; 80 81 /** 82 * Initial metadata key-value pairs that should be included in the request. 83 */ 84 @property(copy, readonly, nullable) NSDictionary *initialMetadata; 85 86 // Channel parameters; take into account of channel signature. 87 88 /** 89 * Custom string that is prefixed to a request's user-agent header field before gRPC's internal 90 * user-agent string. 91 */ 92 @property(copy, readonly, nullable) NSString *userAgentPrefix; 93 94 /** 95 * The size limit for the response received from server. If it is exceeded, an error with status 96 * code GRPCErrorCodeResourceExhausted is returned. 97 */ 98 @property(readonly) NSUInteger responseSizeLimit; 99 100 /** 101 * The compression algorithm to be used by the gRPC call. For more details refer to 102 * https://github.com/grpc/grpc/blob/master/doc/compression.md 103 */ 104 @property(readonly) GRPCCompressionAlgorithm compressionAlgorithm; 105 106 /** 107 * Enable/Disable gRPC call's retry feature. The default is enabled. For details of this feature 108 * refer to 109 * https://github.com/grpc/proposal/blob/master/A6-client-retries.md 110 */ 111 @property(readonly) BOOL retryEnabled; 112 113 // HTTP/2 keep-alive feature. The parameter \a keepaliveInterval specifies the interval between two 114 // PING frames. The parameter \a keepaliveTimeout specifies the length of the period for which the 115 // call should wait for PING ACK. If PING ACK is not received after this period, the call fails. 116 // Negative values are not allowed. 117 @property(readonly) NSTimeInterval keepaliveInterval; 118 @property(readonly) NSTimeInterval keepaliveTimeout; 119 120 // Parameters for connection backoff. Negative values are not allowed. 121 // For details of gRPC's backoff behavior, refer to 122 // https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md 123 @property(readonly) NSTimeInterval connectMinTimeout; 124 @property(readonly) NSTimeInterval connectInitialBackoff; 125 @property(readonly) NSTimeInterval connectMaxBackoff; 126 127 /** 128 * Specify channel args to be used for this call. For a list of channel args available, see 129 * grpc/grpc_types.h 130 */ 131 @property(copy, readonly, nullable) NSDictionary *additionalChannelArgs; 132 133 // Parameters for SSL authentication. 134 135 /** 136 * PEM format root certifications that is trusted. If set to nil, gRPC uses a list of default 137 * root certificates. 138 */ 139 @property(copy, readonly, nullable) NSString *PEMRootCertificates; 140 141 /** 142 * PEM format private key for client authentication, if required by the server. 143 */ 144 @property(copy, readonly, nullable) NSString *PEMPrivateKey; 145 146 /** 147 * PEM format certificate chain for client authentication, if required by the server. 148 */ 149 @property(copy, readonly, nullable) NSString *PEMCertificateChain; 150 151 /** 152 * Deprecated: this option is deprecated. Please use the property \a transport 153 * instead. 154 * 155 * Select the transport type to be used for this call. 156 */ 157 @property(readonly) GRPCTransportType transportType; 158 159 /** 160 * The transport to be used for this call. Users may choose a native transport 161 * identifier defined in \a GRPCTransport or provided by a non-native transport 162 * implementation. If the option is left to be NULL, gRPC will use its default 163 * transport. 164 * 165 * This is currently an experimental option. 166 */ 167 @property(readonly) GRPCTransportID transport; 168 169 /** 170 * Override the hostname during the TLS hostname validation process. 171 */ 172 @property(copy, readonly, nullable) NSString *hostNameOverride; 173 174 /** 175 * A string that specify the domain where channel is being cached. Channels with different domains 176 * will not get cached to the same connection. 177 */ 178 @property(copy, readonly, nullable) NSString *channelPoolDomain; 179 180 /** 181 * Channel id allows control of channel caching within a channelPoolDomain. A call with a unique 182 * channelID will create a new channel (connection) instead of reusing an existing one. Multiple 183 * calls in the same channelPoolDomain using identical channelID are allowed to share connection 184 * if other channel options are also the same. 185 */ 186 @property(readonly) NSUInteger channelID; 187 188 /** 189 * Return if the channel options are equal to another object. 190 */ 191 - (BOOL)hasChannelOptionsEqualTo:(GRPCCallOptions *)callOptions; 192 193 /** 194 * Hash for channel options. 195 */ 196 @property(readonly) NSUInteger channelOptionsHash; 197 198 @end 199 200 /** 201 * Mutable user configurable options for a gRPC call. 202 */ 203 @interface GRPCMutableCallOptions : GRPCCallOptions <NSCopying, NSMutableCopying> 204 205 // Call parameters 206 /** 207 * The authority for the RPC. If nil, the default authority will be used. 208 * 209 * Note: This property does not have effect on Cronet transport and will be ignored. 210 * Note: This property cannot be used to validate a self-signed server certificate. It control the 211 * :authority header field of the call and performs an extra check that server's certificate 212 * matches the :authority header. 213 */ 214 @property(copy, readwrite, nullable) NSString *serverAuthority; 215 216 /** 217 * The timeout for the RPC call in seconds. If set to 0, the call will not timeout. If set to 218 * positive, the gRPC call returns with status GRPCErrorCodeDeadlineExceeded if it is not completed 219 * within \a timeout seconds. Negative value is invalid; setting the parameter to negative value 220 * will reset the parameter to 0. 221 */ 222 @property(readwrite) NSTimeInterval timeout; 223 224 /** 225 * Enable flow control of a gRPC call. The option is default to NO. If set to YES, writeData: method 226 * should only be called at most once before a didWriteData callback is issued, and 227 * receiveNextMessage: must be called each time before gRPC call can issue a didReceiveMessage 228 * callback. 229 * 230 * If writeData: method is called more than once before issuance of a didWriteData callback, gRPC 231 * will continue to queue the message and write them to gRPC core in order. However, the user 232 * assumes their own responsibility of flow control by keeping tracking of the pending writes in 233 * the call. 234 */ 235 @property(readwrite) BOOL flowControlEnabled; 236 237 /** 238 * An array of interceptor factories. When a call starts, interceptors are created 239 * by these factories and chained together with the same order as the factories in 240 * this array. This parameter should not be modified by any interceptor and will 241 * not take effect if done so. 242 */ 243 @property(copy, readwrite) NSArray<id<GRPCInterceptorFactory>> *interceptorFactories; 244 245 // OAuth2 parameters. Users of gRPC may specify one of the following two parameters. 246 247 /** 248 * The OAuth2 access token string. The string is prefixed with "Bearer " then used as value of the 249 * request's "authorization" header field. This parameter should not be used simultaneously with 250 * \a authTokenProvider. 251 */ 252 @property(copy, readwrite, nullable) NSString *oauth2AccessToken; 253 254 /** 255 * The interface to get the OAuth2 access token string. gRPC will attempt to acquire token when 256 * initiating the call. This parameter should not be used simultaneously with \a oauth2AccessToken. 257 */ 258 @property(readwrite, nullable) id<GRPCAuthorizationProtocol> authTokenProvider; 259 260 /** 261 * Initial metadata key-value pairs that should be included in the request. 262 */ 263 @property(copy, readwrite, nullable) NSDictionary *initialMetadata; 264 265 // Channel parameters; take into account of channel signature. 266 267 /** 268 * Custom string that is prefixed to a request's user-agent header field before gRPC's internal 269 * user-agent string. 270 */ 271 @property(copy, readwrite, nullable) NSString *userAgentPrefix; 272 273 /** 274 * The size limit for the response received from server. If it is exceeded, an error with status 275 * code GRPCErrorCodeResourceExhausted is returned. 276 */ 277 @property(readwrite) NSUInteger responseSizeLimit; 278 279 /** 280 * The compression algorithm to be used by the gRPC call. For more details refer to 281 * https://github.com/grpc/grpc/blob/master/doc/compression.md 282 */ 283 @property(readwrite) GRPCCompressionAlgorithm compressionAlgorithm; 284 285 /** 286 * Enable/Disable gRPC call's retry feature. The default is enabled. For details of this feature 287 * refer to 288 * https://github.com/grpc/proposal/blob/master/A6-client-retries.md 289 */ 290 @property(readwrite) BOOL retryEnabled; 291 292 // HTTP/2 keep-alive feature. The parameter \a keepaliveInterval specifies the interval between two 293 // PING frames. The parameter \a keepaliveTimeout specifies the length of the period for which the 294 // call should wait for PING ACK. If PING ACK is not received after this period, the call fails. 295 // Negative values are invalid; setting these parameters to negative value will reset the 296 // corresponding parameter to 0. 297 @property(readwrite) NSTimeInterval keepaliveInterval; 298 @property(readwrite) NSTimeInterval keepaliveTimeout; 299 300 // Parameters for connection backoff. Negative value is invalid; setting the parameters to negative 301 // value will reset corresponding parameter to 0. 302 // For details of gRPC's backoff behavior, refer to 303 // https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md 304 @property(readwrite) NSTimeInterval connectMinTimeout; 305 @property(readwrite) NSTimeInterval connectInitialBackoff; 306 @property(readwrite) NSTimeInterval connectMaxBackoff; 307 308 /** 309 * Specify channel args to be used for this call. For a list of channel args available, see 310 * grpc/grpc_types.h 311 */ 312 @property(copy, readwrite, nullable) NSDictionary *additionalChannelArgs; 313 314 // Parameters for SSL authentication. 315 316 /** 317 * PEM format root certifications that is trusted. If set to nil, gRPC uses a list of default 318 * root certificates. 319 */ 320 @property(copy, readwrite, nullable) NSString *PEMRootCertificates; 321 322 /** 323 * PEM format private key for client authentication, if required by the server. 324 */ 325 @property(copy, readwrite, nullable) NSString *PEMPrivateKey; 326 327 /** 328 * PEM format certificate chain for client authentication, if required by the server. 329 */ 330 @property(copy, readwrite, nullable) NSString *PEMCertificateChain; 331 332 /** 333 * Deprecated: this option is deprecated. Please use the property \a transport 334 * instead. 335 * 336 * Select the transport type to be used for this call. 337 */ 338 @property(readwrite) GRPCTransportType transportType; 339 340 /** 341 * The transport to be used for this call. Users may choose a native transport 342 * identifier defined in \a GRPCTransport or provided by a non-native ttransport 343 * implementation. If the option is left to be NULL, gRPC will use its default 344 * transport. 345 * 346 * An interceptor must not change the value of this option. 347 */ 348 @property(readwrite) GRPCTransportID transport; 349 350 /** 351 * Override the hostname during the TLS hostname validation process. 352 */ 353 @property(copy, readwrite, nullable) NSString *hostNameOverride; 354 355 /** 356 * A string that specify the domain where channel is being cached. Channels with different domains 357 * will not get cached to the same channel. For example, a gRPC example app may use the channel pool 358 * domain 'io.grpc.example' so that its calls do not reuse the channel created by other modules in 359 * the same process. 360 */ 361 @property(copy, readwrite, nullable) NSString *channelPoolDomain; 362 363 /** 364 * Channel id allows a call to force creating a new channel (connection) rather than using a cached 365 * channel. Calls using distinct channelID's will not get cached to the same channel. 366 */ 367 @property(readwrite) NSUInteger channelID; 368 369 @end 370 371 NS_ASSUME_NONNULL_END 372