Plugins pour mMosaic

L'implementation de plugin est la suite d'un projet d'eleve realise en Juin 2000 par GEORGE Lise, HOURS Simon, FERLICOT Frédérici et DEURVEILHER Gilles.

A partir de la version 3.6.9, mMosaic est capable de charger dynamiquement du code executable. Le developpement de plugin est relativement facile, il faut cependant une bonne connaissance de Motif. La methode est assez similaire a celle des plugins netscape en plus simple... mMosaic se base sur le marqueur <OBJECT> du w3c

Votre premier plugin, pas a pas.

Creer une page html avec le code suivant:

        <OBJECT classid=helloworld width=80 height=20>
        </OBJECT>

classid.so est le nom de l'executable qui sera charge dynamiquement par mMosaic. L'executable sera copie dans /usr/local/mMosaic/plugins/helloworld.so. Creer le fichier helloworld.c. Compiler-le de la maniere suivante:

  cc -KPIC -G -I/usr/local/mMosaic/include -o helloworld.so helloworld.c (pour Solaris)

  cc -fpic -shared -I/usr/local/mMosaic/include -o helloworld.so helloworld.c (pour Linux)

Copier ce fichier dans le repertoire de plugin de mMosaic:

 cp helloworld.so /usr/local/mMosaic/helloworld.so
 chmod 755 /usr/local/mMosaic/helloworld.so

Les fonctions du plugins

int MPP_Initialize(HtmlObjectStruct *)
Cette fonction est appelee au moment du 'parsing' par mMosaic. Elle prepare l'appelle a MPP_new. Aucune fenetre n'est pour le moment creee. On teste la validite du plugin, comme par exemple les parametres et/ou la taille de la fenetre de visualisation. Elle positionne la methode de recuperation de donnees du champ DATA du marqueur OBJECT. Elle retourne '1' si tout est bon, sinon '0'.

	int MPP_Initialize(HtmlObjectStruct * obs)
	{
		if (obs->mp_class->release < MP_PLUGIN_RELEASE )
			/* ou afficher un message de chargement */
			return 0;

		if( obs->width == 0 || obs->height == 0) {
			/* en positionnant width et height, il y aura creation
			 * de fenetre ; sinon le plugin est 'externe' */
			obs->width=100;	/* en pixel */
			obs->height = 20;
		}
/* dans le cas ou le tag DATA est present, ne rien faire*/
		obs->load_data_method = MPP_URI_TO_AS_IS; 
		return 1;
	}

void MPP_New(HtmlObjectStruct *)
La fonction est appelee quand mMosaic affiche la page html. L'eventuelle fenetre est creee. Le plugin peut l'utiliser. C'est cette fonction qui active (affiche) l'objet.

	void MPP_New(HtmlObjectStruct *obs)
	{
		Widget mosaic_rowcol;
		Arg args[10];
		Widget label_frame;
		int i;

		/* la widget mMosaic est de type RowColumn */
		mosaic_rowcol=(Widget)(obs->frame); /* XmRowColumn */

		/* On cree une widget label pour y mettre hello world */
		i=0;
		XtSetArg(args[i], XmNwidth, obs->width); i++;
        	XtSetArg(args[i], XmNheight, obs->height); i++;
        	XtSetArg(args[i], XmNborderWidth, 0); i++;
        	XtSetArg(args[i], XmNrecomputeSize, 0); i++;
        	XtSetArg(args[i], XmNalignment, XmALIGNMENT_CENTER); i++;
        	label_frame=XmCreateLabel(mosaic_rowcol,"Hello World", args, i);
		
		/* mMosaic laisse la fenetre non-mapper.
		 * c'est au plugin de le faire
		 */
		XtSetMappedWhenManaged(label_frame,True);
		XtSetMappedWhenManaged(mosaic_rowcol,True);
		XtManageChild(mosaic_rowcol);
		XtRealizeWidget(mosaic_rowcol);	/* au cas ou... */

		/* memoriser les donnees du plugin pour cet objet */
		obs->plugin_data=(void*)label_frame;
	}

void MPP_Destroy(HtmlObjectStruct *)
mMosaic appelle cette fonction quand il change de page. La page courante n'est plus affichee. Il est necessaire de detruire les donnees creees par les fonctions precedentes.

	void MPP_Destroy(HtmlObjectStruct *p)
	{
		Widget label_frame;

		label_frame=(Widget) p->plugin_data;
		XtDestroyWidget(label_frame);
	}

dans le cas present la fonction peut etre vide. mMosaic detruitra sa fenetre et par consequent toutes les filles.

Les structures de donnees

La structure ObjectParamStruct est envoyee a chaque appel de fonction du plugin. Il y a une structure par instance d'OBJECT. La structure MosaicPlugjectClassRec decrit une classe d'objet. Il 'y a qu'UNE SEULE COPIE pour toutes les instances de la meme 'classid'.

typedef struct _MosaicPlugjectClassRec
{
        int release;            /* release of mmosaic plugin */
        int i_cid;              /* internal id , internal use*/
        char * class_id;        /* name of plugin */
        char * bin_path;        /* abs path to binary */
        char * codebase;        /* url to codebase */
        void * dl_handle;       /* return by dlsym, internal use*/
        MPPInitializeProc MPP_Initialize; /* pointer to Initialize func */
        MPPNewProc MPP_New;       /* pointer to MPP_New */
        MPPDestroyProc MPP_Destroy; /* pointer to MPP_Destroy */
 
        void *plugin_ext;       /* if needed by plugin */
        void *ext;              /* futur use */
} MosaicPlugjectClassRec, * MosaicPlugjectClass;

release permet de tester si la version dans laquelle a ete ecrit votre plugin est la meme que celle du navigateur.
plugin_ext Le plugin peut y mettre des informations lors de son premier chargement. Elle seront valables pour toutes les instances de plugin quelques soit la fenetre dans laquelle s'active l'une de ces instances. Un plugin se charge une et une seule fois. Il ne se decharge jamais.

typedef struct _HtmlObjectStruct {     
        int x;                         /* read only */
        int y;                         /* read only */
        int width;                     /* read/write */
        int height;                    /* read/write */
        int border_width;              /* read only */
        int valignment;                /* read only */
                                       
        char * class_id;        /* name of ... */
        char * bin_path;        /* classidPtr donne le bin_path */
        char *content_type;            
        char *codebase;                
        char *data_url;                
                                       
        MPPLoadDataMethod load_data_method; /*read/write */
        char * fname_for_data;  /* in case of MPP_URI_TO_FILE */
                                       
        int param_count;                /* number of params */
        ObjectParamPtr *param_t;        /* table of params */
        int cw_only;                    /* Boolean */
        void * frame;                   /* XtWidget frame, xmRowColumn */
        MosaicPlugjectClass mp_class;   /* point to an uniq class rec */
        int i_oid;      		/* internal id */  
        struct _HtmlObjectStruct *mp_rec;  
        void *plugin_data;             
} HtmlObjectStruct;

x, y C'est la position de la fenetre Rowcol calculee par mMosaic dans sa propre fenetre html.
width, height C'est la taille indiquee par les tag WIDTH et HEIGHT du marqueur OBJECT. Elles peuvent etre initialisee par le plugin dans la fonction Initialize. Si cette valeur est nulle, alors mMosaic considere le plugin comme un viewer externe, mMosaic ne creera pas de fenetre pour le plugin. Comme par exemple pour un plugin audio.
data_url C'est la valeur du tag DATA du marqueur OBJECT. Elle sera convertie suivant la valeur de load_data_method.
load_data_method
```
typedef enum {
        MPP_URI_TO_FILE=1,
        MPP_URI_TO_FD,
        MPP_URI_TO_AURI,
        MPP_URI_TO_AS_IS
} MPPLoadDataMethod ;
```
- MPP_URI_TO_FILE Charge l'url dans un fichier. fname_for_data est le nom du fichier contenant les donnees.
- MPP_URI_TO_FD unused
- MPP_URI_TO_AURI converti l'url en une url absolue a partir de la page de reference.
- MPP_URI_TO_AS_IS ne fait rien.
param_count Nombre de PARAM pour le marqueur OBJECT.
param_t tableau de param de dimension param_count.
- ```
typedef struct _ObjectParamStruct {
        char *name;
        char *value;
        char *valuetype;
} ObjectParamStruct, *ObjectParamPtr;
```
- name valeur du tag NAME du marqueur PARAM
- value valeur du tag VALUE du marqueur PARAM
- valuetype valeur du tag VALUETYPE du marqueur PARAM
frame mMosaic cree une Widget quand cela est necessaire. Si width et height sont non-nuls alors la fenetre est creee.
plugin_data Un pointeur sur une structure de donnees lie a l'instance de cet objet. Le plugin memorise ses donnees ici.

exemples

Dans le repertoire plugins/examples, vous trouverez d'autre exemples de plugin.