Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 193 lines (141 sloc) 8.957 kb
3c357aa @anagromataf - update project settings
anagromataf authored
1 # How to use the SoundCloud API directly
6ab319a @Gernot Starting new documentation
Gernot authored
2
3c357aa @anagromataf - update project settings
anagromataf authored
3 ## Authentication
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
4
3c357aa @anagromataf - update project settings
anagromataf authored
5 ### Using the SCLoginViewController (iOS only)
5a6fd3e @Gernot Documentation updated
Gernot authored
6
3c357aa @anagromataf - update project settings
anagromataf authored
7 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.
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
8
3c357aa @anagromataf - update project settings
anagromataf authored
9 @implementation YourViewController
10
11 // ...
12
13 - (void)login;
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
14 {
3c357aa @anagromataf - update project settings
anagromataf authored
15 [SCSoundCloud requestAccessWithPreparedAuthorizationURLHandler:^(NSURL *preparedURL){
16
17 SCLoginViewController *loginViewController;
18 loginViewController = [SCLoginViewController loginViewControllerWithPreparedURL:preparedURL
19 completionHandler:^(NSError *error){
20
21 if (SC_CANCELED(error)) {
22 NSLog(@"Canceled!");
23 } else if (error) {
24 NSLog(@"Ooops, something went wrong: %@", [error localizedDescription]);
25 } else {
26 NSLog(@"Done!");
27 }
28 }];
29
30 [self presentModalViewController:loginViewController
31 animated:YES];
32
33 }];
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
34 }
3c357aa @anagromataf - update project settings
anagromataf authored
35
36 @end
5a6fd3e @Gernot Documentation updated
Gernot authored
37
3c357aa @anagromataf - update project settings
anagromataf authored
38 ### The more complicated way (a.k.a. Mac OS X)
5a6fd3e @Gernot Documentation updated
Gernot authored
39
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
40 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.
5a6fd3e @Gernot Documentation updated
Gernot authored
41
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
42 [SCSoundCloud requestAccessWithPreparedAuthorizationURLHandler:^(NSURL *preparedURL){
43 // Load the URL in a web view or open it in an external browser
3c357aa @anagromataf - update project settings
anagromataf authored
44 [[NSWorkspace sharedWorkspace] openURL:preparedURL];
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
45 }];
46
47 If you open the URL in an external browser, your app delegate has to handel the redirect URL.
5a6fd3e @Gernot Documentation updated
Gernot authored
48
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
49 - (void)applicationDidFinishLaunching:(NSNotification *)aNotification;
50 {
51 [[NSAppleEventManager sharedAppleEventManager] setEventHandler:self
52 andSelector:@selector(handleURLEvent:withReplyEvent:)
53 forEventClass:kInternetEventClass
54 andEventID:kAEGetURL];
55 }
56
57 - (void)handleURLEvent:(NSAppleEventDescriptor*)event
58 withReplyEvent:(NSAppleEventDescriptor*)replyEvent;
5a6fd3e @Gernot Documentation updated
Gernot authored
59 {
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
60 NSString* url = [[event paramDescriptorForKeyword:keyDirectObject] stringValue];
61
62 BOOL handled = [SCSoundCloud handleRedirectURL:[NSURL URLWithString:url]];
63 if (!handled) {
64 NSLog(@"The URL (%@) could not be handled by the SoundCloud API. Maybe you want to do something with it.", url);
65 }
5a6fd3e @Gernot Documentation updated
Gernot authored
66 }
67
3c357aa @anagromataf - update project settings
anagromataf authored
68 ### The Authenticated Account
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
69
70 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.
71
3c357aa @anagromataf - update project settings
anagromataf authored
72 ### Removen Access
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
73
74 To log out the authenticated user, you have to call the method `[SCSoundCloud removeAccess]`.
5a6fd3e @Gernot Documentation updated
Gernot authored
75
3c357aa @anagromataf - update project settings
anagromataf authored
76 ## Invoking Requests on the API
5a6fd3e @Gernot Documentation updated
Gernot authored
77
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
78 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.
79
80 SCAccount *account = [SCSoundCLoud account];
81
82 id obj = [SCRequest performMethod:SCRequestMethodGET
83 onResource:[NSURL URLWithString:@"https://api.soundcloud.com/me.json"]
84 usingParameters:nil
85 withAccount:account
86 sendingProgressHandler:nil
87 responseHandler:^(NSURLResponse *response, NSData *data, NSError *error){
88 // Handle the response
89 if (error) {
90 NSLog(@"Ooops, something went wrong: %@", [error localizedDescription]);
91 } else {
92 // Check the statuscode and parse the data
93 }
94 }];
95
96 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]`.
97
3c357aa @anagromataf - update project settings
anagromataf authored
98 ### Providing Parameters
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
99
3c357aa @anagromataf - update project settings
anagromataf authored
100 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.
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
101
102
3c357aa @anagromataf - update project settings
anagromataf authored
103 ### Sending Progress
5a6fd3e @Gernot Documentation updated
Gernot authored
104
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
105 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.
5a6fd3e @Gernot Documentation updated
Gernot authored
106
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
107 [SCRequest performMethod:SCRequestMethodPOST
108 onResource:[NSURL URLWithString:@"https://api.soundcloud.com/tracks"]
109 usingParameters:parameters
110 withAccount:account
111 sendingProgressHandler:^(unsigned long long bytesSent, unsigned long long bytesTotal){
112 self.progressView.progress = (float)bytesSent / bytesTotal;
113 }
114 responseHandler:^(NSURLResponse *response, NSData *data, NSError *error){
115 // Handle the response
116 }];
5a6fd3e @Gernot Documentation updated
Gernot authored
117
118
3c357aa @anagromataf - update project settings
anagromataf authored
119 ## Listening for Notifications
5a6fd3e @Gernot Documentation updated
Gernot authored
120
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
121 There are to types of notifications which you might have interest in:
122
123 - SCSoundCloudAccountDidChangeNotification
124 - SCSoundCloudDidFailToRequestAccessNotification
125
3c357aa @anagromataf - update project settings
anagromataf authored
126 ### SCSoundCloudAccountDidChangeNotification
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
127
128 This notification is send each time after the account did change. You could use this notification to update the user info.
129
130 @implementation MyClass
131
132 - (id)init;
133 {
134 self = [super init];
135 if (self) {
136 [[NSNotificationCenter defaultCenter] addObserver:self
137 selector:@selector(accountDidChange:)
138 name:SCSoundCloudAccountDidChangeNotification
139 object:nil];
140 }
141 return self;
142 }
143
144 - (void)dealloc;
145 {
146 [[NSNotificationCenter defaultCenter] removeObserver:self];
147 [super dealloc];
148 }
149
150 - (void)accountDidChange:(NSNotification *)aNotification;
151 {
152 SCAccount *account = [SCSoundCloud account];
153
154 if (account) {
155 [SCRequest performMethod:SCRequestMethodGET
156 onResource:[NSURL URLWithString:@"https://api.soundcloud.com/me.json"]
157 usingParameters:nil
158 withAccount:account
159 sendingProgressHandler:nil
160 responseHandler:^(NSURLResponse *response, NSData *data, NSError *error){
161 // Update the user info
162 }];
163 } else {
164 // Maybe you would like to update your user interface to show that ther is no account.
165 }
166 }
167
168 @end
169
3c357aa @anagromataf - update project settings
anagromataf authored
170 ### SCSoundCloudDidFailToRequestAccessNotification
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
171
172 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.
173
174 - (id)init;
175 {
176 // ...
177 [[NSNotificationCenter defaultCenter] addObserver:self
178 selector:@selector(didFailToRequestAccess:)
179 name:SCSoundCloudDidFailToRequestAccessNotification
180 object:nil];
181 // ...
182 }
183
184 - (void)didFailToRequestAccess:(NSNotification *)aNotification;
185 {
186 NSError *error = [[aNotification userInfo] objectForKey:kNXOAuth2AccountStoreError];
187 NSLog(@"Requesting access to SoundCloud did fail with error: %@", [error localizedDescription]);
188 }
5a6fd3e @Gernot Documentation updated
Gernot authored
189
3c357aa @anagromataf - update project settings
anagromataf authored
190 ## Thats it!
5a6fd3e @Gernot Documentation updated
Gernot authored
191
7544dd0 @anagromataf Update documentation to the new implementation.
anagromataf authored
192 If you haven't had a look at the [documentation of the SoundCloud API](http://developers.soundcloud.com/docs) you should continue there.
Something went wrong with that request. Please try again.