Méthode ILockBytes ::LockRegion (objidl.h)

Article
02/29/2024

La méthode LockRegion restreint l’accès à une plage spécifiée d’octets dans le tableau d’octets.

Syntaxe

HRESULT LockRegion(
  [in] ULARGE_INTEGER libOffset,
  [in] ULARGE_INTEGER cb,
  [in] DWORD          dwLockType
);

Paramètres

[in] libOffset

Spécifie le décalage d’octets pour le début de la plage.

[in] cb

Spécifie, en octets, la longueur de la plage à restreindre.

[in] dwLockType

Spécifie le type de restrictions demandées lors de l’accès à la plage. Ce paramètre utilise l’une des valeurs de l’énumération LOCKTYPE .

Valeur retournée

Cette méthode peut retourner l’une de ces valeurs.

Code de retour	Description
S_OK	La plage d’octets spécifiée a été verrouillée.
STG_E_INVALIDFUNCTION	Le verrouillage n’est pas du tout pris en charge ou le type spécifique de verrou demandé n’est pas pris en charge.
STG_E_ACCESSDENIED	Accès refusé, car l’appelant a une autorisation insuffisante ou un autre appelant a le fichier ouvert et verrouillé.
STG_E_LOCKVIOLATION	Accès refusé, car un autre appelant a le fichier ouvert et verrouillé.
STG_E_INVALIDHANDLE	Un fichier sous-jacent a été fermé prématurément ou la bonne disquette a été remplacée par une autre non valide.

Remarques

ILockBytes ::LockRegion restreint l’accès à la plage d’octets spécifiée. Une fois qu’une région est verrouillée, les tentatives d’accès à la plage restreinte doivent échouer avec l’erreur STG_E_ACCESSDENIED.

La plage d’octets peut dépasser la fin actuelle du tableau d’octets. Le verrouillage au-delà de la fin d’un tableau est utile en tant que méthode de communication entre différentes instances de l’objet de tableau d’octets sans modifier les données qui font réellement partie du tableau d’octets. Par exemple, une implémentation d’ILockBytes pour les fichiers composés peut s’appuyer sur le verrouillage au-delà de la fin actuelle du tableau comme moyen de contrôle d’accès, en utilisant des régions verrouillées spécifiques pour indiquer les autorisations actuellement accordées.

Le paramètre dwLockType spécifie l’un des trois types de verrouillage, à l’aide de valeurs de l’énumération LOCKTYPE . Les types sont les suivants : verrouillage pour exclure d’autres enregistreurs, verrouillage pour exclure d’autres lecteurs ou enregistreurs et verrouillage qui permet à un seul demandeur d’obtenir un verrou sur la plage donnée. Ce troisième type de verrouillage est généralement un alias pour l’un des deux autres types de verrous et permet à un implémenteur d’ajouter également un autre comportement. Un tableau d’octets donné peut prendre en charge l’un des deux premiers types, ou les deux.

Pour déterminer les types de verrous pris en charge par une implémentation ILockBytes particulière, vous pouvez examiner le membre grfLocksSupported de la structure STATSTG retourné par un appel à ILockBytes ::Stat.

Toute région verrouillée avec ILockBytes ::LockRegion doit par la suite être déverrouillée explicitement en appelant ILockBytes ::UnlockRegion avec exactement les mêmes valeurs pour les paramètres libOffset, cb et dwLockType . La région doit être déverrouillée avant que le flux ne soit libéré. Deux régions adjacentes ne peuvent pas être verrouillées séparément, puis déverrouillées avec un seul appel de déverrouillage.

Remarques aux appelants

Étant donné que le type de verrouillage pris en charge est facultatif et peut varier selon les implémentations d’ILockBytes, vous devez fournir du code pour gérer l’erreur STG_E_INVALIDFUNCTION.

Remarques aux implémenteurs

La prise en charge de cette méthode dépend de la façon dont l’objet de stockage créé sur l’implémentation ILockBytes est utilisé. Si vous savez qu’un seul objet de stockage à un moment donné peut être ouvert sur le périphérique de stockage qui sous-tend le tableau d’octets, votre implémentation ILockBytes n’a pas besoin de prendre en charge le verrouillage. Toutefois, si plusieurs ouvertures simultanées d’un objet de stockage sont possibles, le verrouillage de région est nécessaire pour les coordonner.

Une implémentation LockRegion peut choisir de prendre en charge tous les types de verrous, certains ou aucun. Pour les types de verrous non pris en charge, l’implémentation doit retourner STG_E_INVALIDFUNCTION.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	objidl.h
Bibliothèque	Uuid.lib
DLL	Ole32.dll