IAMExtDevice Interface

The IAMExtDevice interface is the base interface for controlling external devices. You can implement this interface to control numerous types of devices; however, the current Microsoft® DirectShow® implementation is specific to VCRs. The IAMExtDevice interface controls general settings of external hardware and is intended to be used in combination with the IAMExtTransport interface, which controls a VCR's more specific settings. You can also implement the IAMTimecodeReader, IAMTimecodeGenerator, and IAMTimecodeDisplay interfaces if your filter manages SMPTE (Society of Motion Picture and Television Engineers) timecode, and the external device has the appropriate features.

For a description of a sample filter that controls a VCR through DirectShow, see Vcrctrl Sample (VCR Control Filter).

Implement this interface when you want to build a filter or application that controls an external device, such as a VCR. Because this interface controls general information about a device, implement the IAMExtTransport interface in addition to control the external device's more specific properties.

An application can directly instantiate and control external devices, such as VCRs, but it is strongly recommended that you always instantiate these devices within the context of a filter graph, even if they are the only filters within the graph.

Use this interface when you want to add external device control to your application.

Applications should use the filter graph to enumerate the filters and then get the IAMExtDevice interface directly from the appropriate filter.

Hardware Requirements

To control an external VCR, certain hardware requirements are recommended. VCRs with an RS-422 serial interface require a special serial port card or an external RS-232-to-RS-422 adapter. In addition, for best performance, your computer should have a serial port card built with a 16,550 high-performance UART (Universal Asynchronous Receiver/Transmitter) to sustain higher baud rates, such as 38.4 baud.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IAMExtDevice methods Description

GetCapability Retrieves the capabilities of the external device.
get_ExternalDeviceID Retrieves the model number of the external device.
get_ExternalDeviceVersion Retrieves the version number of the external device's operating software.
put_DevicePort Specifies the communication port to which the external device is connected.
get_DevicePower Retrieves whether the external device's power mode is on, off, or standby.
put_DevicePower Sets the external device's power mode to on, off, or standby.
Calibrate Calibrates the external device's transport mechanism.
get_DevicePort Retrieves the communication port to which the external device is connected.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMExtDevice methods	Description
GetCapability	Retrieves the capabilities of the external device.
get_ExternalDeviceID	Retrieves the model number of the external device.
get_ExternalDeviceVersion	Retrieves the version number of the external device's operating software.
put_DevicePort	Specifies the communication port to which the external device is connected.
get_DevicePower	Retrieves whether the external device's power mode is on, off, or standby.
put_DevicePower	Sets the external device's power mode to on, off, or standby.
Calibrate	Calibrates the external device's transport mechanism.
get_DevicePort	Retrieves the communication port to which the external device is connected.

IAMExtDevice::Calibrate

IAMExtDevice Interface

Calibrates an external device's transport mechanism.

Syntax

HRESULT Calibrate(
    HEVENT hEvent,
    long Mode,
    long *pStatus
);

Parameters

hEvent
[in] Event used to signal completion of this process.
Mode
[in] Value that activates or deactivates the calibration process. Specify one of the following:

ED_ACTIVE Activates calibration process.
ED_INACTIVE Deactivates calibration process.
NULL Used to determine if current status is active or inactive.

pStatus
[out] Pointer to a variable that will be set to OATRUE to indicate that an event is active or OAFALSE to indicate that it is inactive.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use this method on certain external devices that require calibration; for example, when rewinding a tape and resetting the counter, or computing the frame offset for a timecode reader or generator.
Filters for various external devices can implement this method differently, depending on the calibration that the device needs. This method assumes the IMediaEventSink interface has already established an event sink, or that another event signaling method has been established.

IAMExtDevice::GetCapability

IAMExtDevice Interface

Retrieves the capabilities of the external device.

Syntax

HRESULT GetCapability(
    long Capability,
    long *pValue,
    double *pdblValue
);

Parameters

Capability
[in] Value that specifies which capability you want to check. This parameter must be one of the following values.

ED_DEVCAP_CAN_RECORD Checks whether device can record.
ED_DEVCAP_CAN_RECORD_STROBE Checks whether device can single-frame record.
ED_DEVCAP_CAN_SAVE Checks whether device can save data.
ED_DEVCAP_DEVICE_TYPE Checks the external device type.
ED_DEVCAP_HAS_AUDIO Checks whether device has audio.
ED_DEVCAP_HAS_VIDEO Checks whether the device has video.
ED_DEVCAP_USES_FILES Checks whether device has a built-in file system.

pValue
[out] Pointer to a variable that will receive a value indicating the capabilities of the property specified in the Capability parameter. For all properties except ED_DEVCAP_DEVICE_TYPE, this variable will be set to OATRUE if the property is supported or OAFALSE if the property is not supported. For ED_DEVCAP_DEVICE_TYPE, the variable will be set to one of the following:

ED_DEVTYPE_ATR Audio Tape Recorder
ED_DEVTYPE_CG Character Generator
ED_DEVTYPE_DDR Digital Disc Recorder
ED_DEVTYPE_DVE Digital video effects unit
ED_DEVTYPE_GPI General purpose interface trigger
ED_DEVTYPE_KEYER Video keyer
ED_DEVTYPE_LASERDISK Laser disc
ED_DEVTYPE_MIXER_AUDIO Audio mixer
ED_DEVTYPE_MIXER_VIDEO Video mixer
ED_DEVTYPE_ROUTER Video router
ED_DEVTYPE_TBC Timebase corrector
ED_DEVTYPE_TCG Timecode generator/reader
ED_DEVTYPE_VCR VCR
ED_DEVTYPE_WIPEGEN Video wipe generator
ED_DEVTYPE_JOYSTICK Joystick
ED_DEVTYPE_KEYBOARD Keyboard

pdblValue
[out] Pointer to a variable indicating the capabilities of the specified property (if it is a double value). Pass NULL if not in use.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

All return values are in pValue unless you have large or floating point values to return, in which case they are returned in the pdblValue parameter.

IAMExtDevice::get_DevicePort

IAMExtDevice Interface

Retrieves the communication port to which the external device is connected.

Syntax

HRESULT get_DevicePort(
    long *pDevicePort
);

Parameters

pDevicePort
[out] Pointer to a variable that will be set to one of the following values, indicating which port the device is connected to.

DEV_PORT_1394 IEEE 1394 Bus
DEV_PORT_ARTI ARTI driver
DEV_PORT_COM1 COM1
DEV_PORT_COM2 COM2
DEV_PORT_COM3 COM3
DEV_PORT_COM4 COM4
DEV_PORT_DIAQ Diaquest driver
DEV_PORT_SIM Simulation port
DEV_PORT_USB Universal Serial Bus

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtDevice::put_DevicePort

IAMExtDevice::get_DevicePower

IAMExtDevice Interface

Retrieves the external device's power mode: on, off, or standby.

Syntax

HRESULT get_DevicePower(
    long *pPowerMode
);

Parameters

pPowerMode
[out] Pointer to a variable that will be set to one of the following values indicating the external device's power mode.

ED_POWER_OFF Off
ED_POWER_ON On
ED_POWER_STANDBY Standby

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtDevice::put_DevicePower

IAMExtDevice::get_ExternalDeviceID

IAMExtDevice Interface

Retrieves the model number of the external device.

Syntax

HRESULT get_ExternalDeviceID(
    LPOLESTR *ppszData
);

Parameters

ppszData
[out] Address of a pointer to a variable that will receive the manufacturer-specific identification number or text as a string.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMExtDevice::get_ExternalDeviceVersion

IAMExtDevice Interface

Retrieves the version number of the external device's operating software.

Syntax

HRESULT get_ExternalDeviceVersion(
    LPOLESTR *ppszData
);

Parameters

ppszData
[out] Address of a pointer to a variable that will receive the manufacturer-specific operating software version number from the external device.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMExtDevice::put_DevicePort

IAMExtDevice Interface

Specifies the communication port to which the external device is connected.

Syntax

HRESULT put_DevicePort(
    long DevicePort
);

Parameters

DevicePort
[in] Port to which the device will connect. Specify one of the following:

DEV_PORT_1394 IEEE 1394 Bus
DEV_PORT_ARTI ARTI driver
DEV_PORT_COM1 COM1
DEV_PORT_COM2 COM2
DEV_PORT_COM3 COM3
DEV_PORT_COM4 COM4
DEV_PORT_DIAQ Diaquest driver
DEV_PORT_MIN DEV_PORT_SIM
DEV_PORT_SIM Simulation port (used for "no hardware" simulation)
DEV_PORT_USB Universal serial bus

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtDevice::get_DevicePort

IAMExtDevice::put_DevicePower

IAMExtDevice Interface

Sets the external device's power mode to either on, off, or standby.

Syntax

HRESULT put_DevicePower(
    long PowerMode
);

Parameters

PowerMode
[in] Value indicating which power mode the device will have. Set to one of the following:

ED_POWER_OFF Off
ED_POWER_ON On
ED_POWER_STANDBY Standby

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtDevice::get_DevicePower

ED_ACTIVE	Activates calibration process.
ED_INACTIVE	Deactivates calibration process.
NULL	Used to determine if current status is active or inactive.

ED_DEVCAP_CAN_RECORD	Checks whether device can record.
ED_DEVCAP_CAN_RECORD_STROBE	Checks whether device can single-frame record.
ED_DEVCAP_CAN_SAVE	Checks whether device can save data.
ED_DEVCAP_DEVICE_TYPE	Checks the external device type.
ED_DEVCAP_HAS_AUDIO	Checks whether device has audio.
ED_DEVCAP_HAS_VIDEO	Checks whether the device has video.
ED_DEVCAP_USES_FILES	Checks whether device has a built-in file system.

ED_DEVTYPE_ATR	Audio Tape Recorder
ED_DEVTYPE_CG	Character Generator
ED_DEVTYPE_DDR	Digital Disc Recorder
ED_DEVTYPE_DVE	Digital video effects unit
ED_DEVTYPE_GPI	General purpose interface trigger
ED_DEVTYPE_KEYER	Video keyer
ED_DEVTYPE_LASERDISK	Laser disc
ED_DEVTYPE_MIXER_AUDIO	Audio mixer
ED_DEVTYPE_MIXER_VIDEO	Video mixer
ED_DEVTYPE_ROUTER	Video router
ED_DEVTYPE_TBC	Timebase corrector
ED_DEVTYPE_TCG	Timecode generator/reader
ED_DEVTYPE_VCR	VCR
ED_DEVTYPE_WIPEGEN	Video wipe generator
ED_DEVTYPE_JOYSTICK	Joystick
ED_DEVTYPE_KEYBOARD	Keyboard

DEV_PORT_1394	IEEE 1394 Bus
DEV_PORT_ARTI	ARTI driver
DEV_PORT_COM1	COM1
DEV_PORT_COM2	COM2
DEV_PORT_COM3	COM3
DEV_PORT_COM4	COM4
DEV_PORT_DIAQ	Diaquest driver
DEV_PORT_SIM	Simulation port
DEV_PORT_USB	Universal Serial Bus