GetFullPathNameTransactedA, fonction (winbase.h)

Article
08/27/2023

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

Récupère le chemin d’accès complet et le nom du fichier .wim 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 GetFullPathNameTransactedA(
  [in]  LPCSTR lpFileName,
  [in]  DWORD  nBufferLength,
  [out] LPSTR  lpBuffer,
  [out] LPSTR  *lpFilePart,
  [in]  HANDLE hTransaction
);

Paramètres

[in] lpFileName

Nom du fichier.

Cette chaîne peut utiliser des noms de fichiers courts (le 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 pour recevoir la chaîne terminée par null pour le lecteur et le chemin d’accès, dans les 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 vers un fichier, lpFilePart reçoit 0 (zéro).

[in] hTransaction

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

Valeur retournée

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

Si la mémoire tampon lpBuffer est trop petite pour contenir le chemin, la valeur de retour correspond à la taille, en TCHAR, de la mémoire tampon requise 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

GetFullPathNameTransacted fusionne le nom du lecteur et du répertoire actuels 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 du 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 : est un lecteur mappé au réseau :

Si vous spécifiez « \\test-2\q$\lh », le chemin d’accès 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 d’accès 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 respectivement en noms de chemins longs ou courts.

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.

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.

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	No
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)	No

SMB 3.0 ne prend pas en charge TxF.

Notes

L’en-tête winbase.h définit GetFullPathNameTransacted en tant qu’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. La combinaison 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.

Configuration requise

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