MCI_SETTUNER

This message causes the digital video media control device (MCD) to change the frequency that the tuner device is tuned to.

Syntax

param1
ULONG ulParam1; /* Message flags. */

param2
PMCI_DGV_TUNER_PARMS pParam2; /* Pointer to the MCI_DGV_TUNER_PARMS structure. */

Parameters

ulParam1 (ULONG) - input

The following flags can be used:

MCI_NOTIFY Posts a notification message when the action completes.
MCI_WAIT Does not return control until the action is completed.
MCI_DGV_FREQUENCY Sets the frequency to the value in the `ulFrequency` field. This overrides channel, region, and fine-tuning settings.
MCI_DGV_TV_CHANNEL Sets the channel to the value in the `ulTVChannel` field.
MCI_DGV_REGION Sets the region to the string pointed to by `pszRegion`.
MCI_DGV_FINETUNE_PLUS Indicates the `lFineTune` value is positive.
MCI_DGV_FINETUNE_MINUS Indicates the `lFineTune` value is negative (the value in the field is multiplied by -1).

pParam2 (PMCI_DGV_TUNER_PARMS) - input: A pointer to the MCI_DGV_TUNER_PARMS data structure.

Returns

rc (ULONG) - returns

MCIERR_SUCCESS MMPM/2 command completed successfully.
MCIERR_TUNER_NO_HW Device has no tuner support.
MCIERR_TUNER_CHANNEL_SKIPPED Channel is skipped in the current region.
MCIERR_TUNER_CHANNEL_TOO_HIGH / TOO_LOW Channel is out of range for the region.
MCIERR_INVALID_REGION Region file is missing or invalid.
MCIERR_TUNER_REGION_NOT_SET A channel was specified but no region has been set.
MCIERR_FLAGS_NOT_COMPATIBLE Flags (like PLUS and MINUS fine-tuning) cannot be used together.

Remarks

**Frequency Calculation:** Frequency is typically calculated using the combination of Region, Channel, and Fine-tuning.
**Persistence:** Channels and regions are remembered by the driver. However, fine-tuning must be reset whenever the channel or region changes.
**Regions:** Region strings must correspond to a `.RGN` file in the `\MMOS2\REGION` directory. Examples include `USA`, `USACATV`, `CCIR` (Western Europe), and `JAPAN`.
**Overrides:** If `MCI_DGV_FREQUENCY` is used, it temporarily overrides the channel/region settings. The next call without the frequency flag will revert the tuner to the previously active channel.
**Default Channel:** If a region is set without a specific channel, the driver defaults to the lowest available channel for that region.

Example Code

The following example sets a specific frequency for a tuner device.

USHORT               usDeviceID;
MCI_DGV_TUNER_PARMS  settuner;
ULONG                ulError;

settuner.ulFrequency = 24725; /* Frequency for channel 29 in USA Cable TV */
settuner.pszRegion   = NULL;  /* Not needed for direct frequency input */
settuner.ulTVChannel = 0;     
settuner.lFineTune   = 0;     

ulError = mciSendCommand ( usDeviceID,
                           MCI_SETTUNER,
                           MCI_WAIT | MCI_DGV_FREQUENCY,
                           (PVOID)&settuner,
                           0);

Related Messages

MCI_GETTUNER
MCI_SET