QUrl Class

Documentation des fonctions membres

QUrl::QUrl()

Construit un objet QUrl vide.

QUrl::QUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)

Construit une URL en analysant url. Notez que ce constructeur attend une URL ou une référence URL correcte et n'essaiera pas de deviner l'intention. Par exemple, la déclaration suivante :

QUrl url("example.com");

construira une URL valide, mais il se peut qu'elle ne corresponde pas à ce que l'on attend, car la partie scheme() de l'entrée est manquante. Pour une chaîne comme celle qui précède, les applications peuvent vouloir utiliser fromUserInput(). Pour ce constructeur ou setUrl(), ce qui suit est probablement ce qui était prévu :

QUrl url("https://example.com");

QUrl codera automatiquement en pourcentage tous les caractères qui ne sont pas autorisés dans une URL et décodera les séquences codées en pourcentage qui représentent un caractère non réservé (lettres, chiffres, traits d'union, traits de soulignement, points et tildes). Tous les autres caractères sont laissés dans leur forme originale.

Analyse le fichier url en utilisant le mode d'analyseur parsingMode. Dans TolerantMode (par défaut), QUrl corrigera certaines erreurs, notamment la présence d'un caractère pour cent ('%') non suivi de deux chiffres hexadécimaux, et acceptera n'importe quel caractère dans n'importe quelle position. Dans StrictMode, les erreurs d'encodage ne seront pas tolérées et QUrl vérifiera également que certains caractères interdits ne sont pas présents en clair. Si une erreur est détectée dans StrictMode, isValid() renverra faux. Le mode d'analyse DecodedMode n'est pas autorisé dans ce contexte.

Exemple :

QUrl url("http://www.example.com/List of holidays.xml");
// url.toEncoded() == "http://www.example.com/List%20of%20holidays.xml"

Pour construire un URL à partir d'une chaîne encodée, vous pouvez également utiliser fromEncoded() :

QUrl url = QUrl::fromEncoded("http://qt-project.org/List%20of%20holidays.xml");

Les deux fonctions sont équivalentes et, dans Qt 5, les deux fonctions acceptent les données encodées. Habituellement, le choix du constructeur QUrl ou de setUrl() par rapport à fromEncoded() dépend des données sources : le constructeur et setUrl() prennent un QString, tandis que fromEncoded prend un QByteArray.

Voir également setUrl(), fromEncoded() et TolerantMode.

[noexcept] QUrl::QUrl(const QUrl &other)

Construit une copie de other.

[noexcept] QUrl::QUrl(QUrl &&other)

Move-construit une instance QUrl, en la faisant pointer sur le même objet que other.

[noexcept] QUrl::~QUrl()

Destructeur ; appelé immédiatement avant la suppression de l'objet.

QUrl QUrl::adjusted(QUrl::FormattingOptions options) const

Renvoie une version modifiée de l'URL. La sortie peut être personnalisée en passant des drapeaux avec options.

Les options d'encodage de QUrl::ComponentFormattingOption n'ont pas beaucoup de sens pour cette méthode, pas plus que QUrl::PreferLocalFile.

Cette méthode est toujours équivalente à QUrl(url.toString(options)).

Voir aussi FormattingOptions, toEncoded(), et toString().

QString QUrl::authority(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

Renvoie l'autorité de l'URL si elle est définie, sinon une chaîne vide est renvoyée.

Cette fonction renvoie une valeur non ambiguë, qui peut contenir des caractères encore codés en pourcentage, ainsi que certaines séquences de contrôle non représentables sous forme décodée dans QString.

L'argument options contrôle le formatage du composant d'information de l'utilisateur. La valeur de QUrl::FullyDecoded n'est pas autorisée dans cette fonction. Si vous devez obtenir des données entièrement décodées, appelez userName(), password(), host() et port() individuellement.

Voir aussi setAuthority(), userInfo(), userName(), password(), host() et port().

void QUrl::clear()

Réinitialise le contenu de QUrl. Après l'appel de cette fonction, QUrl est égal à celui qui a été construit avec le constructeur vide par défaut.

Voir aussi isEmpty().

QString QUrl::errorString() const

Renvoie un message d'erreur si la dernière opération qui a modifié cet objet QUrl a rencontré une erreur d'analyse. Si aucune erreur n'a été détectée, cette fonction renvoie une chaîne vide et isValid() renvoie true.

Le message d'erreur renvoyé par cette fonction est de nature technique et peut ne pas être compris par les utilisateurs finaux. Il est surtout utile aux développeurs qui essaient de comprendre pourquoi QUrl n'accepte pas certaines entrées.

Voir aussi QUrl::ParsingMode.

QString QUrl::fileName(QUrl::ComponentFormattingOptions options = FullyDecoded) const

Renvoie le nom du fichier, à l'exclusion du chemin d'accès au répertoire.

Notez que, si cet objet QUrl reçoit un chemin se terminant par une barre oblique, le nom du fichier est considéré comme vide.

Si le chemin d'accès ne contient pas de barre oblique, le nom du fichier est renvoyé dans son intégralité.

Exemple :

QUrl url("http://qt-project.org/support/file.html");
// url.adjusted(RemoveFilename) == "http://qt-project.org/support/"
// url.fileName() == "file.html"

L'argument options détermine le format du nom du fichier. Toutes les valeurs produisent un résultat non ambigu. Avec QUrl::FullyDecoded, toutes les séquences codées en pourcentage sont décodées ; sinon, la valeur renvoyée peut contenir des séquences codées en pourcentage pour certaines séquences de contrôle qui ne peuvent pas être représentées sous forme décodée dans QString.

Voir aussi path().

QString QUrl::fragment(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

Renvoie le fragment de l'URL. Pour déterminer si l'URL analysée contient un fragment, utilisez hasFragment().

L'argument options détermine le formatage du fragment. Toutes les valeurs produisent un résultat non ambigu. Avec QUrl::FullyDecoded, toutes les séquences codées en pourcentage sont décodées ; sinon, la valeur renvoyée peut contenir des séquences codées en pourcentage pour certaines séquences de contrôle non représentables sous forme décodée dans QString.

Notez que QUrl::FullyDecoded peut entraîner une perte de données si ces séquences non représentables sont présentes. Il est recommandé d'utiliser cette valeur lorsque le résultat sera utilisé dans un contexte autre que l'URL.

Voir également setFragment() et hasFragment().

[static, since 6.3] QString QUrl::fromAce(const QByteArray &domain, QUrl::AceProcessingOptions options = {})

Renvoie la forme Unicode du nom de domaine donné domain, qui est encodé dans le codage compatible ASCII (ACE). La sortie peut être personnalisée en passant des drapeaux avec options. Le résultat de cette fonction est considéré comme équivalent à domain.

Si la valeur contenue dans domain ne peut pas être encodée, elle sera convertie en QString et renvoyée.

Le codage compatible ASCII (ACE) est défini par les RFC 3490, RFC 3491 et RFC 3492 et mis à jour par la norme technique Unicode #46. Il fait partie de la spécification IDNA (Internationalizing Domain Names in Applications), qui permet d'écrire des noms de domaine (comme "example.com") en utilisant des caractères non ASCII américains.

Cette fonction a été introduite dans Qt 6.3.

[static] QUrl QUrl::fromCFURL(CFURLRef url)

Construit un QUrl contenant une copie du CFURL url.

[static] QUrl QUrl::fromEncoded(QByteArrayView input, QUrl::ParsingMode mode = TolerantMode)

Analyse input et renvoie l'adresse QUrl correspondante. input est supposé être codé et ne contenir que des caractères ASCII.

Analyse l'URL à l'aide de mode. Voir setUrl() pour plus d'informations sur ce paramètre. QUrl::DecodedMode n'est pas autorisé dans ce contexte.

Voir aussi toEncoded() et setUrl().

[static] QUrl QUrl::fromLocalFile(const QString &localFile)

QUrl Renvoie une représentation de localFile, interprétée comme un fichier local. Cette fonction accepte les chemins séparés par des barres obliques ainsi que le séparateur natif de cette plate-forme.

Cette fonction accepte également les chemins avec une barre oblique double (ou une barre oblique inverse) pour indiquer un fichier distant, comme dans "//servername/path/to/file.txt". Notez que seules certaines plateformes peuvent ouvrir ce fichier en utilisant QFile::open().

Un localFile vide conduit à une URL vide (depuis Qt 5.4).

qDebug()<< QUrl::fromLocalFile("fichier.txt") ; // QUrl("fichier:fichier.txt")qDebug() << QUrl::fromLocalFile("/home/user/file.txt"); // QUrl("file:///home/user/file.txt")
qDebug() << QUrl::fromLocalFile("file:file.txt");       // doesn't make sense; expects path, not url with scheme

Dans la première ligne de l'extrait ci-dessus, l'URL d'un fichier est construite à partir d'un chemin relatif local. Une URL de fichier avec un chemin relatif n'a de sens que s'il existe une URL de base pour la résoudre. Par exemple, l'URL d'un fichier est construite à partir d'un chemin local et relatif :

QUrl url = QUrl::fromLocalFile("fichier.txt") ;QUrl baseUrl = QUrl("file:/home/user/") ;// faux : imprime QUrl("file:file.txt"), car url a déjà un schémaqDebug() << baseUrl.resolved(url);

Pour résoudre ce type d'URL, il est nécessaire de supprimer le schéma au préalable :

// correct : prints QUrl("file:///home/user/file.txt")url.setScheme(QString()) ;qDebug() << baseUrl.resolved(url);

C'est pourquoi il est préférable d'utiliser une URL relative (c'est-à-dire sans schéma) pour les chemins d'accès relatifs aux fichiers :

QUrl url = QUrl("file.txt") ;QUrl baseUrl = QUrl("file:/home/user/") ;// imprime QUrl("file:///home/user/file.txt")qDebug() << baseUrl.resolved(url);

Voir aussi toLocalFile(), isLocalFile() et QDir::toNativeSeparators().

[static] QUrl QUrl::fromNSURL(const NSURL *url)

Construit un QUrl contenant une copie du NSURL url.

[static] QString QUrl::fromPercentEncoding(const QByteArray &input)

Renvoie une copie décodée de input. input est d'abord décodé à partir de l'encodage en pourcentage, puis converti d'UTF-8 en unicode.

[static] QList<QUrl> QUrl::fromStringList(const QStringList &urls, QUrl::ParsingMode mode = TolerantMode)

Convertit une liste de chaînes représentant urls en une liste d'urls, en utilisant QUrl(str, mode). Notez que cela signifie que toutes les chaînes doivent être des urls, et non des chemins locaux par exemple.

[static] QUrl QUrl::fromUserInput(const QString &userInput, const QString &workingDirectory = QString(), QUrl::UserInputResolutionOptions options = DefaultResolution)

Renvoie une URL valide à partir d'une chaîne userInput fournie par l'utilisateur, s'il est possible d'en déduire une. Si ce n'est pas possible, un QUrl() invalide est renvoyé.

Cela permet à l'utilisateur de saisir une URL ou un chemin d'accès à un fichier local sous la forme d'une chaîne de caractères simple. Cette chaîne peut être saisie manuellement dans une barre d'adresse, obtenue à partir du presse-papiers ou transmise via des arguments de ligne de commande.

Lorsque la chaîne ne correspond pas à une URL valide, une meilleure estimation est effectuée, sur la base de diverses hypothèses.

Si la chaîne correspond à un chemin de fichier valide sur le système, une URL file:// est construite à l'aide de QUrl::fromLocalFile().

Si ce n'est pas le cas, on tente de transformer la chaîne en une URL http:// ou ftp://. Cette dernière est utilisée lorsque la chaîne commence par "ftp". Le résultat est ensuite soumis à l'analyseur tolérant de QUrl et, en cas de succès, une adresse QUrl valide est renvoyée, ou bien une adresse QUrl().

Exemples :

• qt-project.org devient http://qt-project.org
• ftp.qt-project.org devient ftp://ftp.qt-project.org
• hostname devient http://hostname
• /home/user/test.html devient file:///home/user/test.html

Afin de pouvoir gérer les chemins relatifs, cette méthode prend un chemin optionnel workingDirectory. Cela est particulièrement utile pour traiter les arguments de ligne de commande. Si workingDirectory est vide, aucune gestion des chemins relatifs ne sera effectuée.

Par défaut, une chaîne d'entrée qui ressemble à un chemin relatif ne sera traitée comme telle que si le fichier existe réellement dans le répertoire de travail donné. Si l'application peut gérer des fichiers qui n'existent pas encore, elle doit passer le drapeau AssumeLocalFile dans options.

bool QUrl::hasFragment() const

Renvoie true si cette URL contient un fragment (c'est-à-dire si # y a été vu).

Voir aussi fragment() et setFragment().

bool QUrl::hasQuery() const

Renvoie true si cette URL contient une requête (c'est-à-dire si ? a été vu sur cette URL).

Voir aussi setQuery(), query(), et hasFragment().

QString QUrl::host(QUrl::ComponentFormattingOptions options = FullyDecoded) const

Renvoie l'hôte de l'URL s'il est défini, sinon une chaîne vide est renvoyée.

L'argument options contrôle le formatage du nom d'hôte. L'option QUrl::EncodeUnicode permet à cette fonction de renvoyer le nom d'hôte sous la forme ACE (ASCII-Compatible Encoding), qui convient à une utilisation dans les canaux qui ne sont pas propres sur 8 bits ou qui nécessitent le nom d'hôte hérité (comme les requêtes DNS ou dans les en-têtes de requêtes HTTP). Si cet indicateur n'est pas présent, cette fonction renvoie le nom de domaine international (IDN) sous forme Unicode, conformément à la liste des domaines de premier niveau autorisés (voir idnWhitelist()).

Tous les autres indicateurs sont ignorés. Les noms d'hôtes ne peuvent pas contenir de caractères de contrôle ou de pourcentage, de sorte que la valeur renvoyée peut être considérée comme entièrement décodée.

Voir aussi setHost(), idnWhitelist(), setIdnWhitelist() et authority().

[static] QStringList QUrl::idnWhitelist()

Renvoie la liste blanche actuelle des domaines de premier niveau autorisés à contenir des caractères non ASCII dans leur composition.

Voir setIdnWhitelist() pour la raison d'être de cette liste.

Voir également setIdnWhitelist() et AceProcessingOption.

bool QUrl::isEmpty() const

Renvoie true si l'URL ne contient pas de données ; sinon, renvoie false.

Voir aussi clear().

bool QUrl::isLocalFile() const

Renvoie true si cette URL pointe vers un chemin d'accès à un fichier local. Une URL est un chemin de fichier local si le schéma est "file".

Notez que cette fonction considère les URL avec des noms d'hôtes comme des chemins d'accès à des fichiers locaux, même si le chemin d'accès éventuel ne peut pas être ouvert avec QFile::open().

Voir également fromLocalFile() et toLocalFile().

bool QUrl::isParentOf(const QUrl &childUrl) const

Renvoie true si cette URL est un parent de childUrl. childUrl est un enfant de cette URL si les deux URL partagent le même schéma et la même autorité, et si le chemin de cette URL est un parent du chemin de childUrl.

bool QUrl::isRelative() const

Renvoie true si l'URL est relative ; sinon, renvoie false. Une URL est une référence relative si son schéma n'est pas défini ; cette fonction équivaut donc à appeler scheme().isEmpty().

Les références relatives sont définies dans la RFC 3986, section 4.2.

Voir aussi Relative URLs vs Relative Paths.

bool QUrl::isValid() const

Renvoie true si l'URL n'est pas vide et est valide ; sinon, renvoie false.

L'URL est soumis à un test de conformité. Chaque partie de l'URL doit être conforme aux règles d'encodage de la norme URI pour que l'URL soit déclarée valide.

bool checkUrl(const QUrl &url) { if (!url.isValid()) {        qDebug("Invalid URL: %s", qUtf8Printable(url.toString()));
       return false; } return true; }

bool QUrl::matches(const QUrl &url, QUrl::FormattingOptions options) const

Renvoie true si cette URL et l'URL donnée url sont égales après avoir appliqué options aux deux URL ; sinon, renvoie false.

Cela équivaut à appeler adjusted(options) sur les deux URL et à comparer les URL résultantes, mais plus rapidement.

QString QUrl::password(QUrl::ComponentFormattingOptions options = FullyDecoded) const

Renvoie le mot de passe de l'URL s'il est défini, sinon une chaîne vide est renvoyée.

L'argument options détermine le format du nom d'utilisateur. Toutes les valeurs produisent un résultat non ambigu. Avec QUrl::FullyDecoded, toutes les séquences codées en pourcentage sont décodées ; sinon, la valeur renvoyée peut contenir des séquences codées en pourcentage pour certaines séquences de contrôle non représentables sous forme décodée dans QString.

Notez que QUrl::FullyDecoded peut entraîner une perte de données si ces séquences non représentables sont présentes. Il est recommandé d'utiliser cette valeur lorsque le résultat sera utilisé dans un contexte autre que celui de l'URL, tel que l'installation dans QAuthenticator ou la négociation d'une connexion.

Voir aussi setPassword().

QString QUrl::path(QUrl::ComponentFormattingOptions options = FullyDecoded) const

Renvoie le chemin d'accès à l'URL.

qDebug()<< QUrl("file:file.txt").path() ; // "file.txt"qDebug() << QUrl("/home/user/file.txt").path();             // "/home/user/file.txt"
qDebug() << QUrl("http://www.example.com/test/123").path(); // "/test/123"

L'argument options détermine la manière de formater le composant chemin. Toutes les valeurs produisent un résultat non ambigu. Avec QUrl::FullyDecoded, toutes les séquences codées en pourcentage sont décodées ; sinon, la valeur renvoyée peut contenir des séquences codées en pourcentage pour certaines séquences de contrôle non représentables sous forme décodée dans QString.

Notez que QUrl::FullyDecoded peut entraîner une perte de données si ces séquences non représentables sont présentes. Il est recommandé d'utiliser cette valeur lorsque le résultat sera utilisé dans un contexte autre que l'URL, comme l'envoi à un serveur FTP.

Un exemple de perte de données est lorsque vous avez des séquences encodées en pourcentage non Unicode et que vous utilisez FullyDecoded (la valeur par défaut) :

qDebug() << QUrl("/foo%FFbar").path();

Dans cet exemple, il y aura un certain niveau de perte de données parce que le %FF ne peut pas être converti.

Une perte de données peut également se produire lorsque le chemin d'accès contient des sous-délimiteurs (tels que +) :

qDebug() << QUrl("/foo+bar%2B").path(); // "/foo+bar+"

Autres exemples de décodage :

const QUrl url("/tmp/Mambo %235%3F.mp3") ;qDebug() << url.path(QUrl::FullyDecoded);  // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::PrettyDecoded); // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::FullyEncoded);  // "/tmp/Mambo%20%235%3F.mp3"

Voir aussi setPath().

int QUrl::port(int defaultPort = -1) const

Renvoie le port de l'URL ou defaultPort si le port n'est pas spécifié.

Exemple :

QTcpSocket sock;
sock.connectToHost(url.host(), url.port(80));

Voir aussi setPort().

QString QUrl::query(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

Renvoie la chaîne de requête de l'URL s'il y a une chaîne de requête, ou un résultat vide si ce n'est pas le cas. Pour déterminer si l'URL analysée contient une chaîne de requête, utilisez hasQuery().

L'argument options détermine le format du composant de requête. Toutes les valeurs produisent un résultat non ambigu. Avec QUrl::FullyDecoded, toutes les séquences codées en pourcentage sont décodées ; sinon, la valeur renvoyée peut contenir des séquences codées en pourcentage pour certaines séquences de contrôle non représentables sous forme décodée dans QString.

Il convient de noter que l'utilisation de QUrl::FullyDecoded dans les requêtes est déconseillée, car les requêtes contiennent souvent des données qui sont censées rester codées en pourcentage, y compris l'utilisation de la séquence "%2B" pour représenter un caractère plus ('+').

Voir aussi setQuery() et hasQuery().

QUrl QUrl::resolved(const QUrl &relative) const

Renvoie le résultat de la fusion de cette URL avec relative. Cette URL est utilisée comme base pour convertir relative en URL absolue.

Si relative n'est pas une URL relative, cette fonction renvoie directement relative. Sinon, les chemins des deux URL sont fusionnés et la nouvelle URL renvoyée a le schéma et l'autorité de l'URL de base, mais avec le chemin fusionné, comme dans l'exemple suivant :

QUrl baseUrl("http://qt.digia.com/Support/") ;QUrl relativeUrl("../Produit/Bibliothèque/") ;qDebug(qUtf8Printable(baseUrl.resolved(relativeUrl).toString()));
// imprime "http://qt.digia.com/Product/Library/"

L'appel à resolved() avec "..." renvoie une adresse QUrl dont le répertoire est supérieur d'un niveau à l'original. De même, l'appel à resolved() avec "../..." supprime deux niveaux du chemin. Si relative est "/", le chemin devient "/".

Voir aussi isRelative().

QString QUrl::scheme() const

Renvoie le schéma de l'URL. Si une chaîne vide est renvoyée, cela signifie que le schéma est indéfini et que l'URL est relative.

Le schéma ne peut contenir que des lettres ou des chiffres US-ASCII, ce qui signifie qu'il ne peut contenir aucun caractère qui nécessiterait un encodage. En outre, les schémas sont toujours renvoyés en minuscules.

Voir aussi setScheme() et isRelative().

void QUrl::setAuthority(const QString &authority, QUrl::ParsingMode mode = TolerantMode)

Définit l'autorité de l'URL à authority.

L'autorité d'une URL est la combinaison d'informations sur l'utilisateur, d'un nom d'hôte et d'un port. Tous ces éléments sont facultatifs ; une autorité vide est donc valide.

Les informations sur l'utilisateur et l'hôte sont séparées par un "@", et l'hôte et le port sont séparés par un " :". Si les informations sur l'utilisateur sont vides, le "@" doit être omis, bien qu'un " :" parasite soit autorisé si le port est vide.

L'exemple suivant montre une chaîne d'autorité valide :

Les données de authority sont interprétées conformément à mode: dans StrictMode, tout caractère "%" doit être suivi d'exactement deux caractères hexadécimaux et certains caractères (y compris l'espace) ne sont pas autorisés sous forme non décodée. Dans TolerantMode (par défaut), tous les caractères sont acceptés sous forme non décodée et l'analyseur tolérant corrigera les "%" errants non suivis de deux caractères hexadécimaux.

Cette fonction ne permet pas à mode d'être QUrl::DecodedMode. Pour définir des données entièrement décodées, appelez setUserName(), setPassword(), setHost() et setPort() individuellement.

Voir également authority(), setUserInfo(), setHost() et setPort().

void QUrl::setFragment(const QString &fragment, QUrl::ParsingMode mode = TolerantMode)

Définit le fragment de l'URL à fragment. Le fragment est la dernière partie de l'URL, représentée par un "#" suivi d'une chaîne de caractères. Il est généralement utilisé dans le protocole HTTP pour faire référence à un lien ou à un point précis d'une page :

Le fragment est parfois également appelé "référence" de l'URL.

Le passage d'un argument de QString() (un null QString) désactivera le fragment. Passer un argument de QString("") (un QString vide mais non nul) définira le fragment comme une chaîne vide (comme si l'URL d'origine avait un "#" solitaire).

Les données de fragment sont interprétées conformément à mode: dans StrictMode, tout caractère "%" doit être suivi d'exactement deux caractères hexadécimaux et certains caractères (y compris l'espace) ne sont pas autorisés sous forme non décodée. Dans TolerantMode, tous les caractères sont acceptés sous forme non décodée et l'analyseur tolérant corrigera les "%" errants non suivis de deux caractères hexadécimaux. Dans DecodedMode, "%" se suffit à lui-même et les caractères codés ne sont pas possibles.

QUrl::DecodedMode doit être utilisé pour définir le fragment à partir d'une source de données qui n'est pas une URL ou avec un fragment obtenu en appelant fragment() avec l'option de formatage QUrl::FullyDecoded.

Voir également fragment() et hasFragment().

void QUrl::setHost(const QString &host, QUrl::ParsingMode mode = DecodedMode)

Définit l'hôte de l'URL à host. L'hôte fait partie de l'autorité.

Les données de host sont interprétées conformément à mode: dans StrictMode, tout caractère '%' doit être suivi d'exactement deux caractères hexadécimaux et certains caractères (y compris l'espace) ne sont pas autorisés sous forme non décodée. Dans TolerantMode, tous les caractères sont acceptés sous forme non décodée et l'analyseur tolérant corrigera les "%" errants non suivis de deux caractères hexadécimaux. Dans DecodedMode, les "%" se suffisent à eux-mêmes et les caractères codés ne sont pas possibles.

Notez que, dans tous les cas, le résultat de l'analyse syntaxique doit être un nom d'hôte valide conformément aux règles de la STD 3, telles que modifiées par la spécification des identificateurs de ressources internationalisés (RFC 3987). Les noms d'hôtes non valides ne sont pas autorisés et feront en sorte que isValid() devienne faux.

Voir également host() et setAuthority().

[static] void QUrl::setIdnWhitelist(const QStringList &list)

Définit la liste blanche des domaines de premier niveau (TLD) autorisés à contenir des caractères non ASCII dans les domaines à la valeur de list.

Notez que si vous appelez cette fonction, vous devez le faire avant de démarrer tout thread susceptible d'accéder à idnWhitelist().

Qt est livré avec une liste par défaut qui contient les domaines de premier niveau d'Internet qui ont publié la prise en charge des noms de domaine internationalisés (IDN) et des règles pour garantir qu'aucune tromperie ne peut se produire entre des caractères d'apparence similaire (tels que la lettre minuscule latine 'a' et l'équivalent cyrillique, qui sont visuellement identiques dans la plupart des polices de caractères).

Cette liste est mise à jour périodiquement, au fur et à mesure que les bureaux d'enregistrement publient de nouvelles règles.

Cette fonction est fournie à ceux qui ont besoin de manipuler la liste, afin d'ajouter ou de supprimer un TLD. Il n'est pas recommandé de modifier sa valeur à des fins autres que des tests, car cela pourrait exposer les utilisateurs à des risques de sécurité.

Voir également idnWhitelist().

void QUrl::setPassword(const QString &password, QUrl::ParsingMode mode = DecodedMode)

Définit le mot de passe de l'URL à password. password fait partie de l'élément user info dans l'autorité de l'URL, comme décrit dans setUserInfo().

Les données de password sont interprétées conformément à mode: dans StrictMode, tout caractère "%" doit être suivi d'exactement deux caractères hexadécimaux et certains caractères (y compris l'espace) ne sont pas autorisés sous forme non décodée. Dans TolerantMode, tous les caractères sont acceptés sous forme non décodée et l'analyseur tolérant corrigera les "%" errants non suivis de deux caractères hexadécimaux. Dans DecodedMode, les "%" se suffisent à eux-mêmes et les caractères codés ne sont pas possibles.

QUrl::DecodedMode doit être utilisé lorsque le mot de passe est défini à partir d'une source de données qui n'est pas une URL, telle qu'une boîte de dialogue de mot de passe présentée à l'utilisateur ou un mot de passe obtenu en appelant password() avec l'option de formatage QUrl::FullyDecoded.

Voir également password() et setUserInfo().

void QUrl::setPath(const QString &path, QUrl::ParsingMode mode = DecodedMode)

Définit le chemin de l'URL à path. Le chemin est la partie de l'URL qui vient après l'autorité mais avant la chaîne de requête.

Pour les schémas non hiérarchiques, le chemin sera tout ce qui suit la déclaration du schéma, comme dans l'exemple suivant :

Les données de path sont interprétées conformément à mode: dans StrictMode, tout caractère "%" doit être suivi d'exactement deux caractères hexadécimaux et certains caractères (y compris l'espace) ne sont pas autorisés sous forme non décodée. Dans TolerantMode, tous les caractères sont acceptés sous forme non décodée et l'analyseur tolérant corrigera les "%" errants non suivis de deux caractères hexadécimaux. Dans DecodedMode, '%' se suffit à lui-même et les caractères codés ne sont pas possibles.

QUrl::DecodedMode doit être utilisé pour définir le chemin d'accès à partir d'une source de données qui n'est pas une URL, telle qu'une boîte de dialogue affichée à l'utilisateur ou un chemin d'accès obtenu en appelant path() avec l'option de formatage QUrl::FullyDecoded.

Voir aussi path().

void QUrl::setPort(int port)

Définit le port de l'URL à port. Le port fait partie de l'autorité de l'URL, comme décrit dans setAuthority().

port doit être compris entre 0 et 65535 inclus. La valeur -1 indique que le port n'est pas spécifié.

Voir également port().

void QUrl::setQuery(const QString &query, QUrl::ParsingMode mode = TolerantMode)

Définit la chaîne de requête de l'URL à query.

Cette fonction est utile si vous devez transmettre une chaîne de requête qui ne correspond pas au modèle clé-valeur ou qui utilise un schéma d'encodage des caractères spéciaux différent de celui suggéré par QUrl.

Passer une valeur de QString() à query (une valeur nulle QString) annule complètement la requête. Toutefois, si l'on passe une valeur de QString(""), la requête sera vide, comme si l'URL d'origine contenait un " ?" solitaire.

Les données de query sont interprétées conformément à mode: dans StrictMode, tout caractère "%" doit être suivi d'exactement deux caractères hexadécimaux et certains caractères (y compris l'espace) ne sont pas autorisés sous forme non décodée. Dans TolerantMode, tous les caractères sont acceptés sous forme non décodée et l'analyseur tolérant corrigera les "%" errants non suivis de deux caractères hexadécimaux. Dans DecodedMode, les "%" se suffisent à eux-mêmes et les caractères codés ne sont pas possibles.

Les chaînes de requête contiennent souvent des séquences codées en pourcentage, c'est pourquoi l'utilisation de DecodedMode est déconseillée. Une séquence spéciale dont il faut tenir compte est celle du caractère plus ('+'). QUrl ne convertit pas les espaces en caractères plus, même si les formulaires HTML affichés par les navigateurs web le font. Afin de représenter un caractère plus réel dans une requête, la séquence "%2B" est généralement utilisée. Cette fonction laissera les séquences "%2B" intactes dans TolerantMode ou StrictMode.

Voir également query() et hasQuery().

void QUrl::setQuery(const QUrlQuery &query)

Définit la chaîne de requête de l'URL à query.

Cette fonction reconstruit la chaîne de requête à partir de l'objet QUrlQuery et la place dans l'objet QUrl. Cette fonction n'a pas de paramètres d'analyse car l'objet QUrlQuery contient des données déjà analysées.

Voir aussi query() et hasQuery().

void QUrl::setScheme(const QString &scheme)

Définit le schéma de l'URL à scheme. Comme un schéma ne peut contenir que des caractères ASCII, aucune conversion ou décodage n'est effectué sur l'entrée. Il doit également commencer par une lettre ASCII.

Le schéma décrit le type (ou protocole) de l'URL. Il est représenté par un ou plusieurs caractères ASCII au début de l'URL.

Un schéma est strictement conforme à la RFC 3986: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

L'exemple suivant montre une URL dont le schéma est "ftp" :

Pour définir le schéma, l'appel suivant est utilisé :

QUrl url;
url.setScheme("ftp");

Le schéma peut également être vide, auquel cas l'URL est interprétée comme relative.

Voir aussi scheme() et isRelative().

void QUrl::setUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)

Analyse url et attribue cette valeur à cet objet. QUrl codera automatiquement en pourcentage tous les caractères qui ne sont pas autorisés dans une URL et décodera les séquences codées en pourcentage qui représentent un caractère non réservé (lettres, chiffres, traits d'union, traits de soulignement, points et tildes). Tous les autres caractères sont laissés dans leur forme originale.

Analyse le fichier url en utilisant le mode d'analyseur parsingMode. Dans TolerantMode (par défaut), QUrl corrigera certaines erreurs, notamment la présence d'un caractère pour cent ('%') non suivi de deux chiffres hexadécimaux, et acceptera n'importe quel caractère à n'importe quelle position. Dans StrictMode, les erreurs d'encodage ne seront pas tolérées et QUrl vérifiera également que certains caractères interdits ne sont pas présents sous forme non encodée. Si une erreur est détectée dans StrictMode, isValid() renverra faux. Le mode d'analyse DecodedMode n'est pas autorisé dans ce contexte et produira un avertissement d'exécution.

Voir aussi url() et toString().

void QUrl::setUserInfo(const QString &userInfo, QUrl::ParsingMode mode = TolerantMode)

Définit les informations sur l'utilisateur de l'URL à userInfo. Les informations sur l'utilisateur sont une partie optionnelle de l'autorité de l'URL, comme décrit dans setAuthority().

Les informations sur l'utilisateur se composent d'un nom d'utilisateur et éventuellement d'un mot de passe, séparés par un " :". Si le mot de passe est vide, les deux points doivent être omis. L'exemple suivant montre une chaîne d'informations utilisateur valide :

Les données de userInfo sont interprétées conformément à mode: dans StrictMode, tout caractère "%" doit être suivi d'exactement deux caractères hexadécimaux et certains caractères (y compris l'espace) ne sont pas autorisés sous forme non décodée. Dans TolerantMode (par défaut), tous les caractères sont acceptés sous forme non décodée et l'analyseur tolérant corrigera les "%" errants non suivis de deux caractères hexadécimaux.

Cette fonction ne permet pas à mode d'être QUrl::DecodedMode. Pour définir des données entièrement décodées, appelez setUserName() et setPassword() individuellement.

Voir aussi userInfo(), setUserName(), setPassword() et setAuthority().

void QUrl::setUserName(const QString &userName, QUrl::ParsingMode mode = DecodedMode)

Définit le nom d'utilisateur de l'URL à userName. userName fait partie de l'élément user info dans l'autorité de l'URL, comme décrit dans setUserInfo().

Les données de userName sont interprétées conformément à mode: dans StrictMode, tout caractère "%" doit être suivi d'exactement deux caractères hexadécimaux et certains caractères (y compris l'espace) ne sont pas autorisés sous forme non décodée. Dans TolerantMode (par défaut), tous les caractères sont acceptés sous forme non décodée et l'analyseur tolérant corrigera les "%" errants non suivis de deux caractères hexadécimaux. Dans DecodedMode, les "%" se suffisent à eux-mêmes et les caractères codés ne sont pas possibles.

QUrl::DecodedMode doit être utilisé pour définir le nom d'utilisateur à partir d'une source de données qui n'est pas une URL, telle qu'une boîte de dialogue de mot de passe montrée à l'utilisateur ou avec un nom d'utilisateur obtenu en appelant userName() avec l'option de formatage QUrl::FullyDecoded.

Voir également userName() et setUserInfo().

[noexcept] void QUrl::swap(QUrl &other)

Remplace cette URL par other. Cette opération est très rapide et n'échoue jamais.

[static, since 6.3] QByteArray QUrl::toAce(const QString &domain, QUrl::AceProcessingOptions options = {})

Renvoie le codage compatible ASCII du nom de domaine donné domain. La sortie peut être personnalisée en passant des drapeaux avec options. Le résultat de cette fonction est considéré comme équivalent à domain.

Le codage compatible ASCII (ACE) est défini par les RFC 3490, RFC 3491 et RFC 3492 et mis à jour par la norme technique Unicode #46. Il fait partie de la spécification IDNA (Internationalizing Domain Names in Applications), qui permet d'écrire des noms de domaine (comme "example.com") en utilisant des caractères non ASCII américains.

Cette fonction renvoie un QByteArray vide si domain n'est pas un nom d'hôte valide. Notez, en particulier, que les littéraux IPv6 ne sont pas des noms de domaine valides.

Cette fonction a été introduite dans Qt 6.3.

CFURLRef QUrl::toCFURL() const

Crée un CFURL à partir d'un QUrl.

L'appelant est propriétaire du CFURL et est responsable de sa libération.

QString QUrl::toDisplayString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

Renvoie une représentation de l'URL sous forme de chaîne de caractères affichable par l'homme. La sortie peut être personnalisée en passant des drapeaux avec options. L'option RemovePassword est toujours activée, car les mots de passe ne doivent jamais être montrés aux utilisateurs.

Avec les options par défaut, le résultat QString peut être transmis ultérieurement à QUrl, mais tout mot de passe présent initialement sera perdu.

Voir aussi FormattingOptions, toEncoded(), et toString().

QByteArray QUrl::toEncoded(QUrl::FormattingOptions options = FullyEncoded) const

Renvoie la représentation codée de l'URL si elle est valide ; sinon, une adresse QByteArray vide est renvoyée. La sortie peut être personnalisée en passant des drapeaux avec options.

Les informations sur l'utilisateur, le chemin et le fragment sont tous convertis en UTF-8, et tous les caractères non ASCII sont ensuite encodés en pourcentage. Le nom de l'hôte est encodé en utilisant Punycode.

QString QUrl::toLocalFile() const

Renvoie le chemin de cette URL formaté comme un chemin de fichier local. Le chemin renvoyé utilisera des barres obliques, même s'il a été créé à l'origine à partir d'un chemin comportant des barres obliques inverses.

Si cette URL contient un nom d'hôte non vide, il sera encodé dans la valeur renvoyée sous la forme trouvée sur les réseaux SMB (par exemple, "//servername/path/to/file.txt").

qDebug()<< QUrl("file:file.txt").toLocalFile() ; // "file.txt"qDebug() << QUrl("file:/home/user/file.txt").toLocalFile(); // "/home/user/file.txt"
qDebug() << QUrl("file.txt").toLocalFile();                 // ""; wasn't a local file as it had no scheme

Remarque : si le chemin d'accès de cette URL contient une séquence binaire non-UTF-8 (telle que %80), le comportement de cette fonction n'est pas défini.

Voir aussi fromLocalFile() et isLocalFile().

NSURL *QUrl::toNSURL() const

Crée un NSURL à partir d'un QUrl.

Le NSURL est libéré automatiquement.

[static] QByteArray QUrl::toPercentEncoding(const QString &input, const QByteArray &exclude = QByteArray(), const QByteArray &include = QByteArray())

Renvoie une copie codée de input. input est d'abord converti en UTF-8, et tous les caractères ASCII qui ne font pas partie du groupe non réservé sont codés en pourcentage. Pour éviter que les caractères soient codés en pourcentage, passez-les à exclude. Pour forcer les caractères à être codés en pourcentage, passez-les à include.

Unreserved est défini comme suit : ALPHA / DIGIT / "-" / "." / "_" / "~"

QByteArray ba = QUrl::toPercentEncoding("{une chaîne de caractères douteuse?}", "{}", "s") ;qDebug(ba.constData());
// imprime "{a fi%73hy %73tring%3F}"

QString QUrl::toString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

Renvoie une représentation sous forme de chaîne de l'URL. La sortie peut être personnalisée en passant des drapeaux avec options. L'option QUrl::FullyDecoded n'est pas autorisée dans cette fonction car elle générerait des données ambiguës.

L'option de formatage par défaut est PrettyDecoded.

Voir aussi FormattingOptions, url(), et setUrl().

[static] QStringList QUrl::toStringList(const QList<QUrl> &urls, QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded))

Convertit une liste de urls en une liste d'objets QString, en utilisant toString(options).

QString QUrl::url(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

Renvoie une représentation sous forme de chaîne de l'URL. La sortie peut être personnalisée en passant des drapeaux avec options. L'option QUrl::FullyDecoded n'est pas autorisée dans cette fonction car elle générerait des données ambiguës.

Le résultat QString peut être renvoyé ultérieurement à QUrl.

Synonyme de toString(options).

Voir aussi setUrl(), FormattingOptions, toEncoded(), et toString().

QString QUrl::userInfo(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

Renvoie les informations sur l'utilisateur de l'URL, ou une chaîne vide si les informations sur l'utilisateur ne sont pas définies.

Cette fonction renvoie une valeur non ambiguë, qui peut contenir des caractères encore codés en pourcentage, ainsi que certaines séquences de contrôle non représentables sous forme décodée dans QString.

L'argument options contrôle le formatage du composant user info. La valeur de QUrl::FullyDecoded n'est pas autorisée dans cette fonction. Si vous devez obtenir des données entièrement décodées, appelez userName() et password() individuellement.

Voir également setUserInfo(), userName(), password() et authority().

QString QUrl::userName(QUrl::ComponentFormattingOptions options = FullyDecoded) const

Renvoie le nom d'utilisateur de l'URL s'il est défini, sinon une chaîne vide est renvoyée.

L'argument options détermine comment formater le composant du nom d'utilisateur. Toutes les valeurs produisent un résultat non ambigu. Avec QUrl::FullyDecoded, toutes les séquences codées en pourcentage sont décodées ; sinon, la valeur renvoyée peut contenir des séquences codées en pourcentage pour certaines séquences de contrôle non représentables sous forme décodée dans QString.

Notez que QUrl::FullyDecoded peut entraîner une perte de données si ces séquences non représentables sont présentes. Il est recommandé d'utiliser cette valeur lorsque le résultat sera utilisé dans un contexte autre que l'URL, par exemple dans QAuthenticator ou lors de la négociation d'une connexion.

Voir aussi setUserName() et userInfo().

[noexcept] QUrl &QUrl::operator=(QUrl &&other)

Move-assigne other à cette instance QUrl.

QUrl &QUrl::operator=(const QString &url)

Attribue à cet objet le url spécifié.

Cet opérateur n'est pas disponible lorsque la macro QT_NO_URL_CAST_FROM_STRING est définie.

[noexcept] QUrl &QUrl::operator=(const QUrl &url)

Attribue le site url spécifié à cet objet.