MCI ACQUIREDEVICE

This message requests that the given device instance be made active. It is also used to request either exclusive or exclusive instance rights for this instance.

Syntax

param1
ULONG ulParam1; /* Flags for device acquisition. */

param2
PMCI_GENERIC_PARMS pParam2; /* Pointer to the default MCI parameter structure. */

Parameters

ulParam1 (ULONG) - input

This parameter can contain any of the following flags:

• MCI_NOTIFY A notification message will be posted to the window specified in the hwndCallback parameter of the data structure pointed to by the pParam2 parameter. The notification will be posted when the action indicated by this message is completed or when an error occurs.
• MCI_WAIT Control is not to be returned until the action indicated by this message is completed or an error occurs.
• MCI_ACQUIRE_QUEUE An **MCI_ACQUIREDEVICE** message is queued and executed as soon as device resources are available. If the request can be satisfied immediately, then it is not queued. If an **MCI_ACQUIREDEVICE** message is queued and an MCI_RELEASEDEVICE or MCI_CLOSE message is sent for that instance, the queued **MCI_ACQUIREDEVICE** message is cancelled.
• MCI_EXCLUSIVE Resources are to be exclusively allocated for the device instance. Exclusive use of resources can be released with an MCI_RELEASEDEVICE message.
• MCI_EXCLUSIVE_INSTANCE Acquires the device instance for exclusive use without acquiring the entire device resource for exclusive use. This flag locks the device instance and prevents it from being made inactive until the application sends an MCI_RELEASEDEVICE or MCI_CLOSE message. The MCI_RELEASEDEVICE puts the instance back into the fully shareable state.

pParam2 (PMCI_GENERIC_PARMS) - input

A pointer to the default media control interface parameter data structure.

Returns

rc (ULONG) - returns

Return codes indicating success or type of failure:

• MCIERR_SUCCESS The function is successful.
• MCIERR_INVALID_DEVICE_ID The device ID is not valid.
• MCIERR_DEVICE_LOCKED The device is acquired for exclusive use.
• MCIERR_INVALID_FLAG Flag is invalid (ulParam1).
• MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together.
• MCIERR_INVALID_CALLBACK_HANDLE The callback handle given is not correct.

Remarks

The application can specify exclusive access, which inhibits other applications from acquiring use of the device until released by the owning application.

When a device is opened by an application, the physical device resource is acquired automatically by the newly created device instance. If the device instance subsequently loses use of the physical resource, it can regain use later by issuing **MCI_ACQUIREDEVICE**. This message enables applications to participate in a device-sharing scheme, driven by WM_ACTIVATE message processing, wherein the use of physical devices generally is granted to the application with which the user is interacting by the application issuing **MCI_ACQUIREDEVICE**.

If a defined device instance loses use of the physical device to other device instances, that use is regained when the other device instances are closed, even if **MCI_ACQUIREDEVICE** is not issued.

When a process acquires use of a shared device that currently is in use by another process, the device instance is saved for the previous process.

Applications receive the MM_MCIPASSDEVICE message whenever they gain or lose use of a device. Use of a device is not obtained until the MM_MCIPASSDEVICE message is received. This message is posted (by way of WinPostMsg) to the window handle specified in the hwndCallback field on the MCI_OPEN message. If an invalid or no hwndCallback parameter is provided on the MCI_OPEN message, then no MM_MCIPASSDEVICE messages are received.

If the device has been acquired exclusively by another device instance, the function returns **MCIERR_DEVICE_LOCKED**.

Example Code

 MCI_GENERIC_PARMS mciGenericParms;       /* Info data structure for cmd */
 USHORT usDeviceID;                       /* Device ID                   */
 HWND hwndMyWindow;                       /* Handle to the PM window     */
 MPARAM mp1;                             /* Message parameter passed    */
                                         /* on window procedure message */

             /* Assign hwndCallback the handle to the PM window routine */

    mciGenericParms.hwndCallback = hwndMyWindow;


             /* Acquire the device if our window is being activated. */

    if ((BOOL)mp1)
      {
       mciSendCommand(usDeviceID,           /* Requested device          */
                      MCI_ACQUIREDEVICE,    /* MCI acquire device message */
                      MCI_NOTIFY,           /* Flags for this message     */
                      (PVOID)&mciGenericParms,
                                            /* Parameter data structure  */
                      0);                   /* No user parameter for     */
                                            /* notification message      */
      }

Related Methods

• MCI_OPEN
• MCI_RELEASEDEVICE