MCI_GROUP
This message allows applications to create and delete groups of device instances. Grouping allows a single command to be sent to the group ID, which the system then broadcasts to every device instance within that group.
Syntax
param1 ULONG ulParam1; /* Grouping flags. */ param2 PMCI_GROUP_PARMS pParam2; /* Pointer to the MCI_GROUP_PARMS structure. */
Parameters
- ulParam1 (ULONG) - input
- This parameter can contain any of the following flags:
- MCI_NOTIFY Posts a notification message when the action completes.
- MCI_WAIT Does not return control until the grouping action is completed.
- MCI_GROUP_MAKE Creates a new group. Requires an array of device IDs in the paulDeviceID field and the count in ulNumDevices.
- MCI_GROUP_DELETE Deletes an existing group. Disassociates the instances but does not close them. Only the group ID is required.
- MCI_GROUP_ALIAS Specifies that pszGroupAlias contains a string alias for the group (valid only with MCI_GROUP_MAKE).
- MCI_GROUP_NOPIECEMEAL Treats the group as a single entity. If one device in the group becomes inactive, the entire group is treated as inactive.
- pParam2 (PMCI_GROUP_PARMS) - input
- A pointer to the MCI_GROUP_PARMS structure. On success with MCI_GROUP_MAKE, the new group ID is returned in the usGroupID field.
Returns
- rc (ULONG) - returns
-
- MCIERR_SUCCESS Group created or deleted successfully.
- MCIERR_DUPLICATE_ALIAS The specified alias is already in use.
- MCIERR_ID_ALREADY_IN_GROUP One of the device IDs is already a member of another group.
- MCIERR_INVALID_GROUP_ID The provided group ID is not valid.
- MCIERR_FLAGS_NOT_COMPATIBLE Incompatible flags were specified (e.g., combining MAKE and DELETE).
Remarks
Once a group is created, sending a command to the Group ID effectively sends it to all members. Supported commands for groups include:
- MCI_PLAY, MCI_STOP, MCI_PAUSE, MCI_RESUME
- MCI_RECORD, MCI_SEEK, MCI_CUE, MCI_SET
- MCI_ACQUIREDEVICE, MCI_RELEASEDEVICE, MCI_CLOSE
Example Code
The following code illustrates how to combine four previously opened devices into a single group.
MCI_GROUP_PARMS mciGroupParameters;
ULONG paulDeviceIDs[4];
ULONG ulRC;
ULONG ulGroupFlags;
/* Assume paulDeviceIDs[0...3] are filled with valid device IDs from mciSendCommand(MCI_OPEN) */
ulGroupFlags = MCI_GROUP_MAKE; /* Flag to create a group */
mciGroupParameters.hwndCallback = (HWND) NULL;
mciGroupParameters.usGroupID = 0; /* Will be filled by the system */
mciGroupParameters.pszGroupAlias = (PSZ) NULL;
mciGroupParameters.ulNumDevices = 4; /* Grouping 4 devices */
mciGroupParameters.paulDeviceID = paulDeviceIDs;
ulRC = mciSendCommand(
0, /* Use 0 as the ID when creating a group */
MCI_GROUP, /* Message type */
ulGroupFlags, /* Flags defined above */
(PVOID)&mciGroupParameters, /* Parameter structure */
0 ); /* No user parameter */
if (!ulRC) {
/* The new Group ID is now in mciGroupParameters.usGroupID */
}