Metodo ILockBytes::LockRegion (objidl.h)

Articolo
08/25/2023

Il metodo LockRegion limita l'accesso a un intervallo specificato di byte nella matrice di byte.

Sintassi

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

Parametri

[in] libOffset

Specifica l'offset di byte per l'inizio dell'intervallo.

[in] cb

Specifica, in byte, la lunghezza dell'intervallo da limitare.

[in] dwLockType

Specifica il tipo di restrizioni richieste per l'accesso all'intervallo. Questo parametro usa uno dei valori dell'enumerazione LOCKTYPE .

Valore restituito

Questo metodo può restituire uno di questi valori.

Codice restituito	Descrizione
S_OK	L'intervallo di byte specificato è stato bloccato.
STG_E_INVALIDFUNCTION	Il blocco non è supportato o il tipo specifico di blocco richiesto non è supportato.
STG_E_ACCESSDENIED	Accesso negato perché il chiamante non dispone di autorizzazioni sufficienti o un altro chiamante ha il file aperto e bloccato.
STG_E_LOCKVIOLATION	Accesso negato perché un altro chiamante ha il file aperto e bloccato.
STG_E_INVALIDHANDLE	Un file sottostante è stato chiuso prematuramente o il disco floppy corretto è stato sostituito da uno non valido.

Commenti

ILockBytes::LockRegion limita l'accesso all'intervallo di byte specificato. Una volta bloccata un'area, i tentativi da parte di altri utenti di accedere all'intervallo con restrizioni devono avere esito negativo con l'errore STG_E_ACCESSDENIED.

L'intervallo di byte può estendersi oltre la fine corrente della matrice di byte. Il blocco oltre la fine di una matrice è utile come metodo di comunicazione tra istanze diverse dell'oggetto matrice di byte senza modificare i dati che fanno effettivamente parte della matrice di byte. Ad esempio, un'implementazione di ILockBytes per i file composti può basarsi sul blocco oltre la fine corrente della matrice come mezzo di controllo di accesso, usando aree bloccate specifiche per indicare le autorizzazioni attualmente concesse.

Il parametro dwLockType specifica uno dei tre tipi di blocco, usando i valori dell'enumerazione LOCKTYPE . I tipi sono i seguenti: blocco per escludere altri writer, blocco per escludere altri lettori o writer e blocco che consente a un solo richiedente di ottenere un blocco sull'intervallo specificato. Questo terzo tipo di blocco è in genere un alias per uno degli altri due tipi di blocco e consente a un implementatore di aggiungere anche altri comportamenti. Una determinata matrice di byte può supportare uno dei primi due tipi o entrambi.

Per determinare i tipi di blocco supportati da un'implementazione ILockBytes specifica, è possibile esaminare il membro grfLocksSupported della struttura STATSTG restituito da una chiamata a ILockBytes::Stat.

Qualsiasi area bloccata con ILockBytes::LockRegion deve essere sbloccata in un secondo momento chiamando ILockBytes::UnlockRegion con esattamente gli stessi valori per i parametri libOffset, cb e dwLockType . L'area deve essere sbloccata prima del rilascio del flusso. Due aree adiacenti non possono essere bloccate separatamente e quindi sbloccate con una singola chiamata di sblocco.

Note ai chiamanti

Poiché il tipo di blocco supportato è facoltativo e può variare in implementazioni diverse di ILockBytes, è necessario fornire il codice per gestire l'errore STG_E_INVALIDFUNCTION.

Note per gli implementatori

Il supporto per questo metodo dipende dalla modalità di utilizzo dell'oggetto di archiviazione basato sull'implementazione ILockBytes . Se si sa che è possibile aprire un solo oggetto di archiviazione in qualsiasi momento nel dispositivo di archiviazione sottostante la matrice di byte, l'implementazione ILockBytes non deve supportare il blocco. Tuttavia, se sono possibili più aperture simultanee di un oggetto di archiviazione, è necessario bloccare l'area per coordinarle.

Un'implementazione lockRegion può scegliere di supportare tutti, alcuni o nessuno dei tipi di blocco. Per i tipi di blocco non supportati, l'implementazione deve restituire STG_E_INVALIDFUNCTION.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [app desktop \| App UWP]
Server minimo supportato	Windows 2000 Server [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	objidl.h
Libreria	Uuid.lib
DLL	Ole32.dll