Skip to content
Snippets Groups Projects
Commit 54f4d53e authored by Jorge Canizales's avatar Jorge Canizales
Browse files

Update Objective-C documentation to v0.6

parent 7cb1ad96
Branches
Tags
No related merge requests found
...@@ -247,7 +247,7 @@ GIDSignIn.sharedInstance.scopes = @[@"https://www.googleapis.com/auth/grpc-testi ...@@ -247,7 +247,7 @@ GIDSignIn.sharedInstance.scopes = @[@"https://www.googleapis.com/auth/grpc-testi
... ...
#import <gRPC/ProtoRPC.h> #import <ProtoRPC/ProtoRPC.h>
// Create a not-yet-started RPC. We want to set the request headers on this object before starting // Create a not-yet-started RPC. We want to set the request headers on this object before starting
// it. // it.
...@@ -258,8 +258,7 @@ ProtoRPC *call = ...@@ -258,8 +258,7 @@ ProtoRPC *call =
// Set the access token to be used. // Set the access token to be used.
NSString *accessToken = GIDSignIn.sharedInstance.currentUser.authentication.accessToken; NSString *accessToken = GIDSignIn.sharedInstance.currentUser.authentication.accessToken;
call.requestMetadata = [NSMutableDictionary dictionaryWithDictionary: call.requestMetadata[@"Authorization"] = [@"Bearer " stringByAppendingString:accessToken]}];
@{@"Authorization": [@"Bearer " stringByAppendingString:accessToken]}];
// Start the RPC. // Start the RPC.
[call start]; [call start];
... ...
......
...@@ -115,7 +115,7 @@ In addition, an `RPCToUnaryCallWithRequest:handler:` method is generated, which ...@@ -115,7 +115,7 @@ In addition, an `RPCToUnaryCallWithRequest:handler:` method is generated, which
not-yet-started RPC object: not-yet-started RPC object:
```objective-c ```objective-c
#import <gRPC/ProtoRPC.h> #import <ProtoRPC/ProtoRPC.h>
ProtoRPC *call = ProtoRPC *call =
[client RPCToUnaryCallWithRequest:request handler:^(AUTHResponse *response, NSError *error) { [client RPCToUnaryCallWithRequest:request handler:^(AUTHResponse *response, NSError *error) {
...@@ -132,10 +132,11 @@ The RPC represented by this object can be started at any later time like this: ...@@ -132,10 +132,11 @@ The RPC represented by this object can be started at any later time like this:
<a name="request-metadata"></a> <a name="request-metadata"></a>
## Set request metadata of a call: Authorization header with an access token ## Set request metadata of a call: Authorization header with an access token
The `ProtoRPC` class has a `requestMetadata` property defined like this: The `ProtoRPC` class has a `requestMetadata` property (inherited from `GRPCCall`) defined like this:
```objective-c ```objective-c
@property(nonatomic, readwrite) NSMutableDictionary *requestMetadata; - (NSMutableDictionary *)requestMetadata; // nonatomic
- (void)setRequestMetadata:(NSDictionary *)requestMetadata; // nonatomic, copy
``` ```
Setting it to a dictionary of metadata keys and values will have them sent on the wire when the call Setting it to a dictionary of metadata keys and values will have them sent on the wire when the call
...@@ -143,33 +144,46 @@ is started. gRPC metadata are pieces of information about the call sent by the c ...@@ -143,33 +144,46 @@ is started. gRPC metadata are pieces of information about the call sent by the c
(and vice versa). They take the form of key-value pairs and are essentially opaque to gRPC itself. (and vice versa). They take the form of key-value pairs and are essentially opaque to gRPC itself.
```objective-c ```objective-c
call.requestMetadata = [NSMutableDictionary dictionaryWithDictionary: call.requestMetadata = @{@"My-Header": @"Value for this header",
@{@"My-Header": @"Value for this header", @"Another-Header": @"Its value"};
@"Another-Header": @"Its value"}]; ```
For convenience, the property is initialized with an empty `NSMutableDictionary`, so that request
metadata elements can be set like this:
```objective-c
call.requestMetadata[@"My-Header"] = @"Value for this header";
``` ```
If you have an access token, OAuth2 specifies it is to be sent in this format: If you have an access token, OAuth2 specifies it is to be sent in this format:
```objective-c ```objective-c
@{@"Authorization": [@"Bearer " stringByAppendingString:accessToken]} call.requestMetadata[@"Authorization"] = [@"Bearer " stringByAppendingString:accessToken];
``` ```
<a name="response-metadata"></a> <a name="response-metadata"></a>
## Get response metadata of a call: Auth challenge header ## Get response metadata of a call: Auth challenge header
The `ProtoRPC` class also has a `responseMetadata` property, analogous to the request metadata we The `ProtoRPC` class also inherits a `responseMetadata` property, analogous to the request metadata
just looked at. It's defined like this: we just looked at. It's defined like this:
```objective-c ```objective-c
@property(atomic, readonly) NSDictionary *responseMetadata; @property(atomic, readonly) NSDictionary *responseMetadata;
``` ```
Because gRPC metadata keys can be repeated, the values of the `responseMetadata` dictionary are To access OAuth2's authentication challenge header you write:
always `NSArray`s. Thus, to access OAuth2's authentication challenge header you write:
```objective-c ```objective-c
call.responseMetadata[@"www-authenticate"][0] call.responseMetadata[@"www-authenticate"]
``` ```
Note that, as gRPC metadata elements are mapped to HTTP/2 headers (or trailers), the keys of the Note that, as gRPC metadata elements are mapped to HTTP/2 headers (or trailers), the keys of the
response metadata are always ASCII strings in lowercase. response metadata are always ASCII strings in lowercase.
Many uses cases of response metadata are getting more details about an RPC error. For convenience,
when a `NSError` instance is passed to an RPC handler block, the response metadata dictionary can
also be accessed this way:
```objective-c
error.userInfo[kGRPCStatusMetadataKey]
```
...@@ -2,15 +2,17 @@ ...@@ -2,15 +2,17 @@
## Installation ## Installation
To run this example you should have [Cocoapods](https://cocoapods.org/#install) installed, as well as the relevant tools to generate the client library code (and a server in another language, for testing). You can obtain the latter by following [these setup instructions](https://github.com/grpc/homebrew-grpc). To run this example you should have [Cocoapods](https://cocoapods.org/#install) installed, as well
as the relevant tools to generate the client library code (and a server in another language, for
testing). You can obtain the latter by following [these setup instructions](https://github.com/grpc/homebrew-grpc).
## Hello Objective-C gRPC! ## Hello Objective-C gRPC!
Here's how to build and run the Objective-C implementation of the [Hello World](https://github.com/grpc/grpc-common/blob/master/protos/helloworld.proto) example used in [Getting started](https://github.com/grpc/grpc-common). Here's how to build and run the Objective-C implementation of the [Hello World](https://github.com/grpc/grpc-common/blob/master/protos/helloworld.proto)
example used in [Getting started](https://github.com/grpc/grpc-common).
The example code for this and our other examples lives in the `grpc-common` The example code for this and our other examples lives in the `grpc-common` GitHub repository. Clone
GitHub repository. Clone this repository to your local machine by running the this repository to your local machine by running the following command:
following command:
```sh ```sh
...@@ -24,7 +26,8 @@ $ cd grpc-common/objective-c/helloworld ...@@ -24,7 +26,8 @@ $ cd grpc-common/objective-c/helloworld
``` ```
### Try it! ### Try it!
To try the sample app, we need a gRPC server running locally. Let's compile and run, for example, the C++ server in this repository: To try the sample app, we need a gRPC server running locally. Let's compile and run, for example,
the C++ server in this repository:
```shell ```shell
$ pushd ../../cpp/helloworld $ pushd ../../cpp/helloworld
...@@ -39,12 +42,15 @@ Now have Cocoapods generate and install the client library for our .proto files: ...@@ -39,12 +42,15 @@ Now have Cocoapods generate and install the client library for our .proto files:
$ pod install $ pod install
``` ```
This might have to compile OpenSSL, which takes around 15 minutes if Cocoapods doesn't have it yet on your computer's cache). (This might have to compile OpenSSL, which takes around 15 minutes if Cocoapods doesn't have it yet
on your computer's cache.)
Finally, open the XCode workspace created by Cocoapods, and run the app. You can check the calling code in `main.m` and see the results in XCode's log console. Finally, open the XCode workspace created by Cocoapods, and run the app. You can check the calling
code in `main.m` and see the results in XCode's log console.
The code sends a `HLWHelloRequest` containing the string "Objective-C" to a local server. The server responds with a `HLWHelloResponse`, which contains a string that is then output to the log. The code sends a `HLWHelloRequest` containing the string "Objective-C" to a local server. The server
responds with a `HLWHelloResponse`, which contains a string that is then output to the log.
## Tutorial ## Tutorial
You can find a more detailed tutorial in [gRPC Basics: Objective-C](https://github.com/grpc/grpc-common/blob/master/objective-c/route_guide/README.md) You can find a more detailed tutorial in [gRPC Basics: Objective-C](https://github.com/grpc/grpc-common/blob/master/objective-c/route_guide/README.md).
\ No newline at end of file
This diff is collapsed.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please to comment