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

Artículo
03/05/2024

El método LockRegion restringe el acceso a un intervalo de bytes especificado en la matriz de bytes.

Sintaxis

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

Parámetros

[in] libOffset

Especifica el desplazamiento de bytes para el principio del intervalo.

[in] cb

Especifica, en bytes, la longitud del intervalo que se va a restringir.

[in] dwLockType

Especifica el tipo de restricciones que se solicitan al acceder al intervalo. Este parámetro usa uno de los valores de la enumeración LOCKTYPE .

Valor devuelto

Este método puede devolver uno de estos valores.

Código devuelto	Descripción
S_OK	El intervalo especificado de bytes se bloqueó.
STG_E_INVALIDFUNCTION	No se admite el bloqueo en absoluto o no se admite el tipo específico de bloqueo solicitado.
STG_E_ACCESSDENIED	Acceso denegado porque el autor de la llamada no tiene permiso suficiente u otro autor de la llamada tiene el archivo abierto y bloqueado.
STG_E_LOCKVIOLATION	Acceso denegado porque otro llamador tiene el archivo abierto y bloqueado.
STG_E_INVALIDHANDLE	Un archivo subyacente se ha cerrado prematuramente o el disco de disquete correcto se ha reemplazado por uno no válido.

Comentarios

ILockBytes::LockRegion restringe el acceso al intervalo de bytes especificado. Una vez bloqueada una región, los intentos de otros usuarios para obtener acceso al intervalo restringido deben producir un error de STG_E_ACCESSDENIED.

El intervalo de bytes puede extenderse más allá del final actual de la matriz de bytes. El bloqueo más allá del final de una matriz es útil como método de comunicación entre diferentes instancias del objeto de matriz de bytes sin cambiar los datos que realmente forman parte de la matriz de bytes. Por ejemplo, una implementación de ILockBytes para archivos compuestos podría depender del bloqueo pasado el final actual de la matriz como medio de control de acceso, usando regiones bloqueadas específicas para indicar los permisos concedidos actualmente.

El parámetro dwLockType especifica uno de los tres tipos de bloqueo, utilizando valores de la enumeración LOCKTYPE . Los tipos son los siguientes: bloqueo para excluir otros escritores, bloqueo para excluir otros lectores o escritores, y bloqueo que permite que solo un solicitante obtenga un bloqueo en el intervalo especificado. Este tercer tipo de bloqueo suele ser un alias para uno de los otros dos tipos de bloqueo y permite que un implementador agregue también otro comportamiento. Una matriz de bytes determinada podría admitir cualquiera de los dos primeros tipos, o ambos.

Para determinar los tipos de bloqueo admitidos por una implementación de ILockBytes determinada, puede examinar el miembro grfLocksSupported de la estructura STATSTG devuelta por una llamada a ILockBytes::Stat.

Cualquier región bloqueada con ILockBytes::LockRegion debe desbloquearse explícitamente llamando a ILockBytes::UnlockRegion con exactamente los mismos valores para los parámetros libOffset, cb y dwLockType . La región debe desbloquearse antes de que se libere la secuencia. Dos regiones adyacentes no se pueden bloquear por separado y, a continuación, desbloquear con una sola llamada de desbloqueo.

Notas a los autores de llamadas

Dado que el tipo de bloqueo admitido es opcional y puede variar en diferentes implementaciones de ILockBytes, debe proporcionar código para tratar el error de STG_E_INVALIDFUNCTION.

Notas para los implementadores

La compatibilidad con este método depende de cómo se use el objeto de almacenamiento basado en la implementación de ILockBytes . Si sabe que solo se puede abrir un objeto de almacenamiento en un momento dado en el dispositivo de almacenamiento que subyace a la matriz de bytes, la implementación de ILockBytes no necesita admitir el bloqueo. Sin embargo, si es posible realizar varias aperturas simultáneas de un objeto de almacenamiento, se necesita el bloqueo de región para coordinarlos.

Una implementación lockRegion puede optar por admitir todos, algunos o ninguno de los tipos de bloqueo. Para los tipos de bloqueo no admitidos, la implementación debe devolver STG_E_INVALIDFUNCTION.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows 2000 Server [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	objidl.h
Library	Uuid.lib
Archivo DLL	Ole32.dll