Permalink
Browse files

- update project settings

- update submodule
- remove access before requesting access
- change documentation
  • Loading branch information...
1 parent a098a55 commit 3c357aa1cbecb1d97ca11c6cbd953e4ba113a291 @anagromataf anagromataf committed Aug 19, 2011
Showing with 159 additions and 63 deletions.
  1. +42 −49 Usage.md → GeneralUsage.md
  2. +1 −1 Outsourced/SoundCloudUI
  3. +113 −13 README.md
  4. +2 −0 SoundCloudAPI.xcodeproj/project.pbxproj
  5. +1 −0 Sources/SoundCloudAPI/SCSoundCloud.m
@@ -1,58 +1,51 @@
-# How to use the SoundCloud API Wrapper
+# How to use the SoundCloud API directly
-If all you want to do is uploading a track to SoundCloud, you should have a look at [SoundCloudUI]() (iOS only). __The SoundCloudUI should always be your first choice.__ It extends the API with a `SCLoginViewController` and a `SCSharingViewController`.
+## Authentication
-### The Basics
+### Using the SCLoginViewController (iOS only)
-You only need to `#import "SCAPI.h"` to include the wrapper headers. The objects you should be most interested in are `SCSoundCloud` for configuration and `SCRequest` for invoking request on the API.
+Assuming your app isn't authenticated (`[SCSoundCloud account] == nil`) or you want to relogin you can use the following example to present a login screen.
-
-### Configure your App
-
-To configure you App you have to set your App's _Client ID_, it's _Client Secret_ and it's _Redirect URL_. The best way to do this is in the `initialize` class method in your app delegate.
-
- + (void)initialize;
+ @implementation YourViewController
+
+ // ...
+
+ - (void)login;
{
- [SCSoundCloud setClientID:@"<Client ID>"
- secret:@"<Client Secret>"
- redirectURL:[NSURL URLWithString:@"<Redirect URL>"]];
+ [SCSoundCloud requestAccessWithPreparedAuthorizationURLHandler:^(NSURL *preparedURL){
+
+ SCLoginViewController *loginViewController;
+ loginViewController = [SCLoginViewController loginViewControllerWithPreparedURL:preparedURL
+ completionHandler:^(NSError *error){
+
+ if (SC_CANCELED(error)) {
+ NSLog(@"Canceled!");
+ } else if (error) {
+ NSLog(@"Ooops, something went wrong: %@", [error localizedDescription]);
+ } else {
+ NSLog(@"Done!");
+ }
+ }];
+
+ [self presentModalViewController:loginViewController
+ animated:YES];
+
+ }];
}
+
+ @end
-You will get your App's _Client ID_, it's _Client Secret_ from [the SoundCloud page where you registered your App](http://soundcloud.com/you/apps). There you should register your App with it's name and a _Redirect URL_. That _Redirect URL_ should comply to a protocol that is handled by your app. See [this page](http://iphonedevelopertips.com/cocoa/launching-your-own-application-via-a-custom-url-scheme.html) on how to set up the protocol in your App. For the curious: in the wrapper we're using _Redirect URL_ instead of _Redirect URI_ because the underlying type is of `NSURL`.
-
-
-### Authentication
-
-#### The easy way (iOS only)
-
-Have a look at [SoundCloudUI](). It extends the API with a `SCLoginViewController`.
-
-#### The more complicated way
+### The more complicated way (a.k.a. Mac OS X)
To request access for a certain user, you have to call the class method `+[SCSoundCloud requestAccessWithPreparedAuthorizationURLHandler:]`. With this call you trigger an authentication process. In this process a web page has to be opened where the user can sign in to SoundCloud and give your App access to it's account.
[SCSoundCloud requestAccessWithPreparedAuthorizationURLHandler:^(NSURL *preparedURL){
// Load the URL in a web view or open it in an external browser
+ [[NSWorkspace sharedWorkspace] openURL:preparedURL];
}];
If you open the URL in an external browser, your app delegate has to handel the redirect URL.
-__On iOS:__s
-
- - (BOOL)application:(UIApplication *)application
- openURL:(NSURL *)url
- sourceApplication:(NSString *)sourceApplication
- annotation:(id)annotation;
- {
- BOOL handled = [SCSoundCloud handleRedirectURL:url];
- if (!handled) {
- NSLog(@"The URL (%@) could not be handled by the SoundCloud API. Maybe you want to do something with it.", url);
- }
- return handled;
- }
-
-__On Mac OS X:__
-
- (void)applicationDidFinishLaunching:(NSNotification *)aNotification;
{
[[NSAppleEventManager sharedAppleEventManager] setEventHandler:self
@@ -72,15 +65,15 @@ __On Mac OS X:__
}
}
-#### The Authenticated Account
+### The Authenticated Account
After a successful authentication, you have access to that account via the class method `[SCSoundCloud account]`. You should never keep a reference to this account. Always access the account with this method.
-#### Removen Access
+### Removen Access
To log out the authenticated user, you have to call the method `[SCSoundCloud removeAccess]`.
-### Invoking Requests on the API
+## Invoking Requests on the API
The best way to invoke a request on the API is by calling the class method (see below) on `SCRequest`. You can call this method without an account (nil) for anonymous requests or with the account you get from `[SCSoundCloud account]`. The response is handled in the block you have to pass in the call. There you get the underlying `NSURLResponse` (e.g., to access the status code), the body of the response or (if something went wrong) an error.
@@ -102,12 +95,12 @@ The best way to invoke a request on the API is by calling the class method (see
In case you would like to cancel the request, you need to keep a reference of the opaque object returned by that method call. Then you can cancel the request with `[SCRequest cancelRequest:obj]`.
-#### Providing Parameters
+### Providing Parameters
-If you have to provide parameters, you must create a NSDictionary containing the key value pairs. If a value is a NSURL (or a NSData ???) it is automatically treated as a multipart data.
+If you have to provide parameters, you must create a NSDictionary containing the key value pairs. If a value is a NSURL it is automatically treated as a multipart data.
-#### Sending Progress
+### Sending Progress
On long running request (e.g., if you upload a track), it is wise to provide the user a feedback how fare the upload is gone. Therefor you can pass a sending progress handler on invocation. This handler is called occasionally with the total and already sent bytes.
@@ -123,14 +116,14 @@ On long running request (e.g., if you upload a track), it is wise to provide the
}];
-### Listening for Notifications
+## Listening for Notifications
There are to types of notifications which you might have interest in:
- SCSoundCloudAccountDidChangeNotification
- SCSoundCloudDidFailToRequestAccessNotification
-#### SCSoundCloudAccountDidChangeNotification
+### SCSoundCloudAccountDidChangeNotification
This notification is send each time after the account did change. You could use this notification to update the user info.
@@ -174,7 +167,7 @@ This notification is send each time after the account did change. You could use
@end
-#### SCSoundCloudDidFailToRequestAccessNotification
+### SCSoundCloudDidFailToRequestAccessNotification
If something went wrong while requesting access to SoundCloud, the notification `SCSoundCloudDidFailToRequestAccessNotification` is send. To get more details about what, a NSError is provided in the userInfo.
@@ -194,6 +187,6 @@ If something went wrong while requesting access to SoundCloud, the notification
NSLog(@"Requesting access to SoundCloud did fail with error: %@", [error localizedDescription]);
}
-### Thats it!
+## Thats it!
If you haven't had a look at the [documentation of the SoundCloud API](http://developers.soundcloud.com/docs) you should continue there.
Submodule SoundCloudUI updated from c1778a to a55670
View
126 README.md
@@ -1,15 +1,6 @@
-# The SoundCloud API Wrapper for Cocoa
+# The SoundCloud API for Cocoa
-So you want to use SoundCloud in your iOS or OSX Desktop Application? Awesome. This little project will help you do it.
-
-If all you want to do is uploading a track to SoundCloud, you should have a look at [SoundCloudUI]() (iOS only). __The SoundCloudUI should always be your first choice.__
-
-The SoundCloud API Wrapper supports iOS from Version 4.0 and MacOS X from Leopard (10.6). It uses SoundClouds [OAuth2](http://oauth.net/2) API and henceforth includes the [NXOAuth2Client](http://github.com/nxtbgthng/OAuth2Client) project.
-
-
-* How to [integrate the SoundCloud API Wrapper into your Project](https://github.com/soundcloud/cocoa-api-wrapper/blob/master/Setup.md).
-* How to [use the SoundCloud API Wrapper](https://github.com/soundcloud/cocoa-api-wrapper/blob/master/Usage.md).
-* How to [share your Audio using SoundCloud](https://github.com/soundcloud/cocoa-api-wrapper/blob/master/Sharing.md).
+So you want to share your tracks in your iOS Application to SoundCloud? With this project you only need a few lines of code for doing that. The SoundCloud API supports iOS from Version 4.0 and MacOS X from Leopard (10.6). It uses SoundClouds [OAuth2](http://oauth.net/2) API and henceforth includes the [NXOAuth2Client](http://github.com/nxtbgthng/OAuth2Client) project.
Afraid of doing the journey alone? Don't be, there's a lot of places where you can find help:
@@ -21,6 +12,115 @@ Please keep in mind that all of this is under heavy development, and things migh
We document the [changes to the different versions](Changes.md). If you've used a previous version, please read it.
-But most important: Have fun building great apps!
+This guide assumes a few things:
+
+* You are using Xcode 4
+* You are using Git.
+
+## 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 SoundCloudAPI as a Git Submodule
+
+ git submodule add git://github.com/soundcloud/CocoaSoundCloudAPI.git SoundCloudAPI
+
+3. Update the Submodules
+
+ 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 dependencies" 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:
+
+ * `libSoundCloudAPI.a` (or `SoundCloudAPI.framework` for a Desktop projects)
+ * `QuartzCore.framework`
+ * `AddressBook.framework`
+ * `AddressBookUI.framework`
+ * `CoreLocation.framework`
+ * `Security.framework`
+ * `CoreGraphics.framework`
+
+4. Next step is to make sure that the Linker finds everything it needs: So go to the Build settings of the project and add the following to *Other Linker Flags*
+
+ -all_load -ObjC
+
+5. We need a few graphics: Please move the `SoundCloud.bundle` from the `SoundCloudAPI/Outsourced/SoundCloudUI/` directory to your Resources.
+
+Yay, done! Congrats! Everything is set up, and you can start using it.
+
+## Usage
+
+### The Basics
+
+You only need to `#import "SCUI.h"` to include the UI headers (or `#import <SoundCloudAPI/SCAPI.h>` on Desktop).
+
+### Configure your App
+
+To configure you App you have to set your App's _Client ID_, it's _Client Secret_ and it's _Redirect URL_. The best way to do this is in the `initialize` class method in your app delegate.
+
+ + (void)initialize;
+ {
+ [SCSoundCloud setClientID:@"<Client ID>"
+ secret:@"<Client Secret>"
+ redirectURL:[NSURL URLWithString:@"<Redirect URL>"]];
+ }
+
+You will get your App's _Client ID_, it's _Client Secret_ from [the SoundCloud page where you registered your App](http://soundcloud.com/you/apps). There you should register your App with it's name and a _Redirect URL_. That _Redirect URL_ should comply to a protocol that is handled by your app. See [this page](http://iphonedevelopertips.com/cocoa/launching-your-own-application-via-a-custom-url-scheme.html) on how to set up the protocol in your App. For the curious: in the wrapper we're using _Redirect URL_ instead of _Redirect URI_ because the underlying type is of `NSURL`.
+
+
+### Using the Share UI (iOS only)
+
+To share a track you just have to create a `SCShareViewController` with the URL to the file you want to share and present it on the current view controller. After a successful upload, the track info can be accessed in the completion handler.
+
+ - (void)upload;
+ {
+ NSURL *trackURL = // ... an URL to the audio file
+
+ SCShareViewController *shareViewController;
+ shareViewController = [SCShareViewController shareViewControllerWithFileURL:trackURL
+ completionHandler:^(NSDictionary *trackInfo, NSError *error){
+
+ if (SC_CANCELED(error)) {
+ NSLog(@"Canceled!");
+ } else if (error) {
+ NSLog(@"Ooops, something went wrong: %@", [error localizedDescription]);
+ } else {
+ // If you want to do something with the uploaded
+ // track this is the right place for that.
+ NSLog(@"Uploaded track: %@", trackInfo);
+ }
+ }];
+
+ // If your app is a registered foursquare app, you can set the client id and secret.
+ // The user will then see a place picker where a location can be selected.
+ // If you don't set them, the user sees a plain plain text filed for the place.
+ [shareViewController setFoursquareClientID:@"<foursquare client id>"
+ clientSecret:@"<foursquare client secret>"];
+
+ // We can preset the title ...
+ [shareViewController setTitle:@"Funny sounds"];
+
+ // ... and other options like the private flag.
+ [shareViewController setPrivate:NO];
+
+ // Now present the share view controller.
+ [self presentModalViewController:shareViewController animated:YES];
+ }
+
+Optionally you can preset set the *title*, a *cover image*, a *creation date* and a flag indicating if the track should be public or private. Look at `SCShareViewController.h` for details.
+
+### Using the API
+
+If you want to provide your own UI for sharing a track or you want to use the SoundCloud API for other purposes, have a look at the [General Usage]() or at [Sharing]().
+
+## Thats it!
-Your friends at SoundCloud.
@@ -40,6 +40,7 @@
F6525B8013D5B34A00ACAE8F /* SCSoundCloud+Private.m in Sources */ = {isa = PBXBuildFile; fileRef = F6525B7C13D5B34A00ACAE8F /* SCSoundCloud+Private.m */; };
F6622B6713D84A2B0057ADD0 /* Cocoa.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = F6622B6613D84A2B0057ADD0 /* Cocoa.framework */; };
F66BAD2E13D97FAB00996800 /* CoreLocation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = F66BAD2D13D97FAB00996800 /* CoreLocation.framework */; };
+ F6E37EAD13FE8B7100D6DDC0 /* libOAuth2Client.a in Frameworks */ = {isa = PBXBuildFile; fileRef = 94E5ADA4122C192900C7021A /* libOAuth2Client.a */; };
F6E88D2513D41F8A008B9CD5 /* SCConstants.h in Headers */ = {isa = PBXBuildFile; fileRef = F6E88D2313D41F8A008B9CD5 /* SCConstants.h */; };
F6E88D2613D41F8A008B9CD5 /* SCConstants.h in Headers */ = {isa = PBXBuildFile; fileRef = F6E88D2313D41F8A008B9CD5 /* SCConstants.h */; };
F6E88D2713D41F8A008B9CD5 /* SCConstants.m in Sources */ = {isa = PBXBuildFile; fileRef = F6E88D2413D41F8A008B9CD5 /* SCConstants.m */; };
@@ -144,6 +145,7 @@
isa = PBXFrameworksBuildPhase;
buildActionMask = 2147483647;
files = (
+ F6E37EAD13FE8B7100D6DDC0 /* libOAuth2Client.a in Frameworks */,
F615810C13FD142F0049FF2E /* libSoundCloudUI.a in Frameworks */,
F66BAD2E13D97FAB00996800 /* CoreLocation.framework in Frameworks */,
F64109B313D87F9F00561D0B /* CoreGraphics.framework in Frameworks */,
@@ -105,6 +105,7 @@ + (SCAccount *)account;
+ (void)requestAccessWithPreparedAuthorizationURLHandler:(SCPreparedAuthorizationURLHandler)aPreparedAuthorizationURLHandler;
{
+ [self removeAccess];
[[NXOAuth2AccountStore sharedStore] requestAccessToAccountWithType:kSCAccountType
withPreparedAuthorizationURLHandler:(SCPreparedAuthorizationURLHandler)aPreparedAuthorizationURLHandler];
}

0 comments on commit 3c357aa

Please sign in to comment.