-	Compagnie ~ Produits ~ Boutique ~ Communauté

Tutoriel

Librairie

Application test

Téléchargement

Manuel de la librairie libSock

La libraire qui fait l'objet de ce tutoriel peut être téléchargée via la rubrique Téléchargement de cette page. L'archive doit simplement être extraite dans le dossier de votre choix. Le répertoire "/Sources" contient le code source de la librairie. L'archive contient également deux dossiers permettant de compiler la libraire sous Windows (projet Visual Studio) et sous Linux (makefile).

Compilation Linux

Pour compiler la librairie sous linux, ouvrez une console dans le répertoire contenant le fichier "libSock.mk" et exécutez les commandes suivantes :

make -f libSock.mk all
make -f libSock.mk install

La libraire sera alors compilée ("libSock.so") et installée dans le répertorie "/user/lib". Un dossier "Includes" est également créé. Il contient les fichiers d'en-têtes déclarant les fonctions contenues dans la libriarie.

Compilation Windows

Le projet Visual Studio contenu dans le répertoire Windows permet de compiler facilement la librairie. Les fichiers importants qui sont générés sont "libSock.dll" et "libSock.lib".

Si vous avez besoin de créer un projet depuis un autre envrionnement de compilation, n'oubliez pas de définir le symbole LIBSOCK_EXPORTS dans la commande de définition du préprocesseur. Cela a pour effet d'activer la directive de compilation __declspec(dllexport) permettant à certaines fonctions d'être exportées de la librairie (voir fichier "libSock.h".

Test de la librairie

Une application testant les fonctions de la librairie est également disponible dans la rubrique Téléchargement et est commentée dans la rubrique Application test.

Manuel

Chacune des fonctions exportées par la libraire est décrite ci après :

Fonction "SK_NewServer"

Cette fonction permet de créer un serveur :

SockError_C SK_NewServer (
unsigned int maxLink,
unsigned int *pID );

maxLink : [in] Nombre maximum de clients / connexions que le serveur pourra gérer.

pID : [out] ID du serveur nouvellement créé. Cette valeur est à utiliser avec les autres fonctions de la librairie.

Valeur de retour : Structure contenant les codes d'erreur en cas d'échec.

Fonction "SK_NewClient"

Cette fonction permet de créer un client. Un client permet de gérer une seule connexion / socket :

SockError_C SK_NewClient (
unsigned int *pID );

pID : [out] ID du client nouvellement créé. Cette valeur est à utiliser avec les autres fonctions de la librairie.

Valeur de retour : Structure contenant les codes d'erreur en cas d'échec.

Fonction "SK_DeleteCS"

Cette fonction permet libérer les ressources d'un client ou d'un serveur :

SockError_C SK_DeleteCS (
unsigned int ID );

ID : [in] ID du client ou du serveur qu'il faut libérer.

Valeur de retour : Structure contenant les codes d'erreur en cas d'échec.

Fonction "SK_Listen"

Cette fonction active ou arrête l'écoute d'un serveur :

SockError_C SK_Listen (
unsigned int ID,
bool state,
unsigned int maxWaiting,
unsigned int port );

ID : [in] ID du serveur sur lequel activer ou arrêter l'écoute.

state : [in] état ON/OFF de l'écoute.

maxWaiting : [in] nombre maximum de clients pouvant simultanément être en attente d'activation de leur demande de connexion (si "state" = TRUE).

port : [in] port sur lequel activer l'écoute (si "state" = TRUE).

Valeur de retour : Structure contenant les codes d'erreur en cas d'échec.

Fonction "SK_Accept"

Cette fonction enterine une demande de connexion réalisée par un client. Elle doit être utilisée avec un serveur et l'écoute doit déjà avoir été activée pas la fonction "SK_Listen" :

SockError_C SK_Accept (
unsigned int ID,
int waitTime,
unsigned int *pIDLink );

ID : [in] ID du serveur sur lequel accepter une connexion.

waitTime : [in] nombre maximum de millisecondes pendant lesquelles la fonction peut bloquer si aucune demande de connexion n'a été faite. Une valeur négative signifie une attente potentiellement infinie. La valeur 0 signifie que la fonction rend la main immédiatement après un seul essai.

pIDLink : [out] ID du lien identifiant le socket client créé sur ce serveur si une demande de connexion a été acceptée. Après l'appel de la fonction, le lien est valide seulement si différent de 0.

Valeur de retour : Structure contenant les codes d'erreur en cas d'échec.

Fonction "SK_Connect"

Cette fonction réalise une demande de connexion vers un serveur dont l'adresse est spécifiée :

SockError_C SK_Connect (
unsigned int ID,
int waitTime,
char* addr,
unsigned int port,
unsigned int *pIDLink );

ID : [in] ID du client a connecter au serveur.

waitTime : [in] nombre maximum de millisecondes pendant lesquelles la fonction peut bloquer si la connexion au serveur n'est pas possible immédiatement. Une valeur négative signifie une attente potentiellement infinie. La valeur 0 signifie que la fonction rend la main immédiatement après un seul essai.

addr : [in] adresse du serveur auquel se connecter. Elle peut être entrée sous forme de nom ou sous forme décimale pointée (ex : "127.0.0.1").

port : [in] numéro de port sur lequel le serveur est en écoute.

pIDLink : [out] ID du lien identifiant le socket si la connexion réussi. Après l'appel de la fonction, le lien est valide seulement si différent de 0.

Valeur de retour : Structure contenant les codes d'erreur en cas d'échec.

Fonction "SK_Disconnect"

Cette fonction ferme une connexion :

SockError_C SK_Disconnect (
unsigned int ID,
unsigned int IDLink );

ID : [in] ID du client ou du serveur qui détient le socket de connexion (fonction SK_NewClient ou SK_NewServer).

IDLink : [in] ID du lien identifiant le socket de connexion (fonction SK_Connect ou SK_Accept).

Valeur de retour : Structure contenant les codes d'erreur en cas d'échec.

Fonction "SK_Write"

Cette fonction écrit un paquet de données sur le socket spécifié :

SockError_C SK_Write (
unsigned int ID,
unsigned int IDLink,
unsigned char *pData,
int *pLength,
int waitTime_ms );

ID : [in] ID du client ou du serveur qui détient le socket (fonction SK_NewClient ou SK_NewServer).

IDLink : [in] ID du lien identifiant le socket (fonction SK_Connect ou SK_Accept).

pData : [in] pointeur vers les données à écrire.

pLength : [in, out] cette variable doit contenir initialement le nombre de données contenues dans pData et qu'il faut envoyer sur le socket. Après l'appel de la fonction, la valeur est modifiée afin de refléter le nombre d'octets de données qui ont réellement pu être evnoyés au correspondant.

waitTime_ms : [in] nombre maximum de millisecondes pendant lesquelles la fonction peut bloquer si les buffers internes du socket sont pleins et qu'on ne peut pas y stoquer les données à envoyer. Une valeur négative signifie une attente potentiellement infinie. La valeur 0 signifie que la fonction rend la main immédiatement arpès un seul essai.

Valeur de retour : Structure contenant les codes d'erreur en cas d'échec.

Fonction "SK_Read"

Cette fonction permet de lire un paquet de données en se mettant en écoute d'un ou plusieurs sockets en même temps. Tous les sockets spécifiés sont en écoute initialement. Toutefois, dès que l'un d'eux à renvoyé des données, il est le seul qui continue à être lu afin de ne pas mélanger les données en provenance de plusieurs clients :

SockError_C SK_Read (
S_ReadList *pList,
unsigned int listLength,
unsigned char *pBuffer,
int *pLength,
int waitTime_ms,
S_ReadList *pIDRead,
bool dontBlockIfData );

pList : [in] pointeur vers une liste de structures de type S_ReadList précisant les sockets sur lesquels la lecture de données doit avoir lieu.

listLength : [in] nombre de structures dans la liste "pList".

pBuffer : [in] pointeur sur la zone mémoire dans laquelle stoquer les données reçues.

pLength : [in, out] cette variable doit contenir initialement le nombre de données à lire sur l'un des sockets spécifiés par "pList". Après l'appel de la fonction, la valeur est modifiée afin de refléter le nombre d'octets de données qui ont réellement pu être lus. La valeur "-1" indique que le socket a été déconnecté.

waitTime_ms : [in] nombre maximum de millisecondes pendant lesquelles la fonction peut bloquer si les buffers internes des sockets considérés sont vides (aucune données reçues). Une valeur négative signifie une attente potentiellement infinie. La valeur 0 signifie que la fonction rend la main immédiatement arpès un seul essai sur chacun des sockets spécifiés.

pIDRead : [out] adresse d'une structure S_ReadList remplie avec les IDs permettant d'identifier le correspondant de qui les données ont été reçues parmi tous ceux qui étaient en écoute.

dontBlockIfData : [in] si TRUE, la fonction rend la main dès qu'au moins un octet a été reçu de l'un des sockets en écoute, même le nombre total de données demandé ("pLength") n'est pas atteint et que le timeout ("waitTime_ms") n'a pas expiré.

Valeur de retour : Structure contenant les codes d'erreur en cas d'échec. Une déconnexion n'est pas considérée comme une erreur et doit donc être détectée en vérifiant que "pLength" ne vaut pas "-1" après l'appel.

Dernière mis à jour : 05/2008