-
Notifications
You must be signed in to change notification settings - Fork 8
Home
- Introduction
- The codebase
- The shortest possible API app!
- Discussion of the interface
- Building for Windows
- Building for OSX
- The OSX Test App
- Using the data
- Licensing
The SoundCloud C API Wrapper is intended to provide a lightweight, easy-to-use interface
to the SoundCloud REST API
It has been developed for Windows and OSX, and compiles with MSVC and XCode respectively.
The code is ANSI C, and is as small as possible without loss of functionality.
This API doesn’t impose structure on WHAT you retrieve or send to the API; it handles the
communication for you, so that connecting to the SoundCloud online API becomes easy.
You ALSO need to read the SoundCloud REST API docs, and get a feel for what sort of thing you want to do!
A good way to think of the role played by this API is that it gives you access to the SoundCloud API Console in a few lines of code, (and also works on the production server, not just the sandbox!).
Please grab the code from the git repo, or click here and we’ll have a quick walk through.
First off, let me explain the ugliness:
Compiling for Windows is complicated by the need for libCURL and libEAY , which aren’t native to the platform. So that you can be up and running right away, I’ve taken the liberty of compiling some static libs for Windows that will allow you to skip the libCURL and openSSL steps. The repo currently contains version 7.19.6 of cURL and version 0.9.8k of openSSL, compiled with VS2003 Standard, which, hopefully, will be compatible with most people’s dev environments. Anyway, this means you get libCURL and openssl folders in the repo so there’s no step that requires you to download a bunch of files and discover that nothing is compatible. From a security perspective, if you have ANY concerns then you must recompile! On the other hand, to start prototyping and testing, this will get you running immediately. Also, it gives you a build framework for you to drop your builds into!
TestApps contains the OS X Test Application which we’ll discuss later.
SoundCloudCAPI contains the library proper and subcomponents, so we’ll focus on that:
In the SoundCloudCAPI we find two subfolders, some project files and the code.
SoundCloudCAPI.h is the file that defines the API. Your application needs ONLY this file.
The Outsourced folder contains a patched version of libOAuth 0.5.3, which handles all the authentication for us!
The API consists of four cross-platform sourcefiles, plus one for Windows and one for OSX.
The test folder contains a very small application to test the API, which we’ll discuss now.
Let’s look at the code:
// Create the API instance with your registered details.
SoundCloudCAPI *scAPI=SoundCloudCAPI_CreateWithDefaultCallbackAndGetCredentials(
"UF6IeQtnCyWHu4gxKbGeDQ","7t94mY84FtvXSqhveryhYRzCGGJoKHlLi6BannW9Cg","",1);
// Are we authorized yet?
while (SoundCloudCAPI_EvaluateCredentials(scAPI)) {
char buffer[256];int code;
printf("Please Auth, then enter the verification code here: ");
scanf("%d",&code);sprintf(buffer,"%d",code);
SoundCloudCAPI_SetVerifier(scAPI, buffer);
}
// Go fetch some data.
void *data;unsigned long long datalen;int errnum;
int res=SoundCloudCAPI_performMethod(scAPI,"GET","/me",0,0,&errnum,&data,&datalen);
if (!res) printf("Got back: %s\n",data);
// Tidy up!
SoundCloudCAPI_Delete(scAPI);
getchar();
Hopefully you can see a rough shape to this-
- Create the API Instance
- Check to see if we’re authorized. If we’re not, pester the user to auth and get us a verifier number.
- Go get some data! Drop it straight to the console!
- Tidy up and exit.
Before we go any further, we have to cover the absolute bare minimum any developer needs to know about OAuth
OAuth is an authentication protocol. This API is coded to make your (the developer) experience as similar as possible to the user experience.
I’m not going to explain how it works underneath. Instead, here’s what the user sees:
- They load your app and go to do something that requires authorisation (anything on the server).
- A webpage pops up, asking them to log into the site, and to confirm that they want to go ahead.
- They click ok, they get a Verifier code to give you, and everything just works!
So, with this API, what do YOU, the developer see?
- First up, you hit this page: register your application here
- You fill in the details, and you get two long base64 encoded strings. That’s where the strings in the _Create line come from. Those strings map to your registration, and what you type in when you register is what the user sees when they’re asked to authorize. You do this every time you build a new app.
- You call _Create with those strings, and now the API knows who you are and what’s going on. The code in the sample will look for a previous auth (on the user’s computer) that it can use.
- You call _EvaluateCredentials. The API now takes a look at the auth from the user’s computer (if there was one). If there wasn’t one, it sets the ball rolling, and walks through the process until we have a webpage URL for the user to auth with.
- When the user DOES auth, the SoundCloud site gives them a six-digit verification code, which you’ll need to hand to the API with _SetVerifier.
- If the _EvaluateCredentials call didn’t find a valid auth the first time, it’ll check again. If we’ve popped up the page for the user and they’ve clicked ok, it’ll detect that, otherwise it’ll pop up the page again in the vain hope they’ll change their minds. If they’ve clicked ok, the auth is saved for you (keychain/registry), and the call returns 0 (we’re authorised and all is good).
- Now we’re authorised, we can do as we please! You use _performMethod (or _performMethodWithCallback, it’s asynchronous twin) for all
the talking. You pass in requests, and it gives you back data! These functions will happily upload files and artwork imagery, post comments,
fetch track details; whatever you need from the API. - Tidy up and exit.
Hey, it sounds like there’s a lot going on behind the scenes with all this Auth stuff. Yes. There is. You can handle it yourself, and it’s been made about as simple as possible to do so, but you’ll get to market faster if you forget ALL about it. ;)
This API started out as a C port of the SoundCloud Cocoa API which uses Objective-C delegates. In a mirroring of the philosophy, we use callback functions in the API. You can add a callback to handle the Auth process, or you
can use the default. You can add a callback and get asynchronous _performMethod routines, or you can use the synchronous versions.
In the traditional C style, whenever we configure the usage of a callback, the user is invited to specify some void* that will be passed to the callback whenever it is invoked. However, usage of callbacks is ALWAYS optional, and a synchronous approach is always available.
Also, we use opaque data structures here. You never do ANYTHING to the SoundCloudCAPI object directly. There are functions for that.
Open the .sln, pick debug_dll. Build.
Hey, why doesn’t the test script run?
Because the DLL needs to be in the folder next to it.
Do you want a static lib or a dll? The builds in git are, sadly, a little rough around the edges at the moment, but I’m sure they’ll get some love before too long. If you’re building/using a DLL SCAPI_WIN_DLL must be defined so you get the imports/exports.
The current git has a binary (yes, I know, but you’ll thank me later) of a release build of cURL (without ldap support) and libeay/libssleay, so this builds in one step. Out pops the DLL. Magic.
OSX builds as a framework, which means you need to compile something that has a bundle, and configure your project to copy it in.
See the test app for an example.
You can recompile it as a static lib if it helps you. There aren’t any special details attached to that.
The Cocoa wrapper comes with a very fully-featured test app, which has been gutted into the app you’ll find in TestApps.
In there you’ll see a lot of code similar to the code in this documentation. This can be a very quick way to test out the API.
The “delete all my tracks” function has been removed since it seemed a little overkill to add a C JSON parser to the project
for that one feature.
There’s a slight gotcha in the app you should be aware of too: the callback function calls a Cocoa function to actually
handle the callback. This is called from a separate posix thread (that doesn’t have an NSAutoreleasePool), so it can leak.
Once you get your XML or JSON back from the API, you’ll probably want to do something with it.
Please allow me to recommend:
I AM NOT A LAWYER AND THIS IS NOT LEGAL ADVICE.
This API is released under an MIT license. This code uses libOAuth, which is MIT license. The xmalloc code is disabled to avoid the potential of LGPL infringment.
libcurl is MIT, and openSSL is BSD-style. See this page for details about license mixing.
Compiling the API into your code and shipping is just fine under the MIT license.
However, linking in openSSL or libcurl might complicate matters.
On OSX you have openSSL and libcurl installed by default, so there’s no need to link to them.
On OSX, this API is MIT license.
On Windows, you should probably either compile the whole thing as a DLL (already supported), or compile curl / openssl into a support dll, and compile the API into your code.