diff options
Diffstat (limited to 'src/objective-c/GRPCClient/GRPCCall.h')
| -rw-r--r-- | src/objective-c/GRPCClient/GRPCCall.h | 189 |
1 files changed, 107 insertions, 82 deletions
diff --git a/src/objective-c/GRPCClient/GRPCCall.h b/src/objective-c/GRPCClient/GRPCCall.h index 7645bb1d34..5ed160d7a0 100644 --- a/src/objective-c/GRPCClient/GRPCCall.h +++ b/src/objective-c/GRPCClient/GRPCCall.h @@ -34,17 +34,18 @@ /** * The gRPC protocol is an RPC protocol on top of HTTP2. * - * While the most common type of RPC receives only one request message and returns only one response - * message, the protocol also supports RPCs that return multiple individual messages in a streaming - * fashion, RPCs that accept a stream of request messages, or RPCs with both streaming requests and + * While the most common type of RPC receives only one request message and + * returns only one response message, the protocol also supports RPCs that + * return multiple individual messages in a streaming fashion, RPCs that accept + * a stream of request messages, or RPCs with both streaming requests and * responses. * - * Conceptually, each gRPC call consists of a bidirectional stream of binary messages, with RPCs of - * the "non-streaming type" sending only one message in the corresponding direction (the protocol - * doesn't make any distinction). + * Conceptually, each gRPC call consists of a bidirectional stream of binary + * messages, with RPCs of the "non-streaming type" sending only one message in + * the corresponding direction (the protocol doesn't make any distinction). * - * Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs can be multiplexed - * transparently on the same TCP connection. + * Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs + * can be multiplexed transparently on the same TCP connection. */ #import <Foundation/Foundation.h> @@ -59,51 +60,56 @@ extern NSString *const kGRPCErrorDomain; /** * gRPC error codes. - * Note that a few of these are never produced by the gRPC libraries, but are of general utility for - * server applications to produce. + * Note that a few of these are never produced by the gRPC libraries, but are of + * general utility for server applications to produce. */ typedef NS_ENUM(NSUInteger, GRPCErrorCode) { /** The operation was cancelled (typically by the caller). */ GRPCErrorCodeCancelled = 1, /** - * Unknown error. Errors raised by APIs that do not return enough error information may be + * Unknown error. Errors raised by APIs that do not return enough error + * information may be * converted to this error. */ GRPCErrorCodeUnknown = 2, /** - * The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. - * INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the - * server (e.g., a malformed file name). + * The client specified an invalid argument. Note that this differs from + * FAILED_PRECONDITION. + * INVALID_ARGUMENT indicates arguments that are problematic regardless of the + * state of the server (e.g., a malformed file name). */ GRPCErrorCodeInvalidArgument = 3, /** - * Deadline expired before operation could complete. For operations that change the state of the - * server, this error may be returned even if the operation has completed successfully. For - * example, a successful response from the server could have been delayed long enough for the - * deadline to expire. + * Deadline expired before operation could complete. For operations that + * change the state of the server, this error may be returned even if the + * operation has completed successfully. For example, a successful response + * from the server could have been delayed long enough for the deadline to + * expire. */ GRPCErrorCodeDeadlineExceeded = 4, /** Some requested entity (e.g., file or directory) was not found. */ GRPCErrorCodeNotFound = 5, - /** Some entity that we attempted to create (e.g., file or directory) already exists. */ + /** Some entity that we attempted to create (e.g., file or directory) already + exists. */ GRPCErrorCodeAlreadyExists = 6, /** - * The caller does not have permission to execute the specified operation. PERMISSION_DENIED isn't - * used for rejections caused by exhausting some resource (RESOURCE_EXHAUSTED is used instead for - * those errors). PERMISSION_DENIED doesn't indicate a failure to identify the caller + * The caller does not have permission to execute the specified operation. + * PERMISSION_DENIED isn't used for rejections caused by exhausting some + * resource (RESOURCE_EXHAUSTED is used instead for those errors). + * PERMISSION_DENIED doesn't indicate a failure to identify the caller * (UNAUTHENTICATED is used instead for those errors). */ GRPCErrorCodePermissionDenied = 7, /** - * The request does not have valid authentication credentials for the operation (e.g. the caller's - * identity can't be verified). + * The request does not have valid authentication credentials for the + * operation (e.g. the caller's identity can't be verified). */ GRPCErrorCodeUnauthenticated = 16, @@ -111,42 +117,47 @@ typedef NS_ENUM(NSUInteger, GRPCErrorCode) { GRPCErrorCodeResourceExhausted = 8, /** - * The RPC was rejected because the server is not in a state required for the procedure's + * The RPC was rejected because the server is not in a state required for the + * procedure's * execution. For example, a directory to be deleted may be non-empty, etc. - * The client should not retry until the server state has been explicitly fixed (e.g. by - * performing another RPC). The details depend on the service being called, and should be found in - * the NSError's userInfo. + * The client should not retry until the server state has been explicitly + * fixed (e.g. by + * performing another RPC). The details depend on the service being called, + * and should be found in the NSError's userInfo. */ GRPCErrorCodeFailedPrecondition = 9, /** - * The RPC was aborted, typically due to a concurrency issue like sequencer check failures, - * transaction aborts, etc. The client should retry at a higher-level (e.g., restarting a read- - * modify-write sequence). + * The RPC was aborted, typically due to a concurrency issue like sequencer + * check failures, transaction aborts, etc. The client should retry at a + * higher-level (e.g., restarting a read-modify-write sequence). */ GRPCErrorCodeAborted = 10, /** - * The RPC was attempted past the valid range. E.g., enumerating past the end of a list. - * Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state - * changes. For example, an RPC to get elements of a list will generate INVALID_ARGUMENT if asked - * to return the element at a negative index, but it will generate OUT_OF_RANGE if asked to return - * the element at an index past the current size of the list. + * The RPC was attempted past the valid range. E.g., enumerating past the end + * of a list. + * Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed + * if the system state changes. For example, an RPC to get elements of a list + * will generate INVALID_ARGUMENT if asked to return the element at a negative + * index, but it will generate OUT_OF_RANGE if asked to return the element at + * an index past the current size of the list. */ GRPCErrorCodeOutOfRange = 11, - /** The procedure is not implemented or not supported/enabled in this server. */ + /** The procedure is not implemented or not supported/enabled in this server. + */ GRPCErrorCodeUnimplemented = 12, /** - * Internal error. Means some invariant expected by the server application or the gRPC library has - * been broken. + * Internal error. Means some invariant expected by the server application or + * the gRPC library has been broken. */ GRPCErrorCodeInternal = 13, /** - * The server is currently unavailable. This is most likely a transient condition and may be - * corrected by retrying with a backoff. + * The server is currently unavailable. This is most likely a transient + * condition and may be corrected by retrying with a backoff. */ GRPCErrorCodeUnavailable = 14, @@ -158,17 +169,19 @@ typedef NS_ENUM(NSUInteger, GRPCErrorCode) { * Safety remark of a gRPC method as defined in RFC 2616 Section 9.1 */ typedef NS_ENUM(NSUInteger, GRPCCallSafety) { - /** Signal that there is no guarantees on how the call affects the server state. */ + /** Signal that there is no guarantees on how the call affects the server + state. */ GRPCCallSafetyDefault = 0, /** Signal that the call is idempotent. gRPC is free to use PUT verb. */ GRPCCallSafetyIdempotentRequest = 1, - /** Signal that the call is cacheable and will not affect server state. gRPC is free to use GET verb. */ + /** Signal that the call is cacheable and will not affect server state. gRPC + is free to use GET verb. */ GRPCCallSafetyCacheableRequest = 2, }; /** - * Keys used in |NSError|'s |userInfo| dictionary to store the response headers and trailers sent by - * the server. + * Keys used in |NSError|'s |userInfo| dictionary to store the response headers + * and trailers sent by the server. */ extern id const kGRPCHeadersKey; extern id const kGRPCTrailersKey; @@ -179,20 +192,24 @@ extern id const kGRPCTrailersKey; @interface GRPCCall : GRXWriter /** - * The container of the request headers of an RPC conforms to this protocol, which is a subset of - * NSMutableDictionary's interface. It will become a NSMutableDictionary later on. - * The keys of this container are the header names, which per the HTTP standard are case- - * insensitive. They are stored in lowercase (which is how HTTP/2 mandates them on the wire), and - * can only consist of ASCII characters. - * A header value is a NSString object (with only ASCII characters), unless the header name has the - * suffix "-bin", in which case the value has to be a NSData object. + * The container of the request headers of an RPC conforms to this protocol, + * which is a subset of NSMutableDictionary's interface. It will become a + * NSMutableDictionary later on. The keys of this container are the header + * names, which per the HTTP standard are case-insensitive. They are stored in + * lowercase (which is how HTTP/2 mandates them on the wire), and can only + * consist of ASCII characters. + * A header value is a NSString object (with only ASCII characters), unless the + * header name has the suffix "-bin", in which case the value has to be a NSData + * object. */ /** - * These HTTP headers will be passed to the server as part of this call. Each HTTP header is a - * name-value pair with string names and either string or binary values. + * These HTTP headers will be passed to the server as part of this call. Each + * HTTP header is a name-value pair with string names and either string or + * binary values. * - * The passed dictionary has to use NSString keys, corresponding to the header names. The value - * associated to each can be a NSString object or a NSData object. E.g.: + * The passed dictionary has to use NSString keys, corresponding to the header + * names. The value associated to each can be a NSString object or a NSData + * object. E.g.: * * call.requestHeaders = @{@"authorization": @"Bearer ..."}; * @@ -205,53 +222,61 @@ extern id const kGRPCTrailersKey; @property(atomic, readonly) NSMutableDictionary *requestHeaders; /** - * This dictionary is populated with the HTTP headers received from the server. This happens before - * any response message is received from the server. It has the same structure as the request - * headers dictionary: Keys are NSString header names; names ending with the suffix "-bin" have a - * NSData value; the others have a NSString value. + * This dictionary is populated with the HTTP headers received from the server. + * This happens before any response message is received from the server. It has + * the same structure as the request headers dictionary: Keys are NSString + * header names; names ending with the suffix "-bin" have a NSData value; the + * others have a NSString value. * - * The value of this property is nil until all response headers are received, and will change before - * any of -writeValue: or -writesFinishedWithError: are sent to the writeable. + * The value of this property is nil until all response headers are received, + * and will change before any of -writeValue: or -writesFinishedWithError: are + * sent to the writeable. */ @property(atomic, readonly) NSDictionary *responseHeaders; /** - * Same as responseHeaders, but populated with the HTTP trailers received from the server before the - * call finishes. + * Same as responseHeaders, but populated with the HTTP trailers received from + * the server before the call finishes. * - * The value of this property is nil until all response trailers are received, and will change - * before -writesFinishedWithError: is sent to the writeable. + * The value of this property is nil until all response trailers are received, + * and will change before -writesFinishedWithError: is sent to the writeable. */ @property(atomic, readonly) NSDictionary *responseTrailers; /** - * The request writer has to write NSData objects into the provided Writeable. The server will - * receive each of those separately and in order as distinct messages. - * A gRPC call might not complete until the request writer finishes. On the other hand, the request - * finishing doesn't necessarily make the call to finish, as the server might continue sending - * messages to the response side of the call indefinitely (depending on the semantics of the - * specific remote method called). + * The request writer has to write NSData objects into the provided Writeable. + * The server will receive each of those separately and in order as distinct + * messages. + * A gRPC call might not complete until the request writer finishes. On the + * other hand, the request finishing doesn't necessarily make the call to + * finish, as the server might continue sending messages to the response side of + * the call indefinitely (depending on the semantics of the specific remote + * method called). * To finish a call right away, invoke cancel. - * host parameter should not contain the scheme (http:// or https://), only the name or IP addr - * and the port number, for example @"localhost:5050". + * host parameter should not contain the scheme (http:// or https://), only the + * name or IP addr and the port number, for example @"localhost:5050". */ - (instancetype)initWithHost:(NSString *)host path:(NSString *)path - requestsWriter:(GRXWriter *)requestsWriter NS_DESIGNATED_INITIALIZER; + requestsWriter:(GRXWriter *)requestsWriter + NS_DESIGNATED_INITIALIZER; /** - * Finishes the request side of this call, notifies the server that the RPC should be cancelled, and - * finishes the response side of the call with an error of code CANCELED. + * Finishes the request side of this call, notifies the server that the RPC + * should be cancelled, and finishes the response side of the call with an error + * of code CANCELED. */ - (void)cancel; /** * Set the call flag for a specific host path. * - * Host parameter should not contain the scheme (http:// or https://), only the name or IP addr - * and the port number, for example @"localhost:5050". + * Host parameter should not contain the scheme (http:// or https://), only the + * name or IP addr and the port number, for example @"localhost:5050". */ -+ (void)setCallSafety:(GRPCCallSafety)callSafety host:(NSString *)host path:(NSString *)path; ++ (void)setCallSafety:(GRPCCallSafety)callSafety + host:(NSString *)host + path:(NSString *)path; // TODO(jcanizales): Let specify a deadline. As a category of GRXWriter? @end @@ -260,7 +285,7 @@ extern id const kGRPCTrailersKey; /** This protocol is kept for backwards compatibility with existing code. */ DEPRECATED_MSG_ATTRIBUTE("Use NSDictionary or NSMutableDictionary instead.") -@protocol GRPCRequestHeaders <NSObject> +@protocol GRPCRequestHeaders<NSObject> @property(nonatomic, readonly) NSUInteger count; - (id)objectForKeyedSubscript:(id)key; @@ -273,6 +298,6 @@ DEPRECATED_MSG_ATTRIBUTE("Use NSDictionary or NSMutableDictionary instead.") #pragma clang diagnostic push #pragma clang diagnostic ignored "-Wdeprecated" /** This is only needed for backwards-compatibility. */ -@interface NSMutableDictionary (GRPCRequestHeaders) <GRPCRequestHeaders> +@interface NSMutableDictionary (GRPCRequestHeaders)<GRPCRequestHeaders> @end #pragma clang diagnostic pop |