IAMExtDevice

COM

IIDb5730a90-1a2c-11cf-8c23-00aa006b6814継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IAMExtDevice インターフェイスは、DV カメラやビデオテープレコーダー (VTR) などの外部デバイスを制御します。

解説(Remarks)

DV デバイスドライバーは、ヘッダーファイル Xprtdefs.h で定義される追加の定数をいくつか必要とします。

Windows Driver Model (WDM) デバイスの場合、WDM ドライバーが PROPSETID_EXT_DEVICE プロパティセットをサポートしていれば、WDM Video Capture Filter が自動的にこのインターフェイスを公開します。詳細については、Windows Driver Kit (WDK) のドキュメントを参照してください。

ハードウェア要件

外部 VCR を制御するには、特定のハードウェア要件が推奨されます。RS-422 シリアルインターフェイスを備えた VCR には、専用のシリアルポートカードまたは外付けの RS-232-RS-422 変換アダプターが必要です。さらに、最高のパフォーマンスを得るには、38.4 ボーなどの高いボーレートを維持できるよう、16550 高性能 UART (Universal Asynchronous Receiver/Transmitter) を搭載したシリアルポートカードを備えていることが望まれます。

メソッド 8

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetCapability(INT Capability, INT* pValue, DOUBLE* pdblValue)

GetCapability メソッドは、外部デバイスの機能を取得します。

Capability	INT	in	確認する機能を指定します。詳細については「解説」を参照してください。
pValue	INT*	out	long 整数を受け取る変数へのポインター。詳細については「解説」を参照してください。
pdblValue	DOUBLE*	out	double を受け取る変数へのポインター。詳細については「解説」を参照してください。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

Capability パラメーターは、どの機能を確認するかを指定するフラグです。このメソッドは、機能フラグに応じて、結果を pValue パラメーターまたは pdblValue パラメーターのいずれかで返します。

以下のフラグの場合、このメソッドは pValue パラメーターに値 OATRUE または OAFALSE を返します。値 OATRUE はその機能が存在することを、値 OAFALSE は存在しないことを示します。

機能フラグ	説明
ED_DEVCAP_AUDIO_INPUTS	デバイスは音声入力を受け付けます。
ED_DEVCAP_CAN_MONITOR_SOURCES	デバイスは、現在選択されている入力に関係なく、任意の入力をモニター対象の出力へ送ることができます。
ED_DEVCAP_CAN_PREVIEW	デバイスはプレビューできます。
ED_DEVCAP_CAN_RECORD	デバイスは録画できます。
ED_DEVCAP_CAN_RECORD_STROBE	デバイスはストローブ録画できます。この機能は、選択したトラックに録画できるマルチトラックデバイスに適用されます。
ED_DEVCAP_CAN_SAVE	デバイスはデータを保存できます。
ED_DEVCAP_CTLTRK_READ	デバイスはコントロールトラックを読み取ることができます。
ED_DEVCAP_HAS_AUDIO	デバイスは音声を備えています。
ED_DEVCAP_HAS_VIDEO	デバイスは映像を備えています。
ED_DEVCAP_INDEX_READ	デバイスはインデックスマークを読み取ることができます。
ED_DEVCAP_NEEDS_CALIBRATING	デバイスはキャリブレーションを必要とします。IAMExtDevice::Calibrate を参照してください。
ED_DEVCAP_TIMECODE_READ	デバイスは SMPTE タイムコードを読み取ることができます。
ED_DEVCAP_TIMECODE_WRITE	デバイスは SMPTE タイムコードを設定できます。
ED_DEVCAP_USES_FILES	デバイスは組み込みのファイルシステムを備えています。
ED_DEVCAP_VIDEO_INPUTS	デバイスは映像入力を受け付けます。

以下のフラグの場合、このメソッドは pValue パラメーターに定義済みの定数を返します。

ED_DEVCAP_DEVICE_TYPE: デバイスの種類を返します。

返される定数	説明
ED_DEVTYPE_ATR	オーディオテープレコーダー
ED_DEVTYPE_CG	キャラクタージェネレーター
ED_DEVTYPE_DDR	デジタルディスクレコーダー
ED_DEVTYPE_DVE	デジタルビデオエフェクトユニット
ED_DEVTYPE_GPI	汎用インターフェイストリガー
ED_DEVTYPE_KEYER	ビデオキーヤー
ED_DEVTYPE_LASERDISK	レーザーディスク
ED_DEVTYPE_MIXER_AUDIO	オーディオミキサー
ED_DEVTYPE_MIXER_VIDEO	ビデオミキサー
ED_DEVTYPE_ROUTER	ビデオルーター
ED_DEVTYPE_TBC	タイムベースコレクター
ED_DEVTYPE_TCG	タイムコードジェネレーター/リーダー
ED_DEVTYPE_VCR	VCR、または VCR の全機能を備えたカムコーダー
ED_DEVTYPE_WIPEGEN	ビデオワイプジェネレーター
ED_DEVTYPE_JOYSTICK	ジョイスティック
ED_DEVTYPE_KEYBOARD	キーボード

ED_DEVCAP_SYNC_ACCURACY: デバイスの同期精度を示す値を返します。

返される定数	説明
ED_SYNCACC_PRECISE	デバイスは高精度を備えています。
ED_SYNCACC_FRAME	デバイスはフレーム単位の精度を備えています。
ED_SYNCACC_ROUGH	デバイスはフレーム単位未満の精度です。

ED_DEVCAP_NORMAL_RATE: デバイスの通常のフレームレートを返します。

返される定数	説明
ED_RATE_24	24 フレーム/秒 (fps)
ED_RATE_25	25 fps
ED_RATE_2997	29.97 fps
ED_RATE_30	30 fps

ED_DEVCAP_SEEK_TYPE: デバイスのシーク精度を示す値を返します。

返される定数	説明
ED_SEEK_PERFECT	デバイスは信号を途切れさせることなく 1 ビデオフレーム以内でシークできます。
ED_SEEK_FAST	デバイスは短い信号の途切れを伴って高速にシークできます。
ED_SEEK_SLOW	デバイスは低速にシークします (テープ走行など)。

以下のフラグの場合、このメソッドは pValue パラメーターに数値を返します。

機能フラグ	返される値
ED_DEVCAP_EXTERNAL_DEVICE_ID	製造元固有の識別子。
ED_DEVCAP_PREROLL	デバイスのプリロール時間。
ED_DEVCAP_POSTROLL	デバイスのポストロール時間。

Windows XP Service Pack 2 以降では、ED_DEVCAP_DEVICE_TYPE に対して以下の追加フラグがサポートされます。

返される定数	説明
ED_DEVTYPE_CAMERA_STORAGE	静止画像または短いビデオファイル用のストレージ。
ED_DEVTYPE_DTV	シリアルバスインターフェイスを備えたデジタルテレビ。
ED_DEVTYPE_PC_VIRTUAL	コンピューター上の仮想デバイスまたはエミュレートされたデバイス。

これらの定数を使用するには、ヘッダーファイル Xprtdefs.h をインクルードしてください。

DV での実装

MSDV ドライバーおよび UVC ドライバーは、以下の動作をサポートします。

ED_DEVCAP_NORMAL_RATE フラグはフレームレートを返します。

返される定数	説明
ED_RATE_25	25 fps (PAL の既定のフレームレート)
ED_RATE_2997	29.997 fps (NTSC の既定のフレームレート)

MSDV に限り、ED_DEVCAP_DEVICE_TYPE フラグはデバイスの種類を返します。取り得る値を次の表に示します。UVC デバイスの場合は、代わりに IKsTopologyInfo インターフェイスを使用してください。

返される定数	説明
ED_DEVTYPE_CAMERA	録画または一時停止録画は可能だが、VCR の全機能は備えていない単純なカメラ。
ED_DEVTYPE_DVHS	デバイスは D-VHS フォーマットをサポートします。
ED_DEVTYPE_UNKNOWN	不明なデバイスの種類。
ED_DEVTYPE_VCR	デバイスは VCR の全機能を備えています。

vtbl 4 HRESULT get_ExternalDeviceID(LPWSTR* ppszData)

get_ExternalDeviceID メソッドは、外部デバイスのモデル番号を取得します。

ppszData

LPWSTR*

out

製造元固有の識別情報を文字列として受け取る LPOLESTR へのポインター。呼び出し側は CoTaskMemFree を呼び出して文字列を解放する必要があります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 5 HRESULT get_ExternalDeviceVersion(LPWSTR* ppszData)

get_ExternalDeviceVersion は、外部デバイスの動作ソフトウェアのバージョン番号を取得します。

ppszData

LPWSTR*

out

製造元固有の動作ソフトウェアのバージョン番号を文字列として受け取る LPOLESTR へのポインター。呼び出し側は CoTaskMemFree を呼び出して文字列を解放する必要があります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 6 HRESULT put_DevicePower(INT PowerMode)

put_DevicePower メソッドは、外部デバイスの電源モードをオン、オフ、またはスタンバイのいずれかに設定します。

PowerMode

INT

デバイスの電源モードを指定します。以下の値のいずれかを使用します。

値	説明
ED_POWER_OFF	オフ
ED_POWER_ON	オン
ED_POWER_STANDBY	スタンバイ

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 7 HRESULT get_DevicePower(INT* pPowerMode)

get_DevicePower メソッドは、外部デバイスの電源モードを取得します。

pPowerMode

INT*

out

デバイスの電源モードを示す以下の値のいずれかを受け取る long 整数へのポインター。

値	説明
ED_POWER_OFF	電源はオフです。
ED_POWER_ON	電源はオンです。
ED_POWER_STANDBY	デバイスはスタンバイモードです。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

Windows XP Service Pack 2 以降では、以下の追加の電源モードが定義されています。

値	説明
ED_POWER_DEVICE_DEPENDENT	機能を制限した状態で電源がオンです。

この定数を使用するには、ヘッダーファイル Xprtdefs.h をインクルードしてください。

DV および MPEG カムコーダーでの実装

MSDV ドライバーおよび UVC ドライバーは、カムコーダーがオンのときに ED_POWER_ON を返します。カムコーダーがオフまたはスタンバイモードの場合、DV ドライバーは読み込まれないため、このメソッドは利用できません。カムコーダーが予期せず取り外された場合、このメソッドは ERROR_GEN_FAILURE を返すことがあります。

MSTape は ED_POWER_OFF と ED_POWER_ON の両方をサポートしますが、ED_POWER_STANDBY はサポートしません。

vtbl 8 HRESULT Calibrate(UINT_PTR hEvent, INT Mode, INT* pStatus)

Calibrate メソッドは、外部デバイスの走行機構をキャリブレーションします。

hEvent

UINT_PTR

イベントへのハンドル。処理が完了するとこのイベントがシグナル状態になります。

Mode

INT

キャリブレーション処理を有効化または無効化する値を指定します:

値	説明
ED_ACTIVE	キャリブレーション処理を有効化します。
ED_INACTIVE	キャリブレーション処理を無効化します。
NULL	何も実行せず、キャリブレーションの状態を pStatus で返します。

pStatus

INT*

out

以下の値のいずれかを受け取る long 整数へのポインター:

値	説明
OATRUE	キャリブレーションは有効です。
OAFALSE	キャリブレーションは無効です。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

キャリブレーションを必要とする一部の外部デバイスでこのメソッドを使用します。たとえば、テープの巻き戻しとカウンターのリセット、またはタイムコードリーダーのフレームオフセットの計算などです。

各種の外部デバイス用のフィルターは、デバイスが必要とするキャリブレーションに応じて、このメソッドを異なる形で実装できます。このメソッドは、IMediaEventSink インターフェイスによってイベントシンクが既に確立されているか、または別のイベントシグナル方式が確立されていることを前提とします。

DV での実装

MSDV ドライバーおよび UVC ドライバーはこのメソッドをサポートしません。このメソッドは E_NOTIMPL を返します。

vtbl 9 HRESULT put_DevicePort(INT DevicePort)

put_DevicePort メソッドは、外部デバイスが接続される通信ポートを設定します。

DevicePort

INT

デバイスを接続するポートを指定します。以下の値のいずれかを使用します。

値	説明
DEV_PORT_1394	IEEE 1394 バス
DEV_PORT_ARTI	ARTI ドライバー
DEV_PORT_COM1	COM1
DEV_PORT_COM2	COM2
DEV_PORT_COM3	COM3
DEV_PORT_COM4	COM4
DEV_PORT_DIAQ	Diaquest ドライバー
DEV_PORT_MIN	DEV_PORT_SIM
DEV_PORT_SIM	シミュレーションポート (「ハードウェアなし」シミュレーションに使用)
DEV_PORT_USB	ユニバーサルシリアルバス

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 10 HRESULT get_DevicePort(INT* pDevicePort)

get_DevicePort メソッドは、外部デバイスが接続されている通信ポートを取得します。

pDevicePort

INT*

out

デバイスが接続されているポートを示す以下の値のいずれかを受け取る long 整数へのポインター:

値	説明
DEV_PORT_1394	IEEE 1394 バス
DEV_PORT_ARTI	ARTI ドライバー
DEV_PORT_COM1	COM1
DEV_PORT_COM2	COM2
DEV_PORT_COM3	COM3
DEV_PORT_COM4	COM4
DEV_PORT_DIAQ	Diaquest ドライバー
DEV_PORT_SIM	シミュレーションポート
DEV_PORT_USB	ユニバーサルシリアルバス

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IAMExtDevice "{B5730A90-1A2C-11CF-8C23-00AA006B6814}"
#usecom global IAMExtDevice IID_IAMExtDevice "{}"
#comfunc global IAMExtDevice_GetCapability              3 int,var,var
#comfunc global IAMExtDevice_get_ExternalDeviceID       4 var
#comfunc global IAMExtDevice_get_ExternalDeviceVersion  5 var
#comfunc global IAMExtDevice_put_DevicePower            6 int
#comfunc global IAMExtDevice_get_DevicePower            7 var
#comfunc global IAMExtDevice_Calibrate                  8 sptr,int,var
#comfunc global IAMExtDevice_put_DevicePort             9 int
#comfunc global IAMExtDevice_get_DevicePort             10 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IAMExtDevice "{B5730A90-1A2C-11CF-8C23-00AA006B6814}"
#usecom global IAMExtDevice IID_IAMExtDevice "{}"
#comfunc global IAMExtDevice_GetCapability              3 int,sptr,sptr
#comfunc global IAMExtDevice_get_ExternalDeviceID       4 sptr
#comfunc global IAMExtDevice_get_ExternalDeviceVersion  5 sptr
#comfunc global IAMExtDevice_put_DevicePower            6 int
#comfunc global IAMExtDevice_get_DevicePower            7 sptr
#comfunc global IAMExtDevice_Calibrate                  8 sptr,int,sptr
#comfunc global IAMExtDevice_put_DevicePort             9 int
#comfunc global IAMExtDevice_get_DevicePort             10 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。