Fonction OpenFileById (winbase.h)
Ouvre le fichier correspondant à l’identifiant spécifié.
Syntaxe
HANDLE OpenFileById(
[in] HANDLE hVolumeHint,
[in] LPFILE_ID_DESCRIPTOR lpFileId,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwFlagsAndAttributes
);
Paramètres
[in] hVolumeHint
Handle pour n’importe quel fichier sur un volume ou un partage sur lequel le fichier à ouvrir est stocké.
[in] lpFileId
Pointeur vers un FILE_ID_DESCRIPTOR qui identifie le fichier à ouvrir.
[in] dwDesiredAccess
Accès à l’objet. L’accès peut être en lecture, en écriture ou les deux.
Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès. Vous ne pouvez pas demander un mode d’accès qui entre en conflit avec le mode de partage spécifié dans une demande ouverte qui a un handle ouvert.
Si ce paramètre est égal à zéro (0), l’application peut interroger les attributs de fichier et d’appareil sans accéder à un appareil. Cela est utile pour une application pour déterminer la taille d’un lecteur de disquette et les formats qu’elle prend en charge sans nécessiter de disquette dans un lecteur. Il peut également être utilisé pour tester l’existence d’un fichier ou d’un répertoire sans les ouvrir pour l’accès en lecture ou en écriture.
[in] dwShareMode
Mode de partage d’un objet, qui peut être lu, écrit, les deux ou aucun.
Vous ne pouvez pas demander un mode de partage qui entre en conflit avec le mode d’accès spécifié dans une demande ouverte qui a un handle ouvert, car cela entraînerait la violation de partage suivante : (ERROR_SHARING_VIOLATION). Pour plus d’informations, consultez Création et ouverture de fichiers.
Si ce paramètre est égal à zéro (0) et si OpenFileById réussit, l’objet ne peut pas être partagé et ne peut pas être ouvert à nouveau tant que le handle n’est pas fermé. Pour plus d’informations, consultez la section Remarques de cette rubrique.
Les options de partage restent en vigueur jusqu’à ce que vous fermez le handle à un objet.
Pour permettre à un processus de partager un objet alors qu’un autre processus a l’objet ouvert, utilisez une combinaison d’une ou plusieurs des valeurs suivantes pour spécifier le mode d’accès qu’ils peuvent demander pour ouvrir l’objet.
[in, optional] lpSecurityAttributes
Réservé.
[in] dwFlagsAndAttributes
Indicateurs de fichier.
Quand OpenFileById ouvre un fichier, il combine les indicateurs de fichier avec les attributs de fichier existants et ignore tous les attributs de fichier fournis. Ce paramètre peut inclure n’importe quelle combinaison des indicateurs suivants.
| Valeur | Signification |
|---|---|
|
Un fichier est ouvert pour une opération de sauvegarde ou de restauration. Le système garantit que le processus appelant remplace les vérifications de sécurité des fichiers lorsque le processus dispose de privilèges SE_BACKUP_NAME et SE_RESTORE_NAME . Pour plus d’informations, consultez Modification des privilèges dans un jeton.
Vous devez définir cet indicateur pour obtenir un handle dans un répertoire. Un handle de répertoire peut être passé à certaines fonctions au lieu d’un handle de fichier. Pour plus d’informations, consultez Handles d’annuaire. |
|
Le système ouvre un fichier sans mise en cache système. Cet indicateur n’affecte pas la mise en cache du disque dur. Lorsqu’il est combiné avec FILE_FLAG_OVERLAPPED, l’indicateur offre des performances asynchrones maximales, car les E/S ne reposent pas sur les opérations synchrones du gestionnaire de mémoire. Toutefois, certaines opérations d’E/S prennent plus de temps, car les données ne sont pas conservées dans le cache. En outre, les métadonnées du fichier peuvent toujours être mises en cache. Pour vider les métadonnées sur le disque, utilisez la fonction FlushFileBuffers.
Une application doit répondre à certaines exigences lors de l’utilisation de fichiers ouverts avec FILE_FLAG_NO_BUFFERING :
Une application peut déterminer une taille de secteur de volume en appelant la fonction GetDiskFreeSpace . |
|
Les données de fichier sont demandées, mais elles doivent continuer à se trouver dans le stockage distant. Il ne doit pas être renvoyé vers le stockage local. Cet indicateur est destiné aux systèmes de stockage distants. |
|
Lorsque cet indicateur est utilisé, le traitement normal du point d’analyse ne se produit pas et OpenFileById tente d’ouvrir le point d’analyse. Lorsqu’un fichier est ouvert, un handle de fichier est retourné, que le filtre qui contrôle le point d’analyse soit opérationnel ou non. Cet indicateur ne peut pas être utilisé avec l’indicateur CREATE_ALWAYS . Si le fichier n’est pas un point d’analyse, cet indicateur est ignoré. |
|
Le fichier est ouvert ou créé pour les E/S asynchrones. Une fois l’opération terminée, l’événement spécifié à l’appel dans la structure CHEVAUCHEMENT EST défini sur l’état signalé. Les opérations qui prennent beaucoup de temps à traiter retournent ERROR_IO_PENDING.
Si cet indicateur est spécifié, le fichier peut être utilisé pour des opérations de lecture et d’écriture simultanées. Le système ne gère pas le pointeur de fichier. Par conséquent, vous devez passer la position du fichier aux fonctions de lecture et d’écriture dans la structure CHEVAUCHEMENT OU mettre à jour le pointeur de fichier. Si cet indicateur n’est pas spécifié, les opérations d’E/S sont sérialisées, même si les appels aux fonctions de lecture et d’écriture spécifient une structure CHEVAUCHÉE . |
|
Un fichier est accédé de manière aléatoire. Le système peut utiliser cette indication pour optimiser la mise en cache du fichier. |
|
Un fichier est accédé de manière séquentielle du début à la fin. Le système peut utiliser cette indication pour optimiser la mise en cache du fichier. Si une application déplace le pointeur de fichier pour un accès aléatoire, la mise en cache optimale peut ne pas se produire. Toutefois, le bon fonctionnement est toujours garanti.
La spécification de cet indicateur peut augmenter les performances pour les applications qui lisent des fichiers volumineux à l’aide d’un accès séquentiel. Les gains de performances peuvent être encore plus notables pour les applications qui lisent des fichiers volumineux principalement séquentiellement, mais qui ignorent parfois de petites plages d’octets. |
|
Le système écrit dans n’importe quel cache intermédiaire et accède directement au disque.
Si FILE_FLAG_NO_BUFFERING n’est pas également spécifié, afin que la mise en cache du système soit en vigueur, les données sont écrites dans le cache système, mais elles sont vidées sur le disque sans délai. Si FILE_FLAG_NO_BUFFERING est également spécifié, de sorte que la mise en cache du système n’est pas appliquée, les données sont immédiatement vidées sur le disque sans passer par le cache système. Le système d’exploitation demande également une écriture via le cache du disque dur sur un média persistant. Toutefois, tous les matériels ne prennent pas en charge cette fonctionnalité d’écriture directe. |
Valeur retournée
Si la fonction réussit, la valeur de retour est un descripteur ouvert vers un fichier spécifié.
Si la fonction échoue, la valeur de retour est INVALID_HANDLE_VALUE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Remarques
Utilisez la fonction CloseHandle pour fermer un handle d’objet retourné par OpenFileById .
Si vous appelez OpenFileById sur un fichier en attente de suppression suite à un appel précédent à DeleteFile, la fonction échoue. Le système d’exploitation retarde la suppression du fichier jusqu’à ce que tous les handles du fichier soient fermés. GetLastError retourne ERROR_ACCESS_DENIED.
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) | Oui |
| Système de fichiers résilient (ReFS) | Oui |
Configuration requise
| 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; FileExtd.lib sur Windows Server 2003 et Windows XP |
| DLL | Kernel32.dll |
| Composant redistribuable | Sdk Windows sur Windows Server 2003 et Windows XP. |