View source for MCI ACQUIREDEVICE

{{DISPLAYTITLE: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==
<PRE>
param1
ULONG ulParam1; /* Flags for device acquisition. */

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

==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==
<PRE>
 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      */
      }
</PRE>

== Related Methods==
* [[MCI_OPEN]]
* [[MCI_RELEASEDEVICE]]

[[Category:MCI]]