IDiscRecorder2::AcquireExclusiveAccess method (imapi2.h)

Article
10/13/2021

Acquires exclusive access to the device.

Syntax

HRESULT AcquireExclusiveAccess(
  [in] VARIANT_BOOL force,
  [in] BSTR         __MIDL__IDiscRecorder20000
);

Parameters

[in] force

Set to VARIANT_TRUE to gain exclusive access to the volume whether the file system volume can or cannot be dismounted. If VARIANT_FALSE, this method gains exclusive access only when there is no file system mounted on the volume.

[in] __MIDL__IDiscRecorder20000

String that contains the friendly name of the client application requesting exclusive access. Cannot be NULL or a zero-length string. The string must conform to the restrictions for the IOCTL_CDROM_EXCLUSIVE_ACCESS control code found in the DDK.

Return value

S_OK is returned on success, but other success codes may be returned as a result of implementation. The following error codes are commonly returned on operation failure, but do not represent the only possible error values:

Return code	Description
E_FAIL	Unspecified failure. Value: 0x80004005
E_ACCESS_DENIED	The device is currently being used by another application. Value: 0x80070005
E_INVALIDARG	One or more arguments are not valid. Value: 0x80070057
E_OUTOFMEMORY	Failed to allocate the required memory. Value: 0x8007000E
E_IMAPI_RECORDER_COMMAND_TIMEOUT	The device failed to accept the command within the timeout period. This may be caused by the device having entered an inconsistent state, or the timeout value for the command may need to be increased. Value: 0xC0AA020D
HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE)	The specified handle is invalid. Value: 6
HRESULT_FROM_WIN32(ERROR_DEV_NOT_EXIST)	The specified network resource or device is no longer available. Value: 55
E_IMAPI_RECORDER_LOCKED	The device associated with this recorder during the last operation has been exclusively locked, causing this operation to fail. Value: 0xC0AA0210

Remarks

You should not have to call this method to acquire the lock yourself because the write operations, such as IDiscFormat2Data::Write, acquires the lock for you.

Each recorder has a lock count. The first call to a recorder locks the device for exclusive access. Applications can use the AcquireExclusiveAccess method multiple times to apply multiple locks on a device. Each call increments the lock count by one.

When unlocking a recorder, the lock count must reach zero to free the device for other clients. Calling the IDiscRecorder2::ReleaseExclusiveAccess method decrements the lock count by one.

An equal number of calls to the AcquireExclusiveAccess and ReleaseExclusiveAccess methods are needed to free a device. Should the application exit unexpectedly or crash while holding the exclusive access, the CDROM.SYS driver will automatically release these exclusive locks.

If the device is already locked, you can call IDiscRecorder2::get_ExclusiveAccessOwner to retrieve the name of the client application that currently has exclusive access.

Requirements

Requirement	Value
Minimum supported client	Windows Vista, Windows XP with SP2 [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	imapi2.h