GetShortPathNameW, fonction (fileapi.h)

Article
03/02/2024

Récupère la forme courte du chemin d’accès spécifié.

Pour plus d’informations sur les noms de fichiers et de chemins d’accès, consultez Naming Files, Paths, and Namespaces.

Syntaxe

DWORD GetShortPathNameW(
  [in]  LPCWSTR lpszLongPath,
  [out] LPWSTR  lpszShortPath,
  [in]  DWORD   cchBuffer
);

Paramètres

[in] lpszLongPath

Chaîne de chemin d’accès.

Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères de large, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez Nommage de fichiers, de chemins et d’espaces de noms.

Conseil

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation de MAX_PATH sans précédencer « \ ?\ ». Pour plus d’informations, consultez la section « Limitation de longueur maximale du chemin d’accès » dans Naming Files, Paths et Namespaces .

[out] lpszShortPath

Pointeur vers une mémoire tampon pour recevoir la forme abrégée terminée par null du chemin spécifié par lpszLongPath .

Le passage de null pour ce paramètre et de zéro pour cchBuffer retourne toujours la taille de mémoire tampon requise pour un lpszLongPath spécifié.

[in] cchBuffer

Taille de la mémoire tampon vers laquelle lpszShortPath pointe, dans les TCHAR.

Définissez ce paramètre sur zéro si lpszShortPath a la valeur NULL.

Valeur retournée

Si la fonction réussit, la valeur de retour est la longueur, en TCHAR, de la chaîne copiée dans lpszShortPath, sans inclure le caractère null de fin.

Si la mémoire tampon lpszShortPath est trop petite pour contenir le chemin d’accès, la valeur de retour est la taille de la mémoire tampon, en TCHAR, qui est nécessaire pour contenir le chemin et le caractère null de fin.

Si la fonction échoue pour une autre raison, la valeur de retour est zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Le chemin que le paramètre lpszLongPath spécifie ne doit pas être un chemin d’accès complet ou long. Le formulaire abrégé peut être plus long que le chemin spécifié.

Si la valeur de retour est supérieure à la valeur spécifiée dans le paramètre cchBuffer , vous pouvez appeler à nouveau la fonction avec une mémoire tampon suffisamment grande pour contenir le chemin d’accès. Pour obtenir un exemple de ce cas en plus de l’utilisation d’une mémoire tampon de longueur nulle pour l’allocation dynamique, consultez la section Exemple de code.

Note Bien que la valeur de retour dans ce cas soit une longueur qui inclut le caractère null de fin, la valeur de retour en cas de réussite n’inclut pas le caractère null de fin dans le nombre.

Si le chemin spécifié est déjà dans sa forme abrégée et que la conversion n’est pas nécessaire, la fonction copie simplement le chemin spécifié dans la mémoire tampon spécifiée par le paramètre lpszShortPath .

Vous pouvez définir le paramètre lpszShortPath sur la même valeur que le paramètre lpszLongPath ; en d’autres termes, vous pouvez définir la mémoire tampon de sortie pour le chemin d’accès court à l’adresse de la chaîne de chemin d’entrée. Veillez toujours à ce que le paramètre cchBuffer représente avec précision la taille totale, en TCHAR, de cette mémoire tampon.

Vous pouvez obtenir le nom long d’un fichier à partir du nom court en appelant la fonction GetLongPathName . Si GetLongPathName n’est pas disponible, vous pouvez également appeler FindFirstFile sur chaque composant du chemin d’accès pour obtenir le nom long correspondant.

Il est possible d’avoir accès à un fichier ou à un répertoire, mais de ne pas avoir accès à certains des répertoires parents de ce fichier ou répertoire. Par conséquent, GetShortPathName peut échouer lorsqu’il ne peut pas interroger le répertoire parent d’un composant de chemin d’accès pour déterminer le nom court de ce composant. Cette case activée peut être ignorée pour les composants d’annuaire qui répondent déjà aux exigences d’un nom court. Pour plus d’informations, consultez la section Noms courts et noms longs de Naming Files, Paths et Namespaces.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Prise en charge
Protocole Server Message Block (SMB) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	No
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	No
Système de fichiers du volume partagé de cluster (CsvFS)	No
Système de fichiers résilient (ReFS)	Oui

SMB 3.0 ne prend pas en charge les noms courts sur les partages avec une fonctionnalité de disponibilité continue.

Le système de fichiers résilient (ReFS) ne prend pas en charge les noms courts. Si vous appelez GetShortPathName sur un chemin qui n’a pas de noms courts sur le disque, l’appel réussit, mais retourne le chemin de nom long à la place. Ce résultat est également possible avec les volumes NTFS, car il n’existe aucune garantie qu’un nom court existera pour un nom long donné.

Exemples

Pour obtenir un exemple qui utilise GetShortPathName, consultez la section Exemple de code pour GetFullPathName.

L’exemple C++ suivant montre comment utiliser une mémoire tampon de sortie allouée dynamiquement.

//...
    long     length = 0;
    TCHAR*   buffer = NULL;

// First obtain the size needed by passing NULL and 0.

    length = GetShortPathName(lpszPath, NULL, 0);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

// Dynamically allocate the correct size 
// (terminating null char was included in length)

    buffer = new TCHAR[length];

// Now simply call again using same long path.

    length = GetShortPathName(lpszPath, buffer, length);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

    _tprintf(TEXT("long name = %s shortname = %s"), lpszPath, buffer);
    
    delete [] buffer;
///...

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	fileapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll