QLocalServer

La classe QLocalServer fournit un serveur local basé sur les sockets. Plus d'informations...

 #include <QLocalServer>

Héritage

Hérite de QObject.

Cette classe a été introduite dans Qt 4.4.

Description détaillée

La classe QLocalServer fournit un serveur local basé sur les sockets.

Cette classe permet d'accepter les connexions locales sur un socket.

Appelez la fonction listen() pour que le serveur se mette à l'écoute de nouvelles connexions sur une clé spécifiée. Le signal newConnection() est alors émis chaque fois qu'un client se connecte au serveur.

Appelez la fonction nextPendingConnection() pour accepter une connexion en attente sous la forme d'un QLocalSocket connecté. La fonction renvoie un pointeur sur un QLocalSocket qui peut être utilisé pour communiquer avec le client.

Si une erreur se produit, la fonction serverError() renvoie le type de l'erreur et la fonction errorString() peut être appelée pour récupérer une description compréhensible de ce qu'il s'est passé.

Lors de l'écoute de nouvelles connexions, le nom sur lequel écoute le serveur est disponible grâce à la fonction serverName().

L'appel à la fonction close() interrompt l'écoute de nouvelles connexions du QLocalServer.

Bien que la classe QLocalServer soit conçue pour être utilisée avec une boucle d'événements, il est possible de l'utiliser sans. Dans ce cas, vous devez utiliser la fonction waitForNewConnection(), qui bloque l'exécution tant qu'une connexion n'est pas disponible ou qu'un délai n'est pas dépassé.

Voir aussi QLocalSocket et QTcpServer.

Fonctions membres

QLocalServer::QLocalServer ( QObject * parent = 0 )

Créer un nouveau serveur local avec le parent donné.

Voir aussi listen().

QLocalServer::~QLocalServer ()

Détruit l'objet QLocalServer. Si le serveur est à l'écoute de nouvelles connexions, il est automatiquement fermé.

Les QLocalSocket clients connectés doivent être déconnectés ou être associés à un autre parent avant que le serveur ne soit supprimé.

Voir aussi close().

void QLocalServer::close ()

Interrompt l'écoute de nouvelles connexions. Les connexions existantes ne sont pas affectées mais toute nouvelle connexion sera refusée.

Voir aussi isListening() et listen().

QString QLocalServer::errorString () const

Retourne un message compréhensible décrivant l'erreur rapportée par la fonction serverError(). Si aucun message ne correspond à l'erreur, une chaîne vide est retournée.

Voir aussi serverError().

QString QLocalServer::fullServerName () const

Retourne le chemin complet sur lequel le serveur écoute.

Note. Cette fonction est spécifique à la plate-forme.

Voir aussi listen() et serverName().

bool QLocalServer::hasPendingConnections () const [virtual]

Retourne true si le serveur a des connexions en attente ; sinon renvoie false.

Voir aussi nextPendingConnection() et setMaxPendingConnections().

void QLocalServer::incomingConnection ( quintptr socketDescriptor ) [virtual protected]

Cette fonction virtuelle est appelée par QLocalServer lorsqu'une nouvelle connexion est disponible. socketDescriptor est le descripteur de socket natif pour la connexion acceptée.

L'implémentation de base crée un QLocalSocket, définit le descripteur de socket et sauvegarde ensuite le QLocalSocket dans une liste interne des connexions en attente. Pour finir, le signal newConnection() est émis.

Reimplémentez cette fonction pour altérer le comportement du serveur lorsqu'une nouvelle connexion est disponible.

Voir aussi newConnection(), nextPendingConnection() et QLocalSocket::setSocketDescriptor().

bool QLocalServer::isListening () const

Retourne true si le serveur est à l'écoute de nouvelles connexions, sinon false.

Voir aussi listen() et close().

bool QLocalServer::listen ( const QString & name )

Indique au serveur d'écouter les nouvelles connexions sur name. Si le serveur est actuellement en écoute la fonction retourne false. Renvoie true en cas de succès, sinon false.

Le nom name peut être un nom seul et QLocalServer déterminera le chemin spécifique à la plate-forme. La fonction serverName() retournera le nom qui a été passé à la fonction listen().

Habituellement, vous allez passer un nom sous la forme « foo » mais, sur Unix, vous pouvez aussi donner un chemin comme  »/tmp/foo » ; sur Windows, cela pourrait être un pipe tel que « \\.\pipe\foo »

Note. Sur Unix, si le serveur subit un crash avant d'être fermé, la fonction listen() échouera avec une erreur AddressInUseError. Pour créer un nouveau serveur le fichier devra être supprimé. Sur Windows, deux serveurs locaux peuvent écouter sur le même pipe en même temps mais les connexions n'iront que vers un seul serveur.

Voir aussi serverName(), isListening() et close().

int QLocalServer::maxPendingConnections () const

Retourne le nombre maximum de connexions pouvant être en attente d'acceptation. La valeur par défaut est 30.

Voir aussi setMaxPendingConnections() et hasPendingConnections().

void QLocalServer::newConnection () [signal]

Le signal est émis chaque fois qu'une nouvelle connexion est disponible.

Voir aussi hasPendingConnections() et nextPendingConnection().

QLocalSocket * QLocalServer::nextPendingConnection () [virtual]

Retourne la prochaine connexion en attente sous forme d'un objet QLocalSocket connecté.

Le socket est créé comme enfant du serveur, ce qui signifie qu'il sera automatiquement supprimé lorsque l'objet QLocalServer sera détruit. Il reste possible de supprimer l'objet explicitement quand vous avez fini de l'utiliser, afin d'économiser la mémoire.

La fonction renvoie 0 si elle est appelée lorsqu'il n'y a aucune connexion en attente.

Voir aussi hasPendingConnections(), newConnection() et incomingConnection().

bool QLocalServer::removeServer ( const QString & name ) [static]

Retire toute instance de serveur qui pourrait provoquer un échec lors de l'appel à la fonction listen() et retourne true en cas de réussite ; sinon retourne false. Cette fonction sert aux récupérations après un crash, lorsque l'instance de serveur précédente n'a pas été nettoyée.

Sur Windows, cette fonction ne fait rien ; Sur Unix, la fonction supprime le fichier socket donné name.

Avertissement : Attention à ne pas enlever les sockets d'instances en cours d'exécution.

Cette fonction a été introduite dans Qt 4.5.

QAbstractSocket::SocketError QLocalServer::serverError () const

Retourne le type de la dernière erreur ou NoError.

Voir aussi errorString().

QString QLocalServer::serverName () const

Retourne le nom du serveur si le serveur est à l'écoute de nouvelles connexions ; sinon retourne QString()

Voir aussi listen() et fullServerName().

void QLocalServer::setMaxPendingConnections ( int numConnections )

Fixe le nombre maximum de connexions en attente d'être acceptés à numConnections. Le QLocalServer n'acceptera pas plus de numConnections connexions entrantes avant que la fonction nextPendingConnection() soit appelée.

Note. Même si QLocalServer arrête d'accepter de nouvelles connexions après avoir atteint le maximum de connexions en attente, le système d'exploitation peut continuer à les garder en file d'attente, ce qui fera que les clients signaleront qu'ils sont connectés.

Voir aussi maxPendingConnections() et hasPendingConnections().

bool QLocalServer::waitForNewConnection ( int msec = 0, bool * timedOut = 0 )

Attend au plus msec millisecondes ou jusqu'à la disponibilité d'une nouvelle connexion. Retourne true si une connexion est disponible ; sinon retourne false. Si la fonction dépasse le délai et que timedOut est différent de zéro, *timedOut sera défini à true.

Cette fonction est bloquante. Son utilisation est déconseillée dans une application à interface utilisateur monothread, car l'application arrêtera de répondre jusqu'au retour de la fonction. La fonction waitForNewConnection() est principalement utile lorsqu'il n'y a aucune boucle d'événements disponible.

L'alternative non bloquante est de se connecter au signal newConnection().

Si msect vaut -1, la fonction attendra indéfiniment.

Voir aussi hasPendingConnections() et nextPendingConnection().

Remerciements

Merci à Alexandre Laurent pour la traduction, ainsi qu'à Ilya Diallo, Ali-K?mal Aydin et Claude Leloup pour la relecture !