GetFullPathNameTransactedW, fonction (winbase.h)

Article
11/20/2024

[Microsoft recommande vivement aux développeurs d’utiliser d’autres moyens pour répondre aux besoins de votre application. De nombreux scénarios développés par TxF peuvent être réalisés par le biais de techniques plus simples et plus facilement disponibles. En outre, TxF peut ne pas être disponible dans les futures versions de Microsoft Windows. Pour plus d’informations et d’alternatives à TxF, consultez Alternatives à l’utilisation de NTFS transactionnel.]

Récupère le chemin d’accès complet et le nom de fichier du fichier spécifié en tant qu’opération transactionnelle.

Pour effectuer cette opération sans transactions, utilisez la fonction GetFullPathName.

Pour plus d’informations sur les noms de fichiers et de chemins d’accès, consultez noms de fichiers, chemins et espaces de noms.

Syntaxe

DWORD GetFullPathNameTransactedW(
  [in]  LPCWSTR lpFileName,
  [in]  DWORD   nBufferLength,
  [out] LPWSTR  lpBuffer,
  [out] LPWSTR  *lpFilePart,
  [in]  HANDLE  hTransaction
);

Paramètres

[in] lpFileName

Nom du fichier.

Cette chaîne peut utiliser des noms de fichiers courts (formulaire 8.3) ou longs. Cette chaîne peut être un nom de partage ou de volume.

Le fichier doit résider sur l’ordinateur local ; sinon, la fonction échoue et le dernier code d’erreur est défini sur ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] nBufferLength

Taille de la mémoire tampon à recevoir la chaîne terminée par null pour le lecteur et le chemin d’accès, dans TCHAR.

[out] lpBuffer

Pointeur vers une mémoire tampon qui reçoit la chaîne terminée par null pour le lecteur et le chemin d’accès.

[out] lpFilePart

Pointeur vers une mémoire tampon qui reçoit l’adresse (dans lpBuffer) du composant de nom de fichier final dans le chemin d’accès. Spécifiez NULL si vous n’avez pas besoin de recevoir ces informations.

Si lpBuffer pointe vers un répertoire et non un fichier, lpFilePart reçoit 0 (zéro).

[in] hTransaction

Handle de la transaction. Ce handle est retourné par la fonction CreateTransaction.

Valeur de retour

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

Si le lpBuffer tampon est trop petit pour contenir le chemin d’accès, la valeur de retour est la taille, dans TCHARs, de la mémoire tampon requise pour contenir le chemin d’accès et le caractère null de fin.

Si la fonction échoue pour une autre raison, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

GetFullPathNameTransacted fusionne le nom du lecteur et du répertoire actuel avec un nom de fichier spécifié pour déterminer le chemin d’accès complet et le nom de fichier d’un fichier spécifié. Il calcule également l’adresse de la partie nom de fichier du chemin d’accès complet et du nom de fichier. Cette fonction ne vérifie pas que le chemin d’accès et le nom de fichier résultants sont valides ou qu’ils voient un fichier existant sur le volume associé.

Les noms de partage et de volume sont des entrées valides pour lpFileName. Par exemple, la liste suivante identité le chemin d’accès et les noms de fichiers retournés si test-2 est un ordinateur distant et U : il s’agit d’un lecteur mappé sur le réseau :

Si vous spécifiez « \\test-2\q$\lh », le chemin retourné est « \\test-2\q$\lh »
Si vous spécifiez « \\ ?\UNC\test-2\q$\lh », le chemin d’accès retourné est « \\ ?\UNC\test-2\q$\lh »
Si vous spécifiez « U : » le chemin retourné est « U :\ »

GetFullPathNameTransacted ne convertit pas le nom de fichier spécifié, lpFileName. Si le nom de fichier spécifié existe, vous pouvez utiliser GetLongPathNameTransacted, GetLongPathName, ou GetShortPathName pour convertir en noms de chemin long ou court, respectivement.

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

Remarque 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.

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

Technologie	Supporté
Protocole SMB (Server Message Block) 3.0	Non
Basculement transparent SMB 3.0 (TFO)	Non
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Non
Cluster Shared Volume File System (CsvFS)	Non
Système de fichiers résilient (ReFS)	Non

SMB 3.0 ne prend pas en charge TxF.

Note

L’en-tête winbase.h définit GetFullPathNameTransacted comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winbase.h (inclure Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll