Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Documentation updated

  • Loading branch information...
commit 5a6fd3efade3cc9f219b8e9230b5f2803c204240 1 parent 6ab319a
@Gernot Gernot authored
View
43 Changes.md
@@ -0,0 +1,43 @@
+# Changes to the Cocoa API Wrapper
+
+## Changes from version 1
+
+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.
+
+
+### The SCSoundCloudAPI interface
+
+* 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.
+* Also removed the delegate method `soundCloudAPI:didChangeAuthenticationStatus:` and replaced it with `soundCloudAPIDidAuthenticate:` and `soundCloudAPIDidResetAuthentication:`
+
+* The verifier was removed since it's not needed anymore with OAuth2
+
+* `soundCloudAPI:requestedAuthenticationWithURL:` was renamed to `soundCloudAPI:preparedAuthorizationURL:`
+* `soundCloudAPI:didEncounterError:` was renamed to `soundCloudAPI:didFailToGetAccessTokenWithError:`
+* `configurationForSoundCloudAPI:` was removed. You pass the API configuration in the initializer of the API object now.
+
+* `performMethod:onResource:withParameters:context:` was renamed to `-performMethod:onResource:withParameters:context:connectionDelegate:` and now takes a connection delegate and returns a SCSoundCloudConnection object
+* `SCSoundCloudAPIDelegate` was moved into `SCSoundCloudConnectionDelegate`. The connection delegate can now be set per request and not API wide.
+* Also `-cancelRequest:` was removed. Use `-cancel` in `SCSoundCloudConnection` now.
+
+* The authentication process was streamlined. Therefore `-authorizeRequestToken` was removed and `-handleOpenRedirectURL:` and `-authorizeWithUsername:password:` were added. See next chapter.
+
+
+### The Authentication Process
+
+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.
+
+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 :)
+
+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.
+
+
+## Changelog for the Beta of 2.0
+
+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.
+
+### 2.0 Beta 2 to 2.0 Beta 3
+
+* Renamed `-soundCloudAPIDidGetAccessToken:` to `-soundCloudAPIDidAuthenticate:` & added `-soundCloudAPIDidResetAuthentication:`
+* Introduced `SCSoundCloudAPIConnection` and added `connectionDelegate:` per request
+* Moved `SCSoundCloudAPIDelegate` into `SCSoundCloudAPIConnectionDelegate`
View
186 OLD-README.md
@@ -1,186 +0,0 @@
-# SoundCloud API Wrapper
-
-
-## WARNING
-*WARNING: The details of the Readme differ from the implementation of the current version 2.0beta6 and will be updated in the coming days.*
-*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.*
-
-## Intro
-
-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.
-
-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/).
-
-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).
-
-## QuickStart
-
-In your terminal:
-
-- git clone git://github.com/soundcloud/cocoa-api-wrapper.git SoundCloudAPI
-- cd SoundCloudAPI
-- git submodule update --recursive --init
-
-In your Xcode project:
-
-- drag SoundCloudAPI.xcodeproj into your project
-- add it as a build dependency
-- add the static library as a liked target
-- add "[relative path to SoundCloudAPI]/Sources/SoundCloudAPI" to your header search path in the build settings
-- 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)
-
-## Using the Wrapper in your code
-
-### The Basics
-
-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.
-
-
-### Instantiating the API object
-
-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.
-
-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).
-
- SCSoundCloudAPIConfiguration *scAPIConfig = [SCSoundCloudAPIConfiguration configurationForProductionWithConsumerKey:CLIENT_KEY
- consumerSecret:CLIENT_SECRET
- callbackURL:[NSURL URLWithString:CALLBACK_URL]];
- // scAPI is a instance variable
- // more on authDelegate in the next section
- scAPI = [[SCSoundCloudAPI alloc] initWithAuthenticationDelegate:authDelegate
- apiConfiguration:scAPIConfig];
- [scAPI setResponseFormat:SCResponseFormatJSON];
- [scAPI setDelegate:self]; // this is the connection delegate
-
-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*.
-
-
-### The Authentication Delegate
-
-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.
-
- #pragma mark SCSoundCloudAPIAuthenticationDelegate
-
- - (void)soundCloudAPIDidAuthenticate:(SCSoundCloudAPI *)scAPI;
- {
- // big cheers!! the user sucesfully signed in
- // now activate your interface and send requests
- }
-
- - (void)soundCloudAPIDidResetAuthentication:(SCSoundCloudAPI *)scAPI;
- {
- // the user did signed off
- // deactivate the interface and offer the user to sign in again
- }
-
- - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI didFailToGetAccessTokenWithError:(NSError *)error;
- {
- // inform your user and let him retry the authentication
- }
-
-There is a forth delegate method which is used for the authentication flow: `-soundCloudAPI:preparedAuthorizationURL:`
-
-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.
-
- - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI preparedAuthorizationURL:(NSURL *)authorizationURL;
- {
- // example for iOS
- // One could also open a UIWebView and load the URL inside the app.
- [[UIApplication sharedApplication] openURL:authorizationURL]; // you should warn the user before doing this
- }
-
-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.
-
- - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url;
- {
- return [scAPI handleOpenRedirectURL:url];
- }
-
- // AND / OR
-
- - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions;
- {
- NSURL *launchURL = [launchOptions objectForKey:UIApplicationLaunchOptionsURLKey];
- return [scAPI handleOpenRedirectURL:launchURL];
- }
-
-As an alternative to authenticating using a browser you can also implement `-soundCloudAPI:preparedAuthorizationURL:` as follows to use the *user credentials flow*:
-
- - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI preparedAuthorizationURL:(NSURL *)authorizationURL;
- {
- // open a view which asks the user for username & password
- // example for iOS
- MYCredentialsViewController *vc = [[[MyCredentialsViewController alloc] initWithDelegate:self] autorelease];
- [navigationController pushViewController:vs animated:YES];
- }
-
- // after the user entered his credentials
- - (void)credentialsController:(MYCredentialsViewController *)controller
- didGetUsername:(NSString *)username
- password:(NSString *)password;
- {
- // authorize with it
- [scAPI authorizeWithUsername:username password:password];
- }
-
-But consider that this bypasses one of the major reasons for using OAuth, by passing the user credentials through your app.
-
-
-### Invoking Requests on the API
-
-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.
-
-The context can be used to pass data to the delegate callbacks. It is retained for as long as the `SCSoundCloudConnection` instance exists.
-
-
-### The Connection Delegate Protocol
-
-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.
-
-
-## Changes from version 1
-
-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.
-
-
-### The SCSoundCloudAPI interface
-
-* 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.
-* Also removed the delegate method `soundCloudAPI:didChangeAuthenticationStatus:` and replaced it with `soundCloudAPIDidAuthenticate:` and `soundCloudAPIDidResetAuthentication:`
-
-* The verifier was removed since it's not needed anymore with OAuth2
-
-* `soundCloudAPI:requestedAuthenticationWithURL:` was renamed to `soundCloudAPI:preparedAuthorizationURL:`
-* `soundCloudAPI:didEncounterError:` was renamed to `soundCloudAPI:didFailToGetAccessTokenWithError:`
-* `configurationForSoundCloudAPI:` was removed. You pass the API configuration in the initializer of the API object now.
-
-* `performMethod:onResource:withParameters:context:` was renamed to `-performMethod:onResource:withParameters:context:connectionDelegate:` and now takes a connection delegate and returns a SCSoundCloudConnection object
-* `SCSoundCloudAPIDelegate` was moved into `SCSoundCloudConnectionDelegate`. The connection delegate can now be set per request and not API wide.
-* Also `-cancelRequest:` was removed. Use `-cancel` in `SCSoundCloudConnection` now.
-
-* The authentication process was streamlined. Therefore `-authorizeRequestToken` was removed and `-handleOpenRedirectURL:` and `-authorizeWithUsername:password:` were added. See next chapter.
-
-
-### The Authentication Process
-
-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.
-
-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 :)
-
-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.
-
-
-## Changelog for the Beta of 2.0
-
-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.
-
-### 2.0 Beta 2 to 2.0 Beta 3
-
-* Renamed `-soundCloudAPIDidGetAccessToken:` to `-soundCloudAPIDidAuthenticate:` & added `-soundCloudAPIDidResetAuthentication:`
-* Introduced `SCSoundCloudAPIConnection` and added `connectionDelegate:` per request
-* Moved `SCSoundCloudAPIDelegate` into `SCSoundCloudAPIConnectionDelegate`
-
-
-## Feedback
-
-Please feel free to contact [me](mailto:ullrich@nxtbgthng.com?subject=SoundCloud API wrapper)
View
19 README.md
@@ -2,15 +2,22 @@
So you want to use SoundCloud in your iOS or OSX Desktop Application? Awesome. This little guide will help you do it.
-There's three parts to it:
-* How to [integrate the SoundCLoud API Wrapper into your Project](Setup.md)
-* How to [use the SoundCloud API Wrapper](Usage.md)
-* How to [share your Audio using SoundCloud](Sharing.md)
+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.
+
+There's three parts to this Guide:
+
+* How to [integrate the SoundCLoud API Wrapper into your Project](Setup.md).
+* How to [use the SoundCloud API Wrapper](Usage.md).
+* How to [share your Audio using SoundCloud](Sharing.md).
Afraid of doing the journey alone? Don't be, there's a lot of places where you can find help:
-* The SoundCloud API documentation. You'll need this.
-* The SoundCloud API Discussion Group
+
+* The SoundCloud API Wiki. You'll need this.
+* The SoundCloud API Discussion Group.
+* 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).
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.
+We document the [changes to the different versions](Changes.md). When you've used a previous version, please tead it.
+
Your Friends at SoundCloud.
View
44 Setup.md
@@ -1,3 +1,45 @@
# How to integrate the SoundCloud API Wrapper
-* Lalalala
+This guide assumes a few things:
+
+* You are using Xcode 4
+* You are using Git.
+
+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 ;-)
+
+## Setup
+
+We're taking a fresh new iOS Project as an example. Integration into an existing project and/or a Desktop project should be similar.
+
+### In the Terminal
+
+1. Go to your project directory.
+
+2. Add the Cocoa API Wrapper as a Git Subproject
+
+ git submodule add git://github.com/soundcloud/cocoa-api-wrapper.git SoundCloudAPI
+
+3. Update the Subprojects (the API Wrapper includes the NXOAuth2Framework as a subproject)
+
+ git submodule update --init --recursive
+
+### In Xcode
+
+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.
+
+2. To be able to find the Headers, you still need to add `SoundCloudAPI/**` to the `Header Search Path` of the main project.
+
+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:
+
+ * `libSOundCloud.a` (or `SoundCloudAPI.framework` on Desktop)
+ * `libOAuth2Client.a` (or `OAuth2Client.framework` on Desktop)
+ * `Security.framework`
+ * `AudioToolbox.framework` (if you want streaming)
+
+Congrats! Everything is set up, and you can start using it. [Here's how](Usage.md).
+
+## Updating
+
+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:
+
+ git submodule update --init --recursive
View
14 Sharing.md
@@ -1,5 +1,4 @@
-SoundCloud Upload & Share Guide for iOS and OSX
-===============================================
+# SoundCloud Upload & Share Guide for iOS and OSX
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.
@@ -12,6 +11,7 @@ Currently the following Services are supported:
- Twitter
- Facebook (Profiles and Pages)
- Foursquare
+- Tumblr
- Myspace
Here's what you need to do for sharing:
@@ -23,8 +23,7 @@ Here's what you need to do for sharing:
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.
-Getting the users connections
------------------------------
+## Getting the users connections
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:
@@ -44,8 +43,7 @@ What this returns is a JSON array of connections which looks like this:
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!
-Provide a UI for the User's connections
----------------------------------------
+## Provide a UI for the User's connections
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.
@@ -102,8 +100,7 @@ When sharing **private**, you don't want to supply sharing connections, share to
nil];
-Bonus: Making new connections
------------------------------
+## Bonus: Making new connections
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.
@@ -124,6 +121,7 @@ The services that are currently supported are:
- `twitter`
- `facebook_profile` (this will also connect Facebook pages!)
- `foursquare`
+- `tumblr`
- `myspace`
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!
View
133 Usage.md
@@ -1,3 +1,134 @@
# How to use the SoundCloud API Wrapper
-* fill me with text
+### The Basics
+
+You only need to `#import "SCAPI.h"` to include the wrapper headers.
+
+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.
+
+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.
+
+
+### Instantiating the API object
+
+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.
+
+To create an instance of `SCSoundCloudAPI` you can use the following code.
+
+ SCSoundCloudAPIConfiguration *scAPIConfig = [SCSoundCloudAPIConfiguration configurationForProductionWithConsumerKey:CLIENT_KEY
+ consumerSecret:CLIENT_SECRET
+ callbackURL:[NSURL URLWithString:CALLBACK_URL]];
+ // scAPI is a instance variable
+ scAPI = [[SCSoundCloudAPI alloc] initWithDelegate:self
+ authenticationDelegate:authDelegate
+ apiConfiguration:scAPIConfig];
+
+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).
+
+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*.
+
+
+### The Authentication Delegate (The easy way)
+
+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.
+
+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.
+
+Here's some sample code for using all the other neat things the `SCAuthenticationDelegate` might provide:
+
+ #pragma mark SCSoundCloudAPIAuthenticationDelegate
+
+ - (void)soundCloudAPIDidAuthenticate:(SCSoundCloudAPI *)scAPI;
+ {
+ // big cheers!! the user sucesfully signed in
+ }
+
+ - (void)soundCloudAPIDidResetAuthentication:(SCSoundCloudAPI *)scAPI;
+ {
+ // the user did signed off
+ }
+
+ - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI didFailToGetAccessTokenWithError:(NSError *)error;
+ {
+ // inform your user and let him retry the authentication
+ }
+
+### The Authentication Delegate (The "a little bit more manual, but still easy" way)
+
+There are however some situations where you might want to implement more stuff in the Auth Flow.
+
+* 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.
+
+* 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.
+
+* 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**.
+
+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.
+
+ - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI preparedAuthorizationURL:(NSURL *)authorizationURL;
+ {
+ // example for iOS
+ // One could also open a UIWebView and load the URL inside the app.
+ [[UIApplication sharedApplication] openURL:authorizationURL]; // you should warn the user before doing this
+ }
+
+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.
+
+ - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url;
+ {
+ return [scAPI handleOpenRedirectURL:url];
+ }
+
+ // AND / OR
+
+ - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions;
+ {
+ NSURL *launchURL = [launchOptions objectForKey:UIApplicationLaunchOptionsURLKey];
+ return [scAPI handleOpenRedirectURL:launchURL];
+ }
+
+As an alternative to authenticating using a browser you can also implement `-soundCloudAPI:preparedAuthorizationURL:` as follows to use the *user credentials flow*:
+
+ - (void)soundCloudAPI:(SCSoundCloudAPI *)scAPI preparedAuthorizationURL:(NSURL *)authorizationURL;
+ {
+ // open a view which asks the user for username & password
+ // example for iOS
+ MYCredentialsViewController *vc = [[[MyCredentialsViewController alloc] initWithDelegate:self] autorelease];
+ [navigationController pushViewController:vs animated:YES];
+ }
+
+ // after the user entered his credentials
+ - (void)credentialsController:(MYCredentialsViewController *)controller
+ didGetUsername:(NSString *)username
+ password:(NSString *)password;
+ {
+ // authorize with it
+ [scAPI authorizeWithUsername:username password:password];
+ }
+
+But consider that this bypasses one of the major reasons for using OAuth, by passing the user credentials through your app.
+
+
+### Invoking Requests on the API
+
+There is one central method for sending requests to the API:
+
+ - (id)performMethod:(NSString *)httpMethod
+ onResource:(NSString *)resource
+ withParameters:(NSDictionary *)parameters
+ context:(id)context
+ userInfo:(id)userInfo;
+
+This method returns an `id` which you can use to cancel the request later using `-cancelConnection:` method.
+
+The context can be used to pass data to the delegate callbacks. It is retained for as long as the underlying Connection exists.
+
+### The Connection Delegate Protocol
+
+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?
+
+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.
+
+### So, yeah, the request comes back, what do I do now?
+
+Since in an existing app you usually already have a JSON parser, use it to parse the data that comes back in
Please sign in to comment.
Something went wrong with that request. Please try again.