QPluginLoader

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

#include <QPluginLoader>

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 !