QPluginLoader

La classe QPluginLoader charge un plu-gin � l'ex�cution. Plus d'informations...

#include <QPluginLoader>

Voir la position dans l'arbre des classes.

H�ritage

H�rite de QObject.

Description d�taill�e

La classe QPluginLoader charge un plug-in � l'ex�cution.

Cette classe fournit un acc�s � un plug-in Qt. Un plug-in Qt est stock� dans une biblioth�que partag�e (une DLL, un SO, un DYLIB) et offre ces quelques b�n�fices aux biblioth�ques charg�es par l'interm�diaire de QLibrary :

• QPluginLoader v�rifie qu'un plug-in est li� � la m�me version de Qt que l'application ;
• QPluginLoader fournit un acc�s direct � l'objet racine (instance()), au lieu de vous forcer � d�finir une fonction C manuellement.

Une instance d'un objet QPluginLoader ne s'occupe que d'un fichier de biblioth�que partag�e, que l'on appelle un plug-in. Elle permet d'acc�der aux fonctionnalit�s du plug-in sans se soucier de la plateforme. Pour sp�cifier quel plug-in charger, passer soit un nom de fichier dans le constructeur, soit le modifier avec setFileName().

Les fonctions les plus importantes sont load() pour le chargement dynamique d'un fichier de plug-ins, isLoaded() pour v�rifier que le chargement s'est bien effectu� et instance() pour acc�der au composant de base du plug-in. Cette derni�re fonction essaye implicitement de charger le plug-in si ce n'est pas encore fait. Plusieurs instances de la classe peuvent �tre utilis�es pour acc�der � un m�me plug-in physique.

D�s qu'il est charg�, le plug-in reste en m�moire jusqu'� ce que toutes les instances de QPluginLoader soient supprim�es, ou bien jusqu'� la fin de l'application. Vous pouvez essayer de d�charger un plug-in avec unload(), mais si d'autres instances de QPluginLoader utilisent encore la m�me biblioth�que, l'appel �chouera et le d�chargement ne sera effectif que lorsque toutes les instances auront appel� cette fonction. Juste avant qu'il ne soit d�charg�, le composant principal sera �galement supprim�.

Pour acc�l�rer le chargement et la validation des plug-ins, certaines informations collect�es au chargement sont mises en cache dans la m�moire persistante (gr�ce � QSettings). Par exemple, le r�sultat d'une op�ration de chargement (succ�s ou �chec) est stock� dans ce cache : les chargements subs�quents �choueront sur un plug-in invalide. Cependant, si la date de modification d'un plug-in a chang�, l'entr�e du cache est invalid�e et mise � jour avec l'op�ration de chargement.

Ceci signifie aussi que la date doit �tre mise � jour � chaque fois qu'un plug-in est mis � jour, ainsi que les ressources d�pendantes (comme une autre biblioth�que partag�e), vu que ces ressources peuvent influencer le chargement.

Regardez Comment cr�er des plugins Qt pour plus d'informations sur la mani�re d'�tendre votre application avec des plug-ins.

Notez que QPluginLoader ne peut pas �tre utilis�e si vous liez votre application statiquement � Qt. Dans ce cas, vous devrez aussi lier vos plug-ins statiquement. Vous pouvez utiliser QLibrary si vous devez charger des biblioth�ques partag�es dans une application li�e statiquement.

Note : sur Symbian, les fichiers stub du plug-in doivent �tre utilis�s lorsqu'un chemin vers le plug-in est n�cessaire. Dans le cas du chargement de plug-ins, les stubs peuvent �tre consid�r�s comme ayant le m�me nom que le binaire de l'actuel plug-in. En pratique, ils ont l'extension  ».qtplugin » � la place de  ».dll », mais ces diff�rences sont g�r�es de fa�on transparente par QPluginLoader et QLibrary pour �viter d'avoir � g�rer des besoins sp�cifiques au plug-in de Symbian dans la plupart des applications Qt. Les stubs des plug-ins sont n�cessaires �tant donn� que la plateforme de s�curit� de Symbian emp�che tout acc�s au r�pertoire o� le binaire du plug-in actuel est localis�.

Voir aussi QLibrary et l'exemple Plug & Paint.

Propri�t�s

fileName : QString

Cette propri�t� stocke le nom de fichier du plug-in.

Pour �tre chargeable, l'extension doit �tre valide pour la plateforme (.so sur UNIX, .dylib sur Mac OS X et .dll sur Windows). Elle peut �tre v�rifi�e avec QLibrary::isLibrary().

Si le fichier n'existe pas, il ne sera pas stock� et cette propri�t� contiendra donc une cha�ne de caract�res vide.

Par d�faut, cette propri�t� contient une cha�ne de caract�res vide.

Note : sur Symbian, fileName doit pointer sur un fichier stub du plug-in.

Fonctions d'acc�s

QString fileName () const
void setFileName ( const QString & nomDeFichier )

Voir aussi load().

loadHints : QLibrary::LoadHints

Cette propri�t� donne quelques indices sur la mani�re dont load() devrait se comporter.

Vous pouvez donner des indications sur la mani�re dont les symboles du plug-in sont r�solus. Par d�faut, aucune indication n'est d�finie.

Voir la documentation de QLibrary::loadHints pour une description compl�te sur la fa�on dont cette propri�t� fonctionne.

Cette propri�t� a �t� introduite dans Qt 4.4.

Fonctions d'acc�s

QLibrary::LoadHints loadHints () const
void setLoadHints ( QLibrary::LoadHints indices )

Voir aussi QLibrary::loadHints.

Fonctions membres

QPluginLoader::QPluginLoader ( QObject * parent = 0 )

Construit un chargeur de plug-in avec le parent fourni.

QPluginLoader::QPluginLoader ( const QString & fileName, QObject * parent = 0 )

Construit un chargeur de plug-in avec le parent fourni qui chargera le fichier filename sp�cifi�.

Pour �tre chargeable, l'extension doit �tre valide pour la plateforme (.so sur UNIX, .dylib sur Mac OS X et .dll sur Windows). Elle peut �tre v�rifi�e avec QLibrary::isLibrary().

Note : sur Symbian, fileName doit pointer sur un fichier stub du plug-in.

Voir aussi setFileName().

QPluginLoader::~QPluginLoader ()

D�truit l'objet QPluginLoader.

� moins que unload() n'ait �t� appel�e explicitement, le plug-in reste en m�moire jusqu'� la fin de l'application.

Voir aussi isLoaded() et unload().

QString QPluginLoader::errorString () const

Retourne une cha�ne de caract�res avec la description de la derni�re erreur.

Cette fonction a �t� introduite dans Qt 4.2.

QObject * QPluginLoader::instance ()

Retourne l'objet racine du plug-in, charg� si n�cessaire. La fonction retourne 0 si le plug-in ne peut �tre charg�, ou si l'objet racine ne peut �tre instanci�.

Si l'objet racine a �t� supprim�, cette fonction le recr�e.

Le composant racine, retourn� par cette fonction, n'est pas supprim� quand le QPluginLoader est d�truit. Si vous voulez vous en assurer, vous devriez appeler unload() d�s que vous n'en avez plus besoin. Quand la biblioth�que est finalement d�charg�e, le composant principal sera automatiquement d�truit.

L'objet retourn� est un QObject. Utilisez qobject_cast() pour acc�der aux interfaces qui vous int�ressent.

Voir aussi load().

bool QPluginLoader::isLoaded () const

Retourne true si le plug-in est charg�, false sinon.

Voir aussi load().

bool QPluginLoader::load ()

Charge le plug-in et retourne true s'il a �t� charg� correctement ; sinon retourne false. Vu que instance() appelle toujours cette fonction avant la r�solution de symboles, il n'est pas n�cessaire de l'appeler explicitement. Dans certaines situations, vous pourriez vouloir charger le plug-in en avance, auquel cas vous pourriez utiliser cette fonction.

Voir aussi unload().

QObjectList QPluginLoader::staticInstances () [static]

Retourne une liste d'instances statiques du plug-in (objet racine) d�tenues par le chargeur.

bool QPluginLoader::unload ()

D�charge le plug-in et retourne true si le plug-in peut �tre d�charg�, sinon false.

Cela arrive automatiquement � la fermeture de l'application, vous ne devriez donc pas appeler cette fonction.

Si d'autres instances de QPluginLoader utilisent toujours le m�me plug-in, l'appel �chouera, et le d�chargement n'aura lieu que lorsque toutes les instances auront appel� unload().

N'essayez pas de supprimer l'objet racine. Reposez-vous sur le fait qu'il sera supprim� automatiquement d�s que cela sera n�cessaire.

Voir aussi instance() et load().

En relation mais non membres de la classe

void qRegisterStaticPluginInstanceFunction ( QtPluginInstanceFunction function )

Enregistre la fonction function donn�e avec le chargeur de plug-in.

Cette fonction a �t� introduite dans Qt 4.4.

Remerciements

Merci � Thibaut Cuvelier pour la traduction et � Jonathan Courtois, Thibaut Cuvelier ainsi qu'� Jacques Thery pour leur relecture !