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

Artigo
08/25/2023

O método LockRegion restringe o acesso a um intervalo especificado de bytes na matriz de bytes.

Sintaxe

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

Parâmetros

[in] libOffset

Especifica o deslocamento de bytes para o início do intervalo.

[in] cb

Especifica, em bytes, o comprimento do intervalo a ser restrito.

[in] dwLockType

Especifica o tipo de restrições que estão sendo solicitadas ao acessar o intervalo. Esse parâmetro usa um dos valores da enumeração LOCKTYPE .

Retornar valor

Esse método pode retornar um desses valores.

Código de retorno	Descrição
S_OK	O intervalo de bytes especificado foi bloqueado.
STG_E_INVALIDFUNCTION	Não há suporte para bloqueio ou não há suporte para o tipo específico de bloqueio solicitado.
STG_E_ACCESSDENIED	Acesso negado porque o chamador não tem permissão suficiente ou outro chamador tem o arquivo aberto e bloqueado.
STG_E_LOCKVIOLATION	Acesso negado porque outro chamador tem o arquivo aberto e bloqueado.
STG_E_INVALIDHANDLE	Um arquivo subjacente foi fechado prematuramente ou o disquete correto foi substituído por um inválido.

Comentários

ILockBytes::LockRegion restringe o acesso ao intervalo de bytes especificado. Depois que uma região é bloqueada, as tentativas de outras pessoas de obter acesso ao intervalo restrito devem falhar com o erro STG_E_ACCESSDENIED.

O intervalo de bytes pode se estender além do final atual da matriz de bytes. Bloquear além do final de uma matriz é útil como um método de comunicação entre diferentes instâncias do objeto de matriz de bytes sem alterar dados que, na verdade, fazem parte da matriz de bytes. Por exemplo, uma implementação de ILockBytes para arquivos compostos pode depender do bloqueio após o final atual da matriz como um meio de controle de acesso, usando regiões bloqueadas específicas para indicar permissões concedidas no momento.

O parâmetro dwLockType especifica um dos três tipos de bloqueio, usando valores da enumeração LOCKTYPE . Os tipos são os seguintes: bloqueio para excluir outros gravadores, bloqueio para excluir outros leitores ou gravadores e bloqueio que permite que apenas um solicitante obtenha um bloqueio no intervalo determinado. Esse terceiro tipo de bloqueio geralmente é um alias para um dos outros dois tipos de bloqueio e permite que um implementador também adicione outro comportamento. Uma determinada matriz de bytes pode dar suporte a qualquer um dos dois primeiros tipos ou ambos.

Para determinar os tipos de bloqueio compatíveis com uma implementação de ILockBytes específica, você pode examinar o membro grfLocksSupported da estrutura STATSTG retornada por uma chamada para ILockBytes::Stat.

Qualquer região bloqueada com ILockBytes::LockRegion deve ser desbloqueada explicitamente chamando ILockBytes::UnlockRegion com exatamente os mesmos valores para os parâmetros libOffset, cb e dwLockType . A região deve ser desbloqueada antes que o fluxo seja liberado. Duas regiões adjacentes não podem ser bloqueadas separadamente e desbloqueadas com uma única chamada de desbloqueio.

Anotações aos Chamadores

Como o tipo de bloqueio com suporte é opcional e pode variar em diferentes implementações de ILockBytes, você deve fornecer código para lidar com o erro STG_E_INVALIDFUNCTION.

Observações aos implementadores

O suporte para esse método depende de como o objeto de armazenamento criado sobre a implementação ILockBytes é usado. Se você souber que apenas um objeto de armazenamento em um determinado momento pode ser aberto no dispositivo de armazenamento subjacente à matriz de bytes, a implementação do ILockBytes não precisará dar suporte ao bloqueio. No entanto, se várias aberturas simultâneas de um objeto de armazenamento forem possíveis, o bloqueio de região será necessário para coordená-las.

Uma implementação lockRegion pode optar por dar suporte a todos, alguns ou nenhum dos tipos de bloqueio. Para tipos de bloqueio sem suporte, a implementação deve retornar STG_E_INVALIDFUNCTION.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	objidl.h
Biblioteca	Uuid.lib
DLL	Ole32.dll