sparrowNet

SparrowNet is a basic network API based on SDL_net.  Until now UDP is not implemented!  However, you can use the ip structs from here for the UDP part of SDL_net on your own.  ;)

Furthermore sparrowNet has some fancy functions for getting and submitting scores for the compo4all online highscore system and for the IRC chat protocol.

Summary
sparrowNetSparrowNet is a basic network API based on SDL_net.
General & TCP StuffTypes and Functions for initializing sparrowNet and sending data over tcp.
Types and Macros
spNetIPAn IP address resolved by sparrowNet.
SP_INVALID_IPSame as INADDR_NONE of SDL_Net.
spNetTCPConnectiona type for open tcp connections.
spNetTCPServera type for server sessions.
Functions
spInitNetInitializes sparrowNet.
spQuitNetQuits sparrowNet.
spNetResolveResolves a ip to a hostname.
spNetResolveHostGives you the hostname to an ip.
spNetOpenClientTCPOpens a connection to an ip
spNetOpenServerTCPCreates a server, which listens at a port
spNetAcceptTCPIf a client tries to connect to your server, this function returns an established tcp connection from your server to the client.
spNetGetConnectionIPGives you the ip of your connected client.
spNetSendTCPSends a tcp package to the ether.
spNetSendHTTPSends text over TCP with spNetSendTCP.
spNetReceiveTCPReceives data from the other side.
spNetReceiveHTTPReceives data from the other side until the other side disconnects.
spNetReceiveTCPUnblockedReceives data from the other side.
spNetReceiveHTTPUnblockedReceives data from the other side until the other side disconnects.
spNetReceiveStillWaitingSays, whether a receive call (identified by the thread handle) still waits for an incoming signal.
spNetReceiveFinishedSays, whether a receive call (identified by the thread handle) still waits for an incoming signal.
spNetCloseTCPCloses a tcp connection or a server session.
Compo4all stuffTypes and Functions for sending and receiving data to and from the compo4all server.
Macros
Compo4all statusesStatuses for the committing and score-loading functions.
Types
spNetC4AGameType for a linked list of games from the compo4all highscore servers
spNetC4AScoreType for a linked list of scores gotten from the compo4all highscore servers
spNetC4AProfileA struct for your unique C4A Profile.
Functions
spNetC4AGetProfileReads your profile out of your c4a-prof file.
spNetC4AFreeProfileFrees the profile you got from spNetC4AGetProfile.
spNetC4AGetGameLoads all games listed on the C4A server.
spNetC4AGetGameParallelLoads all games listed on the C4A server.
spNetC4ADeleteGamesFrees the linked list returned by spNetC4AGetGame.
spNetC4AGetScoreLoads a top 500 for a given game from the compo4all server.
spNetC4AGetScoreOfMonthLoads a top 500 of a month for a given game from the compo4all server.
spNetC4AGetScoreLoads a top 500 for a given game from the compo4all server.
spNetC4AFilterScoreMakes, that every name appears only once in the scoreList
spNetC4AGetScoreOfMonthLoads a top 500 of a month for a given game from the compo4all server.
spNetC4CopyScoreListMakes an unique copy of the passed scorelist, e.g.
spNetC4AMakeScoresUniqueRemoves any double occurence of names in the score.
spNetC4ADeleteScoresFrees the linked list returned by spNetC4AGetScore.
spNetC4ACommitScoreCommits a score to a specific game to compo4all server.
spNetC4ACommitScoreParallelCommits a score to a specific game to compo4all server.
spNetC4ACreateProfileCreates a new profile on skeezix’ server.
spNetC4ADeleteAccountDeletes the given profile on skeezix server and maybe the file on your system.
spNetC4AEditProfileEdits an already existing profile on skeezix’ server.
spNetC4ACancelTaskCancels the C4A task running right now (if one is started).
spNetC4ACancelTaskParallelCancels the given C4A task.
spNetC4AGetTaskResultGets the result of the task when finished (check with spNetC4AGetStatus).
spNetC4AGetTaskResultParallelGets the result of the given task when finished (check with spNetC4AGetStatusParallel).
spNetC4AGetTimeOutGives you the time out of the C4A tasks.
spNetC4AGetTimeOutParallelGives you the time out of the given C4A task.
spNetC4AGetStatusGets the status of spNetC4AGetScore, spNetC4ACommitScore, spNetC4ACreateProfile, spNetC4AEditProfile & spNetC4ADeleteAccount.
spNetC4AGetStatusParallelGets the status of <spNetC4AGetScoreParallel> & spNetC4ACommitScoreParallel.
spNetC4ADeleteProfileFileDeletes the profile file on your system, NOT the online account at skeezix server.
spNetC4ADeleteTaskDeletes the task struct returned by the parallel working task functions.
spNetC4ASetCaching(De)Activates caching for C4A scores.
spNetC4AHowManyCachedReturns how many scores are cached
IRC chat protocol stuffTypes and Functions for connecting to an IRC server, join channels and receive and send message.
Types
spNetIRCMessageType for a linked list of IRC messages managed from the IRC server.
spNetIRCNickType for a linked list of IRC nicks managed from the IRC server.
spNetIRCChannelType for a linked list of IRC channels managed from the IRC server.
spNetIRCServerHandle type for interaction with the irc server.
Functions
spNetIRCConnectServerConnects to an IRC server.
spNetIRCServerReadyReturns, whether the server is ready to be used, e.g.
spNetIRCJoinChannelJoins an IRC channel.
spNetIRCChannelReadyReturns, whether the channel is ready to be used, e.g.
spNetIRCSendMessageSends a message (PRIVMSG) to a channel or another user.
spNetIRCPartChannelLeave a channel / conversation.
spNetIRCCloseServerCloses the connection to the server, finishs the thread and releases the pointer handle!

General & TCP Stuff

Types and Functions for initializing sparrowNet and sending data over tcp.

Summary
Types and Macros
spNetIPAn IP address resolved by sparrowNet.
SP_INVALID_IPSame as INADDR_NONE of SDL_Net.
spNetTCPConnectiona type for open tcp connections.
spNetTCPServera type for server sessions.
Functions
spInitNetInitializes sparrowNet.
spQuitNetQuits sparrowNet.
spNetResolveResolves a ip to a hostname.
spNetResolveHostGives you the hostname to an ip.
spNetOpenClientTCPOpens a connection to an ip
spNetOpenServerTCPCreates a server, which listens at a port
spNetAcceptTCPIf a client tries to connect to your server, this function returns an established tcp connection from your server to the client.
spNetGetConnectionIPGives you the ip of your connected client.
spNetSendTCPSends a tcp package to the ether.
spNetSendHTTPSends text over TCP with spNetSendTCP.
spNetReceiveTCPReceives data from the other side.
spNetReceiveHTTPReceives data from the other side until the other side disconnects.
spNetReceiveTCPUnblockedReceives data from the other side.
spNetReceiveHTTPUnblockedReceives data from the other side until the other side disconnects.
spNetReceiveStillWaitingSays, whether a receive call (identified by the thread handle) still waits for an incoming signal.
spNetReceiveFinishedSays, whether a receive call (identified by the thread handle) still waits for an incoming signal.
spNetCloseTCPCloses a tcp connection or a server session.

Types and Macros

spNetIP

An IP address resolved by sparrowNet.

Variables

address.ipv4 (Uint32)32 bit ipv4 address
address.ipv4_bytes (Uint8[4])4 x 8bit ipv4 address
address.ipv6 (Uint32[4])128 bit ipv6 address
address.ipv6_bytes (Uint8[16])16 x 8bit ipv6 address
port (Uint16)port of the address
sdl_address (IPaddress)ip address struct of SDL

SP_INVALID_IP

Same as INADDR_NONE of SDL_Net.  Means, that the ip returned by spNetResolve was not found and is invalid.

spNetTCPConnection

a type for open tcp connections.  In fact just SDL_net’s TCPsocket.

spNetTCPServer

a type for server sessions.  In fact just SDL_net’s TCPsocket.

Functions

spInitNet

PREFIX void spInitNet(void)

Initializes sparrowNet.  Call always before using this library!

spQuitNet

PREFIX void spQuitNet(void)

Quits sparrowNet.

spNetResolve

PREFIX spNetIP spNetResolve(char *host,
Uint16 port)

Resolves a ip to a hostname.  Only ipv4 is supported at the moment!

Parameters

hostthe host name
portthe port you want to access (later)

Returns

spNetIPthe ip in the type spNetIP.  If address.ipv4 is SP_INVALID_IP, the function calls failed!

spNetResolveHost

PREFIX char* spNetResolveHost(spNetIP ip,
char *host,
int host_len)

Gives you the hostname to an ip.

Parameters

ipip the the host you want to know
hosta pointer, where to put the string
host_lenthe maximal length of the host string.  Keep the ending 0 in mind!

Returns

char*the pointer “host” from above

spNetOpenClientTCP

PREFIX spNetTCPConnection spNetOpenClientTCP(spNetIP ip)

Opens a connection to an ip

Parameters

ipthe ip

Returns

spNetTCPConnectionhandle for the connection

spNetOpenServerTCP

PREFIX spNetTCPServer spNetOpenServerTCP(Uint16 port)

Creates a server, which listens at a port

Parameters

portthe port

Returns

spNetTCPServerhandle for the server

spNetAcceptTCP

PREFIX spNetTCPConnection spNetAcceptTCP(spNetTCPServer server)

If a client tries to connect to your server, this function returns an established tcp connection from your server to the client.

Parameters

serverthe server returned by spNetOpenServerTCP

spNetGetConnectionIP

PREFIX spNetIP spNetGetConnectionIP(spNetTCPConnection connection)

Gives you the ip of your connected client.

Parameters

connectiona connection, where you want to know other side

Returns spNetIP - the ip as spNetIP

spNetSendTCP

PREFIX int spNetSendTCP(spNetTCPConnection connection,
void *data,
int length)

Sends a tcp package to the ether.

Parameters

connectionthe connection to send a tcp package with
datadata to send.  Can be a pointer to literally anything.
lengthlength of the data to be sent (in bytes)

Returns

intthe number of sent bytes.  If unequal length the connection seem to be closed

spNetSendHTTP

PREFIX int spNetSendHTTP(spNetTCPConnection connection,
char *data)

Sends text over TCP with spNetSendTCP.

Parameters

connectionthe connection to send a tcp package with
datathe string to send

Returns

intthe number of sent bytes.  If unequal length the connection seem to be closed

spNetReceiveTCP

PREFIX int spNetReceiveTCP(spNetTCPConnection connection,
void *data,
int length)

Receives data from the other side.  This function blocks your application until the client actually sends something!

Parameters

connectionthe connection you want to receive tcp packages from
datadata to receive.  Can be a pointer to literally anything.
lengthmaximal data to receive

Returns

intthe number of received bytes.  If 0 something strange happend.  E.g. your counterside explodes or just closed the connection.  However your connection is invalid now!  Better close, too.

spNetReceiveHTTP

PREFIX int spNetReceiveHTTP(spNetTCPConnection connection,
char *data,
int length)

Receives data from the other side until the other side disconnects.  This function blocks your application until the client actually sends something!  You can of course use other protocols than http.  ;)

Parameters

connectionthe connection you want to receive tcp packages from
datapointer to the text to receive
lengthmaximal length of the text

Returns

intthe number of received characters.  If 0 something strange happend.  E.g. your counterside explodes or just closed the connection.  However your connection is invalid now!  Better close, too.

spNetReceiveTCPUnblocked

PREFIX SDL_Thread* spNetReceiveTCPUnblocked(spNetTCPConnection connection,
void *data,
int length)

Receives data from the other side.  This function does not block your application!  However, it may need a while until your counterpart sends something and your data string stays invalid.

Parameters

connectionthe connection you want to receive tcp packages from
datadata to receive.  Can be a pointer to literally anything.
lengthmaximal data to receive

Returns

SDL_Thread*a handle to the created background thread.  E.g. you can kill it with SDL_KillThread if you don’t want to wait anymore.  If (void*)(-1) is returned the connection is closed (or your counterside exploded).

spNetReceiveHTTPUnblocked

PREFIX SDL_Thread* spNetReceiveHTTPUnblocked(spNetTCPConnection connection,
char *data,
int length)

Receives data from the other side until the other side disconnects.  This function does not block your application!  However, it may need a while until your counterpart sends something and your data string stays invalid.  You can of course use other protocols than http.  ;)

Parameters

connectionthe connection you want to receive tcp packages from
datapointer to the text to receive
lengthmaximal length of the text

Returns

SDL_Thread*a handle to the created background thread.  E.g. you can kill it with SDL_KillThread if you don’t want to wait anymore.  If (void*)(-1) is returned the connection is closed (or your counterside exploded).

spNetReceiveStillWaiting

PREFIX int spNetReceiveStillWaiting(SDL_Thread *thread)

Says, whether a receive call (identified by the thread handle) still waits for an incoming signal.  Usefull for timeouts.

Parameters

threadthread of the receiving call, which is maybe still running

Returns

int1 if the thread still waits or 0 if not.

spNetReceiveFinished

PREFIX int spNetReceiveFinished(SDL_Thread *thread)

Says, whether a receive call (identified by the thread handle) still waits for an incoming signal.  Usefull for timeouts.  If the thread is finished the number of received bytes is returned.

Parameters

threadthread of the receiving call, which is maybe still running

Returns

int0 if the thread still waits, -1 if the thread is not found and the number of received bytes else.

spNetCloseTCP

PREFIX void spNetCloseTCP(spNetTCPConnection connection)

Closes a tcp connection or a server session.

Parameter

connectionconnection to close

Compo4all stuff

Types and Functions for sending and receiving data to and from the compo4all server.

Summary
Macros
Compo4all statusesStatuses for the committing and score-loading functions.
Types
spNetC4AGameType for a linked list of games from the compo4all highscore servers
spNetC4AScoreType for a linked list of scores gotten from the compo4all highscore servers
spNetC4AProfileA struct for your unique C4A Profile.
Functions
spNetC4AGetProfileReads your profile out of your c4a-prof file.
spNetC4AFreeProfileFrees the profile you got from spNetC4AGetProfile.
spNetC4AGetGameLoads all games listed on the C4A server.
spNetC4AGetGameParallelLoads all games listed on the C4A server.
spNetC4ADeleteGamesFrees the linked list returned by spNetC4AGetGame.
spNetC4AGetScoreLoads a top 500 for a given game from the compo4all server.
spNetC4AGetScoreOfMonthLoads a top 500 of a month for a given game from the compo4all server.
spNetC4AGetScoreLoads a top 500 for a given game from the compo4all server.
spNetC4AFilterScoreMakes, that every name appears only once in the scoreList
spNetC4AGetScoreOfMonthLoads a top 500 of a month for a given game from the compo4all server.
spNetC4CopyScoreListMakes an unique copy of the passed scorelist, e.g.
spNetC4AMakeScoresUniqueRemoves any double occurence of names in the score.
spNetC4ADeleteScoresFrees the linked list returned by spNetC4AGetScore.
spNetC4ACommitScoreCommits a score to a specific game to compo4all server.
spNetC4ACommitScoreParallelCommits a score to a specific game to compo4all server.
spNetC4ACreateProfileCreates a new profile on skeezix’ server.
spNetC4ADeleteAccountDeletes the given profile on skeezix server and maybe the file on your system.
spNetC4AEditProfileEdits an already existing profile on skeezix’ server.
spNetC4ACancelTaskCancels the C4A task running right now (if one is started).
spNetC4ACancelTaskParallelCancels the given C4A task.
spNetC4AGetTaskResultGets the result of the task when finished (check with spNetC4AGetStatus).
spNetC4AGetTaskResultParallelGets the result of the given task when finished (check with spNetC4AGetStatusParallel).
spNetC4AGetTimeOutGives you the time out of the C4A tasks.
spNetC4AGetTimeOutParallelGives you the time out of the given C4A task.
spNetC4AGetStatusGets the status of spNetC4AGetScore, spNetC4ACommitScore, spNetC4ACreateProfile, spNetC4AEditProfile & spNetC4ADeleteAccount.
spNetC4AGetStatusParallelGets the status of <spNetC4AGetScoreParallel> & spNetC4ACommitScoreParallel.
spNetC4ADeleteProfileFileDeletes the profile file on your system, NOT the online account at skeezix server.
spNetC4ADeleteTaskDeletes the task struct returned by the parallel working task functions.
spNetC4ASetCaching(De)Activates caching for C4A scores.
spNetC4AHowManyCachedReturns how many scores are cached

Macros

Compo4all statuses

Statuses for the committing and score-loading functions.

SP_C4A_PROGRESStransfer of data is in progress
SP_C4A_OKprocess is done and everything was fine
SP_C4A_ERRORprocess is done, but something went wrong

Types

spNetC4AGame

Type for a linked list of games from the compo4all highscore servers

Variables

longnamefull name of the game
shortnameshort name of the game
statusthe status of the highscore: 1 means available, 2 even more available (called “active” by skeezix, don’t really know, what this means), 0 inactive, which means, you shouldn’t show that game except for testing purpose.
genrethe genre of the game.
fieldwhich kind of game is it?  0 means just an indie game, 1 is a mame game, -1 means “don’t know” or “to be decided”.
nextpointer to the next element in the list

spNetC4AScore

Type for a linked list of scores gotten from the compo4all highscore servers

Variables

longnamefull name of the player
shortnamethree digit short name of the player
scorethe reached points
commitTimetime of type time_t (seconds since 1.1.1970 00:00:00), when the score was committed.  Use localtime of time.h to “decrypt” this type.  ;)
nextpointer to the next element in the list
rankrank in the score

spNetC4AProfile

A struct for your unique C4A Profile.

Variables

pridunique id of your account.  Keep it for you.  ;)
longnameyour full name
shortnameyour 3 digit short name

Functions

spNetC4AGetProfile

PREFIX spNetC4AProfilePointer spNetC4AGetProfile(void)

Reads your profile out of your c4a-prof file.  On the pandora the file is created by compo4all and stored on a pandora specific place.  On other systems for now your c4a-prof should be in the folder of your application.

Returns

spNetC4AProfilePointera pointer to an spNetC4AProfile struct

spNetC4AFreeProfile

PREFIX void spNetC4AFreeProfile(spNetC4AProfilePointer profile)

Frees the profile you got from spNetC4AGetProfile.

Parameters

profileprofile to free.  However of course your profile is not deleted.  ;)

spNetC4AGetGame

PREFIX int spNetC4AGetGame(spNetC4AGamePointer *gameList,
int timeOut)

Loads all games listed on the C4A server.  Use spNetC4AGetStatus to get the status of the task.  Only one compo4all background task can run at one time!

Parameters

gameLista pointer to spNetC4AGamePointer, which is in fact a pointer to spNetC4AGame.  The available games are saved here.
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut

Returns

int1 if the function failed for some reason, 0 at success starting the task.

spNetC4AGetGameParallel

PREFIX spNetC4ATaskPointer spNetC4AGetGameParallel(
   spNetC4AGamePointer *gameList,
   int timeOut
)

Loads all games listed on the C4A server.  Use spNetC4AGetStatusParallel to get the status of the task.  Don’t forget to delete the returned task struct with spNetC4ADeleteTask at the end.

Parameters

gameLista pointer to spNetC4AGamePointer, which is in fact a pointer to spNetC4AGame.  The available games are saved here.
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut

Returns

spNetC4ATaskPointerPointer to <spNetC4ATask> at success and NULL if an error occured.

spNetC4ADeleteGames

PREFIX void spNetC4ADeleteGames(spNetC4AGamePointer *gameList)

Frees the linked list returned by spNetC4AGetGame.

Parameters

firstGamepointer to spNetC4AGame to free

spNetC4AGetScore

PREFIX int spNetC4AGetScore(spNetC4AScorePointer *scoreList,
spNetC4AProfilePointer profile,
char *game,
int timeOut)

Loads a top 500 for a given game from the compo4all server.  The task runs in background!  Use spNetC4AGetStatus to get the status of the task.  Only one compo4all background task can run at one time!

Parameters

scoreLista pointer to spNetC4AScorePointer, which is in fact a pointer to spNetC4AScore.  The scores are saved here.
profilean optional pointer to your profile.  If given only your scores are added to the scores-list above
gamename of the game on the server
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut

Returns

int1 if the function failed for some reason, 0 at success starting the task.

See also: spNetC4AGetScoreOfMonth

spNetC4AGetScoreOfMonth

PREFIX int spNetC4AGetScoreOfMonth(spNetC4AScorePointer *scoreList,
spNetC4AProfilePointer profile,
char *game,
int year,
int month,
int timeOut)

Loads a top 500 of a month for a given game from the compo4all server.  The task runs in background!  Use spNetC4AGetStatus to get the status of the task.  Only one compo4all background task can run at one time!

Parameters

scoreLista pointer to spNetC4AProfilePointer, which is in fact a pointer to spNetC4AScore.  The scores are saved here.
profilean optional pointer to your profile.  If given only your scores are added to the scores-list above
gamename of the game on the server
yearyear to load (e.g.  2013)
monthmonth to load (e.g.  3 for march)
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut

Returns

int1 if the function failed for some reason, 0 at success starting the task.

See also: spNetC4AGetScore

spNetC4AGetScore

PREFIX spNetC4ATaskPointer spNetC4AGetScoreParallel(
   spNetC4AScorePointer *scoreList,
   spNetC4AProfilePointer profile,
   char *game,
   int timeOut
)

Loads a top 500 for a given game from the compo4all server.  The task runs in background!  Use spNetC4AGetStatus to get the status of the task.  Only one compo4all background task can run at one time!

Parameters

scoreLista pointer to spNetC4AScorePointer, which is in fact a pointer to spNetC4AScore.  The scores are saved here.
profilean optional pointer to your profile.  If given only your scores are added to the scores-list above
gamename of the game on the server
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut

Returns

spNetC4ATaskPointerPointer to <spNetC4ATask> at success and NULL if an error occured.

See also: <spNetC4AGetScoreOfMonthParallel>

spNetC4AFilterScore

PREFIX void spNetC4AFilterScore(spNetC4AScorePointer *scoreList)

Makes, that every name appears only once in the scoreList

Parameter

scoreLista pointer to spNetC4AScorePointer, which is in fact a pointer to spNetC4AScore.  These scores are changed.

spNetC4AGetScoreOfMonth

PREFIX spNetC4ATaskPointer spNetC4AGetScoreOfMonthParallel(
   spNetC4AScorePointer *scoreList,
   spNetC4AProfilePointer profile,
   char *game,
   int year,
   int month,
   int timeOut
)

Loads a top 500 of a month for a given game from the compo4all server.  The task runs in background!  Use spNetC4AGetStatusParallel to get the status of the task.  Don’t forget to delete the returned task struct with spNetC4ADeleteTask at the end.

Parameters

scoreLista pointer to spNetC4AProfilePointer, which is in fact a pointer to spNetC4AScore.  The scores are saved here.
profilean optional pointer to your profile.  If given only your scores are added to the scores-list above
gamename of the game on the server
yearyear to load (e.g.  2013)
monthmonth to load (e.g.  3 for march)
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut

Returns

spNetC4ATaskPointerPointer to <spNetC4ATask> at success and NULL if an error occured.

See also: <spNetC4AGetScoreParallel>

spNetC4CopyScoreList

Makes an unique copy of the passed scorelist, e.g. if you want to remove double names with spNetC4AMakeScoresUnique afterwards.  Don’t forget to free every copy with spNetC4ADeleteScores afterwards!

Parameters

scoreLista pointer to spNetC4AProfilePointer, which is in fact a pointer to spNetC4AScore, which shall be copied
newLista pointer to spNetC4AProfilePointer, which is in fact a pointer to spNetC4AScore, to which the copy shall be written

spNetC4AMakeScoresUnique

PREFIX void spNetC4AMakeScoresUnique(spNetC4AScorePointer *scoreList)

Removes any double occurence of names in the score.  Afterwars every name only occurs ones with the best score of this player.  Be careful: Afterwards you can’t use this list for uploading scores if they don’t exist anymore.  If you want both make a copy of the list with <spNetC4ACopyScoreList> before (instead of getting the scores twice).

Parameters

scoreLista pointer to spNetC4AProfilePointer, which is in fact a pointer to spNetC4AScore

spNetC4ADeleteScores

PREFIX void spNetC4ADeleteScores(spNetC4AScorePointer *scoreList)

Frees the linked list returned by spNetC4AGetScore.

Parameters

firstScorepointer to spNetC4AScore to free

spNetC4ACommitScore

PREFIX int spNetC4ACommitScore(spNetC4AProfilePointer profile,
char *game,
int score,
spNetC4AScorePointer *scoreList,
int timeOut)

Commits a score to a specific game to compo4all server.  The task runs in background!  Use spNetC4AGetStatusParallel to get the status of the task.  Don’t forget to delete the returned task struct with spNetC4ADeleteTask at the end.

Parameters

profilethe profile you want to commit tthe score with
gamename of the game on the server.  If this is empty (“”), at least the c4a cache will be tried to commit.
scorereached score
scoreListpass the struct returned by spNetC4AGetScore to compare your score to that list and avoid committing the same score twice.  If it is not in the list, it will added afterwards for later comparements.
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut.  If timeOut is 0, no thread is started, but the score is written to the cache if enabled!

Returns

int1 if the function failed for some reason (e.g. the score is already in the scoreList), 0 at success starting the task.

spNetC4ACommitScoreParallel

PREFIX spNetC4ATaskPointer spNetC4ACommitScoreParallel(
   spNetC4AProfilePointer profile,
   char *game,
   int score,
   spNetC4AScorePointer *scoreList,
   int timeOut
)

Commits a score to a specific game to compo4all server.  The task runs in background!  Use spNetC4AGetStatusParallel to get the status of the task.  Don’t forget to delete the returned task struct with spNetC4ADeleteTask at the end.

Parameters

profilethe profile you want to commit tthe score with
gamename of the game on the server
scorereached score
scoreListpass the struct returned by spNetC4AGetScore to compare your score to that list and avoid committing the same score twice.  If it is not in the list, it will added afterwards for later comparements.
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut If timeOut is 0, no thread is started, but the score is written to the cache if enabled!

Returns

spNetC4ATaskPointerPointer to <spNetC4ATask> at success and NULL if an error occured.

spNetC4ACreateProfile

PREFIX int spNetC4ACreateProfile(spNetC4AProfilePointer *profile,
char *longname,
char *shortname,
char *password,
char *email,
int timeOut)

Creates a new profile on skeezix’ server.  Blocks your application!  However, if network is avaible, should be quite fast.  Furthermore it creates the c4a-prof file needed by all supported applications.  The path of the file is platform depended.  Overwrites an already existing file!  The task runs in background!  Use spNetC4AGetStatus to get the status of the task.  Only one compo4all background task can run at one time!  Only for Pandora: If no c4a-prof is created until now and no c4a-mame appdata folder is available it will be created in the first folder in /media with pandora/appdata in it.  It MAY be, that skeezix’s C4A Manager will not find this c4a-prof if it will be installed later on another SD card!  However the spaghetti client, the fusilli client and the Sparrow C4A Manager will find this profile file in any case (if you don’t create a second c4a-prof with skeezix c4a manager.  It that case it is random which c4a-prof is used in the end...)

Parameters

profilea pointer to a pointer to spNetC4AProfile, where the profile shall be saved to.
longnamethe long name of the player.  Should only be alphanumeric.
shortnamethe short name of the player.  Should exactly 3 alphanumeric, capital letters.
passwordalphanumeric password
emailthe mail address of the new account.  Can be “”.
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut

Returns

int1 if the function failed for some reason, 0 at success starting the task.

See Also

spNetC4AEditProfile

spNetC4ADeleteAccount

PREFIX int spNetC4ADeleteAccount(spNetC4AProfilePointer *profile,
int deleteFile,
int timeOut)

Deletes the given profile on skeezix server and maybe the file on your system.  The task runs in background!  Use spNetC4AGetStatus to get the status of the task.  Only one compo4all background task can run at one time!

Parameters

profileprofile to delete from the server.
deleteFile1 if you want to delete the c4a-prof file at the end (at success), too.  0 leaves to file.
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut

Returns

int1 if the function failed for some reason, 0 at success starting the task.

spNetC4AEditProfile

PREFIX int spNetC4AEditProfile(spNetC4AProfilePointer *profile,
char *longname,
char *shortname,
char *password,
char *email,
int timeOut)

Edits an already existing profile on skeezix’ server.  Blocks your application!  However, if network is avaible, should be quite fast.  Furthermore it rewrites the c4a-prof file needed by all supported applications.  The path of the file is platform depended.  If the account doesn’t exist now, it will created.  The big difference to spNetC4ACreateProfile is, that the prid is read from the profile struct instead of being new created.  The task runs in background!  Use spNetC4AGetStatus to get the status of the task.  Only one compo4all background task can run at one time!

Parameters

profilethe profile to change.
longnamethe long name of the player.  Should only be alphanumeric.
shortnamethe short name of the player.  Should exactly 3 alphanumeric, capital letters.
passwordalphanumeric password
emailthe mail address of the new account.  Can be “”.
timeOutafter this time in ms the thread is killed.  Get it with spNetC4AGetTimeOut

Returns

int1 if the function failed for some reason, 0 at success starting the task.

See Also

spNetC4ACreateProfile

spNetC4ACancelTask

PREFIX void spNetC4ACancelTask(void)

Cancels the C4A task running right now (if one is started).

spNetC4ACancelTaskParallel

PREFIX void spNetC4ACancelTaskParallel(spNetC4ATaskPointer task)

Cancels the given C4A task.  Don’t forget to delete it afterwards with spNetC4ADeleteTask!

Parameters

taskpointer to <spNetC4ATask> returned from the parallel functions.

spNetC4AGetTaskResult

PREFIX int spNetC4AGetTaskResult(void)

Gets the result of the task when finished (check with spNetC4AGetStatus).

Returns

int0 if everything went fine, 1 at error

spNetC4AGetTaskResultParallel

PREFIX int spNetC4AGetTaskResultParallel(spNetC4ATaskPointer task)

Gets the result of the given task when finished (check with spNetC4AGetStatusParallel).

Parameters

taskpointer to <spNetC4ATask> returned from the parallel functions.

Returns

int0 if everything went fine, 1 at error

spNetC4AGetTimeOut

PREFIX int spNetC4AGetTimeOut(void)

Gives you the time out of the C4A tasks.

Returns

intthe timeOut in ms.

spNetC4AGetTimeOutParallel

PREFIX int spNetC4AGetTimeOutParallel(spNetC4ATaskPointer task)

Gives you the time out of the given C4A task.

Parameters

taskpointer to <spNetC4ATask> returned from the parallel functions.

Returns

intthe timeOut in ms.

spNetC4AGetStatus

spNetC4AGetStatusParallel

PREFIX int spNetC4AGetStatusParallel(spNetC4ATaskPointer task)

Gets the status of <spNetC4AGetScoreParallel> & spNetC4ACommitScoreParallel.

Parameters

taskpointer to <spNetC4ATask> returned from the parallel functions

Returns

intCompo4all statuses

spNetC4ADeleteProfileFile

PREFIX void spNetC4ADeleteProfileFile(void)

Deletes the profile file on your system, NOT the online account at skeezix server.  See also spNetC4ADeleteAccount.

spNetC4ADeleteTask

PREFIX void spNetC4ADeleteTask(spNetC4ATaskPointer task)

Deletes the task struct returned by the parallel working task functions.

Parameters

taskPointer to <spNetC4ATask>, which is returned by the parallel functions.

spNetC4ASetCaching

PREFIX void spNetC4ASetCaching(int value)

(De)Activates caching for C4A scores.  If caching is enabled every time spNetC4ACommitScore* fails, it is written to a cache file and the next time spNetC4ACommitScore* is called it will be tried to be committed again

Parameters

value0: No caching 1: Everything is cached 2: Only the best score of a game is cached 3: Same like 2, but lower score is better

spNetC4AHowManyCached

PREFIX int spNetC4AHowManyCached(void)

Returns how many scores are cached

Returns

intthe number of cached scores

IRC chat protocol stuff

Types and Functions for connecting to an IRC server, join channels and receive and send message.

Summary
Types
spNetIRCMessageType for a linked list of IRC messages managed from the IRC server.
spNetIRCNickType for a linked list of IRC nicks managed from the IRC server.
spNetIRCChannelType for a linked list of IRC channels managed from the IRC server.
spNetIRCServerHandle type for interaction with the irc server.
Functions
spNetIRCConnectServerConnects to an IRC server.
spNetIRCServerReadyReturns, whether the server is ready to be used, e.g.
spNetIRCJoinChannelJoins an IRC channel.
spNetIRCChannelReadyReturns, whether the channel is ready to be used, e.g.
spNetIRCSendMessageSends a message (PRIVMSG) to a channel or another user.
spNetIRCPartChannelLeave a channel / conversation.
spNetIRCCloseServerCloses the connection to the server, finishs the thread and releases the pointer handle!

Types

spNetIRCMessage

Type for a linked list of IRC messages managed from the IRC server.

Variables

typetype of the message (not always set)
useruser.  * means server
messagemessage of the message
nextpointer to the next element in the list
ctcpchar[16], if not “” the name of the ctcp event like ACTION.

spNetIRCNick

Type for a linked list of IRC nicks managed from the IRC server.

Variables

namename of the nick
rightsrights of the nick, e.g.  ‘ ‘, @ or +
nextpointer to the next element in the list

spNetIRCChannel

Type for a linked list of IRC channels managed from the IRC server.  With channel are meant channels from the type #meow and queries!

Variables

namename of the channel
statusinternal status flag of the channel
first_nickpointer to spNetIRCNick, first nick in the channel
last_nickpointer to spNetIRCNick, last nick in the channel
nextpointer to the next element in the list
first_messagepointer to spNetIRCMessage, first message in the channel
last_messagepointer to spNetIRCMessage, last message in the channel
last_read_messagepointer to spNetIRCMessage, last read message.  You have to update this yourself!
close_queryinternal message flag
first_add_messagepointer to spNetIRCMessage, internal chain
last_add_messagepointer to spNetIRCMessage, internal chain
last_add_read_messagepointer to spNetIRCMessage, internal chain

spNetIRCServer

Handle type for interaction with the irc server.  You should not use it direct but with the spNetIRC* functions.

Variables

namename/url of the server
portport of the server (most of the time 6667)
nicknamenickname of the chatter
realnamethe REAL name of the chatter!
firstChannelpointer the first element of a list of all channels
ipspNetIP struct.  IP of the server.
connectionspNetTCPConnection struct. connection handle to the server
threadSDL thread struct
finish_flagmessages for the server to finish
statusinternal status flag
counterinternal nickname counter
original_nicknameinternal nickname to copy from
first_messagepointer to spNetIRCMessage, first message of the server
last_messagepointer to spNetIRCMessage, last message of the server
last_read_messagepointer to spNetIRCMessage, last read message.  You have to update this yourself!
first_add_messagepointer to spNetIRCMessage, internal chain
last_add_messagepointer to spNetIRCMessage, internal chain
last_add_read_messagepointer to spNetIRCMessage, internal chain

Functions

spNetIRCConnectServer

PREFIX spNetIRCServerPointer spNetIRCConnectServer(char *name,
Uint16 port,
char *nickname,
char *username,
char *realname,
char *password)

Connects to an IRC server.  If the attempt was sucessful a new thread is created and a pointer to spNetIRCServer returned.

Parameters

namename/url of the server
portport of the server (e.g.  6667)
nicknamenickname to use.  If the nickname is already used, it will be used another one with numbers and stuff
usernameyour user name
realnameyour real name
passwordpassword

Returns

spNetIRCServerPointera pointer to spNetIRCServer to use in further spNetIRC* functions

spNetIRCServerReady

PREFIX int spNetIRCServerReady(spNetIRCServerPointer server)

Returns, whether the server is ready to be used, e.g. for joining channels

Parameters

serverpointer to spNetIRCServer struct

Returns

int1: the server is ready; 0: not ready.  If you try to join a channel on a not ready server, it may not work!

spNetIRCJoinChannel

PREFIX spNetIRCChannelPointer spNetIRCJoinChannel(spNetIRCServerPointer server,
char *name)

Joins an IRC channel.  Call it only if <spNetIRCReady> returns 1!

Parameters

serverpointer to spNetIRCServer struct
namename of the channel.  Has to start with #!

Returns

spNetIRCChannelPointerPointer to spNetIRCServerReady struct, handle for the channel

spNetIRCChannelReady

PREFIX int spNetIRCChannelReady(spNetIRCChannelPointer channel)

Returns, whether the channel is ready to be used, e.g. for sending messages

Parameters

channelpointer to spNetIRCChannel struct

Returns

int1: the channel is ready; 0: not ready.  -1: an error occured, e.g. you are banned

spNetIRCSendMessage

PREFIX void spNetIRCSendMessage(spNetIRCServerPointer server,
spNetIRCChannelPointer channel,
char *message)

Sends a message (PRIVMSG) to a channel or another user.  If channel is NULL it will be send to the server instead (e.g. spNetIRCSendMessage(server,NULL,”quit”) for /quit).

Parameters

serverpointer to spNetIRCServer struct
channelpointer to spNetIRCChannel struct, may be NULL
messagemessage to send

spNetIRCPartChannel

PREFIX void spNetIRCPartChannel(spNetIRCServerPointer server,
spNetIRCChannelPointer channel)

Leave a channel / conversation.  You should not use the channel pointer after this point.  It may need some time for the PART command to get to the server but at one point the pointer will be invalid!  It will removed from server then automaticly.

Parameters

spNetIRCServerPointera pointer to spNetIRCServer
channelpointer to spNetIRCChannel struct

spNetIRCCloseServer

PREFIX void spNetIRCCloseServer(spNetIRCServerPointer server)

Closes the connection to the server, finishs the thread and releases the pointer handle!

Parameters

spNetIRCServerPointera pointer to spNetIRCServer, which describes which server shall be exited
PREFIX void spInitNet(void)
Initializes sparrowNet.
PREFIX void spQuitNet(void)
Quits sparrowNet.
PREFIX spNetIP spNetResolve(char *host,
Uint16 port)
Resolves a ip to a hostname.
PREFIX char* spNetResolveHost(spNetIP ip,
char *host,
int host_len)
Gives you the hostname to an ip.
PREFIX spNetTCPConnection spNetOpenClientTCP(spNetIP ip)
Opens a connection to an ip
PREFIX spNetTCPServer spNetOpenServerTCP(Uint16 port)
Creates a server, which listens at a port
PREFIX spNetTCPConnection spNetAcceptTCP(spNetTCPServer server)
If a client tries to connect to your server, this function returns an established tcp connection from your server to the client.
PREFIX spNetIP spNetGetConnectionIP(spNetTCPConnection connection)
Gives you the ip of your connected client.
PREFIX int spNetSendTCP(spNetTCPConnection connection,
void *data,
int length)
Sends a tcp package to the ether.
PREFIX int spNetSendHTTP(spNetTCPConnection connection,
char *data)
Sends text over TCP with spNetSendTCP.
PREFIX int spNetReceiveTCP(spNetTCPConnection connection,
void *data,
int length)
Receives data from the other side.
PREFIX int spNetReceiveHTTP(spNetTCPConnection connection,
char *data,
int length)
Receives data from the other side until the other side disconnects.
PREFIX SDL_Thread* spNetReceiveTCPUnblocked(spNetTCPConnection connection,
void *data,
int length)
Receives data from the other side.
PREFIX SDL_Thread* spNetReceiveHTTPUnblocked(spNetTCPConnection connection,
char *data,
int length)
Receives data from the other side until the other side disconnects.
PREFIX int spNetReceiveStillWaiting(SDL_Thread *thread)
Says, whether a receive call (identified by the thread handle) still waits for an incoming signal.
PREFIX int spNetReceiveFinished(SDL_Thread *thread)
Says, whether a receive call (identified by the thread handle) still waits for an incoming signal.
PREFIX void spNetCloseTCP(spNetTCPConnection connection)
Closes a tcp connection or a server session.
PREFIX spNetC4AProfilePointer spNetC4AGetProfile(void)
Reads your profile out of your c4a-prof file.
PREFIX void spNetC4AFreeProfile(spNetC4AProfilePointer profile)
Frees the profile you got from spNetC4AGetProfile.
PREFIX int spNetC4AGetGame(spNetC4AGamePointer *gameList,
int timeOut)
Loads all games listed on the C4A server.
PREFIX spNetC4ATaskPointer spNetC4AGetGameParallel(
   spNetC4AGamePointer *gameList,
   int timeOut
)
Loads all games listed on the C4A server.
PREFIX void spNetC4ADeleteGames(spNetC4AGamePointer *gameList)
Frees the linked list returned by spNetC4AGetGame.
PREFIX int spNetC4AGetScore(spNetC4AScorePointer *scoreList,
spNetC4AProfilePointer profile,
char *game,
int timeOut)
Loads a top 500 for a given game from the compo4all server.
PREFIX int spNetC4AGetScoreOfMonth(spNetC4AScorePointer *scoreList,
spNetC4AProfilePointer profile,
char *game,
int year,
int month,
int timeOut)
Loads a top 500 of a month for a given game from the compo4all server.
PREFIX void spNetC4AFilterScore(spNetC4AScorePointer *scoreList)
Makes, that every name appears only once in the scoreList
PREFIX void spNetC4AMakeScoresUnique(spNetC4AScorePointer *scoreList)
Removes any double occurence of names in the score.
PREFIX void spNetC4ADeleteScores(spNetC4AScorePointer *scoreList)
Frees the linked list returned by spNetC4AGetScore.
PREFIX int spNetC4ACommitScore(spNetC4AProfilePointer profile,
char *game,
int score,
spNetC4AScorePointer *scoreList,
int timeOut)
Commits a score to a specific game to compo4all server.
PREFIX spNetC4ATaskPointer spNetC4ACommitScoreParallel(
   spNetC4AProfilePointer profile,
   char *game,
   int score,
   spNetC4AScorePointer *scoreList,
   int timeOut
)
Commits a score to a specific game to compo4all server.
PREFIX int spNetC4ACreateProfile(spNetC4AProfilePointer *profile,
char *longname,
char *shortname,
char *password,
char *email,
int timeOut)
Creates a new profile on skeezix’ server.
PREFIX int spNetC4ADeleteAccount(spNetC4AProfilePointer *profile,
int deleteFile,
int timeOut)
Deletes the given profile on skeezix server and maybe the file on your system.
PREFIX int spNetC4AEditProfile(spNetC4AProfilePointer *profile,
char *longname,
char *shortname,
char *password,
char *email,
int timeOut)
Edits an already existing profile on skeezix’ server.
PREFIX void spNetC4ACancelTask(void)
Cancels the C4A task running right now (if one is started).
PREFIX void spNetC4ACancelTaskParallel(spNetC4ATaskPointer task)
Cancels the given C4A task.
PREFIX int spNetC4AGetTaskResult(void)
Gets the result of the task when finished (check with spNetC4AGetStatus).
PREFIX int spNetC4AGetStatus(void)
Gets the status of spNetC4AGetScore, spNetC4ACommitScore, spNetC4ACreateProfile, spNetC4AEditProfile & spNetC4ADeleteAccount.
PREFIX int spNetC4AGetTaskResultParallel(spNetC4ATaskPointer task)
Gets the result of the given task when finished (check with spNetC4AGetStatusParallel).
PREFIX int spNetC4AGetStatusParallel(spNetC4ATaskPointer task)
Gets the status of spNetC4AGetScoreParallel & spNetC4ACommitScoreParallel.
PREFIX int spNetC4AGetTimeOut(void)
Gives you the time out of the C4A tasks.
PREFIX int spNetC4AGetTimeOutParallel(spNetC4ATaskPointer task)
Gives you the time out of the given C4A task.
PREFIX void spNetC4ADeleteProfileFile(void)
Deletes the profile file on your system, NOT the online account at skeezix server.
PREFIX void spNetC4ADeleteTask(spNetC4ATaskPointer task)
Deletes the task struct returned by the parallel working task functions.
PREFIX void spNetC4ASetCaching(int value)
(De)Activates caching for C4A scores.
PREFIX int spNetC4AHowManyCached(void)
Returns how many scores are cached
PREFIX spNetIRCServerPointer spNetIRCConnectServer(char *name,
Uint16 port,
char *nickname,
char *username,
char *realname,
char *password)
Connects to an IRC server.
PREFIX int spNetIRCServerReady(spNetIRCServerPointer server)
Returns, whether the server is ready to be used, e.g.
PREFIX spNetIRCChannelPointer spNetIRCJoinChannel(spNetIRCServerPointer server,
char *name)
Joins an IRC channel.
PREFIX int spNetIRCChannelReady(spNetIRCChannelPointer channel)
Returns, whether the channel is ready to be used, e.g.
PREFIX void spNetIRCSendMessage(spNetIRCServerPointer server,
spNetIRCChannelPointer channel,
char *message)
Sends a message (PRIVMSG) to a channel or another user.
PREFIX void spNetIRCPartChannel(spNetIRCServerPointer server,
spNetIRCChannelPointer channel)
Leave a channel / conversation.
PREFIX void spNetIRCCloseServer(spNetIRCServerPointer server)
Closes the connection to the server, finishs the thread and releases the pointer handle!
An IP address resolved by sparrowNet.
A struct for your unique C4A Profile.
Type for a linked list of games from the compo4all highscore servers
Type for a linked list of scores gotten from the compo4all highscore servers
Statuses for the committing and score-loading functions.
Type for a linked list of IRC nicks managed from the IRC server.
Type for a linked list of IRC messages managed from the IRC server.
a type for open tcp connections.
Handle type for interaction with the irc server.
Type for a linked list of IRC channels managed from the IRC server.
Close