Référence du fichier functions.c

code interne des fonctions Scol contient le code interne des fonctions de l'API Scol Plus de détails...

Aller au code source de ce fichier.

Fonctions
int	sc_getFile (mmachine m)
	Récupère un fichier sur le net et l'enregistre localement.
void	sc_newUrlCBend (struct StrExample *strEx)
	Callback interne appelée lorsque le trnasfert de données est terminé après un appel à sc_newGetUrl.
size_t	sc_newUrlCB (void *ptr, size_t size, size_t nmemb, void *p_strEx)
	Callback interne appelée lorsque le transfert est en cours (à chaque paquet reçu).
int	sc_newGetUrl (mmachine m)
	Code interne de la fonction Scol example_newUrl.
int	sc_delGetUrl (mmachine m)
	Destruction explicite d'un objet Scol.

---

Description détaillée

code interne des fonctions Scol contient le code interne des fonctions de l'API Scol

Auteur:

iri <iri-@-irizone.net>

Date:

novembre 2010

Définition dans le fichier functions.c.

---

Documentation des fonctions

int sc_delGetUrl

(

mmachine

m

)

Destruction explicite d'un objet Scol.

Paramètres:

structure

mmachine

Renvoie:

int 0 (or NIL)

Cettedestruction, après le test sur la validité de l'objet, consiste à appeler la fonction OBJdelTM en lui passant le handle Scol en argument. C'est tout.

Définition à la ligne 450 du fichier functions.c.

{
    int obj;

    MMechostr (MSKDEBUG, "sc_delGetUrl entering ...\n");

    /* On récupère l'objet et on le teste */
    obj = MTOP (MMget (m, 0));
    if (obj == NIL)
    {
        MMechostr (MSKDEBUG, "sc_delGetUrl : object aleady destroyed\n");
        MMset (m, 0, NIL);
        return 0;
    }

    /* On utilise la fonctiond e conversion \a PTOM car ns avons besoin de l'objet Scol */
    OBJdelTM (m, OBJCURL_HANDLE, PTOM (obj));
    /* On fait retourner 0 à la fonction Scol appelante */
    MMset (m, 0, 0);

    return 0;
}

int sc_getFile

(

mmachine

m

)

Récupère un fichier sur le net et l'enregistre localement.

Paramètres:

struct

mmachine

Renvoie:

0

Code interne de la fonction Scol example_getFile

On récupère les valeurs des arguments passés à la fonction Scol grâce aux fonctions habituelles. On teste leur validité.

On code normalement la partie correspondante à la bibliothèque libcurl, comme si c'était un programme C quelconque (ce qui est d'ailleurs le cas !). On n'oublie pas de libérer les ressources précédemment allouées et on retourne 0 à la fonction Scol si tout est ok.

Notez qu'en cas d'erreurs sur les arguments, la fonctions Scol renverra d'autres valeurs :

1 - si le fichier distant ou local vaut nil; 2 - si la bibliothèque libcuel n'a pu s'initialiser correctement; 3 - si le fichier local n'a pu être ouvert en écriture.

Définition à la ligne 50 du fichier functions.c.

{
    int murl, mlocalfile, len;
    char * url, * localfile, * err = NULL;

    CURL * hCurl;     /* handle */
    CURLcode rCurl; /* result */
    FILE * fp = NULL;

    MMechostr (MSKDEBUG, "sc_getFile : entering ...\n");

    mlocalfile = MTOP (MMpull (m));
    murl = MTOP (MMpull (m));

    if ((mlocalfile == NIL) || (murl == NIL))
    {
        MMechostr (MSKDEBUG, "sc_getFile error : url or localfile is nil\n");
        MMpush (m, ITOM (1));
        return 0;
    }

    hCurl = curl_easy_init();
    if (hCurl)    /* init ok */
    {
        len = sizeof (char) * (MMsizestr (m, mlocalfile));
        localfile = (char *) malloc (len+1);
        strncpy (localfile, MMstartstr (m, mlocalfile), len);
        localfile[len] = '\0';

        fp = fopen (localfile, "w");
        if (fp == NULL)
        {
            curl_easy_cleanup (hCurl);
            free (localfile); localfile = NULL;
            MMpush (m, ITOM (3));
            return 0;
        }

        err = (char *) malloc (sizeof (char) * (CURL_ERROR_SIZE +1));
        len = sizeof (char) * (MMsizestr (m, murl));
        url = (char *) malloc (len+1);
        strncpy (url, MMstartstr (m, murl), len);
        url[len] = '\0';

        curl_easy_setopt (hCurl, CURLOPT_URL, url);
        curl_easy_setopt (hCurl, CURLOPT_WRITEFUNCTION, fwrite);
        curl_easy_setopt (hCurl, CURLOPT_WRITEDATA, (FILE *) fp);
        curl_easy_setopt (hCurl, CURLOPT_USERAGENT, "libcurl-agent/1.0");
        curl_easy_setopt (hCurl, CURLOPT_ERRORBUFFER, err);
        rCurl = curl_easy_perform (hCurl);

        MMechostr (MSKDEBUG, "sc_getFile : err = %s ...\n", err);
        curl_easy_cleanup (hCurl);
        fclose (fp);

        free (localfile); localfile = NULL;
        free (url); url = NULL;
        free (err); err = NULL;

        MMpush (m, ITOM (0));
        return 0;
    }

    MMpush (m, ITOM (2));
    return 0;
}

int sc_newGetUrl

(

mmachine

m

)

Code interne de la fonction Scol example_newUrl.

Paramètres:

struct

mmachine

Renvoie:

0

Cette fonction propose d'envoyer une requête simple de type GET à un serveur et d'exécuter une fonction Scol spécifique (callback) à chaque réception de paquets en réponse à la requête.

Ce code présente :

• la création d'objet de type Scol
• la définition d'une fonction réflexe Scol

Pour créer un objet Scol, il est impératif de connaître le canal sur lequel le créer. D'autres paramètres peuvent être requis suivant les cas mais le canal est le seul requis dans tous les cas. Il n'y a aucun traitement à faire au sujet du canal, c'est transparent, le traitement est fait bien en profondeur, au niveau du kernel. Cependant, le canal doit être présent dans la pile, en position 0, lors de l'appel de la fonction de création. Ceci est impératif ! Le canal doit être à l'étage 0 de la pile ! Si ce n'est pas le cas, vous devez le déplacer.

Pour créer un objet Scol, il faut tout d'abord lui allouer de la mémoire (c'est le cas le plus fréquent (si ce n'est le seul dans une pratique usuelle) d'allocation directe de mémoire d'un objet de la VM). Ce sera fait avec MMalloc avec pour argument, la machine Scol courante, la taille à allouer et le type (tableau (TYPETAB) ou buffer (TYPEBUF)) :

 int objtab = MMalloc (m, sizeof (type), TYPEDEF);

Comme toute allocation, celle-ci doit être testée. On stocke alors le nouvel objet via la fonction MMstore : la machine Scol, le retour de MMalloc, un flag correspondant à l'objet et le pointeur système.

 MMstore (m, objtab, OBJ_HANDLE, (int) obj_handle);

Alors, il est possible d'inclure ledit objet dans la pile afin de le retourner à la fonction appelante de création, généralement via un \æ MMpush des plus classiques.

Enfin, création de l'objet du type Scol défini, via OBJcreate qui prend en arguments : la machine Scol, le type d'objet, l'objet système, le type del'objet parent (peut être NULL) et l'objet système du parent (peut être NULL).

Récapitulatif :

• création de l'objet en C ou en C++ selon les cas
• allocation de émmoire pour l'objet au sein de la VM (MMalloc)
• stockage de l'objet (MMstore)
• empilement pour le retour de la fonction Scol (MMpush)
• creation de l'objet Scol (OBJcreate)

Pour ajouter une fonction réflexe à un objet Scol :

Il faut un objet valide (c'est une évidence mais il convient donc de tester sa validité !); et appeler la fonction OBJaddreflex. Celle-ci prend en argument :

• la machine Scol en cours,
• le type Scol de l'objet,
• un flag spécifique à la callback

La fonction exemple demande une url en entrée et retourne un objet Scol de type ObjCurl en sortie. Entre temps, la fonction Scol aura également définie une callback qui sera exécutée à chaque paquet reçu. Son proptotype Scol : fun [Chn S S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl

En entrée :

• le canal
• l'url
• un paramètre non traité ici mais qui pourrait être un header pour la requête par exemple
• une callback
• un paramètre utilisateur utilisée dans la callback

En retour, un nouvel objet de type ObjCurl.

La callback, dont le type est (rappel) : fun [ObjCurl u0 S I S S] u1 est ainsi définie :

• l'objet de type ObjCurl dont dépend la callback,
• le paramètre utilisateur,
• le paquet de données reçu,
• la taille du paquet reçu,
• l'url d'origine,
• le message d'erreur éventuel de libcurl.

Définition à la ligne 325 du fichier functions.c.

{
    int mchannel, murl;
    int curltab, sizetab, tmp_res, n;
    CURLcode rCurl;
    struct StrExample strEx;

    MMechostr (MSKDEBUG, "sc_newGetUrl : entering ...\n");

    memset (strEx.cerr, '\0', CURL_ERROR_SIZE);

    /* Récupération du canal dans lequel se déroule toute notre action ! */
    mchannel = MMget (m, 4);
    if (mchannel == NIL)
    {
        MMechostr (0, "sc_newGetUrl error : channel is nil\n");
        MMpull (m);
        MMpush (m, NIL);
        return 0;
    }

    /* Récupération de l'url distante */
    murl = MTOP (MMget (m, 3));
    if (murl == NIL)
    {
        MMechostr (0, "sc_newGetUrl error : url is nil\n");
        MMpull (m);
        MMpush (m, NIL);
        return 0;
    }

    /* On place le canal à l'étage 0 de la pile ! C'est IMPORTANT ! L'étage 0 (paramèter utilisateur
        de la callback) se retrouve en 4 on en aura besoin plus tard d'où la non-utilisation de MMset ... */
    INVERT (m, 0, 4);

    /* initialisation globale de la libcurl */
    if (curl_global_init (CURL_GLOBAL_ALL) != CURLE_OK)
    { /* échec de l'initialisation globale, on arrête tout */
        MMechostr (0, "sc_newGetUrl error : global init failed\n");
        MMpull (m);
        MMpush (m, NIL);
        return 0;
    }

    /* initialisation d'une session de la libcurl */
    strEx.hcurl = curl_easy_init();
    /* initialisation OK, on continue  */
    if (strEx.hcurl)
    {
        /* calcul de la taille nécessaire en mémoire pour l'objet concerné */
        sizetab = sizeof (strEx.hcurl) + 1;
        /* allocation de la mémoire de la taille précédemment retournée */
        curltab = MMmalloc (m, sizetab, TYPETAB);
        /* test du retour de l'allocation */
        if ((curltab == NIL))
        {
            MMechostr (0, "sc_newGetUrl error : insufficient memory\n");
            curl_easy_cleanup (strEx.hcurl);
            MMpull (m);
            MMpush (m, NIL);
            return 0;
        }
        /* stockage de l'objet dans l'espace mémoire alloué */
        MMstore (m, curltab, OBJCURL_HANDLE, (int) strEx.hcurl);
        /* empile de l'objet pour son utilisation en retour de la fonction Scol appelante */
        MMpush (m, PTOM (curltab));
        /* Création de l'objet Scol proprement dit
         après le MMpushprécédent, le canal se tretrouve donc en position 1 dans la pile, ce qui
         est ok pour l'appel de OBJcreate. Après, on aura plus besoin de connaître le canal
         et on pourra sacrifier l'étage 1 si besoin est */
        OBJcreate (m, ObjCurl, (int) strEx.hcurl, -1, -1);

        n = sizeof (char) * (MMsizestr (m, murl));
        strEx.url = (char *) malloc (n+1);
        strncpy (strEx.url, MMstartstr (m, murl), n);
        strEx.url[n] = '\0';

        strEx.m2m = m;

        /* on intervertit des étages dans la pile :
            l'objet session de libcurl passe à l'étage 2
            le paramètreutilisateur repasse en position 0, comme au départ */
        INVERT (m, 0, 2);   /* hCurl se retrouve en 2 */
        INVERT (m, 0, 4);   /* user param se retrouve en 0 */
        /* On ajoute la callback définie dans le package Scol */
        OBJaddreflex (m, ObjCurl, CURL_CB_GET);

        curl_easy_setopt (strEx.hcurl, CURLOPT_URL, strEx.url);
        curl_easy_setopt (strEx.hcurl, CURLOPT_ERRORBUFFER, strEx.cerr);
        curl_easy_setopt (strEx.hcurl, CURLOPT_WRITEDATA, &strEx);
        curl_easy_setopt (strEx.hcurl, CURLOPT_WRITEFUNCTION, sc_newUrlCB);
        curl_easy_setopt (strEx.hcurl, CURLOPT_USERAGENT, "libcurl-agent/1.0");

        rCurl = curl_easy_perform (strEx.hcurl);
        sc_newUrlCBend (&strEx);

        curl_easy_cleanup (strEx.hcurl);
        curl_global_cleanup();

        free (strEx.url);
        /*free (strEx.cerr);*/

        return 0;
    }

    /* l'initialisation a échoué */
    MMechostr (0, "sc_newGetUrl error : easy init failed\n");
    curl_global_cleanup();

    MMpull (m);
    MMpush (m, NIL);
    return 0;
}

size_t sc_newUrlCB	(	void *	ptr,
		size_t	size,
		size_t	nmemb,
		void *	p_strEx
	)

Callback interne appelée lorsque le transfert est en cours (à chaque paquet reçu).

Paramètres:

	void	* ptr : pointeur sur les dernières données reçues
	size_t	size : taille d'un bloc
	size_t	nmemb : nombre de blocs
	void	* strEx : pointeur sur la structure strExample associée à la connexion

Renvoie:

la taille total du paquet reçu (ou -1 pour stopper la transaction)

Cette fonction va appeler la callback Scol définie lors de la demande de transfert.

Pour appeler une telle callback, il faut savoir si elle existe (si une telle fonction Scol a été définie dans l'environnement appelant) : c'est ce que va entre autres réalisée OBJbeginreflex : elle retournera 0 si c'est OK.

Cette fonction prend les arguments suivants : la machine Scol courante; l'objet Scol concerné, le pointeur objet système concerné un flag spécifique au type de callback souhaité (une même machine Scol, un objet Scol et un même objet système peuvent avoir plusieurs callbacks telles que clic, rollover, création, destruction, ...). Si tout est ok, elle retournera 0. Il est donc impératif de tester son retour.

Chaque callback Scol contient au moins deux arguments implicites dans le code interne :

• l'objet Scol appelant;
• le paramètre utilisateur, laissé à la discrétion du programmeur Scol

Il est possible d'en ajouter d'autres. Pour cela, il est nécessaire de les empiler sur la pile courante dans l'ordre de la fonction callback Scol :

callback_Scol : objet_Scol paramètre_utilisateur paramètre_supplémentaire_1 paramètre_supplémentaire_2... paramètre_supplémentaire_n

Dans le code interne, il faudra alors empiler d'abord paramètre_supplémentaire_1 puis paramètre_supplémentaire_2 ... jusqu'à paramètre_supplémentaire_n.

Comme on a vu; l'objet_scol et le paramètre_utulisateur ne sont pas explicités dans la pile MAIS ils doivent être présents lors de la déclaration de la callback (cf commentaire de sc_newGetUrl).

Enfin, on peut appeler la fonction (si et seulement si OBJbeginreflex a retourné 0) OBJcallreflex qui elle-même demandera l'exécution de la fonction Scol correspondante.

OBJcallreflex prend deux arguments : la machine Scol courante et le nombre d'arguments supplémentaires, c'est-à-dire ceux qu'on a explicité juste avant.

Définition à la ligne 203 du fichier functions.c.

{
    mmachine m;
    char * data = NULL;
    int cb;
    size_t n;
    struct StrExample * strEx;
    CURL * hCurl;

    MMechostr (MSKDEBUG, "sc_newUrlCB : entering ...\n");
    strEx = (struct StrExample *) p_strEx;

    m = (mmachine) strEx->m2m;
    hCurl = (CURL *) strEx->hcurl;

    cb = OBJbeginreflex (m, ObjCurl, (int) hCurl, CURL_CB_GET);
    if (cb)     /* pas de callback Scol enregistré avec ces paramètres */
    {
        MMechostr (0, "sc_newUrlCB error : no callback defined ! errcode = %d\n", cb);
        return -1;
    }

    n = (sizeof (char) * size * nmemb);
    data = (char *) malloc (n+1);
    if (data == NULL)
        return -1;
    strncpy (data, ptr, n);
    data[n] = '\0';

    /* ajout des paramètres supplémentaires (en plus de
        l'objet 'ObjCurl' et du paramètre utilisateur 'u0') */
    Mpushstrbloc (m,  data);            /* données reçues */
    MMpush (m, ITOM (size*nmemb));      /* taille du paquet reçu */
    Mpushstrbloc (m,  strEx->url);      /* url (rappel) */
    Mpushstrbloc (m,  strEx->cerr);     /* message d'erreur éventuel de libcurl */
    /* appel de la callback Scol avec 4 paramètres supplémentaires qui seront cherchés dans la pile */
    OBJcallreflex (m, 4);
    if (data)
        free (data);

    return size*nmemb;
}

void sc_newUrlCBend

(

struct StrExample *

strEx

)

Callback interne appelée lorsque le trnasfert de données est terminé après un appel à sc_newGetUrl.

Paramètres:

structstrExample

Renvoie:

(void)

Lorsque le transfert est terminée, la callback Scol est une dernière fois appelée : aucune donnée n'est évidemment transmise; aune taille n'est tramise; l'url est transmise; l'erreur est transmise.

Comme c'est la même callback Scol qui est appelée, les 4 arguments supplémentaires sont ajoutées et la fonction Scol définie appelée (OBJcallreflex).

Définition à la ligne 133 du fichier functions.c.

{
    mmachine m;
    CURL * hCurl;
    int cb;

    MMechostr (MSKDEBUG, "sc_newUrlCBend : entering ...\n");

    m = (mmachine) strEx->m2m;
    hCurl = (CURL *) strEx->hcurl;

    cb = OBJbeginreflex (m, ObjCurl, (int) hCurl, CURL_CB_GET);
    if (cb)
    {
        MMechostr (0, "sc_newUrlCBend error : no callback defined ! errcode = %d\n", cb);
        return;
    }

    MMpush (m, NIL);
    MMpush (m, NIL);
    Mpushstrbloc (m,  strEx->url);
    Mpushstrbloc (m,  strEx->cerr);
    OBJcallreflex (m, 4);
    return;
}