## 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

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