View source for Using C4A with libSparrowNet

= Features of libSparrowNet =

Skeezix created a quite neat score submit system with his Compo4all. Unfortunately his client implementation has some disadvantages.
* You have to use the spaghetti client, which is small and practical, but only exists for the pandora officially.
* For loading game lists, high scores and similar you always need to do HTTP magic on your own.
* You needed skeezix Manager to create, edit or delete accounts.

So Ziz started to reimplement the behaviour of the spaghetti client and the account management in his sparrowNet lib, which is in fact a part of sparrow3D, but doesn't need the (big) libSparrow3D.so file. Furthermore he encapsulated the HTTP magic to practical functions you just have to call. All the functions are threaded and most of them can be used parallel, e.g. loading three highscore at one time. Loading scores may need some time and parallizing stuff really helps here.

A complete documentation can be found [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#Compo4all_stuff here]

= The basic system =

This article will not explain the possibilities of the whole libSparrowNet here. However as the C4A part uses it, you have to init it at begin with [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spInitNet spInitNet] and to quit it at program termination with [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spQuitNet spQuitNet].

The idea is, that every task is done in the background and you can get informations about the progress and the time left until timeout to show it to the user. If you e.g. commit a score you can do it in the background and the player can continue playing the next game to get an even higher score.

Let's assume you just started a task. It doesn't matter, whether you want to get the list of games, scores of a specific game, submit a score for a game or even edit the accont: Every task uses the same background thread structure. Most of the times you have two methods to call the functions, e.g. [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AGetGame spNetC4AGetGame] and [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AGetGameParallel spNetC4AGetGameParallel]. Only one function of the first kind can run at one time. This is easy, but as you see, you can't run two task (e.g. getting high scores of different games) at ones. For this you can use the ...Parallel functions. However these return a handle you have to keep and to free with [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4ADeleteTask spNetC4ADeleteTask] if you are done. This article will not explain this in detail here, but the documentation should explain it quite well. Everything explained here works also for the ...Parallel functions, just keep in mind to add "Parallel" to the function and to keep and free the task handle.

With [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AGetStatus spNetC4AGetStatus] you can get the status of the running process.
* SP_C4A_PROGRESS means a process is running right now. This also means, that no other process can be started (except with the ...Parallel functions)
* SP_C4A_OK means, that the last process exited without errors. Get the result with [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AGetTaskResult spNetC4AGetTaskResult]. Even if everything went well, that doesn't mean, that your task was fulfilled! So don't forget to check afterwards.
* SP_C4A_ERROR means, that the last process exited with errors.

Every task is started with a time out. After this time the task is canceled. However you can cancel the task on yourself of course, too, e.g. if the user don't want to wait anymore. Use [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4ACancelTask spNetC4ACancelTask] for this. You get the remaining time until the time out with [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AGetTimeOut spNetC4AGetTimeOut].

= The functions =

The functions you can call are:
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AGetProfile spNetC4AGetProfile]
: This function does not work parallel. It just loads the profile if it exists (!) for later use. You need such a profile! If the loading fails, you have to create an account or tell the user to do so with one of the compo4all managers.
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AFreeProfile spNetC4AFreeProfile]
: Frees the profile. In memory. It doesn't delete it, just frees the pointer. ;)
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AGetGame spNetC4AGetGame]
: Fills a list of all available games on skeezix c4a server.
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4ADeleteGame spNetC4ADeleteGame]
: Deletes the list created with the function above. It doesn't delete anything on skeezix server. ;)
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AGetScore spNetC4AGetScore] and [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AGetScoreOfMonth spNetC4AGetScoreOfMonth]
: Load the scores of a game on skeezix server. The second function loads only scores of a specific month.
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4ADeleteScore spNetC4ADeleteScores]
: Deletes the list created with the functions above.
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4ACommitScore spNetC4ACommitScore]
: Commits a score. This is, what the spaghetti client would do. The platform identifier (e.g. "pandora" for the Open Pandora or "gcw" for the GCW Zero) are set by libSparrowNet automaticly. If you add a highscore list to the call, it will check, whether the user already submitted this score. This is practical, if you didn't have a connection at the last submit attempt. So the easist way is to save every highscore local, to get the available highscore from skeezix server and to commit everything you have - libSparrowNet will not commit scores twice.
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4ACreateProfile spNetC4ACreateProfile]
: Creates a new profile locally and on skeezix server. The local c4a-prof file will be on different locations depending on the target system.
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4ADeleteAccount spNetC4ADeleteAccount]
: Really deletes your c4a-prof file and the account on skeezix server. This CAN'T be undone easily (in fact if you edit the account again with the same unique ID, although it was deleted, it is restored, but for this you need a backup of your c4a-prof file or at least the unique id). So be careful with this function.
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4AEditProfile spNetC4AEditProfile]
: Edits a given profile. As the unique id stays, this changes the short and long username in every score submitted with this account.
* [http://ziz.gp2x.de/documentation/files/sparrowNet-h.html#spNetC4ADeleteProfileFile spNetC4ADeleteProfileFile]
: Deletes the profile file on the system, but not in skeezix server.

= Example =

This small example will load a profile, load the scores of a game and if a profile was loaded correctly commit a score (if this isn't in the list loaded before and commited already):

<syntaxhighlight lang="cpp">
  spInitNet();
  
  //Getting the profile
  spNetC4AProfilePointer profile = spNetC4AGetProfile();
  if (profile) //Did it work?
  {
    printf("Your profile:\n");
    printf("Long Name: %s\n",profile->longname);
    printf("Short Name: %s\n",profile->shortname);
    printf("E-Mail: %s\n",profile->email);
    printf("Password: %s\n",profile->password);
  }
  else
    printf("No profile found. Put it to this folder or create it with compo4all!\n");
  
  //Loading the scores of game_name. If the profile was loaded only
  //the scores of this user will be added to the list.
  spNetC4AScorePointer score;
  spNetC4AGetScore(&score,profile,"game_name",10000); //10000 ms timeout
  //The task is running now, we could do other things and show the timeout counter.
  //But we will just wait:
  while (spNetC4AGetStatus() == SP_C4A_PROGRESS)
    //sparrow3D has a function for this, but I don't want to use this bloated lib here.
    //Furthermore in your game you probably not just cycle without doing anything.
    #ifdef WIN32
      Sleep(1);
    #else
      usleep(200);
    #endif
  if (spNetC4AGetStatus() == SP_C4A_OK)
  {
    //Everything went fine, let's print the high score
    spNetC4AScorePointer mom = score;
    while (mom)
    {
      //the time are the ms since 1.1.1970, so we need to convert it.
      struct tm * local = localtime (&(mom->commitTime));
      printf(" %2i.%2i.%i - %2i:%02i: %s (%s) - %i\n",
        local->tm_mday,local->tm_mon+1,local->tm_year+1900,
        local->tm_hour,local->tm_min,mom->longname,mom->shortname,mom->score);
      mom = mom->next;
    }
  }
  else
    printf("Fetshing Highscore failed with status code: %i\n",spNetC4AGetStatus());
  
  //If we have a profile let's submit something
  if (profile)
  {
    //Please don't do this for real games, this will really submit scores to the game
    if (spNetC4ACommitScore(profile,"game_name",10000,&score))
      printf("Submit failed. Probably is the score already in the high score\n");
    else
    {
      while (spNetC4AGetStatus() == SP_C4A_PROGRESS)
      #ifdef WIN32
        Sleep(1);
      #else
        usleep(200);
      #endif
      if (spNetC4AGetStatus() == SP_C4A_OK)
        printf("Submit succeded\n");
      else
        printf("Submit failed with status code: %i\n",spNetC4AGetStatus());
  }
  
  //Winter wrap up:
  if (score)
    spNetC4ADeleteScores(&score);
  if (profile)
    spNetC4AFreeProfile(profile);
  spQuitNet();
</syntaxhighlight>