ホーム › Media.DeviceManager › IMDSPDeviceControl

IMDSPDeviceControl

COM

📘 Microsoft Learn (日本語) · English

IID1dcb3a14-33ed-11d3-8470-00c04f79dbc0継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IMDSPDeviceControl インターフェイスは、デバイスを制御するためのメソッドを提供します。

メソッド 8

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

vtbl 3 HRESULT GetDCStatus(DWORD* pdwStatus)

GetDCStatus メソッドは、デバイスの制御ステータスを取得します。

pdwStatus

DWORD*

out

デバイスの制御ステータスを格納する DWORD へのポインター。制御ステータス値には、次のフラグのうち 1 つ以上が含まれます。

フラグ	説明
WMDM_STATUS_READY	Windows Media Device Manager とそのサブコンポーネントが準備完了状態です。
WMDM_STATUS_BUSY	現在、操作が実行中です。どの操作であるかを判断するには、他のステータス値を評価してください。
WMDM_STATUS_DEVICECONTROL_PLAYING	デバイスは現在再生中です。
WMDM_STATUS_DEVICECONTROL_RECORDING	デバイスは現在録音中です。
WMDM_STATUS_DEVICECONTROL_PAUSED	デバイスは現在一時停止中です。
WMDM_STATUS_DEVICECONTROL_REMOTE	デバイスの再生操作または録音操作が、アプリケーションによってリモートで制御されています。
WMDM_STATUS_DEVICECONTROL_STREAM	再生メソッドまたは録音メソッドが、メディアデバイスとの間でデータをストリーミングしています。

戻り値

このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	pdwStatus パラメーターが無効なポインターまたは NULL ポインターです。
E_FAIL	不特定のエラーが発生しました。

解説(Remarks)

この呼び出しは、このインターフェイスのデバイス制御操作に固有のステータス値を返します。制御ステータスからは、再生や録音など、デバイスの制御に関連する動作の状態についての情報が得られます。ただし、デバイスがデータをダウンロード中であるか、他の理由でアクセスされているかといった、デバイス全体のステータスに関する情報は得られません。デバイス制御以外の理由でデバイスがビジー状態である場合はビジーコードが返されるため、より詳細な情報を得るには、対応する IMDSPDevice インターフェイスの GetStatus メソッドを呼び出す必要があります。

ステータス値 WMDM_STATUS_BUSY が返され、かつステータス値の表の他の値がステータス値に含まれていない場合は、このインターフェイスの Play、Record、Pause、Resume、Stop の各メソッドを呼び出してはなりません。

vtbl 4 HRESULT GetCapabilities(DWORD* pdwCapabilitiesMask)

GetCapabilities メソッドは、この制御インターフェイスが関連付けられているデバイスの機能マスクを取得します。この機能は、メディアデバイスがサポートするデバイス制御のメソッドを示します。

pdwCapabilitiesMask

DWORD*

out

デバイスの機能を格納する DWORD へのポインター。この変数には次のフラグが返される場合があります。

フラグ	説明
MDM_DEVICECAP_CANPLAY	メディアデバイスは MP3 オーディオを再生できます。
MDM_DEVICECAP_CANSTREAMPLAY	メディアデバイスは、ホストコンピューターから直接ストリーミングオーディオを再生できます。
MDM_DEVICECAP_CANRECORD	メディアデバイスはオーディオを録音できます。
MDM_DEVICECAP_CANSTREAMRECORD	メディアデバイスは、ホストコンピューターに直接ストリーミングオーディオを録音できます。
MDM_DEVICECAP_CANPAUSE	メディアデバイスは、再生操作または録音操作の途中で一時停止できます。
MDM_DEVICECAP_CANRESUME	メディアデバイスは、一時停止コマンドの後に操作を再開できます。
MDM_DEVICECAP_CANSTOP	メディアデバイスは、ファイルの末尾に達する前に再生を停止できます。
MDM_DEVICECAP_CANSEEK	メディアデバイスは、ファイルの先頭以外の位置にシークできます。

戻り値

このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	pdwCapabilitiesMask パラメーターが無効なポインターまたは NULL ポインターです。
E_FAIL	不特定のエラーが発生しました。

vtbl 5 HRESULT Play()

Play メソッドは、現在のシーク位置から再生を開始します。Seek メソッドが呼び出されていない場合、再生は最初のファイルの先頭から開始され、再生の長さは定義されません。

戻り値

このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_BUSY	デバイスがビジー状態です。
WMDM_E_NOTSUPPORTED	このデバイスでは再生機能が実装されていません。
E_FAIL	不特定のエラーが発生しました。

解説(Remarks)

このメソッドは、デバイス再生 (メディアデバイスの記憶メディア上にあるオーディオトラックの再生) と、ストリーミングオーディオ再生 (ユーザーのコンピューターからメディアデバイスへオーディオデータをストリーミングし、デバイス上で再生すること) の両方を実行するために使用します。どちらの形式の再生が行われるかは、Seek メソッドによって決まります。

一部のデバイスは、デバイス再生またはストリーミングオーディオ再生のいずれかをサポートしていません。特定の種類の再生を開始する前に、GetCapabilities メソッドを呼び出す必要があります。サポートされていない再生を試みた場合、このメソッドは WMDM_E_NOTSUPPORTED を返します。

再生操作を実行する前に、メディアデバイスが特定のオーディオ形式を再生できるかどうかを確認するには、IMDSPDevice::GetFormatSupport メソッドを呼び出します。

vtbl 6 HRESULT Record(WAVEFORMATEX* pFormat)

Record メソッドは、現在のシーク位置から、デバイスの外部録音入力による録音を開始します。事前に Seek メソッドを呼び出しておく必要があります。

pFormat

WAVEFORMATEX*

データを録音する形式を格納する _WAVEFORMATEX 構造体へのポインター。

戻り値

このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_BUSY	デバイスは既に操作を実行中です。
WMDM_E_NOTSUPPORTED	このデバイスでは録音機能が実装されていません。
E_FAIL	不特定のエラーが発生しました。

解説(Remarks)

このメソッドは、デバイス録音 (メディアデバイスに保存するオーディオトラックの録音) と、メディアデバイスからコンピューターへオーディオデータをストリーミングして録音することの、両方を実行するために使用します。どちらの形式の録音が行われるかは、Seek メソッドによって決まります。

一部のデバイスは、いずれの種類の録音もサポートしていません。録音を開始する前に、GetCapabilities メソッドを呼び出す必要があります。サポートされていない種類の録音を試みた場合、このメソッドは WMDM_E_NOTSUPPORTED を返します。

pFormat パラメーターに引数を指定して、録音するオーディオデータの形式を指定できます。デバイスがサポートする形式を確認するには、IMDSPDevice::GetFormatSupport を参照してください。pFormat パラメーターに NULL を設定した場合、デバイスは既定の形式でオーディオデータを録音します。

デバイス録音を使用する場合は、録音操作の完了後に記憶メディアの内容を列挙して、新しいオブジェクトを見つける必要があります。

vtbl 7 HRESULT Pause()

Pause メソッドは、現在の再生セッションまたは録音セッションを、コンテンツ内の現在の位置で一時停止します。(IMDSPDeviceControl.Pause)

戻り値

このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
S_FALSE	デバイスは既に一時停止しています。
WMDM_E_NOTSUPPORTED	このデバイスでは一時停止機能が実装されていません。
E_FAIL	不特定のエラーが発生しました。

解説(Remarks)

現在の再生セッションまたは録音セッションが一時停止され、現在のファイル位置が保存されます。その後 Resume メソッドを呼び出すと、保存されたファイル位置から再生操作または録音操作が再開されます。

vtbl 8 HRESULT Resume()

Resume メソッドは、Pause の呼び出し時に保存されたファイル位置から、現在の再生操作または録音操作を再開します。

戻り値

このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
S_FALSE	デバイスは一時停止していません。
WMDM_E_NOTSUPPORTED	このデバイスでは再開機能が実装されていません。
E_FAIL	不特定のエラーが発生しました。

vtbl 9 HRESULT Stop()

Stop メソッドは、現在のストリームを停止します。

戻り値

このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_BUSY	デバイスがビジー状態です。
WMDM_E_NOTSUPPORTED	このデバイスでは停止機能が実装されていません。
E_FAIL	不特定のエラーが発生しました。

vtbl 10 HRESULT Seek(DWORD fuMode, INT nOffset)

Seek メソッドは、Play メソッドまたは Record メソッドが開始位置として使用する位置にシークします。(IMDSPDeviceControl.Seek)

fuMode

DWORD

実行するシーク操作のモード。fuMode パラメーターには、次のいずれかのモードを指定する必要があります。

モード	説明
MDSP_SEEK_BOF	ファイルの先頭から nOffset 単位後の位置にシークします。
MDSP_SEEK_CUR	現在の位置から nOffset 単位離れた位置にシークします。
MDSP_SEEK_EOF	ファイルの末尾から nOffset 単位前の位置にシークします。

nOffset

INT

fuMode で指定した起点から開始位置を移動させる単位数。nOffset の単位はコンテンツによって定義されます。音楽の場合はミリ秒、電子書籍の場合はページなどになります。

nOffset が正の値の場合は、ファイル内を前方にシークすることを示します。負の値の場合は、後方にシークすることを示します。nOffset と fuMode の組み合わせが、ファイルの先頭より前、またはファイルの末尾より後の位置へのシークを示す場合は無効であり、メソッドは E_INVALIDARG を返します。

戻り値

このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	1 つ以上のパラメーターが無効です。
WMDM_E_NOTSUPPORTED	このデバイスでは Seek が実装されていません。
E_FAIL	不特定のエラーが発生しました。

解説(Remarks)

シーク位置は、デバイスの記憶メディア上の場所を指す IWMDMStorage インターフェイス、またはストリーミングオーディオをサポートするように実装された IWMDMOperation インターフェイスのいずれかを渡すことで指定します。また、指定したインターフェイスが指すオブジェクト内の特定の位置を示すために、IMDSPObjectInfo インターフェイスを渡すこともできます。

デバイス再生の場合、Play の前に Seek が呼び出されないと、再生はメディアデバイスの最初の記憶メディア上にある最初のオーディオトラックから開始されます。

デバイス録音の場合、Record の前に Seek が呼び出されないと、録音操作は失敗します。Record メソッドの呼び出し後、IMDSPObjectInfo::GetLastPlayPosition メソッドを呼び出すと、常にその時点までの合計再生長が報告され、その値は IMDSPObjectInfo::GetTotalLength から返される値と等しくなります。録音の長さを制限するには、Seek の呼び出しから戻った後に IMDSPObjectInfo::SetPlayLength メソッドを呼び出します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMDSPDeviceControl "{1DCB3A14-33ED-11D3-8470-00C04F79DBC0}"
#usecom global IMDSPDeviceControl IID_IMDSPDeviceControl "{}"
#comfunc global IMDSPDeviceControl_GetDCStatus      3 var
#comfunc global IMDSPDeviceControl_GetCapabilities  4 var
#comfunc global IMDSPDeviceControl_Play             5
#comfunc global IMDSPDeviceControl_Record           6 var
#comfunc global IMDSPDeviceControl_Pause            7
#comfunc global IMDSPDeviceControl_Resume           8
#comfunc global IMDSPDeviceControl_Stop             9
#comfunc global IMDSPDeviceControl_Seek             10 int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IMDSPDeviceControl "{1DCB3A14-33ED-11D3-8470-00C04F79DBC0}"
#usecom global IMDSPDeviceControl IID_IMDSPDeviceControl "{}"
#comfunc global IMDSPDeviceControl_GetDCStatus      3 sptr
#comfunc global IMDSPDeviceControl_GetCapabilities  4 sptr
#comfunc global IMDSPDeviceControl_Play             5
#comfunc global IMDSPDeviceControl_Record           6 sptr
#comfunc global IMDSPDeviceControl_Pause            7
#comfunc global IMDSPDeviceControl_Resume           8
#comfunc global IMDSPDeviceControl_Stop             9
#comfunc global IMDSPDeviceControl_Seek             10 int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。