MCI CONNECTION

This message requests the device ID of a connected device instance. An alias also can be assigned to the connected device to facilitate the sending of string commands to that device.

Syntax

param1
ULONG ulParam1; /* Flags for connection operation. */

param2
PMCI_CONNECTION_PARMS pParam2; /* Pointer to the MCI_CONNECTION_PARMS data 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_QUERY_CONNECTION Indicates that the media driver must return the device ID of the connected device in the usToDeviceID field. The **MCI_CONNECTOR_TYPE** and **MCI_CONNECTOR_INDEX** flags specify parameters that identify the desired connector. Once the device ID is obtained, an application can send messages directly to the connected device to obtain advanced functionality not directly provided by the original device. If no connection exists, **MCIERR_NO_CONNECTION** is returned.
• MCI_CONNECTOR_TYPE Indicates that the ulConnectorType field specifies a connector type for the primary device. When this flag is used, the ulConnectorIndex field is interpreted as a relative index rather than an absolute index. The following connector types are currently defined:

• **MCI_MIDI_STREAM_CONNECTOR** Digital input or output for the sequencer device. This data typically is streamed to an amplifier mixer device.
• **MCI_CD_STREAM_CONNECTOR** Digital output for a CD audio device capable of reading the data directly off a disc. The data typically is streamed to an amplifier mixer device.
• **MCI_WAVE_STREAM_CONNECTOR** Digital input or output for the waveform audio device. The data typically is streamed to an amplifier mixer device.
• **MCI_XA_STREAM_CONNECTOR** Digital output for the CD XA device. The data typically is streamed to an amplifier mixer device.
• **MCI_AMP_STREAM_CONNECTOR** Digital input or output for an amplifier mixer device.
• **MCI_HEADPHONES_CONNECTOR** The connector on the device that is typically used to attach headphones to the device.
• **MCI_SPEAKERS_CONNECTOR** The connector on the device that is typically used to attach speakers to the device.
• **MCI_MICROPHONE_CONNECTOR** The connector on the device that is typically used to attach a microphone to the device.
• **MCI_LINE_IN_CONNECTOR** The connector on the device that is typically used to provide line level input to the device.
• **MCI_LINE_OUT_CONNECTOR** The connector on the device that is typically used to provide line level output from the device.
• **MCI_VIDEO_IN_CONNECTOR** The connector on the device that is typically used to provide video input to the device.
• **MCI_VIDEO_OUT_CONNECTOR** The connector on the device that is typically used to provide video output from the device.
• **MCI_UNIVERSAL_CONNECTOR** A connector on a device that does not fall into any of the other categories. This connector can be used to access device-dependent function. The manufacturer of the device should define the exact use of this connector.

• MCI_CONNECTOR_INDEX Indicates that the ulConnectorIndex field contains the connector index for the primary device. If this flag is not specified then an index of 1 is assumed.
• MCI_CONNECTOR_ALIAS Indicates that the pszAlias field contains an alias for the device instance connected to the specified connector. If the alias already exists for another device, the error **MCIERR_DUPLICATE_ALIAS** is returned. If the connected to device already has an alias, the error **MCIERR_CANNOT_ADD_ALIAS** is returned. The primary purpose of this function is to permit access to connected devices through the string interface.

pParam2 (PMCI_CONNECTION_PARMS) - input

A pointer to the MCI_CONNECTION_PARMS data structure.

Returns

rc (ULONG) - returns

Return codes indicating success or type of failure:

• MCIERR_SUCCESS The function is successful.
• MCIERR_ALREADY_CONNECTED A connection already exists for the specified connector.
• MCIERR_INVALID_CONNECTION Connection between the specified connection types is invalid.
• MCIERR_CANNOT_ADD_ALIAS The alias was not added.
• MCIERR_DUPLICATE_ALIAS The alias already exists.
• MCIERR_NO_CONNECTION No connection exists for the queried connector.
• MCIERR_INVALID_DEVICE_ID The device ID is not valid.
• MCIERR_INVALID_DEVICE_ORDINAL The device ordinal given is invalid.
• MCIERR_MISSING_FLAG A required flag is missing.
• MCIERR_UNSUPPORTED_CONN_TYPE This device does not support the given connector type.
• MCIERR_INVALID_CONNECTOR_TYPE The given connector type is invalid.
• MCIERR_INVALID_CONNECTOR_INDEX Invalid connector index given.
• MCIERR_MISSING_PARAMETER Required parameter is missing.
• MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together.

Remarks

It is recommended that all applications refer to connectors using the **MCI_CONNECTOR_TYPE** flag. This provides device independence from differences in connector numbering for various hardware devices. Additionally, the **MCI_CONNECTOR_INDEX** flag can be used to address different connectors of the same type.

If only the **MCI_CONNECTOR_INDEX** flag is used, the referenced connector is device dependent. The connector type of a particular connector index, as well as the number of connectors, can be retrieved using the **MCI_CONNECTORINFO** or **MCI_SYSINFO** messages.

For a list of connector types which are supported by various device types, see the **Remarks** section for MCI_CONNECTORINFO.

Example Code

    USHORT usWaveDeviceID;
    USHORT usAmpDeviceID;
    MCI_CONNECTION_PARMS connectionparms;

    connectionparms.ulConnectorType = MCI_WAVE_STREAM_CONNECTOR;

                                         /* Get the Amp/Mixer device ID */

    mciSendCommand ( usWaveDeviceID,      /* WaveAudio device ID */
      MCI_CONNECTION,                    /* CONNECTION message  */
      MCI_QUERY_CONNECTION | MCI_WAIT,   /* Flags for this msg  */
      (PVOID) &connectionparms,          /* Data structure      */
      0 );                               /* No user parameter   */

    usAmpDeviceID = connectionparms.usToDeviceID;
                                         /* Device ID amp mixer */

Related Methods

• MCI_CONNECTOR
• MCI_CONNECTORINFO