Fonction OpenFileById (winbase.h)

Article
08/27/2023

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.

Valeur	Signification
FILE_SHARE_DELETE 0x00000004	Active les opérations d’ouverture suivantes sur un objet pour demander l’accès à la suppression. Sinon, d’autres processus ne peuvent pas ouvrir l’objet s’ils demandent un accès de suppression. Si cet indicateur n’est pas spécifié, mais que l’objet a été ouvert pour l’accès de suppression, la fonction échoue.
FILE_SHARE_READ 0x00000001	Active les opérations d’ouverture suivantes sur un objet pour demander l’accès en lecture. Sinon, d’autres processus ne peuvent pas ouvrir l’objet s’ils demandent un accès en lecture. Si cet indicateur n’est pas spécifié, mais que l’objet a été ouvert pour l’accès en lecture, la fonction échoue.
FILE_SHARE_WRITE 0x00000002	Active les opérations d’ouverture suivantes sur un objet pour demander l’accès en écriture. Sinon, d’autres processus ne peuvent pas ouvrir l’objet s’ils demandent un accès en écriture. Si cet indicateur n’est pas spécifié, mais que l’objet a été ouvert pour l’accès en écriture ou a un mappage de fichiers avec accès en écriture, la fonction échoue.

Valeur

Signification

FILE_SHARE_DELETE
0x00000004

Active les opérations d’ouverture suivantes sur un objet pour demander l’accès à la suppression.

Sinon, d’autres processus ne peuvent pas ouvrir l’objet s’ils demandent un accès de suppression.

Si cet indicateur n’est pas spécifié, mais que l’objet a été ouvert pour l’accès de suppression, la fonction échoue.

FILE_SHARE_READ
0x00000001

Active les opérations d’ouverture suivantes sur un objet pour demander l’accès en lecture.

Sinon, d’autres processus ne peuvent pas ouvrir l’objet s’ils demandent un accès en lecture.

Si cet indicateur n’est pas spécifié, mais que l’objet a été ouvert pour l’accès en lecture, la fonction échoue.

FILE_SHARE_WRITE
0x00000002

Active les opérations d’ouverture suivantes sur un objet pour demander l’accès en écriture.

Sinon, d’autres processus ne peuvent pas ouvrir l’objet s’ils demandent un accès en écriture.

Si cet indicateur n’est pas spécifié, mais que l’objet a été ouvert pour l’accès en écriture ou a un mappage de fichiers avec accès en écriture, la fonction échoue.

[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
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	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.
FILE_FLAG_NO_BUFFERING 0x20000000	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 : L’accès aux fichiers doit commencer à des décalages d’octets au sein d’un fichier qui sont des multiples entiers de la taille du secteur du volume. L’accès au fichier doit concerner des nombres d’octets qui sont des multiples entiers de la taille du secteur de volume. Par exemple, si la taille du secteur est de 512 octets, une application peut demander des lectures et des écritures de 512, 1024, 1536 ou 2048 octets, mais pas de 335, 981 ou 7171 octets. Les adresses de mémoire tampon pour les opérations de lecture et d’écriture doivent être alignées sur les secteurs, ce qui signifie qu’elles sont alignées sur les adresses en mémoire qui sont des multiples entiers de la taille du secteur de volume. Selon le disque, cette exigence peut ne pas être appliquée. Une façon d’aligner les mémoires tampons sur les multiples entiers de la taille du secteur de volume consiste à utiliser VirtualAlloc pour allouer les mémoires tampons. Il alloue de la mémoire alignée sur les adresses qui sont des multiples entiers de la taille de la page mémoire du système d’exploitation. Étant donné que les tailles de page mémoire et de secteur de volume sont toutes deux égales à 2, cette mémoire est également alignée sur les adresses qui sont des multiples entiers d’une taille de secteur de volume. Les pages mémoire ont une taille de 4 à 8 Ko ; les secteurs sont de 512 octets (disques durs) ou de 2 048 octets (CD), et par conséquent, les secteurs de volume ne peuvent jamais être plus volumineux que les pages de mémoire. Une application peut déterminer une taille de secteur de volume en appelant la fonction GetDiskFreeSpace .
FILE_FLAG_OPEN_NO_RECALL 0x00100000	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.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	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é.
FILE_FLAG_OVERLAPPED 0x40000000	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 .
FILE_FLAG_RANDOM_ACCESS 0x10000000	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.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	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.
FILE_FLAG_WRITE_THROUGH 0x80000000	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.