Skip to content

Discussion of the Interface

Jump to bottom Edit New page
DaveGamble edited this page Sep 13, 2010 · 1 revision

Discussion of the interface

  • Create
  • Delete
  • Credentials
  • Authorization and Credential Status
  • Response format
  • Asynch method callbacks
  • Parameters
  • Perform Method
  • Default authentication routines
  • Logging

Make sure you read the Introduction first!

SoundCloudCAPI.h contains the entire interface.

Create

There are three _Create functions:

  • _Create(details)
  • _CreateWithCallback(details,callback details)
  • _CreateWithDefaultCallbackAndGetCredentials(details)

It is expected that SoundCloud_CreateWithDefaultCallbackAndGetCredentials will be what you usually use.
It simply calls SoundCloudCAPI_CreateWithCallback(details,SoundCloudCAPI_DefaultAuthenticationCallback) and then
SoundCloudCAPI_DefaultAuthenticationLoad().

If you call _CreateWithCallback() you can provide your own authentication callback.
If you call _Create(), no callback will be used. We’ll discuss this later.

‘details’ here consists of 4 values: key,secret,callbackURL,server.
You get key/secret when you register your app, as above.
callbackURL can be NULL/"" or a URL which will trigger your app once the user has authed.
The server flag is used to select sandbox vs production: SCProductionType_Sandbox / SCProductionType_Production.

Delete

  • _Delete(scAPI)

Simple enough? After this call, scAPI is no longer a valid pointer, and must be discarded.
All memory is free().

Somewhat unusually, you CAN call _Delete while there are asynchronous transfers in progress
without ill effect. HOWEVER, if you do this, your callback will receive the stale pointer to the deleted API,
which it must not use.

Credentials

  • _SetCredentials
  • _GetCredentials
  • _RemoveCredentials

These calls configure the access credentials that the API uses to connect to the server.
If you are using the DefaultCallback for authorisation, then you will never need these.
However, if you implement your own callback, these functions allow you to specify/retrieve
the credential data. The data is returned to you as a null-terminated string for you to save.
Return it to _SetCredentials as a null-terminated string. DO NOT PROCESS THE STRING.
The string format is simple, although necessarily impossible to modify (since it’s crypto).
It is strongly suggested that you do not try to parse the string. EvaluateCredentials is
what you need.

Authorization and Credential Status

  • _EvaluateCredentials
  • _GetUserAuthorizationURL
  • _SetVerifier

_ EvaluateCredentials is a state machine that handles all the OAuth for you.
It returns SCAuthenticationStatus_Authenticated (0) when you're ready to rock. If you specified a callback (or you're using the default), you'll see SCAuthenticationStatus_WillCallback (-1) until you’re authenticated, when you’ll see 0.

If you didn’t specify a callback, then the return code makes YOU the callback.

  • SCAuthenticationStatus_ErrorCouldNotRequest == 3
    You have no internet connection, or the server is hiding.
  • SCAuthenticationStatus_UserMustAuthorize == 2
    The user needs to auth you, with the URL.
  • SCAuthenticationStatus_ErrorCouldNotAccess == 1
    Server said no. No internet connection perhaps?
  • SCAuthenticationStatus_Authenticated == 0
    You’re set!
  • SCAuthenticationStatus_CredentialsHaveChanged == 256
    This value is ORR-ed in to tell you that you need to call _GetCredentials
    and save the result somewhere.

If you specified a callback that was your own code, then your code is called
with status = value from above, and everything works the same way.

If you’re using the default callback:

  • It saves credentials whenever they change
  • It logs an error (more on this later) when you get an _ErrorCouldNot x
  • It calls _GetUserAuthorizationURL, and pops that URL up when _UserMustAuthorize

_GetUserAuthorizationURL will return as a string the URL that the user needs to visit in order to authenticate.

_SetVerifier accepts as a string the verification code provided by SoundCloud when they authed. (eg “123456”).

If you specified a callback URL when you call Create, you can receive the verification code automatically; parse the URL you get back (see the code in the OSX Test App), which will have “?oauth_verifier=123456” appended.

Response format

  • _SetResponseFormat

Do you prefer SCResponseFormatXML or SCResponseFormatJSON ?

Asynch method callbacks

If you’re using asynch data transfer, you probably want a progress bar, right?

void (*SoundCloudCAPICallback)(SoundCloudCAPI *api,int reason,int errornum,void *data,unsigned long long count,unsigned long long total,void *user);

  • SoundCloudCAPICallback
    This gets called with a “reason” (for calling) code, which is:
  • SoundCloudCAPICallback_didFinishWithData == 0
    Transfer complete! The server sent us a reply.
    data points to the data, count=total=the length of the data. errornum=0.
  • SoundCloudCAPICallback_didFailWithError == 1
    Something went wrong (in transfer). Look at errornum.
    errornum = the error number.
  • SoundCloudCAPICallback_didReceiveBytes == 2
    We’re getting some data from server. count=total bytes so far.
  • SoundCloudCAPICallback_didSendBytes == 3
    We’re uploading to the server now. We’ve sent count bytes out of total.

Parameters

When you PUT or POST things to the server, you probably want to specify some parameters.
For instance, using “comment[body]” allows you to post comment text. You can add
as many parameters as you please by allocating an array of SoundCloudCAPI_Parameter structs,
and filling them in as follows:

  • Sending a text value:
    key=“comment[body]”
    value=“Hey, That was a great track! I really liked what you did with the cowbell!”
    value_len=0 (will be strlen(value) on return)
    filename=0
  • Sending data / a file
    key=“track[asset_data]”
    value=ptr to the data from the file in memory
    value_len=size of the data array
    filename=“Output 1-2.mp3”

You supply a pointer to this array and the size when you call _performMethod, and off it goes!

Perform Method

  • _performMethod
  • _performMethodWithCallback

First off, the difference: WithCallback will spawn a thread to do the request, and will call your callback. It has NO return value. _performMethod, on the other hand, takes a pointer to a void* and a pointer to a long long, and returns the data to you synchronously. It tells you if it has failed on return, and provides an errornum, just like a callback would get.

_performMethod[WithCallback] is best explained by example:

In the following, x is either pointers to errornum/data/data_len (for _performMethod), or the callback function and user data.


// Get me my tracks:
SoundCloudCAPI_performMethod(scAPI,"GET","/me/tracks",0,0,x);

// Delete a track: 
SoundCloudCAPI_performMethod(scAPI,"DELETE","/tracks/123456",0,0,x);

// Get the comments for a track: 
SoundCloudCAPI_performMethod(scAPI,"GET","/tracks/123456/comments",0,0,x);

// Update a track name: 
SoundCloudCAPI_Parameter param;param.key="track[title]";param.value="New track name!";
SoundCloudCAPI_performMethod(scAPI,"PUT","/tracks/123456",&param,1,x);

// Post a comment: 
SoundCloudCAPI_Parameter param2;param2.key="comment[body]";param2.value="Needs more cowbell.";
SoundCloudCAPI_performMethod(scAPI,"POST","/tracks/123456/comments",&param2,1,x);

// Upload an mp3:
const char *filename="freshbeats.mp3";
FILE *f=fopen(filename);fseek(f,0,SEEK_END);int datalen=ftell(f);fseek(f,0,SEEK_SET);
char *data=malloc(datalen);fread(data,1,datalen,f);fclose(f);

SoundCloudCAPI_Parameter params[2];
params[0].key="track[title]";
params[0].value="Fresh beats.";
params[1].key="track[asset_data]";
params[1].value=data;
params[1].value_len=datalen;
params[1].filename=filename;
SoundCloudCAPI_performMethod(scAPI,"POST","/me/tracks",params,2,x);

Default authentication routines

  • _DefaultAuthenticationCallback
  • _DefaultAuthenticationLoad
  • _DefaultAuthenticationSave
  • _DefaultAuthenticationOpenAuthURL

Maybe you want to use your own code for part of the authentication process, and rely on the default for some other stuff?
You can use Load and Save together, or use OpenAuthURL to save writing the code.
You can handle the cases you want to, and simply invoke DefaultAuthenticationCallback in any unhandled cases.

Logging.

  • _SetLogLevel

How much do you want the API to leak out about what it’s doing?
By default it is silent. You can get logging to stderr for Errors or Debug.

Add a custom footer
Add a custom sidebar
Clone this wiki locally