Skip to content
This repository
Browse code

Documentation updated

  • Loading branch information...
commit 5a6fd3efade3cc9f219b8e9230b5f2803c204240 1 parent 6ab319a
Gernot Poetsch Gernot authored
43 Changes.md
Source Rendered
... ... @@ -0,0 +1,43 @@
  1 +# Changes to the Cocoa API Wrapper
  2 +
  3 +## Changes from version 1
  4 +
  5 +We tried to get rid of the major obstacles that occurred while using the API wrapper. Therefore we had to change the interface but instead of adding stuff we tried to get rid of everything that was distracting. The next sections will describe in a short manner what was removed, what was renamed and what you have to do to move to version 2.
  6 +
  7 +
  8 +### The SCSoundCloudAPI interface
  9 +
  10 +* Removed the `status`. It had too much complexity attached to it. Therefore added `isAuthenticated` which is a simple BOOL to check if the API is connected already.
  11 +* Also removed the delegate method `soundCloudAPI:didChangeAuthenticationStatus:` and replaced it with `soundCloudAPIDidAuthenticate:` and `soundCloudAPIDidResetAuthentication:`
  12 +
  13 +* The verifier was removed since it's not needed anymore with OAuth2
  14 +
  15 +* `soundCloudAPI:requestedAuthenticationWithURL:` was renamed to `soundCloudAPI:preparedAuthorizationURL:`
  16 +* `soundCloudAPI:didEncounterError:` was renamed to `soundCloudAPI:didFailToGetAccessTokenWithError:`
  17 +* `configurationForSoundCloudAPI:` was removed. You pass the API configuration in the initializer of the API object now.
  18 +
  19 +* `performMethod:onResource:withParameters:context:` was renamed to `-performMethod:onResource:withParameters:context:connectionDelegate:` and now takes a connection delegate and returns a SCSoundCloudConnection object
  20 +* `SCSoundCloudAPIDelegate` was moved into `SCSoundCloudConnectionDelegate`. The connection delegate can now be set per request and not API wide.
  21 +* Also `-cancelRequest:` was removed. Use `-cancel` in `SCSoundCloudConnection` now.
  22 +
  23 +* The authentication process was streamlined. Therefore `-authorizeRequestToken` was removed and `-handleOpenRedirectURL:` and `-authorizeWithUsername:password:` were added. See next chapter.
  24 +
  25 +
  26 +### The Authentication Process
  27 +
  28 +The authentication process was too complicated in the previous version. So we streamlined it. Also there's a second authentication scheme now (user credentials). See previous sections for details. This section describes how the process changed.
  29 +
  30 +In version 1 `-soundCloudAPIdidChangeAuthenticationStatus:` had to be implemented and depending on the status different things had to be triggered. Since we got rid of all the different statuses this There's not much left for you to implement :)
  31 +
  32 +In `-soundCloudAPI:preparedAuthorizationURL:` you just have to decide which authentication flow you're using and depending on that either open a webView (or the browser) and present the user with the authentication page, or query the user for username & password. Once you got the response from either your URL callback or the username and password you pass them to the API with either `-handleOpenRedirectURL:` or `-authorizeWithUsername:password:`. That's it.
  33 +
  34 +
  35 +## Changelog for the Beta of 2.0
  36 +
  37 +The wrapper is still subject to change. Although we thing that v2.0beta3 should be quite stable in it's interface now. But we're willing to optimize things even further and are hoping for your input.
  38 +
  39 +### 2.0 Beta 2 to 2.0 Beta 3
  40 +
  41 +* Renamed `-soundCloudAPIDidGetAccessToken:` to `-soundCloudAPIDidAuthenticate:` & added `-soundCloudAPIDidResetAuthentication:`
  42 +* Introduced `SCSoundCloudAPIConnection` and added `connectionDelegate:` per request
  43 +* Moved `SCSoundCloudAPIDelegate` into `SCSoundCloudAPIConnectionDelegate`
186 OLD-README.md
Source Rendered
... ... @@ -1,186 +0,0 @@
1   -# SoundCloud API Wrapper
2   -
3   -
4   -## WARNING
5   -*WARNING: The details of the Readme differ from the implementation of the current version 2.0beta6 and will be updated in the coming days.*
6   -*Also note that the Streaming library that now comes with the API Wrapper is still early alpha and will be updated in the near future.*
7   -
8   -## Intro
9   -
10   -A wrapper on the [SoundCloud](http://soundcloud.com) API for Mac OS & iOS (Cocoa & Cocoa touch). This wrapper supports the [OAuth 2](http://oauth.net/2) version of the API and uses the [OAuth2Client](http://github.com/nxtbgthng/OAuth2Client) project.
11   -
12   -If you haven't yet now is the right time to have a look at the [SoundCloud API wiki](http://wiki.github.com/soundcloud/api/).
13   -
14   -If you're looking for additional documentation on this wrapper have a look at the [wiki](http://wiki.github.com/soundcloud/cocoa-api-wrapper/) where you'll find the documentation for [version 1](http://github.com/soundcloud/cocoa-api-wrapper/tree/v1.0).
15   -
16   -## QuickStart
17   -
18   -In your terminal:
19   -
20   -- git clone git://github.com/soundcloud/cocoa-api-wrapper.git SoundCloudAPI
21   -- cd SoundCloudAPI
22   -- git submodule update --recursive --init
23   -
24   -In your Xcode project:
25   -
26   -- drag SoundCloudAPI.xcodeproj into your project
27   -- add it as a build dependency
28   -- add the static library as a liked target
29   -- add "[relative path to SoundCloudAPI]/Sources/SoundCloudAPI" to your header search path in the build settings
30   -- you can also include the [OAuth2Client](http://github.com/nxtbgthng/OAuth2Client) headers by adding "[relative path to SoundCloudAPI]/Outsourced/OAuth2Client/Sources/OAuth2Client" too (although you might not need them)
31   -
32   -## Using the Wrapper in your code
33   -
34   -### The Basics
35   -
36   -You only need to `#import "SCAPI.h"` to include the wrapper headers. The file you should be most interested in is `SCSoundCloudAPI.h`. It defines the main interface as well as the protocol for the authentication delegate. All the magic that happens in the OAuth2Client is well hidden from you.
37   -
38   -
39   -### Instantiating the API object
40   -
41   -It is recommended that you have one central instance of the `SCSoundCloudAPI` object. You may keep it in a controller object that lives as a [singleton](http://cocoawithlove.com/2008/11/singletons-appdelegates-and-top-level.html) in you application. You can use this controller as a central place to build your API request, too.
42   -
43   -To create an instance of `SCSoundCloudAPI` you can use the following code. Obtain the client key & secret for your app on [http://soundcloud.com/you/apps](http://soundcloud.com/you/apps).
44   -
45   - SCSoundCloudAPIConfiguration *scAPIConfig = [SCSoundCloudAPIConfiguration configurationForProductionWithConsumerKey:CLIENT_KEY
46   - consumerSecret:CLIENT_SECRET
47   - callbackURL:[NSURL URLWithString:CALLBACK_URL]];
48   - // scAPI is a instance variable
49   - // more on authDelegate in the next section
50   - scAPI = [[SCSoundCloudAPI alloc] initWithAuthenticationDelegate:authDelegate
51   - apiConfiguration:scAPIConfig];
52   - [scAPI setResponseFormat:SCResponseFormatJSON];
53   - [scAPI setDelegate:self]; // this is the connection delegate
54   -
55   -Until this nothing magical should happen. Your left with the `scAPI` and may query for it's status with `scAPI.isAuthenticated`. If you want to start the authentication flow you need to do a call to `[scAPI requestAuthentication]`. If the API object isn't authenticated it will start the authentication flow with your *authentication delegate*.
56   -
57   -
58   -### The Authentication Delegate
59   -
60   -You should have one instance of this in your code (for example your app delegate could be your authentication delegate). This delegate receives callbacks when a connection to SoundCloud was established (i.e. when your app receives an access token), when the connection was lost or when there was an error while receiving the access token.
61   -
62   - #pragma mark SCSoundCloudAPIAuthenticationDelegate
63   -
64   - - (void)soundCloudAPIDidAuthenticate:(SCSoundCloudAPI *)scAPI;
65   - {
66   - // big cheers!! the user sucesfully signed in
67   - // now activate your interface and send requests
68   - }
69   -
70   - - (void)soundCloudAPIDidResetAuthentication:(SCSoundCloudAPI *)scAPI;
71   - {
72   - // the user did signed off
73   - // deactivate the interface and offer the user to sign in again
74   - }
75   -
76   - - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI didFailToGetAccessTokenWithError:(NSError *)error;
77   - {
78   - // inform your user and let him retry the authentication
79   - }
80   -
81   -There is a forth delegate method which is used for the authentication flow: `-soundCloudAPI:preparedAuthorizationURL:`
82   -
83   -This method is invoked when `[scAPI requestAuthentication]` is called on an not yet authorized `SCSoundCloudAPI` object. If you passed an redirect URL with your API configuration while instantiating the API object you'll receive an authorization URL. Open this in an external browser or a web view inside your app. It's important to understand the idea behind OAuth: The user leaves his credentials in a known environment. Ideally the web site he knows in a browser of his trust.
84   -
85   - - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI preparedAuthorizationURL:(NSURL *)authorizationURL;
86   - {
87   - // example for iOS
88   - // One could also open a UIWebView and load the URL inside the app.
89   - [[UIApplication sharedApplication] openURL:authorizationURL]; // you should warn the user before doing this
90   - }
91   -
92   -The user will be able to log in at SoundCloud and give your application access. Once this is done your redirect URL is being triggered. Make sure to implement the corresponding method in you application delegate.
93   -
94   - - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url;
95   - {
96   - return [scAPI handleOpenRedirectURL:url];
97   - }
98   -
99   - // AND / OR
100   -
101   - - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions;
102   - {
103   - NSURL *launchURL = [launchOptions objectForKey:UIApplicationLaunchOptionsURLKey];
104   - return [scAPI handleOpenRedirectURL:launchURL];
105   - }
106   -
107   -As an alternative to authenticating using a browser you can also implement `-soundCloudAPI:preparedAuthorizationURL:` as follows to use the *user credentials flow*:
108   -
109   - - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI preparedAuthorizationURL:(NSURL *)authorizationURL;
110   - {
111   - // open a view which asks the user for username & password
112   - // example for iOS
113   - MYCredentialsViewController *vc = [[[MyCredentialsViewController alloc] initWithDelegate:self] autorelease];
114   - [navigationController pushViewController:vs animated:YES];
115   - }
116   -
117   - // after the user entered his credentials
118   - - (void)credentialsController:(MYCredentialsViewController *)controller
119   - didGetUsername:(NSString *)username
120   - password:(NSString *)password;
121   - {
122   - // authorize with it
123   - [scAPI authorizeWithUsername:username password:password];
124   - }
125   -
126   -But consider that this bypasses one of the major reasons for using OAuth, by passing the user credentials through your app.
127   -
128   -
129   -### Invoking Requests on the API
130   -
131   -There is one central method for sending requests to the API: `-performMethod:onResource:withParameters:context:connectionDelegate:`. This method returns an `id` which you can use to cancel the request later using `-cancelConnection:` method.
132   -
133   -The context can be used to pass data to the delegate callbacks. It is retained for as long as the `SCSoundCloudConnection` instance exists.
134   -
135   -
136   -### The Connection Delegate Protocol
137   -
138   -The second important delegate in the wrapper is `SCSoundCloudConnectionDelegate`. Use it to implement callbacks for requests you send via the API. If you're familiar with [NSURLConnection and it's delegate](http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/URLLoadingSystem/Tasks/UsingNSURLConnection.html) you'll instantly feel familiar with this protocol. That's why I won't go into detail here. It offers you callbacks for certain events during the lifecycle of a request to the API. Notice that each callback contains the `(id)context` object that you passed when performing the request.
139   -
140   -
141   -## Changes from version 1
142   -
143   -We tried to get rid of the major obstacles that occurred while using the API wrapper. Therefore we had to change the interface but instead of adding stuff we tried to get rid of everything that was distracting. The next sections will describe in a short manner what was removed, what was renamed and what you have to do to move to version 2.
144   -
145   -
146   -### The SCSoundCloudAPI interface
147   -
148   -* Removed the `status`. It had too much complexity attached to it. Therefore added `isAuthenticated` which is a simple BOOL to check if the API is connected already.
149   -* Also removed the delegate method `soundCloudAPI:didChangeAuthenticationStatus:` and replaced it with `soundCloudAPIDidAuthenticate:` and `soundCloudAPIDidResetAuthentication:`
150   -
151   -* The verifier was removed since it's not needed anymore with OAuth2
152   -
153   -* `soundCloudAPI:requestedAuthenticationWithURL:` was renamed to `soundCloudAPI:preparedAuthorizationURL:`
154   -* `soundCloudAPI:didEncounterError:` was renamed to `soundCloudAPI:didFailToGetAccessTokenWithError:`
155   -* `configurationForSoundCloudAPI:` was removed. You pass the API configuration in the initializer of the API object now.
156   -
157   -* `performMethod:onResource:withParameters:context:` was renamed to `-performMethod:onResource:withParameters:context:connectionDelegate:` and now takes a connection delegate and returns a SCSoundCloudConnection object
158   -* `SCSoundCloudAPIDelegate` was moved into `SCSoundCloudConnectionDelegate`. The connection delegate can now be set per request and not API wide.
159   -* Also `-cancelRequest:` was removed. Use `-cancel` in `SCSoundCloudConnection` now.
160   -
161   -* The authentication process was streamlined. Therefore `-authorizeRequestToken` was removed and `-handleOpenRedirectURL:` and `-authorizeWithUsername:password:` were added. See next chapter.
162   -
163   -
164   -### The Authentication Process
165   -
166   -The authentication process was too complicated in the previous version. So we streamlined it. Also there's a second authentication scheme now (user credentials). See previous sections for details. This section describes how the process changed.
167   -
168   -In version 1 `-soundCloudAPIdidChangeAuthenticationStatus:` had to be implemented and depending on the status different things had to be triggered. Since we got rid of all the different statuses this There's not much left for you to implement :)
169   -
170   -In `-soundCloudAPI:preparedAuthorizationURL:` you just have to decide which authentication flow you're using and depending on that either open a webView (or the browser) and present the user with the authentication page, or query the user for username & password. Once you got the response from either your URL callback or the username and password you pass them to the API with either `-handleOpenRedirectURL:` or `-authorizeWithUsername:password:`. That's it.
171   -
172   -
173   -## Changelog for the Beta of 2.0
174   -
175   -The wrapper is still subject to change. Although we thing that v2.0beta3 should be quite stable in it's interface now. But we're willing to optimize things even further and are hoping for your input.
176   -
177   -### 2.0 Beta 2 to 2.0 Beta 3
178   -
179   -* Renamed `-soundCloudAPIDidGetAccessToken:` to `-soundCloudAPIDidAuthenticate:` & added `-soundCloudAPIDidResetAuthentication:`
180   -* Introduced `SCSoundCloudAPIConnection` and added `connectionDelegate:` per request
181   -* Moved `SCSoundCloudAPIDelegate` into `SCSoundCloudAPIConnectionDelegate`
182   -
183   -
184   -## Feedback
185   -
186   -Please feel free to contact [me](mailto:ullrich@nxtbgthng.com?subject=SoundCloud API wrapper)
19 README.md
Source Rendered
@@ -2,15 +2,22 @@
2 2
3 3 So you want to use SoundCloud in your iOS or OSX Desktop Application? Awesome. This little guide will help you do it.
4 4
5   -There's three parts to it:
6   -* How to [integrate the SoundCLoud API Wrapper into your Project](Setup.md)
7   -* How to [use the SoundCloud API Wrapper](Usage.md)
8   -* How to [share your Audio using SoundCloud](Sharing.md)
  5 +The SoundCloud API Wrapper supports iOS from Version 3.0 and MacOS X from Leopard (10.5). It uses SoundClouds [OAuth2](http://oauth.net/2) API and henceforth includes the [NXOAuth2CLient](http://github.com/nxtbgthng/OAuth2Client) project.
  6 +
  7 +There's three parts to this Guide:
  8 +
  9 +* How to [integrate the SoundCLoud API Wrapper into your Project](Setup.md).
  10 +* How to [use the SoundCloud API Wrapper](Usage.md).
  11 +* How to [share your Audio using SoundCloud](Sharing.md).
9 12
10 13 Afraid of doing the journey alone? Don't be, there's a lot of places where you can find help:
11   -* The SoundCloud API documentation. You'll need this.
12   -* The SoundCloud API Discussion Group
  14 +
  15 +* The SoundCloud API Wiki. You'll need this.
  16 +* The SoundCloud API Discussion Group.
  17 +* If you're looking for additional documentation on this wrapper have a look at the [wiki](http://wiki.github.com/soundcloud/cocoa-api-wrapper/) where you'll find the documentation for [version 1](http://github.com/soundcloud/cocoa-api-wrapper/tree/v1.0).
13 18
14 19 Please keep in mind that all of this is under heavy development, and things might change from time to time. Please update your frameworks often, and keep this space in mind.
15 20
  21 +We document the [changes to the different versions](Changes.md). When you've used a previous version, please tead it.
  22 +
16 23 Your Friends at SoundCloud.
44 Setup.md
Source Rendered
... ... @@ -1,3 +1,45 @@
1 1 # How to integrate the SoundCloud API Wrapper
2 2
3   -* Lalalala
  3 +This guide assumes a few things:
  4 +
  5 +* You are using Xcode 4
  6 +* You are using Git.
  7 +
  8 +If you're still on Xcode 3 or do code management in another way, the steps should be equivalent, albeit not as straight forward. You should really consider upgrading ;-)
  9 +
  10 +## Setup
  11 +
  12 +We're taking a fresh new iOS Project as an example. Integration into an existing project and/or a Desktop project should be similar.
  13 +
  14 +### In the Terminal
  15 +
  16 +1. Go to your project directory.
  17 +
  18 +2. Add the Cocoa API Wrapper as a Git Subproject
  19 +
  20 + git submodule add git://github.com/soundcloud/cocoa-api-wrapper.git SoundCloudAPI
  21 +
  22 +3. Update the Subprojects (the API Wrapper includes the NXOAuth2Framework as a subproject)
  23 +
  24 + git submodule update --init --recursive
  25 +
  26 +### In Xcode
  27 +
  28 +1. Drag the `SoundCloudAPI.xcodeproj` file below your project file. If it asks you to save this as a Workspace, say yes. For projects in the _root_ hierarchy of a workspace, Xcode ensures "implicit depenencies" between them. That's a good thing.
  29 +
  30 +2. To be able to find the Headers, you still need to add `SoundCloudAPI/**` to the `Header Search Path` of the main project.
  31 +
  32 +3. Now the Target needs to know about the new libraries it should link against. So in the _Project_, select the _Target_, and in _Build Phases_ go to the _Link Binary with Libraries_ section. Add the following:
  33 +
  34 + * `libSOundCloud.a` (or `SoundCloudAPI.framework` on Desktop)
  35 + * `libOAuth2Client.a` (or `OAuth2Client.framework` on Desktop)
  36 + * `Security.framework`
  37 + * `AudioToolbox.framework` (if you want streaming)
  38 +
  39 +Congrats! Everything is set up, and you can start using it. [Here's how](Usage.md).
  40 +
  41 +## Updating
  42 +
  43 +So, from time to time there will be updates. For that, go to the API Wrapper directory and check out the latest version! After this, you might need to update the submodules, too. To do this, please run the following when you're done:
  44 +
  45 + git submodule update --init --recursive
14 Sharing.md
Source Rendered
... ... @@ -1,5 +1,4 @@
1   -SoundCloud Upload & Share Guide for iOS and OSX
2   -===============================================
  1 +# SoundCloud Upload & Share Guide for iOS and OSX
3 2
4 3 So you are familiar with the [SoundCloud API Wrapper](https://github.com/soundcloud/cocoa-api-wrapper) and want to use it to share the sounds you upload? And you want to use the [existing connections on SoundCloud](http://soundcloud.com/settings/connections) or make new ones? Awesome. Here's how to do it.
5 4
@@ -12,6 +11,7 @@ Currently the following Services are supported:
12 11 - Twitter
13 12 - Facebook (Profiles and Pages)
14 13 - Foursquare
  14 +- Tumblr
15 15 - Myspace
16 16
17 17 Here's what you need to do for sharing:
@@ -23,8 +23,7 @@ Here's what you need to do for sharing:
23 23
24 24 Depending on the privacy settings of your upload, the task is a little bit different: You want to share public tracks on social networks, and private uploads via mail.
25 25
26   -Getting the users connections
27   ------------------------------
  26 +## Getting the users connections
28 27
29 28 For getting the user's connections, use the connections resource at [`/me/connections.json`](https://github.com/soundcloud/api/wiki/10.7-Resources%3A-connections). With the API Wrapper, it looks like this:
30 29
@@ -44,8 +43,7 @@ What this returns is a JSON array of connections which looks like this:
44 43
45 44 Use a [JSON library](http://code.google.com/p/json-framework/) to transform this into Ojbective-C structures. We recommend to do this as soon as possible, preferrably directly after the start of the App, so the user does not have to wait for connections to load. You might even want to store this info, but make sure to update it it on use, because not only your app might change it!
46 45
47   -Provide a UI for the User's connections
48   ----------------------------------------
  46 +## Provide a UI for the User's connections
49 47
50 48 In your upload screen for *public* files, we recommend using a table to display the connections. You can use `UISwitch` controls as AccessoryViews of your `UITableCell`s.
51 49
@@ -102,8 +100,7 @@ When sharing **private**, you don't want to supply sharing connections, share to
102 100
103 101 nil];
104 102
105   -Bonus: Making new connections
106   ------------------------------
  103 +## Bonus: Making new connections
107 104
108 105 So what about users that have not yet connected their favorite services to SoundCloud? Can they do it from within your app? Yes, they can, and it's quite easy.
109 106
@@ -124,6 +121,7 @@ The services that are currently supported are:
124 121 - `twitter`
125 122 - `facebook_profile` (this will also connect Facebook pages!)
126 123 - `foursquare`
  124 +- `tumblr`
127 125 - `myspace`
128 126
129 127 The URL you get back in the JSON should be opened in a WebView. Listen for your callback URL in `-webView:shouldStartLoadWithRequest:navigationType:`. If you get it, close the webView and reload the connections. Voilà, your new connections are there and ready to use!
133 Usage.md
Source Rendered
... ... @@ -1,3 +1,134 @@
1 1 # How to use the SoundCloud API Wrapper
2 2
3   -* fill me with text
  3 +### The Basics
  4 +
  5 +You only need to `#import "SCAPI.h"` to include the wrapper headers.
  6 +
  7 +The object you should be most interested in is `SCSoundCloudAPI`. It is the main interface for everything SoundCloud. All the magic that happens in the OAuth2Client is well hidden from you.
  8 +
  9 +Therefore it has two delegates: The `SCAPIDelegate` and the `SCAPIAuthenticationDelegate`. The main idea is as follows: In more complex applications, you may want to have different instances of the API, but there should still be one spot where everything concerning Authentication is decided. In many cases, those two delegates point to the same singleton object, though.
  10 +
  11 +
  12 +### Instantiating the API object
  13 +
  14 +It is recommended that you have one central instance of the `SCSoundCloudAPI` object. You may keep it in a controller object that lives as a [singleton](http://cocoawithlove.com/2008/11/singletons-appdelegates-and-top-level.html) in your application. You can use this controller as a central place to build your API requests, too.
  15 +
  16 +To create an instance of `SCSoundCloudAPI` you can use the following code.
  17 +
  18 + SCSoundCloudAPIConfiguration *scAPIConfig = [SCSoundCloudAPIConfiguration configurationForProductionWithConsumerKey:CLIENT_KEY
  19 + consumerSecret:CLIENT_SECRET
  20 + callbackURL:[NSURL URLWithString:CALLBACK_URL]];
  21 + // scAPI is a instance variable
  22 + scAPI = [[SCSoundCloudAPI alloc] initWithDelegate:self
  23 + authenticationDelegate:authDelegate
  24 + apiConfiguration:scAPIConfig];
  25 +
  26 +You will get your App's _Client Key_, it's _Client Secret_ and the _Callback URL_ from [the SoundCloud page where you registered your App](http://soundcloud.com/you/apps).
  27 +
  28 +You may now ask the `scAPI` variable for the authentication status with `scAPI.isAuthenticated`. If you want to start the authentication flow you need to do a call to `[scAPI requestAuthentication]`. If it's not already authenticated, it will start the authentication flow with your *authentication delegate*.
  29 +
  30 +
  31 +### The Authentication Delegate (The easy way)
  32 +
  33 +You should have one instance of this in your code (for example your app delegate could be your authentication delegate). This delegate receives callbacks when a connection to SoundCloud was established (i.e. when your app receives an access token), when the connection was lost or when there was an error while receiving the access token.
  34 +
  35 +In most cases, **you do not need to implement anything for showing the Login ViewController**. This is true in the case that your App requires iOS4, and thus `UIApplication` has a `rootViewController` property and you use it. In this case, the API Wrapper will display the `SCLoginViewController` automagically.
  36 +
  37 +Here's some sample code for using all the other neat things the `SCAuthenticationDelegate` might provide:
  38 +
  39 + #pragma mark SCSoundCloudAPIAuthenticationDelegate
  40 +
  41 + - (void)soundCloudAPIDidAuthenticate:(SCSoundCloudAPI *)scAPI;
  42 + {
  43 + // big cheers!! the user sucesfully signed in
  44 + }
  45 +
  46 + - (void)soundCloudAPIDidResetAuthentication:(SCSoundCloudAPI *)scAPI;
  47 + {
  48 + // the user did signed off
  49 + }
  50 +
  51 + - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI didFailToGetAccessTokenWithError:(NSError *)error;
  52 + {
  53 + // inform your user and let him retry the authentication
  54 + }
  55 +
  56 +### The Authentication Delegate (The "a little bit more manual, but still easy" way)
  57 +
  58 +There are however some situations where you might want to implement more stuff in the Auth Flow.
  59 +
  60 +* In iOS 3, there is no `rootViewController` for the application. The API Wrapper uses this to present and dismiss the LoginViewController as a modal ViewController. So if you want iOS3 compatibility, you need to do this manually by implementing `-soundCloudAPIDisplayViewController:` and `-soundCloudAPIDismissViewController:` in your Authentication delegate. In these methods, you usually just trigger the `-presentModalViewController:animated:` and the `-dismissModalViewControlerAnimated:` methods of the desired ViewController.
  61 +
  62 +* Depending on your App, you might want to have either a close button in the top right corner or a reload button. You can customize that with `SCLoginViewController`'s `showReloadButton` property in the `-soundCloudAPIWillDisplayViewController:` delegate method.
  63 +
  64 +* If you're on the Desktop OS X, or you don't like the easy way, and for some reason want to do the OAuth/WebView stuff yourself, there's `-soundCloudAPIPreparedAuthorizationURL:`. If you implement this method, **all the automatic SCLoginViewController magic described above won't happen**.
  65 +
  66 +This method is invoked when `[scAPI requestAuthentication]` is called on `SCSoundCloudAPI` object which is not yet authorized. If you passed an redirect URL with your API configuration while instantiating the API object you'll receive an authorization URL. Open this in an external browser or a web view inside your app. It's important to understand the idea behind OAuth: The user leaves his credentials in a known environment. Ideally in a browser of his trust.
  67 +
  68 + - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI preparedAuthorizationURL:(NSURL *)authorizationURL;
  69 + {
  70 + // example for iOS
  71 + // One could also open a UIWebView and load the URL inside the app.
  72 + [[UIApplication sharedApplication] openURL:authorizationURL]; // you should warn the user before doing this
  73 + }
  74 +
  75 +The user will be able to log in at SoundCloud and give your application access. Once this is done your redirect URL is being triggered. Make sure to implement the corresponding method in you application delegate. On the Desktop use the analogous methods.
  76 +
  77 + - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url;
  78 + {
  79 + return [scAPI handleOpenRedirectURL:url];
  80 + }
  81 +
  82 + // AND / OR
  83 +
  84 + - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions;
  85 + {
  86 + NSURL *launchURL = [launchOptions objectForKey:UIApplicationLaunchOptionsURLKey];
  87 + return [scAPI handleOpenRedirectURL:launchURL];
  88 + }
  89 +
  90 +As an alternative to authenticating using a browser you can also implement `-soundCloudAPI:preparedAuthorizationURL:` as follows to use the *user credentials flow*:
  91 +
  92 + - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI preparedAuthorizationURL:(NSURL *)authorizationURL;
  93 + {
  94 + // open a view which asks the user for username & password
  95 + // example for iOS
  96 + MYCredentialsViewController *vc = [[[MyCredentialsViewController alloc] initWithDelegate:self] autorelease];
  97 + [navigationController pushViewController:vs animated:YES];
  98 + }
  99 +
  100 + // after the user entered his credentials
  101 + - (void)credentialsController:(MYCredentialsViewController *)controller
  102 + didGetUsername:(NSString *)username
  103 + password:(NSString *)password;
  104 + {
  105 + // authorize with it
  106 + [scAPI authorizeWithUsername:username password:password];
  107 + }
  108 +
  109 +But consider that this bypasses one of the major reasons for using OAuth, by passing the user credentials through your app.
  110 +
  111 +
  112 +### Invoking Requests on the API
  113 +
  114 +There is one central method for sending requests to the API:
  115 +
  116 + - (id)performMethod:(NSString *)httpMethod
  117 + onResource:(NSString *)resource
  118 + withParameters:(NSDictionary *)parameters
  119 + context:(id)context
  120 + userInfo:(id)userInfo;
  121 +
  122 +This method returns an `id` which you can use to cancel the request later using `-cancelConnection:` method.
  123 +
  124 +The context can be used to pass data to the delegate callbacks. It is retained for as long as the underlying Connection exists.
  125 +
  126 +### The Connection Delegate Protocol
  127 +
  128 +The second important delegate in the wrapper is `SCSoundCloudConnectionDelegate`. Use it to implement callbacks for requests you send via the API. If you're familiar with [NSURLConnection and its delegate](http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/URLLoadingSystem/Tasks/UsingNSURLConnection.html) you'll instantly feel familiar with this protocol. That's why I won't go into detail here. It offers you callbacks for certain events during the lifecycle of a request to the API. Notice that each callback contains the `(id)context` object that you passed when performing the request. It also collects the data, so you don't have to. Nice, eh?
  129 +
  130 +There's even an experimental for performing methods on the API that you can give the callbacks to as blocks. The nice thing about it is that the call and the asynchrounous success or failure methods are neatly bundled. We're loving this, and it will be the standard way of doing things once blocks are supported everywhere.
  131 +
  132 +### So, yeah, the request comes back, what do I do now?
  133 +
  134 +Since in an existing app you usually already have a JSON parser, use it to parse the data that comes back in

0 comments on commit 5a6fd3e

Please sign in to comment.
Something went wrong with that request. Please try again.