IAMExtDevice Interface

The IAMExtDevice interface is the base interface for controlling external devices. Developers can implement this interface to control numerous types of devices; however, the current 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 which controls a VCR through DirectShow, see Vcrctrl Sample (VCR Control Filter).

When to Implement

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.

When to Use

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.

---

IAMExtDevice::Calibrate

IAMExtDevice Interface

Calibrates an external device's transport mechanism.

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:

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

pStatus

[out] Value indicating whether an event is active (OATRUE) or inactive (OAFALSE).

Return Values

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.

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.

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

pValue

[out] Value indicating the capabilities of the property specified in the Capability parameter. Returns OATRUE if the property is supported or OAFALSE if the property is not supported for all properties except ED_DEVCAP_DEVICE_TYPE. In this case, returns one of the following:

Value	Meaning
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] Value indicating the capabilities of the specified property (if it is a double value). Pass NULL if not in use.

Return Values

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.

HRESULT get_DevicePort(
  long *pDevicePort );

Parameters

pDevicePort

[in] Port to which the device is connected. Retrieves one of the following:

Value	Meaning
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 Values

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.

HRESULT get_DevicePower(
  long *pPowerMode );

Parameters

pPowerMode

[out] External device's power mode; can be one of the following values.

Value	Meaning
ED_POWER_OFF	Off
ED_POWER_ON	On
ED_POWER_STANDBY	Standby

Return Values

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.

HRESULT get_ExternalDeviceID(
  LPOLESTR *ppszData );

Parameters

ppszData

[out] Returns the manufacturer-specific identification number or text as a string.

Return Values

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.

HRESULT get_ExternalDeviceVersion(
  LPOLESTR *ppszData );

Parameters

ppszData

[out] Returns the manufacturer-specific operating software version number from the external device.

Return Values

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.

HRESULT put_DevicePort(
  long DevicePort
  );

Parameters

DevicePort

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

Value	Meaning
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 Values

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.

HRESULT put_DevicePower(
  long PowerMode );

Parameters

PowerMode

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

Value	Meaning
ED_POWER_OFF	Off
ED_POWER_ON	On
ED_POWER_STANDBY	Standby

Return Values

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

See Also

IAMExtDevice::get_DevicePower

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page