QUrl Class

Documentation des fonctions membres

QUrl::QUrl()

Crée 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 valide ou une référence d'URL et ne tentera pas de deviner l'intention. Par exemple, la déclaration suivante :

QUrl url("example.com");

construira une URL valide, mais celle-ci risque de ne pas correspondre à ce que l'on attend, car la partie scheme() de l'entrée est manquante. Pour une chaîne comme celle ci-dessus, les applications peuvent préférer utiliser fromUserInput(). Pour ce constructeur ou setUrl(), ce qui suit correspond probablement à l'intention initiale :

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

QUrl effectuera automatiquement l’encodage en pourcentage de tous les caractères non autorisés dans une URL et décodera les séquences encodées en pourcentage représentant un caractère non réservé (lettres, chiffres, tirets, traits de soulignement, points et tildes). Tous les autres caractères sont conservés sous leur forme d’origine.

Analyse l’ url e en utilisant le mode d’analyse parsingMode. Dans TolerantMode (par défaut), QUrl corrigera certaines erreurs, notamment la présence d’un caractère pourcentage (« % ») non suivi de deux chiffres hexadécimaux, et acceptera n’importe quel caractère à n’importe quelle position. En mode 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 leur forme non encodée. Si une erreur est détectée en mode StrictMode, la fonction isValid() renverra false. 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 une 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");

Ces deux fonctions sont équivalentes et, dans Qt 5, elles acceptent toutes deux des données encodées. En général, le choix entre le constructeur QUrl ou setUrl() et fromEncoded() dépendra des données source : le constructeur et setUrl() prennent une chaîne « QString », tandis que fromEncoded prend une chaîne « QByteArray ».

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

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

Crée une copie de other.

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

Crée une instance de `QUrl` en la faisant pointer vers le même objet que celui vers lequel pointait ` other `.

[noexcept] QUrl::~QUrl()

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

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

Renvoie une version ajustée de l'URL. Le résultat peut être personnalisé en passant des indicateurs via options.

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

Cela revient toujours à QUrl(url.toString(options)).

Voir également FormattingOptions, toEncoded() et toString().

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

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

Cette fonction renvoie une valeur sans ambiguïté, qui peut contenir des caractères encore encodé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’informations utilisateur. La valeur ` QUrl::FullyDecoded ` n’est pas autorisée dans cette fonction. Si vous avez besoin d’obtenir des données entièrement décodées, appelez les fonctions ` userName()`, ` password()`, ` host()` et ` port()` individuellement.

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

void QUrl::clear()

Réinitialise le contenu de ` QUrl`. Après l'appel de cette fonction, ` QUrl ` correspond à un objet construit à l'aide du constructeur par défaut (vide).

Voir également isEmpty().

QString QUrl::errorString() const

Renvoie un message d'erreur si la dernière opération ayant 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 cherchent à comprendre pourquoi QUrl n'accepte pas certaines entrées.

Voir également QUrl::ParsingMode.

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

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

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

Si le chemin ne contient aucune barre oblique, il est renvoyé dans son intégralité en tant que nom de fichier.

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 ` contrôle le formatage de la partie « nom de fichier ». Toutes les valeurs produisent un résultat sans ambiguïté. Avec ` QUrl::FullyDecoded`, toutes les séquences encodées en pourcentage sont décodées ; sinon, la valeur renvoyée peut contenir certaines séquences encodées en pourcentage correspondant à des séquences de contrôle qui ne peuvent pas être représentées sous forme décodée dans ` QString`.

Voir également path().

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

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

L'argument ` options ` contrôle le formatage du fragment. Toutes les valeurs produisent un résultat sans ambiguïté. Avec ` QUrl::FullyDecoded`, toutes les séquences encodées en pourcentage sont décodées ; sinon, la valeur renvoyée peut contenir certaines séquences encodées en pourcentage correspondant à des séquences de contrôle qui ne peuvent pas être représentées 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 qu’une 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é selon le codage compatible ASCII (ACE). Le résultat peut être personnalisé en passant des indicateurs à l'aide de options. Le résultat de cette fonction est considéré comme équivalent à domain.

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

L'encodage compatible ASCII (ACE) est défini par les RFC 3490, 3491 et 3492 et mis à jour par la norme technique Unicode n° 46. Il fait partie de la spécification IDNA (Internationalizing Domain Names in Applications), qui permet d’écrire des noms de domaine (tels que "example.com") à l’aide de caractères non US-ASCII.

Cette fonction a été introduite dans Qt 6.3.

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

Crée un objet ` QUrl ` contenant une copie de l'URL CFURL url.

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

Analyse l'URL input et renvoie l'URL correspondante QUrl. L'URL input est supposée être sous forme encodée, ne contenant 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 également toEncoded() et setUrl().

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

Renvoie une représentation de type « QUrl » 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 plateforme.

Cette fonction accepte également les chemins d'accès commençant par deux barres obliques (ou barres obliques inversées) pour indiquer un fichier distant, comme dans « //servername/path/to/file.txt ». Notez que seules certaines plateformes peuvent réellement ouvrir ce fichier à l'aide de la fonction QFile::open().

Un ` localFile ` vide génère une URL vide (depuis Qt 5.4).

qDebug() << QUrl::fromLocalFile("file.txt");            // QUrl("file:file.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, une URL de fichier est construite à partir d'un chemin d'accès local et relatif. Une URL de fichier comportant un chemin d'accès relatif n'a de sens que s'il existe une URL de base permettant de la résoudre. Par exemple :

QUrl url = QUrl::fromLocalFile("file.txt");
QUrl baseUrl = QUrl("file:/home/user/");
// incorrect : affiche QUrl("file:file.txt"), car url possède déjà un schéma
qDebug() << baseUrl.resolved(url);

Pour résoudre une telle URL, il faut d'abord supprimer le schéma :

// correct : affiche 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/");
// affiche QUrl("file:///home/user/file.txt")
qDebug() << baseUrl.resolved(url);

Voir également toLocalFile(), isLocalFile() et QDir::toNativeSeparators().

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

Crée un objet ` QUrl ` contenant une copie de l'URL ` url`.

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

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

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

Convertit une liste de chaînes de caractères représentant des adresses de type « urls » en une liste d'URL, à l'aide de la fonction QUrl(str, mode). Notez que cela implique que toutes les chaînes doivent être des URL, et non pas, par exemple, des chemins d'accès locaux.

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

Renvoie une URL valide à partir d'une chaîne fournie par l'utilisateur userInput si une URL peut être déduite. Si cela n'est pas possible, une valeur non valide QUrl() est renvoyée.

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 la barre d’adresse, récupérée depuis le presse-papiers ou transmise via des arguments de ligne de commande.

Lorsque la chaîne n’est pas déjà une URL valide, une estimation est effectuée en se basant sur diverses hypothèses.

Si la chaîne correspond à un chemin d’accès valide sur le système, une URL de type `file://` est construite à l’aide de la fonction ` QUrl::fromLocalFile()`.

Si ce n’est pas le cas, le programme tente de transformer la chaîne en une URL de type http:// ou ftp://. Cette dernière option est utilisée si la chaîne commence par « ftp ». Le résultat est ensuite soumis au parseur tolérant de la fonction QUrl; en cas de succès, une URL QUrl valide est renvoyée, sinon une erreur QUrl() est générée.

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 accepte un chemin facultatif « workingDirectory ». Cela s’avère particulièrement utile lors du traitement des arguments de ligne de commande. Si « workingDirectory » est vide, aucun traitement des chemins relatifs ne sera effectué.

Par défaut, une chaîne d’entrée ressemblant à un chemin relatif ne sera traitée comme telle que si le fichier existe réellement dans le répertoire de travail indiqué. 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 elle comporte le caractère « # »).

Voir également fragment() et setFragment().

bool QUrl::hasQuery() const

Renvoie « true » si cette URL contient une requête (c'est-à-dire si elle comporte le caractère « ? »).

Voir également 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 ` fait en sorte que cette fonction renvoie le nom d’hôte au format ACE (ASCII-Compatible Encoding), qui convient aux canaux non compatibles 8 bits ou nécessitant le nom d’hôte traditionnel (comme les requêtes DNS ou les en-têtes de requêtes HTTP). Si ce drapeau n’est pas présent, cette fonction renvoie le nom de domaine international (IDN) au format 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ôte ne peuvent pas contenir de caractères de contrôle ni de caractères « % » ; la valeur renvoyée peut donc être considérée comme entièrement décodée.

Voir également setHost(), idnWhitelist(), setIdnWhitelist() et authority().

[static] QStringList QUrl::idnWhitelist()

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

Voir setIdnWhitelist() pour connaître la justification de cette liste.

Voir également setIdnWhitelist() et AceProcessingOption.

bool QUrl::isEmpty() const

Renvoie « true » si l'URL ne contient aucune donnée ; 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 considérée comme un chemin d'accès à un fichier local si son schéma est « file ».

Notez que cette fonction considère les URL comportant un nom d’hôte comme des chemins d’accès à des fichiers locaux, même si le chemin d’accès au fichier final 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 une URL parente de « childUrl ». « childUrl » est une URL fille de cette URL si les deux URL partagent le même schéma et la même autorité, et si le chemin d'accès de cette URL est une URL parente du chemin d'accès 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 section 4.2 de la RFC 3986.

Voir également 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 soumise à un test de conformité. Chaque partie de l'URL doit respecter les règles d'encodage de la norme URI pour que l'URL soit considérée comme 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 fournie sont identiques après avoir appliqué options aux deux ; sinon, renvoie false.

Cela revient à appeler adjusted(options) sur les deux URL et à comparer les URL obtenues, mais de manière plus rapide.

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 ` contrôle le formatage de la partie « nom d'utilisateur ». Toutes les valeurs produisent un résultat sans ambiguïté. Avec ` QUrl::FullyDecoded`, toutes les séquences encodées en pourcentage sont décodées ; sinon, la valeur renvoyée peut contenir certaines séquences encodées en pourcentage pour certaines séquences de contrôle non représentables sous forme décodée dans ` QString`.

Notez que la valeur « 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 qu'une URL, par exemple pour la configuration dans « QAuthenticator » ou la négociation d'une connexion.

Voir également setPassword().

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

Renvoie le chemin d'accès de 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 le formatage des éléments du chemin d'accès. Toutes les valeurs produisent un résultat sans ambiguïté. Avec ` QUrl::FullyDecoded`, toutes les séquences codées en pourcentage sont décodées ; dans le cas contraire, la valeur renvoyée peut contenir certaines 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`.

Notez que la valeur « 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 qu’une URL, par exemple lors d’un envoi vers un serveur FTP.

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

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

Dans cet exemple, il y aura une certaine perte de données car l’ %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 également 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 en a une, ou un résultat vide dans le cas contraire. Pour déterminer si l'URL analysée contenait une chaîne de requête, utilisez la fonction hasQuery().

L'argument ` options ` contrôle le formatage de la partie « requête ». Toutes les valeurs produisent un résultat sans ambiguïté. Avec ` QUrl::FullyDecoded`, toutes les séquences encodées en pourcentage sont décodées ; dans le cas contraire, la valeur renvoyée peut contenir certaines séquences encodé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`.

Notez que l'utilisation de ` QUrl::FullyDecoded ` dans les requêtes est déconseillée, car celles-ci contiennent souvent des données censées rester encodées en pourcentage, notamment l'utilisation de la séquence « %2B » pour représenter le caractère plus (« + »).

Voir également setQuery() et hasQuery().

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

Renvoie le résultat de la fusion de cette URL avec relative. Cette URL sert de base pour convertir relative en une 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 conserve 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("../Product/Library/");
qDebug(qUtf8Printable(baseUrl.resolved(relativeUrl).toString()));
// affiche « http://qt.digia.com/Product/Library/ »

L'appel de la méthode `resolved()` avec « .. » renvoie un ` QUrl ` dont le répertoire se trouve un niveau au-dessus de celui d'origine. De même, l'appel de la méthode `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 n'est pas défini et que l'URL est donc 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 nécessitant un encodage. De plus, les schémas sont toujours renvoyés en minuscules.

Voir également setScheme() et isRelative().

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

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

L'autorité d'une URL est la combinaison des informations 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 utilisateur et l'hôte sont séparés par un « @ », et l'hôte et le port sont séparés par un « : ». Si les informations utilisateur sont vides, le « @ » doit être omis ; toutefois, un « : » isolé est autorisé si le port est vide.

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

Les données de l’ authority e sont interprétées conformément à la norme 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 (valeur par défaut), tous les caractères sont acceptés sous forme non décodée et l'analyseur tolérant corrigera les caractères « % » isolés non suivis de deux caractères hexadécimaux.

Cette fonction ne permet pas de définir mode comme QUrl::DecodedMode. Pour définir des données entièrement décodées, appelez individuellement les fonctions setUserName(), setPassword(), setHost() et setPort().

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

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

Définit le fragment de l'URL sur 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é en 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 type QString() (un QString nul) effacera le fragment. Le passage d’un argument de type QString(« ») (un QString vide mais non nul) définira le fragment sur une chaîne vide (comme si l’URL d’origine ne comportait qu’un seul « # »).

Les données de fragment sont interprétées conformément à mode: dans StrictMode, tout caractère « % » doit être suivi exactement de deux caractères hexadécimaux et certains caractères (y compris l’espace) ne sont pas autorisés sous leur forme non codée. Dans TolerantMode, tous les caractères sont acceptés sous leur forme non codée et l’analyseur tolérant corrigera les « % » isolés non suivis de deux caractères hexadécimaux. Dans DecodedMode, les caractères « % » représentent eux-mêmes et les caractères encodés ne sont pas autorisés.

QUrl::DecodedMode Cette option doit être utilisée lors de la définition du 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 sur host. L'hôte fait partie de l'autorité.

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

Notez que, dans tous les cas, le résultat de l’analyse doit être un nom d’hôte valide selon les règles de la norme STD 3, telles que modifiées par la spécification relative aux identifiants de ressources internationalisés (RFC 3987). Les noms d’hôtes non valides ne sont pas autorisés et entraîneront la valeur « false » pour isValid().

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 leurs noms de domaine sur la valeur list.

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

Qt est fourni avec une liste par défaut contenant les domaines de premier niveau Internet qui ont annoncé la prise en charge des noms de domaine internationalisés (IDN) ainsi que des règles visant à garantir qu’aucune confusion ne puisse se produire entre des caractères d’apparence similaire (tels que la lettre minuscule latine « 'a' » et son équivalent cyrillique, qui sont visuellement identiques dans la plupart des polices).

Cette liste est mise à jour régulièrement, à mesure que les bureaux d’enregistrement publient de nouvelles règles.

Cette fonction est fournie à l’intention de 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 à d’autres fins 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 sur « password ». L'password fait partie de l'élément « user info » dans l'autorité de l'URL, comme décrit dans setUserInfo().

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

QUrl::DecodedMode Cette méthode doit être utilisée lors de la définition du mot de passe à partir d’une source de données autre qu’une URL, par exemple une boîte de dialogue de mot de passe affiché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 d'accès de l'URL sur path. Le chemin d'accès correspond à la partie de l'URL qui se trouve après le nom de domaine et avant la chaîne de requête.

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

Les données 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 leur forme non codée. Dans TolerantMode, tous les caractères sont acceptés sous leur forme non codée et l'analyseur tolérant corrigera les « % » isolés non suivis de deux caractères hexadécimaux. Dans DecodedMode, les caractères « % » représentent eux-mêmes et les caractères encodés ne sont pas autorisés.

QUrl::DecodedMode Il convient d’utiliser cette option lors de la définition du chemin à partir d’une source de données qui n’est pas une URL, comme une boîte de dialogue affichée à l’utilisateur ou un chemin obtenu en appelant path() avec l’option de formatage QUrl::FullyDecoded.

Voir également path().

void QUrl::setPort(int port)

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

port La valeur doit être comprise entre 0 et 65535 inclus. Définir le port sur -1 indique que celui-ci 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 sur 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 proposé par QUrl.

Le fait de transmettre la valeur QString() à query ( QString nul) supprime complètement la requête. En revanche, transmettre la valeur QString(« ») définira la requête sur une valeur vide, comme si l’URL d’origine ne comportait qu’un seul « ? ».

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

Les chaînes de requête contiennent souvent des séquences encodées en pourcentage ; l’utilisation de DecodedMode est donc déconseillée. Il convient de prêter une attention particulière à la séquence du signe « plus » (« + »). QUrl ne convertit pas les espaces en signes « plus », contrairement aux formulaires HTML envoyés par les navigateurs web. Pour représenter un véritable signe « plus » dans une requête, on utilise généralement la séquence « %2B ». Cette fonction laisse les séquences « %2B » inchangées 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 sur query.

Cette fonction reconstitue la chaîne de requête à partir de l'objet QUrlQuery et l'attribue à cet objet QUrl. Cette fonction ne dispose pas de paramètres d'analyse, car l'QUrlQuery contient des données déjà analysées.

Voir également query() et hasQuery().

void QUrl::setScheme(const QString &scheme)

Définit le schéma de l'URL sur scheme. Étant donné qu'un schéma ne peut contenir que des caractères ASCII, aucune conversion ni aucun décodage n'est effectué sur la valeur d'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 norme RFC 3986: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

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

Pour définir le schéma, on utilise l’appel suivant :

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

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

Voir également scheme() et isRelative().

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

Analyse url et attribue cette valeur à cet objet. QUrl effectue automatiquement l'encodage en pourcentage de tous les caractères non autorisés dans une URL et décode les séquences encodées en pourcentage qui représentent un caractère non réservé (lettres, chiffres, tirets, traits de soulignement, points et tildes). Tous les autres caractères conservent leur forme d'origine.

Analyse la chaîne url en utilisant le mode d’analyse parsingMode. En mode TolerantMode (par défaut), QUrl corrigera certaines erreurs, notamment la présence d’un caractère pourcentage (« % ») non suivi de deux chiffres hexadécimaux, et acceptera n’importe quel caractère à n’importe quelle position. En mode « 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 leur forme non encodée. Si une erreur est détectée en mode « StrictMode », isValid() renverra « false ». Le mode d’analyse DecodedMode n’est pas autorisé dans ce contexte et générera un avertissement d’exécution.

Voir également url() et toString().

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

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

Les informations d'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, le deux-points doit être omis. L'exemple suivant illustre une chaîne d'informations d'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 leur forme non décodée. Dans TolerantMode (valeur par défaut), tous les caractères sont acceptés sous forme non décodée et l’analyseur tolérant corrigera les caractères « % » isolés non suivis de deux caractères hexadécimaux.

Cette fonction ne permet pas de définir mode comme QUrl::DecodedMode. Pour définir des données entièrement décodées, appelez setUserName() et setPassword() séparément.

Voir également userInfo(), setUserName(), setPassword() et setAuthority().

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

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

Les données « 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 leur forme non décodée. Dans TolerantMode (valeur par défaut), tous les caractères sont acceptés sous forme non codée et l'analyseur tolérant corrigera les caractères « % » isolés non suivis de deux caractères hexadécimaux. Dans DecodedMode, les caractères « % » représentent eux-mêmes et les caractères codés ne sont pas autorisés.

QUrl::DecodedMode Cette option doit être utilisée lors de la configuration du nom d’utilisateur à partir d’une source de données qui n’est pas une URL, comme une boîte de dialogue de mot de passe affiché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 ne pose jamais de problème.

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

Renvoie l'encodage compatible ASCII du nom de domaine donné domain. Le résultat peut être personnalisé en passant des indicateurs via options. Le résultat de cette fonction est considéré comme équivalent à domain.

L'encodage compatible ASCII (ACE) est défini par les RFC 3490, 3491 et 3492 et mis à jour par la norme technique Unicode n° 46. Il fait partie de la spécification IDNA (Internationalizing Domain Names in Applications), qui permet d'écrire des noms de domaine (tels que "example.com") à l'aide de caractères non US-ASCII.

Cette fonction renvoie un QByteArray vide si domain n'est pas un nom d'hôte valide. Notez notamment que les littéraux IPv6 ne constituent 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 chargé de le libérer.

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

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

Avec les options par défaut, l’ QString ainsi obtenue peut être transmise ultérieurement à une fonction QUrl, mais tout mot de passe présent initialement sera perdu.

Voir également FormattingOptions, toEncoded() et toString().

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

Renvoie la représentation encodée de l'URL si celle-ci est valide ; dans le cas contraire, un objet vide de type ` QByteArray ` est renvoyé. La sortie peut être personnalisée en passant des indicateurs via ` options`.

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

QString QUrl::toLocalFile() const

Renvoie le chemin d'accès de cette URL sous la forme d'un chemin d'accès local. Le chemin renvoyé utilisera des barres obliques, même s'il a été initialement créé à partir d'un chemin comportant des barres obliques inversées.

Si cette URL contient un nom d'hôte non vide, celui-ci sera encodé dans la valeur renvoyée sous la forme utilisé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 une partie du 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 également 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 encodée de ` input`. ` input ` est d'abord converti en UTF-8, puis tous les caractères ASCII n'appartenant pas au groupe des caractères non réservés sont encodés en pourcentage. Pour empêcher l'encodage en pourcentage de certains caractères, transmettez-les à ` exclude`. Pour forcer l'encodage en pourcentage de certains caractères, transmettez-les à ` include`.

Le terme « non réservé » est défini comme suit : ALPHA / DIGIT / "-" / "." / "_" / "~"

QByteArray ba = QUrl::toPercentEncoding("{une chaîne suspecte ?}", "{}", "s");
qDebug(ba.constData());
// affiche « {a fi%73hy %73tring%3F} »

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

Renvoie une représentation sous forme de chaîne de caractères de l'URL. Le résultat peut être personnalisé en passant des indicateurs avec l'option « 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 également FormattingOptions, url() et setUrl().

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

Convertit une liste d'objets ` urls ` en une liste d'objets ` QString `, à l'aide de la fonction ` toString` (options).

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

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

L'QString résultante peut être transmise ultérieurement à un QUrl.

Synonyme de ` toString(options)`.

Voir également setUrl(), FormattingOptions, toEncoded() et toString().

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

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

Cette fonction renvoie une valeur sans ambiguïté, qui peut contenir des caractères encore encodé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’informations utilisateur. La valeur QUrl::FullyDecoded n’est pas autorisée dans cette fonction. Si vous avez besoin d’obtenir des données entièrement décodées, appelez les fonctions userName() et password() séparément.

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 contrôle le formatage de la composante « nom d'utilisateur ». Toutes les valeurs produisent un résultat sans ambiguïté. Avec QUrl::FullyDecoded, toutes les séquences encodées en pourcentage sont décodées ; sinon, la valeur renvoyée peut contenir certaines séquences encodées en pourcentage pour certaines séquences de contrôle non représentables sous forme décodée dans QString.

Notez que la valeur « 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 qu’une URL, par exemple pour définir une valeur dans « QAuthenticator » ou pour négocier une connexion.

Voir également setUserName() et userInfo().

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

Cette opération attribue l'other à cette instance QUrl.

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

Attribue l'url spécifiée à cet objet.

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 l'url ion spécifiée à cet objet.