recipes/fusilli-client/files/sparrowNet.h

   1  /* This file is part of sparrow3d.
   2   * Sparrow3d is free software: you can redistribute it and/or modify
   3   * it under the terms of the GNU General Public License as published by
   4   * the Free Software Foundation, either version 2 of the License, or
   5   * (at your option) any later version.
   6   *
   7   * Sparrow3d is distributed in the hope that it will be useful,
   8   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   9   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10   * GNU General Public License for more details.
  11   *
  12   * You should have received a copy of the GNU General Public License
  13   * along with Foobar.  If not, see <http://www.gnu.org/licenses/>
  14   *
  15   * For feedback and questions about my Files and Projects please mail me,
  16   * Alexander Matthes (Ziz) , zizsdl_at_googlemail.com */
  17
  18 #ifndef _SPARROW_NET_H
  19 #define _SPARROW_NET_H
  20
  21 #include "sparrowDefines.h"
  22 #include <SDL_net.h>
  23 #include <SDL_thread.h>
  24 #include <time.h>
  25
  26 /* File: sparrowNet
  27  *
  28  * SparrowNet is a basic network API based on SDL_net. Until now UDP is not
  29  * implemented! However, you can use the ip structs from here for the UDP
  30  * part of SDL_net on your own. ;)
  31  *
  32  * Furthermore sparrowNet has some fancy functions for getting and submitting
  33  * scores for the compo4all online highscore system.*/
  34
  35 enum spAddress {IPV4, IPV6};
  36
  37 /* Section: General & TCP Stuff
  38  *
  39  * Types and Functions for initializing sparrowNet and sending data over tcp.*/
  40
  41 /* Type: spNetIP
  42  *
  43  * An IP address resolved by sparrowNet.
  44  *
  45  * Variables:
  46  * address.ipv4 (Uint32) - 32 bit ipv4 address
  47  * address.ipv4_bytes (Uint8[4]) - 4 x 8bit ipv4 address
  48  * address.ipv6 (Uint32[4]) - 128 bit ipv6 address
  49  * address.ipv6_bytes (Uint8[16]) - 16 x 8bit ipv6 address
  50  * port (Uint16) - port of the address
  51  * sdl_address (IPaddress) - ip address struct of SDL*/
  52 typedef struct spNetIPStruct *spNetIPPointer;
  53 typedef struct spNetIPStruct {
  54         enum spAddress type;
  55         union {
  56                 Uint32 ipv4;
  57                 Uint8 ipv4_bytes[4];
  58                 Uint32 ipv6[4];
  59                 Uint8 ipv6_bytes[16];
  60         } address;
  61         Uint16 port;
  62         IPaddress sdl_address;
  63 } spNetIP;
  64
  65 typedef struct spNetC4ATaskStruct *spNetC4ATaskPointer;
  66 typedef struct spNetC4ATaskStruct {
  67         SDL_mutex* statusMutex;
  68         int status;
  69         void *dataPointer;
  70         int timeOut;
  71         SDL_Thread* thread;
  72         int result;
  73         int threadStatus;
  74         int message;
  75 } spNetC4ATask;
  76
  77 /* Define: SP_INVALID_IP
  78  *
  79  * Same as INADDR_NONE of SDL_Net. Means, that the ip returned by <spNetResolve>
  80  * was not found and is invalid. */
  81 #define SP_INVALID_IP INADDR_NONE
  82
  83 /* Type: spNetTCPConnection
  84  *
  85  * a type for open tcp connections. In fact just SDL_net's TCPsocket.*/
  86 typedef TCPsocket spNetTCPConnection;
  87 /* Type: spNetTCPServer
  88  *
  89  * a type for server sessions. In fact just SDL_net's TCPsocket.*/
  90 typedef TCPsocket spNetTCPServer;
  91
  92 /* Function: spInitNet
  93  *
  94  * Initializes sparrowNet. Call always before using this library!*/
  95 PREFIX void spInitNet();
  96
  97 /* Function: spQuitNet
  98  *
  99  * Quits sparrowNet.*/
 100 PREFIX void spQuitNet();
 101
 102 /* Function: spNetResolve
 103  *
 104  * Resolves a hostname to an ip. Only ipv4 is supported at the moment!
 105  *
 106  * Parameters:
 107  * host - the host name
 108  * port - the port you want to access (later)
 109  *
 110  * Returns:
 111  * spNetIP - the ip in the type <spNetIP>. If address.ipv4 is SP_INVALID_IP, the
 112  * function calls failed!*/
 113 PREFIX spNetIP spNetResolve(char* host,Uint16 port);
 114
 115 /* Function: spNetResolveHost
 116  *
 117  * Gives you the hostname to an ip.
 118  *
 119  * Parameters:
 120  * ip - ip the the host you want to know
 121  * host - a pointer, where to put the string
 122  * host_len - the maximal length of the host string. Keep the ending 0 in mind!
 123  *
 124  * Returns:
 125  * char* - the pointer "host" from above*/
 126 PREFIX char* spNetResolveHost(spNetIP ip,char* host,int host_len);
 127
 128 /* Function: spNetOpenClientTCP
 129  *
 130  * Opens a connection to an ip
 131  *
 132  * Parameters:
 133  * ip - the ip
 134  *
 135  * Returns:
 136  * spNetTCPConnection - handle for the connection */
 137 PREFIX spNetTCPConnection spNetOpenClientTCP(spNetIP ip);
 138
 139 /* Function: spNetOpenServerTCP
 140  *
 141  * Creates a server, which listens at a port
 142  *
 143  * Parameters:
 144  * port - the port
 145  *
 146  * Returns:
 147  * spNetTCPServer - handle for the server*/
 148 PREFIX spNetTCPServer spNetOpenServerTCP(Uint16 port);
 149
 150 /* Function: spNetAcceptTCP
 151  *
 152  * If a client tries to connect to your server, this function returns an
 153  * established tcp connection from your server to the client.
 154  *
 155  * Parameters:
 156  * server - the server returned by <spNetOpenServerTCP>*/
 157 PREFIX spNetTCPConnection spNetAcceptTCP(spNetTCPServer server);
 158
 159 /* Function: spNetGetConnectionIP
 160  *
 161  * Gives you the ip of your connected client.
 162  *
 163  * Parameters:
 164  * connection - a connection, where you want to know other side
 165  *
 166  * Returns
 167  * spNetIP - the ip as <spNetIP>*/
 168 PREFIX spNetIP spNetGetConnectionIP(spNetTCPConnection connection);
 169
 170 /* Function: spNetSendTCP
 171  *
 172  * Sends a tcp package to the ether.
 173  *
 174  * Parameters:
 175  * connection - the connection to send a tcp package with
 176  * data - data to send. Can be a pointer to literally anything.
 177  * length - length of the data to be sent (in bytes)
 178  *
 179  * Returns:
 180  * int - the number of sent bytes. If unequal length the connection seem to be
 181  * closed */
 182 PREFIX int spNetSendTCP(spNetTCPConnection connection,void* data,int length);
 183
 184 /* Function: spNetSendHTTP
 185  *
 186  * Sends text over TCP with spNetSendTCP.
 187  *
 188  * Parameters:
 189  * connection - the connection to send a tcp package with
 190  * data - the string to send
 191  *
 192  * Returns:
 193  * int - the number of sent bytes. If unequal length the connection seem to be
 194  * closed */
 195 PREFIX int spNetSendHTTP(spNetTCPConnection connection,char* data);
 196
 197 /* Function: spNetReceiveTCP
 198  *
 199  * Receives data from the other side. This function blocks your application
 200  * until the client actually sends something!
 201  *
 202  * Parameters:
 203  * connection - the connection you want to receive tcp packages from
 204  * data - data to receive. Can be a pointer to literally anything.
 205  * length - maximal data to receive
 206  *
 207  * Returns:
 208  * int - the number of received bytes. If 0 something strange happend. E.g. your
 209  * counterside explodes or just closed the connection. However your connection
 210  * is invalid now! Better close, too. */
 211 PREFIX int spNetReceiveTCP(spNetTCPConnection connection,void* data,int length);
 212
 213 /* Function: spNetReceiveHTTP
 214  *
 215  * Receives data from the other side until the other side disconnects. This
 216  * function blocks your application until the client actually sends something!
 217  * You can of course use other protocols than http. ;)
 218  *
 219  * Parameters:
 220  * connection - the connection you want to receive tcp packages from
 221  * data - pointer to the text to receive
 222  * length - maximal length of the text
 223  *
 224  * Returns:
 225  * int - the number of received characters. If 0 something strange happend. E.g.
 226  * your counterside explodes or just closed the connection. However your
 227  * connection is invalid now! Better close, too. */
 228 PREFIX int spNetReceiveHTTP(spNetTCPConnection connection,char* data,int length);
 229
 230 /* Function: spNetReceiveTCPUnblocked
 231  *
 232  * Receives data from the other side. This function does not block your
 233  * application! However, it may need a while until your counterpart sends
 234  * something and your data string stays invalid.
 235  *
 236  * Parameters:
 237  * connection - the connection you want to receive tcp packages from
 238  * data - data to receive. Can be a pointer to literally anything.
 239  * length - maximal data to receive
 240  *
 241  * Returns:
 242  * SDL_Thread* - a handle to the created background thread. E.g. you can kill
 243  * it with SDL_KillThread if you don't want to wait anymore. If (void*)(-1) is
 244  * returned the connection is closed (or your counterside exploded).*/
 245 PREFIX SDL_Thread* spNetReceiveTCPUnblocked(spNetTCPConnection connection,void* data,int length);
 246
 247 /* Function: spNetReceiveHTTPUnblocked
 248  *
 249  * Receives data from the other side until the other side disconnects. This
 250  * function does not block your application! However, it may need a while until
 251  * your counterpart sends something and your data string stays invalid. You
 252  * can of course use other protocols than http. ;)
 253  *
 254  * Parameters:
 255  *
 256  * connection - the connection you want to receive tcp packages from
 257  * data - pointer to the text to receive
 258  * length - maximal length of the text
 259  *
 260  * Returns:
 261  * SDL_Thread* - a handle to the created background thread. E.g. you can kill
 262  * it with SDL_KillThread if you don't want to wait anymore. If (void*)(-1) is
 263  * returned the connection is closed (or your counterside exploded).*/
 264 PREFIX SDL_Thread* spNetReceiveHTTPUnblocked(spNetTCPConnection connection,char* data,int length);
 265
 266 /* Function: spNetReceiveStillWaiting
 267  *
 268  * Says, whether a receive call (identified by the thread handle) still waits
 269  * for an incoming signal. Usefull for timeouts.
 270  *
 271  * Parameters:
 272  * thread - thread of the receiving call, which is maybe still running
 273  *
 274  * Returns:
 275  * int - 1 if the thread still waits or 0 if not.*/
 276 PREFIX int spNetReceiveStillWaiting(SDL_Thread* thread);
 277
 278 /* Function: spNetCloseTCP
 279  *
 280  * Closes a tcp connection or a server session.
 281  *
 282  * Parameter:
 283  * connection - connection to close*/
 284 PREFIX void spNetCloseTCP(spNetTCPConnection connection);
 285
 286 /* Section: Compo4all stuff
 287  *
 288  * Types and Functions for sending and receiving data to and from the compo4all
 289  * server.*/
 290
 291 /* Defines: Compo4all statuses
 292  *
 293  * Statuses for the committing and score-loading functions.
 294  *
 295  * SP_C4A_PROGRESS - transfer of data is in progress
 296  * SP_C4A_OK - process is done and everything was fine
 297  * SP_C4A_ERROR - process is done, but something went wrong */
 298 #define SP_C4A_PROGRESS 1
 299 #define SP_C4A_OK 0
 300 #define SP_C4A_ERROR -1
 301 #define SP_C4A_TIMEOUT -2
 302 #define SP_C4A_CANCELED -3
 303
 304 /* Type: spNetC4AGame
 305  *
 306  * Type for a linked list of games from the compo4all highscore servers
 307  *
 308  * Variables:
 309  * longname - full name of the game
 310  * shortname - short name of the game
 311  * status - the status of the highscore: 1 means available, 2 even more
 312  * available (called "active" by skeezix, don't really know, what this means),
 313  * 0 inactive, which means, you shouldn't show that game except for testing
 314  * purpose.
 315  * genre - the genre of the game.
 316  * field - which kind of game is it? 0 means just an indie game, 1 is a mame
 317  * game, -1 means "don't know" or "to be decided".
 318  * next - pointer to the next element in the list*/
 319 typedef struct spNetC4AGameStruct *spNetC4AGamePointer;
 320 typedef struct spNetC4AGameStruct {
 321         char longname[256];
 322         char shortname[256];
 323         int status;
 324         char genre[256];
 325         int field;
 326         spNetC4AGamePointer next;
 327 } spNetC4AGame;
 328
 329 /* Type: spNetC4AScore
 330  *
 331  * Type for a linked list of scores gotten from the compo4all highscore servers
 332  *
 333  * Variables:
 334  * longname - full name of the player
 335  * shortname - three digit short name of the player
 336  * score - the reached points
 337  * commitTime - time of type time_t (seconds since 1.1.1970 00:00:00),
 338  * when the score was committed. Use localtime of time.h to "decrypt"
 339  * this type. ;)
 340  * next - pointer to the next element in the list
 341  * rank - rank in the score */
 342 typedef struct spNetC4AScoreStruct *spNetC4AScorePointer;
 343 typedef struct spNetC4AScoreStruct {
 344         char longname[256];
 345         char shortname[256];
 346         int score;
 347         time_t commitTime;
 348         spNetC4AScorePointer next;
 349         int rank;
 350 } spNetC4AScore;
 351
 352 /* Type: spNetC4AProfile
 353  *
 354  * A struct for your *unique* C4A Profile.
 355  *
 356  * Variables:
 357  * prid - unique id of your account. Keep it for you. ;)
 358  * longname - your full name
 359  * shortname - your 3 digit short name */
 360 typedef struct spNetC4AProfileStruct *spNetC4AProfilePointer;
 361 typedef struct spNetC4AProfileStruct {
 362         char prid[256];
 363         char longname[256];
 364         char shortname[256];
 365         char password[256];
 366         char email[256];
 367 } spNetC4AProfile;
 368
 369
 370 /* Function: spNetC4AGetProfile
 371  *
 372  * Reads your profile out of your c4a-prof file. On the pandora the file is
 373  * created by compo4all and stored on a pandora specific place. On other systems
 374  * for now your c4a-prof should be in the folder of your application.
 375  *
 376  * Returns:
 377  * spNetC4AProfilePointer - a pointer to an <spNetC4AProfile> struct*/
 378 PREFIX spNetC4AProfilePointer spNetC4AGetProfile();
 379
 380 /* Function: spNetC4AFreeProfile
 381  *
 382  * Frees the profile you got from <spNetC4AGetProfile>.
 383  *
 384  * Parameters:
 385  * profile - profile to free. However of course your profile is not deleted. ;)*/
 386 PREFIX void spNetC4AFreeProfile(spNetC4AProfilePointer profile);
 387
 388 /* Function: spNetC4AGetGame
 389  *
 390  * Loads all games listed on the C4A server. Use <spNetC4AGetStatus> to get the
 391  * status of the task. Only one compo4all background task can run at one time!
 392  *
 393  * Parameters:
 394  * gameList - a pointer to spNetC4AGamePointer, which is in fact a pointer to
 395  * <spNetC4AGame>. The available games are saved here.
 396  * timeOut - after this time in ms the thread is killed. Get it with
 397  * <spNetC4AGetTimeOut>
 398  *
 399  * Returns:
 400  * int - 1 if the function failed for some reason, 0 at success starting
 401  * the task.*/
 402 PREFIX int spNetC4AGetGame(spNetC4AGamePointer* gameList,int timeOut);
 403
 404 /* Function: spNetC4AGetGameParallel
 405  *
 406  * Loads all games listed on the C4A server. Use
 407  * <spNetC4AGetStatusParallel> to get the status of the task. Don't
 408  * forget to delete the returned task struct with <spNetC4ADeleteTask>
 409  * at the end.
 410  *
 411  * Parameters:
 412  * gameList - a pointer to spNetC4AGamePointer, which is in fact a pointer to
 413  * <spNetC4AGame>. The available games are saved here.
 414  * timeOut - after this time in ms the thread is killed. Get it with
 415  * <spNetC4AGetTimeOut>
 416  *
 417  * Returns:
 418  * spNetC4ATaskPointer - Pointer to <spNetC4ATask> at success and NULL if an
 419  * error occured.*/
 420 PREFIX spNetC4ATaskPointer spNetC4AGetGameParallel(spNetC4AGamePointer* gameList,int timeOut);
 421
 422 /* Function: spNetC4ADeleteGames
 423  *
 424  * Frees the linked list returned by <spNetC4AGetGame>.
 425  *
 426  * Parameters:
 427  * firstGame - pointer to <spNetC4AGame> to free*/
 428 PREFIX void spNetC4ADeleteGames(spNetC4AGamePointer* gameList);
 429
 430 /* Function: spNetC4AGetScore
 431  *
 432  * Loads a top 500 for a given game from the compo4all server. The task runs
 433  * in background! Use <spNetC4AGetStatus> to get the status of the task. Only
 434  * one compo4all background task can run at one time!
 435  *
 436  * Parameters:
 437  * scoreList - a pointer to spNetC4AScorePointer, which is in fact a pointer to
 438  * <spNetC4AScore>. The scores are saved here.
 439  * profile - an optional pointer to your profile. If given only your scores are
 440  * added to the scores-list above
 441  * game - name of the game on the server
 442  * timeOut - after this time in ms the thread is killed. Get it with
 443  * <spNetC4AGetTimeOut>
 444  *
 445  * Returns:
 446  * int - 1 if the function failed for some reason, 0 at success starting
 447  * the task.
 448  *
 449  * See also: <spNetC4AGetScoreOfMonth>*/
 450 PREFIX int spNetC4AGetScore(spNetC4AScorePointer* scoreList,spNetC4AProfilePointer profile,char* game,int timeOut);
 451
 452 /* Function: spNetC4AGetScoreOfMonth
 453  *
 454  * Loads a top 500 of a month for a given game from the compo4all
 455  * server. The task runs
 456  * in background! Use <spNetC4AGetStatus> to get the status of the task. Only
 457  * one compo4all background task can run at one time!
 458  *
 459  * Parameters:
 460  * scoreList - a pointer to spNetC4AProfilePointer, which is in fact a pointer to
 461  * <spNetC4AScore>. The scores are saved here.
 462  * profile - an optional pointer to your profile. If given only your scores are
 463  * added to the scores-list above
 464  * game - name of the game on the server
 465  * year - year to load (e.g. 2013)
 466  * month - month to load (e.g. 3 for march)
 467  * timeOut - after this time in ms the thread is killed. Get it with
 468  * <spNetC4AGetTimeOut>
 469  *
 470  * Returns:
 471  * int - 1 if the function failed for some reason, 0 at success starting
 472  * the task.
 473  *
 474  * See also: <spNetC4AGetScore>*/
 475 PREFIX int spNetC4AGetScoreOfMonth(spNetC4AScorePointer* scoreList,spNetC4AProfilePointer profile,char* game,int year,int month,int timeOut);
 476
 477 /* Function: spNetC4AGetScore
 478  *
 479  * Loads a top 500 for a given game from the compo4all server. The task runs
 480  * in background! Use <spNetC4AGetStatus> to get the status of the task. Only
 481  * one compo4all background task can run at one time!
 482  *
 483  * Parameters:
 484  * scoreList - a pointer to spNetC4AScorePointer, which is in fact a pointer to
 485  * <spNetC4AScore>. The scores are saved here.
 486  * profile - an optional pointer to your profile. If given only your scores are
 487  * added to the scores-list above
 488  * game - name of the game on the server
 489  * timeOut - after this time in ms the thread is killed. Get it with
 490  * <spNetC4AGetTimeOut>
 491  *
 492  * Returns:
 493  * spNetC4ATaskPointer - Pointer to <spNetC4ATask> at success and NULL if an
 494  * error occured.
 495  *
 496  * See also: <spNetC4AGetScoreOfMonthParallel>*/
 497 PREFIX spNetC4ATaskPointer spNetC4AGetScoreParallel(spNetC4AScorePointer* scoreList,spNetC4AProfilePointer profile,char* game,int timeOut);
 498
 499 /* Function: spNetC4AFilterScore
 500  *
 501  * Makes, that every name appears only once in the scoreList
 502  *
 503  * Parameter:
 504  * scoreList - a pointer to spNetC4AScorePointer, which is in fact a pointer to
 505  * <spNetC4AScore>. These scores are changed.*/
 506 PREFIX void spNetC4AFilterScore(spNetC4AScorePointer* scoreList);
 507
 508 /* Function: spNetC4AGetScoreOfMonth
 509  *
 510  * Loads a top 500 of a month for a given game from the compo4all
 511  * server. The task runs in background! Use
 512  * <spNetC4AGetStatusParallel> to get the status of the task. Don't
 513  * forget to delete the returned task struct with <spNetC4ADeleteTask>
 514  * at the end.
 515  *
 516  * Parameters:
 517  * scoreList - a pointer to spNetC4AProfilePointer, which is in fact a pointer to
 518  * <spNetC4AScore>. The scores are saved here.
 519  * profile - an optional pointer to your profile. If given only your scores are
 520  * added to the scores-list above
 521  * game - name of the game on the server
 522  * year - year to load (e.g. 2013)
 523  * month - month to load (e.g. 3 for march)
 524  * timeOut - after this time in ms the thread is killed. Get it with
 525  * <spNetC4AGetTimeOut>
 526  *
 527  * Returns:
 528  * spNetC4ATaskPointer - Pointer to <spNetC4ATask> at success and NULL if an
 529  * error occured.
 530  *
 531  * See also: <spNetC4AGetScoreParallel>*/
 532 PREFIX spNetC4ATaskPointer spNetC4AGetScoreOfMonthParallel(spNetC4AScorePointer* scoreList,spNetC4AProfilePointer profile,char* game,int year,int month,int timeOut);
 533
 534 /* Function: spNetC4CopyScoreList
 535  *
 536  * Makes an unique copy of the passed scorelist, e.g. if you want to remove
 537  * double names with <spNetC4AMakeScoresUnique> afterwards. Don't forget to
 538  * free every copy with <spNetC4ADeleteScores> afterwards!
 539  *
 540  * Parameters:
 541  * scoreList - a pointer to spNetC4AProfilePointer, which is in fact a pointer to
 542  * <spNetC4AScore>, which shall be copied
 543  * newList - a pointer to spNetC4AProfilePointer, which is in fact a pointer to
 544  * <spNetC4AScore>, to which the copy shall be written*/
 545 PREFIX void spNetC4ACopyScoreList(spNetC4AScorePointer* scoreList,spNetC4AScorePointer* newList);
 546
 547 /* Function: spNetC4AMakeScoresUnique
 548  *
 549  * Removes any double occurence of names in the score. Afterwars every
 550  * name only occurs ones with the best score of this player. Be careful:
 551  * Afterwards you can't use this list for uploading scores if they don't
 552  * exist anymore. If you want both make a copy of the list with
 553  * <spNetC4ACopyScoreList> before (instead of getting the scores twice).
 554  *
 555  * Parameters:
 556  * scoreList - a pointer to spNetC4AProfilePointer, which is in fact a pointer to
 557  * <spNetC4AScore> */
 558 PREFIX void spNetC4AMakeScoresUnique(spNetC4AScorePointer* scoreList);
 559
 560 /* Function: spNetC4ADeleteScores
 561  *
 562  * Frees the linked list returned by <spNetC4AGetScore>.
 563  *
 564  * Parameters:
 565  * firstScore - pointer to <spNetC4AScore> to free*/
 566 PREFIX void spNetC4ADeleteScores(spNetC4AScorePointer* scoreList);
 567
 568 /* Function: spNetC4ACommitScore
 569  *
 570  * Commits a score to a specific game to compo4all server. The task runs
 571  * in background! Use <spNetC4AGetStatusParallel> to get the status of the task.
 572  * Don't forget to delete the returned task struct with <spNetC4ADeleteTask>
 573  * at the end.
 574  *
 575  * Parameters:
 576  * profile - the profile you want to commit tthe score with
 577  * game - name of the game on the server. If this is empty (""), at least the
 578  * c4a cache will be tried to commit.
 579  * score - reached score
 580  * scoreList - pass the struct returned by <spNetC4AGetScore> to compare
 581  * your score to that list and avoid committing the same score twice. If
 582  * it is not in the list, it will added afterwards for later
 583  * comparements.
 584  * timeOut - after this time in ms the thread is killed. Get it with
 585  * <spNetC4AGetTimeOut>. If timeOut is 0, no thread is started, but the
 586  * score is written to the cache if enabled!
 587  *
 588  * Returns:
 589  * int - 1 if the function failed for some reason (e.g. the score is
 590  * already in the scoreList), 0 at success starting the task.*/
 591 PREFIX int spNetC4ACommitScore(spNetC4AProfilePointer profile,char* game,int score,spNetC4AScorePointer* scoreList,int timeOut);
 592
 593 /* Function: spNetC4ACommitScoreParallel
 594  *
 595  * Commits a score to a specific game to compo4all server. The task runs
 596  * in background! Use <spNetC4AGetStatusParallel> to get the status of the task.
 597  * Don't forget to delete the returned task struct with <spNetC4ADeleteTask>
 598  * at the end.
 599  *
 600  * Parameters:
 601  * profile - the profile you want to commit tthe score with
 602  * game - name of the game on the server
 603  * score - reached score
 604  * scoreList - pass the struct returned by <spNetC4AGetScore> to compare
 605  * your score to that list and avoid committing the same score twice. If
 606  * it is not in the list, it will added afterwards for later
 607  * comparements.
 608  * timeOut - after this time in ms the thread is killed. Get it with
 609  * <spNetC4AGetTimeOut> If timeOut is 0, no thread is started, but the
 610  * score is written to the cache if enabled!
 611  *
 612  * Returns:
 613  * spNetC4ATaskPointer - Pointer to <spNetC4ATask> at success and NULL if an
 614  * error occured.*/
 615 PREFIX spNetC4ATaskPointer spNetC4ACommitScoreParallel(spNetC4AProfilePointer profile,char* game,int score,spNetC4AScorePointer* scoreList,int timeOut);
 616
 617 /* Function: spNetC4ACreateProfile
 618  *
 619  * Creates a new profile on skeezix' server. Blocks your application! However,
 620  * if network is avaible, should be quite fast. Furthermore it creates the
 621  * c4a-prof file needed by all supported applications. The path of the file is
 622  * platform depended. Overwrites an already existing file! The task runs
 623  * in background! Use <spNetC4AGetStatus> to get the status of the task. Only
 624  * one compo4all background task can run at one time!
 625  * Only for Pandora: If no c4a-prof is created until now and no c4a-mame appdata
 626  * folder is available it will be created in the first folder in /media with
 627  * pandora/appdata in it. It MAY be, that skeezix's C4A Manager will not find
 628  * this c4a-prof if it will be installed later on another SD card! However the
 629  * spaghetti client, the fusilli client and the Sparrow C4A Manager will find
 630  * this profile file in any case (if you don't create a second c4a-prof with
 631  * skeezix c4a manager. It that case it is random which c4a-prof is used in the
 632  * end...)
 633  *
 634  * Parameters:
 635  *
 636  * profile - a pointer to a pointer to <spNetC4AProfile>, where the profile
 637  * shall be saved to.
 638  * longname - the long name of the player. Should only be alphanumeric.
 639  * shortname - the short name of the player. Should exactly 3 alphanumeric,
 640  * capital letters.
 641  * password - alphanumeric password
 642  * email - the mail address of the new account. Can be "".
 643  * timeOut - after this time in ms the thread is killed. Get it with
 644  * <spNetC4AGetTimeOut>
 645  *
 646  * Returns:
 647  * int - 1 if the function failed for some reason, 0 at success starting
 648  * the task.
 649  *
 650  * See Also:
 651  * <spNetC4AEditProfile>*/
 652 PREFIX int spNetC4ACreateProfile(spNetC4AProfilePointer* profile, char* longname,char* shortname,char* password,char* email,int timeOut);
 653
 654 /* Function: spNetC4ADeleteAccount
 655  *
 656  * Deletes the given profile on skeezix server and maybe the file on your
 657  * system. The task runs
 658  * in background! Use <spNetC4AGetStatus> to get the status of the task. Only
 659  * one compo4all background task can run at one time!
 660  *
 661  * Parameters:
 662  * profile - profile to delete from the server.
 663  * deleteFile - 1 if you want to delete the c4a-prof file at the end
 664  * (at success), too. 0 leaves to file.
 665  * timeOut - after this time in ms the thread is killed. Get it with
 666  * <spNetC4AGetTimeOut>
 667  *
 668  * Returns:
 669  * int - 1 if the function failed for some reason, 0 at success starting
 670  * the task.*/
 671 PREFIX int spNetC4ADeleteAccount(spNetC4AProfilePointer* profile,int deleteFile,int timeOut);
 672
 673 /* Function: spNetC4AEditProfile
 674  *
 675  * Edits an already existing profile on skeezix' server. Blocks your
 676  * application! However, if network is avaible, should be quite fast.
 677  * Furthermore it rewrites the c4a-prof file needed by all supported
 678  * applications. The path of the file is platform depended. If the account
 679  * doesn't exist now, it will created. The big difference to
 680  * <spNetC4ACreateProfile> is, that the prid is read from the profile struct
 681  * instead of being new created. The task runs
 682  * in background! Use <spNetC4AGetStatus> to get the status of the task. Only
 683  * one compo4all background task can run at one time!
 684  *
 685  * Parameters:
 686  *
 687  * profile - the profile to change.
 688  * longname - the long name of the player. Should only be alphanumeric.
 689  * shortname - the short name of the player. Should exactly 3 alphanumeric,
 690  * capital letters.
 691  * password - alphanumeric password
 692  * email - the mail address of the new account. Can be "".
 693  * timeOut - after this time in ms the thread is killed. Get it with
 694  * <spNetC4AGetTimeOut>
 695  *
 696  * Returns:
 697  * int - 1 if the function failed for some reason, 0 at success starting
 698  * the task.
 699  *
 700  * See Also:
 701  * <spNetC4ACreateProfile>*/
 702 PREFIX int spNetC4AEditProfile(spNetC4AProfilePointer* profile,char* longname,char* shortname,char* password,char* email,int timeOut);
 703
 704 /* Function: spNetC4ACancelTask
 705  *
 706  * Cancels the C4A task running right now (if one is started).*/
 707 PREFIX void spNetC4ACancelTask();
 708
 709 /* Function: spNetC4ACancelTaskParallel
 710  *
 711  * Cancels the given C4A task. Don't forget to delete it afterwards with
 712  * <spNetC4ADeleteTask>!
 713  *
 714  * Parameters:
 715  * task - pointer to <spNetC4ATask> returned from the parallel functions.*/
 716 PREFIX void spNetC4ACancelTaskParallel(spNetC4ATaskPointer task);
 717
 718 /* Function: spNetC4AGetTaskResult
 719  *
 720  * Gets the result of the task when finished (check with
 721  * <spNetC4AGetStatus>).
 722  *
 723  * Returns:
 724  * int - 0 if everything went fine, 1 at error*/
 725 PREFIX int spNetC4AGetTaskResult();
 726
 727 /* Function: spNetC4AGetTaskResultParallel
 728  *
 729  * Gets the result of the given task when finished (check with
 730  * <spNetC4AGetStatusParallel>).
 731  *
 732  * Parameters:
 733  * task - pointer to <spNetC4ATask> returned from the parallel functions.
 734  *
 735  * Returns:
 736  * int - 0 if everything went fine, 1 at error*/
 737 PREFIX int spNetC4AGetTaskResultParallel(spNetC4ATaskPointer task);
 738
 739 /* Function: spNetC4AGetTimeOut
 740  *
 741  * Gives you the time out of the C4A tasks.
 742  *
 743  * Returns:
 744  * int - the timeOut in ms.*/
 745 PREFIX int spNetC4AGetTimeOut();
 746
 747 /* Function: spNetC4AGetTimeOutParallel
 748  *
 749  * Gives you the time out of the given C4A task.
 750  *
 751  * Parameters:
 752  * task - pointer to <spNetC4ATask> returned from the parallel functions.
 753  *
 754  * Returns:
 755  * int - the timeOut in ms.*/
 756 PREFIX int spNetC4AGetTimeOutParallel(spNetC4ATaskPointer task);
 757
 758 /* Function: spNetC4AGetStatus
 759  *
 760  * Gets the status of <spNetC4AGetScore>, <spNetC4ACommitScore>,
 761  * <spNetC4ACreateProfile>, <spNetC4AEditProfile> & <spNetC4ADeleteAccount>.
 762  *
 763  * Returns:
 764  * int - <Compo4all statuses>*/
 765 PREFIX int spNetC4AGetStatus();
 766
 767 /* Function: spNetC4AGetStatusParallel
 768  *
 769  * Gets the status of <spNetC4AGetScoreParallel> & <spNetC4ACommitScoreParallel>.
 770  *
 771  * Parameters:
 772  * task - pointer to <spNetC4ATask> returned from the parallel functions
 773  *
 774  * Returns:
 775  * int - <Compo4all statuses>*/
 776 PREFIX int spNetC4AGetStatusParallel(spNetC4ATaskPointer task);
 777
 778
 779 /* Function: spNetC4ADeleteProfileFile
 780  *
 781  * Deletes the profile file on your system, NOT the online account at skeezix
 782  * server. See also <spNetC4ADeleteAccount>.*/
 783 PREFIX void spNetC4ADeleteProfileFile();
 784
 785 /* Function: spNetC4ADeleteTask
 786  *
 787  * Deletes the task struct returned by the parallel working task functions.
 788  *
 789  * Parameters:
 790  * task - Pointer to <spNetC4ATask>, which is returned by the parallel functions.*/
 791 PREFIX void spNetC4ADeleteTask(spNetC4ATaskPointer task);
 792
 793 /* Function: spNetC4ASetCaching
 794  *
 795  * (De)Activates caching for C4A scores. If caching is enabled every time
 796  * spNetC4ACommitScore* fails, it is written to a cache file and the next time
 797  * spNetC4ACommitScore* is called it will be tried to be committed again
 798  *
 799  * Parameters:
 800  * value - 0: No caching
 801  * 1: Everything is cached
 802  * 2: Only the best score of a game is cached
 803  * 3: Same like 2, but lower score is better*/
 804 PREFIX void spNetC4ASetCaching(int value);
 805
 806 /* Function: spNetC4AHowManyCached
 807  *
 808  * Returns how many scores are cached
 809  *
 810  * Returns:
 811  * int - the number of cached scores*/
 812 PREFIX int spNetC4AHowManyCached();
 813 #endif