ILockBytes::LockRegion-Methode (objidl.h)

Artikel
08/25/2023

Die LockRegion-Methode schränkt den Zugriff auf einen angegebenen Bytebereich im Bytearray ein.

Syntax

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

Parameter

[in] libOffset

Gibt den Byteoffset für den Anfang des Bereichs an.

[in] cb

Gibt in Bytes die Länge des zu beschränkenden Bereichs an.

[in] dwLockType

Gibt den Typ der Einschränkungen an, die beim Zugriff auf den Bereich angefordert werden. Dieser Parameter verwendet einen der Werte aus der LOCKTYPE-Enumeration .

Rückgabewert

Diese Methode kann einen dieser Werte zurückgeben.

Rückgabecode	Beschreibung
S_OK	Der angegebene Bytebereich wurde gesperrt.
STG_E_INVALIDFUNCTION	Die Sperrung wird überhaupt nicht unterstützt, oder der spezifische Typ der angeforderten Sperre wird nicht unterstützt.
STG_E_ACCESSDENIED	Zugriff verweigert, weil der Aufrufer über unzureichende Berechtigungen verfügt oder ein anderer Aufrufer die Datei geöffnet und gesperrt hat.
STG_E_LOCKVIOLATION	Zugriff verweigert, da die Datei bei einem anderen Aufrufer geöffnet und gesperrt ist.
STG_E_INVALIDHANDLE	Eine zugrunde liegende Datei wurde vorzeitig geschlossen, oder die richtige Diskette wurde durch eine ungültige datei ersetzt.

Hinweise

ILockBytes::LockRegion schränkt den Zugriff auf den angegebenen Bytebereich ein. Sobald eine Region gesperrt ist, müssen andere Versuche, Zugriff auf den eingeschränkten Bereich zu erhalten, mit dem STG_E_ACCESSDENIED Fehler fehlschlagen.

Der Bytebereich kann über das aktuelle Ende des Bytearrays hinaus reichen. Das Sperren über das Ende eines Arrays hinaus ist als Kommunikationsmethode zwischen verschiedenen Instanzen des Bytearrayobjekts nützlich, ohne daten zu ändern, die tatsächlich Teil des Bytearrays sind. Beispielsweise könnte eine Implementierung von ILockBytes für zusammengesetzte Dateien davon abhängen, dass das Sperren am aktuellen Ende des Arrays als Mittel zur Zugriffssteuerung über bestimmte gesperrte Regionen verwendet wird, um derzeit erteilte Berechtigungen anzugeben.

Der dwLockType-Parameter gibt einen von drei Sperrtypen an, wobei Werte aus der LOCKTYPE-Enumeration verwendet werden. Die Typen sind wie folgt: Sperren, um andere Autoren auszuschließen, Sperren, um andere Leser oder Autoren auszuschließen, und Sperren, die es nur einem Anforderer ermöglicht, eine Sperre für den angegebenen Bereich zu erhalten. Dieser dritte Sperrtyp ist normalerweise ein Alias für einen der beiden anderen Sperrtypen und ermöglicht es einem Implementer, auch anderes Verhalten hinzuzufügen. Ein angegebenes Bytearray kann einen der ersten beiden Typen oder beide unterstützen.

Um die von einer bestimmten ILockBytes-Implementierung unterstützten Sperrtypen zu ermitteln, können Sie das grfLocksSupported-Element der STATSTG-Struktur untersuchen, das durch einen Aufruf von ILockBytes::Stat zurückgegeben wird.

Jede mit ILockBytes::LockRegion gesperrte Region muss später explizit entsperrt werden, indem ILockBytes::UnlockRegion mit genau den gleichen Werten für die Parameter libOffset, cb und dwLockType aufgerufen wird. Die Region muss entsperrt werden, bevor der Stream freigegeben wird. Zwei angrenzende Regionen können nicht separat gesperrt und dann mit einem einzelnen Entsperrungsaufruf entsperrt werden.

Hinweise für Anrufer

Da der unterstützte Sperrtyp optional ist und in verschiedenen Implementierungen von ILockBytes variieren kann, müssen Sie Code bereitstellen, um den STG_E_INVALIDFUNCTION-Fehler zu beheben.

Hinweise zu Implementierern

Die Unterstützung für diese Methode hängt davon ab, wie das Speicherobjekt verwendet wird, das auf der ILockBytes-Implementierung basiert. Wenn Sie wissen, dass nur ein Speicherobjekt zu einem bestimmten Zeitpunkt auf dem Speichergerät geöffnet werden kann, das dem Bytearray zugrunde liegt, muss Ihre ILockBytes-Implementierung die Sperrung nicht unterstützen. Wenn jedoch mehrere gleichzeitige Öffnungen eines Speicherobjekts möglich sind, ist eine Regionssperre erforderlich, um sie zu koordinieren.

Eine LockRegion-Implementierung kann alle, einige oder keinen der Sperrtypen unterstützen. Für nicht unterstützte Sperrtypen sollte die Implementierung STG_E_INVALIDFUNCTION zurückgeben.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	objidl.h
Bibliothek	Uuid.lib
DLL	Ole32.dll