This message allows applications to create and delete groups of device instances. Group commands allow applications to control several devices using a single command.

ulParam1 (ULONG)

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.

Note: The MCI_GROUP message supports several flags, some of which can be used in combination with each other. Valid combinations are described in the flag descriptions below. An invalid combination results in the MCIERR_FLAGS_NOT_COMPATIBLE error return code.

MCI_GROUP_MAKE
This flag specifies the creation of a group. MCI_GROUP_MAKE ties several instances together such that a single command sent to the group is actually sent to each instance in the group. This flag can be combined with any of the other group flags except MCI_GROUP_DELETE, in which case an MCIERR_FLAGS_NOT_COMPATIBLE error is returned. Instances must have been previously opened but these instances can be in any mode (such as playing, stopped, paused, and so forth) for this message to be successful. An array of device IDs is provided by the application in the paulDeviceID field of the MCI_GROUP_PARMS data structure. The number of these IDs is provided by the application in the ulNumDevices field. If one or more device IDs are invalid, then the MCIERR_INVALID_DEVICE_ID error is returned.

If a device ID or alias references an instance already in another group, the MCIERR_ID_ALREADY_IN_GROUP error message is returned.

MCI_GROUP_DELETE
This flag deletes an existing group by disassociating the instances from each other. None of the device instances in the group are closed just the group reference. None of the other flags can be combined with MCI_GROUP_DELETE since the only information required by this flag is a group ID. If any other flags are specified, an MCIERR_FLAGS_NOT_COMPATIBLE error is returned. The MCIERR_INVALID_GROUP_ID error is returned if an invalid ID is passed.
MCI_GROUP_ALIAS
This flag specifies that the pszGroupAlias field contains an alias for the group. This flag is valid only with the MCI_GROUP_MAKE flag. The given alias can then be used to refer to the group from the mciSendString interface. If the alias is already in use, the MCIERR_DUPLICATE_ALIAS error is returned.
MCI_GROUP_NOPIECEMEAL
This flag specifies that the group is to be treated as a whole entity rather than a group of separate parts. If one of the parts (instances) becomes inactive, then all the instances in the group become inactive. This flag is only valid with the MCI_GROUP_MAKE flag. If a group is created with the MCI_GROUP_NOPIECEMEAL flag specified and one or more of the device instances is already inactive, then the entire group (all device instances) will be made inactive.

pParam2 (PMCI_GROUP_PARMS)

A pointer to the MCI_GROUP_PARMS structure.

rc (ULONG)

Return codes indicating success or type of failure:

MCIERR_SUCCESS

If the function succeeds, 0 is returned.
MCIERR_DUPLICATE_ALIAS
An alias is already in use.
MCIERR_GROUP_COMMAND
An unsupported GROUP command is sent to a group.
MCIERR_FLAGS_NOT_COMPATIBLE
Flags cannot be used together.
MCIERR_ID_ALREADY_IN_GROUP
A device ID or alias references an instance already in another group.
MCIERR_INVALID_GROUP_ID
An invalid group ID is passed.

---

[Back] [Next]