Share via

3.2.4.19 Application Requests Locking of an Array of Byte Ranges

  • Article

The application provides:

  • A handle to the Open identifying a file or named pipe.

  • An array of byte ranges to lock. For each range, the application provides:

    • A starting offset, in bytes.

    • A length, in bytes.

    • Whether the range is to be locked exclusively, or shared.

    • Whether the lock request is to wait until the lock can be acquired to return, or whether it is to fail immediately if the range is locked by another Open.

If the handle is invalid, or if no Open referenced by the handle is found, the client MUST return an implementation-specific error code. If the handle is valid and Open is found, the client MUST proceed as follows.

For the specified Open, the client MUST select a connection as specified in section 3.2.4.1.7. If no connection is available, the client MUST fail the lock operation.

Otherwise, the client initializes an SMB2 LOCK Request following the syntax specified in section 2.2.26. The SMB2 header MUST be initialized as follows:

  • The Command field is set to SMB2 LOCK.

  • The MessageId field is set as specified in section 3.2.4.1.3.

  • The SessionId field is set to Open.TreeConnect.Session.SessionId.

  • The TreeId field is set to Open.TreeConnect.TreeConnectId.

The SMB2 LOCK Request MUST be initialized as follows:

  • The FileId field is set to Open.FileId.

  • The LockCount field is set to the number of byte ranges being locked.

  • For each range being locked, the client creates an SMB2_LOCK_ELEMENT structure and places it in the Locks[] array of the request, setting the following values:

    • The offset is set to the offset of the range being locked.

    • The length is set to the length of the range to be locked.

    • If the lock is to be acquired shared, the client sets the SMB2_LOCKFLAG_SHARED_LOCK bit in the Flags field.

    • If the lock is to be acquired exclusively, the client sets the SMB2_LOCKFLAG_EXCLUSIVE_LOCK bit in the Flags field.

    • If the lock is to fail immediately if the range is already locked, the client sets the SMB2_LOCKFLAG_FAIL_IMMEDIATELY bit in the Flags field. If the Locks[] array has more than one element, the client MUST set SMB2_LOCKFLAG_FAIL_IMMEDIATELY.

If any of the Booleans Open.ResilientHandle, Open.IsPersistent, or Connection.SupportsMultiChannel is TRUE, the client MUST do the following:

  • Scan through Open.OperationBuckets and find an entry with its Free field set to TRUE. If no such element could be found, an implementation-specific error MUST be returned to the application.

  • Set the Free element of the chosen entry to FALSE.

  • The fields of the SMB2 lock request MUST be set as follows:

    • LockSequenceIndex is set to the index value of the chosen entry.

    • LockSequenceNumber is set to the SequenceNumber of the chosen entry.

Otherwise the client MUST set LockSequenceIndex and LockSequenceNumber to 0.

The request MUST be sent to the server.