Win32 API 日本語リファレンス
ホームMedia.MediaFoundation › IMFPMediaItem

IMFPMediaItem

COM
IID90eb3e6b-ecbf-45cc-b1da-c6fe3ea70d57継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

メディア項目を表します。(非推奨。)

メソッド 19

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

vtbl 3 HRESULT GetMediaPlayer(IMFPMediaPlayer** ppMediaPlayer)

このメディア項目を作成した MFPlay プレイヤーオブジェクトへのポインターを取得します。

ppMediaPlayerIMFPMediaPlayer**outプレイヤーオブジェクトの IMFPMediaPlayer インターフェイスへのポインターを受け取ります。呼び出し元はこのインターフェイスを解放する必要があります。

戻り値

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

vtbl 4 HRESULT GetURL(LPWSTR* ppwszURL)

このメディア項目の作成に使用された URL を取得します。

ppwszURLLPWSTR*outURL を格納した null 終端文字列へのポインターを受け取ります。呼び出し元は CoTaskMemFree を呼び出してこの文字列を解放する必要があります。

戻り値

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

戻り値コード 説明
S_OK
メソッドが成功しました。
MF_E_NOTFOUND
このメディア項目に関連付けられた URL がありません。
MF_E_SHUTDOWN
IMFPMediaPlayer::Shutdown メソッドが呼び出されました。

解説(Remarks)

このメソッドは、アプリケーションが IMFPMediaPlayer::CreateMediaItemFromURL を呼び出してメディア項目を作成した場合に適用されます。アプリケーションが IMFPMediaPlayer::CreateMediaItemFromObject を呼び出してメディア項目を作成した場合、そのメディア項目に対する GetURL メソッドは MF_E_NOTFOUND を返します。

vtbl 5 HRESULT GetObject(IUnknown** ppIUnknown)

このメディア項目の作成に使用されたオブジェクトを取得します。

ppIUnknownIUnknown**outオブジェクトの IUnknown インターフェイスへのポインターを受け取ります。呼び出し元はこのインターフェイスを解放する必要があります。

戻り値

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

戻り値コード 説明
S_OK
メソッドが成功しました。
MF_E_NOTFOUND
メディア項目はオブジェクトからではなく URL から作成されました。
MF_E_SHUTDOWN
IMFPMediaPlayer::Shutdown メソッドが呼び出されました。

解説(Remarks)

アプリケーションが IMFPMediaPlayer::CreateMediaItemFromObject を使用してメディア項目を作成した場合、オブジェクトポインターが設定されます。それ以外の場合、GetObject は MF_E_NOTFOUND を返します。

vtbl 6 HRESULT GetUserData(UINT_PTR* pdwUserData)

メディア項目に格納されているアプリケーション定義の値を取得します。

pdwUserDataUINT_PTR*outメディア項目のアプリケーション定義の値を受け取ります。

戻り値

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

解説(Remarks)

この値は、メディア項目を最初に作成する際に、IMFPMediaPlayer::CreateMediaItemFromURL または IMFPMediaPlayer::CreateMediaItemFromObject メソッドの dwUserData パラメーターに指定することで割り当てることができます。値を更新するには、IMFPMediaItem::SetUserData を呼び出します。

このメソッドは、プレイヤーオブジェクトがシャットダウンされた後でも呼び出すことができます。

vtbl 7 HRESULT SetUserData(UINT_PTR dwUserData)

アプリケーション定義の値をメディア項目に格納します。

dwUserDataUINT_PTRinアプリケーション定義の値。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

解説(Remarks)

このメソッドは、プレイヤーオブジェクトがシャットダウンされた後でも呼び出すことができます。

vtbl 8 HRESULT GetStartStopPosition(GUID* pguidStartPositionType, PROPVARIANT* pvStartValue, GUID* pguidStopPositionType, PROPVARIANT* pvStopValue)

メディア項目の開始時刻と停止時刻を取得します。

pguidStartPositionTypeGUID*outoptional開始位置の時間単位を受け取ります。「解説」を参照してください。このパラメーターには NULL を指定できます。
pvStartValuePROPVARIANT*outoptional開始位置を受け取ります。このパラメーターの意味とデータ型は pguidStartPositionType パラメーターによって示されます。pguidStartPositionTypeNULL の場合、pvStartValue パラメーターは NULL でなければならず、それ以外の場合は NULL にできません。
pguidStopPositionTypeGUID*outoptional停止位置の時間単位を受け取ります。「解説」を参照してください。このパラメーターには NULL を指定できます。
pvStopValuePROPVARIANT*outoptional停止位置。このパラメーターの意味とデータ型は pguidStopPositionType パラメーターによって示されます。pguidStopPositionTypeNULL の場合、pvStopValue パラメーターは NULL でなければならず、それ以外の場合は NULL にできません。

戻り値

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

解説(Remarks)

pguidStartPositionType および pguidStopPositionType パラメーターは、使用される時間単位を受け取ります。現在サポートされている値は MFP_POSITIONTYPE_100NS のみです。

説明
MFP_POSITIONTYPE_100NS 100 ナノ秒単位。時間パラメーター(pvStartValue または pvStopValue)は次のデータ型を使用します:
  • バリアント型 (vt): VT_I8
  • バリアントメンバー: hVal
vtbl 9 HRESULT SetStartStopPosition(GUID* pguidStartPositionType, PROPVARIANT* pvStartValue, GUID* pguidStopPositionType, PROPVARIANT* pvStopValue)

メディア項目の開始時刻と停止時刻を設定します。

pguidStartPositionTypeGUID*inoptional開始位置の時間単位。「解説」を参照してください。このパラメーターには NULL を指定できます。
pvStartValuePROPVARIANT*inoptional開始位置。このパラメーターの意味とデータ型は pguidStartPositionType パラメーターによって示されます。pguidStartPositionTypeNULL の場合、pvStartValue パラメーターは NULL でなければならず、それ以外の場合は NULL にできません。
pguidStopPositionTypeGUID*inoptional停止位置の時間単位。「解説」を参照してください。このパラメーターには NULL を指定できます。
pvStopValuePROPVARIANT*inoptional停止位置。このパラメーターの意味とデータ型は pguidStopPositionType パラメーターによって示されます。pguidStopPositionTypeNULL の場合、pvStopValue パラメーターは NULL でなければならず、それ以外の場合は NULL にできません。

戻り値

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

戻り値コード 説明
S_OK
メソッドが成功しました。
E_INVALIDARG
無効な引数です。
MF_E_OUT_OF_RANGE
開始時刻または停止時刻が無効です。次のいずれかがこのエラーの原因となります:
  • 時刻が 0 未満である。
  • 時刻がメディア項目の総再生時間を超えている。
  • 停止時刻が開始時刻より前である。

解説(Remarks)

既定では、メディア項目はファイルの先頭から末尾まで再生されます。このメソッドは開始時刻および/または停止時刻を調整します:

pguidStartPositionType および pguidStopPositionType パラメーターは、使用される時間単位を示します。現在サポートされている値は MFP_POSITIONTYPE_100NS のみです。
説明
MFP_POSITIONTYPE_100NS 100 ナノ秒単位。時間パラメーター(pvStartValue または pvStopValue)は次のデータ型を使用します:
  • バリアント型 (vt): VT_I8
  • バリアントメンバー: hVal
以前に設定した時刻をクリアするには、空の PROPVARIANT(VT_EMPTY)を使用します。

調整された開始時刻と停止時刻は、このメディア項目を指定して次に IMFPMediaPlayer::SetMediaItem が呼び出されたときに使用されます。メディア項目がすでにプレイヤーに設定されている場合、SetMediaItem を再度呼び出さない限り変更は反映されません。

HRESULT PlayMediaClip(
    IMFPMediaPlayer *pPlayer,
    PCWSTR pszURL,
    LONGLONG    hnsStart,
    LONGLONG    hnsEnd
    )
{
    IMFPMediaItem *pItem = NULL;
    PROPVARIANT varStart, varEnd;

    ULONGLONG hnsDuration = 0;

    HRESULT hr = pPlayer->CreateMediaItemFromURL(pszURL, TRUE, 0, &pItem);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = GetPlaybackDuration(pItem, &hnsDuration);
    if (FAILED(hr))
    {
        goto done;
    }

    if ((ULONGLONG)hnsEnd > hnsDuration)
    {
        hnsEnd = hnsDuration;
    }

    hr = InitPropVariantFromInt64(hnsStart, &varStart);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = InitPropVariantFromInt64(hnsEnd, &varEnd);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pItem->SetStartStopPosition(
        &MFP_POSITIONTYPE_100NS,
        &varStart,
        &MFP_POSITIONTYPE_100NS,
        &varEnd
        );
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pPlayer->SetMediaItem(pItem);

done:
    SafeRelease(&pItem);
    return hr;
}
vtbl 10 HRESULT HasVideo(BOOL* pfHasVideo, BOOL* pfSelected)

メディア項目がビデオストリームを含むかどうかを照会します。

pfHasVideoBOOL*outoptionalメディア項目に少なくとも 1 つのビデオストリームが含まれる場合は TRUE、それ以外の場合は FALSE の値を受け取ります。
pfSelectedBOOL*outoptional少なくとも 1 つのビデオストリームが選択されている場合は TRUE、それ以外の場合は FALSE の値を受け取ります。

戻り値

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

解説(Remarks)

再生開始前にストリームを選択または選択解除するには、IMFPMediaItem::SetStreamSelection を呼び出します。

vtbl 11 HRESULT HasAudio(BOOL* pfHasAudio, BOOL* pfSelected)

メディア項目がオーディオストリームを含むかどうかを照会します。

pfHasAudioBOOL*outoptionalメディア項目に少なくとも 1 つのオーディオストリームが含まれる場合は TRUE、それ以外の場合は FALSE の値を受け取ります。
pfSelectedBOOL*outoptional少なくとも 1 つのオーディオストリームが選択されている場合は TRUE、それ以外の場合は FALSE の値を受け取ります。

戻り値

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

解説(Remarks)

再生開始前にストリームを選択または選択解除するには、IMFPMediaItem::SetStreamSelection を呼び出します。

vtbl 12 HRESULT IsProtected(BOOL* pfProtected)

メディア項目が保護されたコンテンツを含むかどうかを照会します。

pfProtectedBOOL*out

次のいずれかの値を受け取ります。

意味
TRUE
メディア項目は保護されたコンテンツを含みます。このメディア項目を再生しようとすると再生エラーが発生します。
FALSE
メディア項目は保護されたコンテンツを含みません。

戻り値

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

vtbl 13 HRESULT GetDuration(GUID* guidPositionType, PROPVARIANT* pvDurationValue)

メディア項目の再生時間を取得します。

guidPositionTypeGUID*in

再生時間の値に使用する時間単位を指定します。次の値が定義されています。

意味
MFP_POSITIONTYPE_100NS
100 ナノ秒単位。

pvDurationValue で返される値は LARGE_INTEGER です。

  • バリアント型 (vt): VT_I8
  • バリアントメンバー: hVal
pvDurationValuePROPVARIANT*out再生時間を受け取る PROPVARIANT へのポインター。

戻り値

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

解説(Remarks)

このメソッドは、IMFPMediaItem::SetStartStopPosition で設定された値に関係なく、コンテンツの総再生時間を返します。

#include <propvarutil.h>

HRESULT GetPlaybackDuration(IMFPMediaItem *pItem, ULONGLONG *phnsDuration)
{
    PROPVARIANT var;

    HRESULT hr = pItem->GetDuration(MFP_POSITIONTYPE_100NS, &var);

    if (SUCCEEDED(hr))
    {
        hr = PropVariantToUInt64(var, phnsDuration);
        PropVariantClear(&var);
    }

    return hr;
}
vtbl 14 HRESULT GetNumberOfStreams(DWORD* pdwStreamCount)

メディア項目内のストリーム(オーディオ、ビデオ、その他)の数を取得します。

pdwStreamCountDWORD*outストリームの数を受け取ります。

戻り値

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

vtbl 15 HRESULT GetStreamSelection(DWORD dwStreamIndex, BOOL* pfEnabled)

ストリームが再生対象として選択されているかどうかを照会します。(IMFPMediaItem.GetStreamSelection)

dwStreamIndexDWORDinストリームの 0 から始まるインデックス。ストリームの数を取得するには、IMFPMediaItem::GetNumberOfStreams を呼び出します。
pfEnabledBOOL*out

ブール値を受け取ります。

意味
TRUE
ストリームが選択されています。再生中、このストリームは再生されます。
FALSE
ストリームは選択されていません。再生中、このストリームは再生されません。

戻り値

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

解説(Remarks)

ストリームを選択または選択解除するには、IMFPMediaItem::SetStreamSelection を呼び出します。

vtbl 16 HRESULT SetStreamSelection(DWORD dwStreamIndex, BOOL fEnabled)

ストリームを選択または選択解除します。

dwStreamIndexDWORDinストリームの 0 から始まるインデックス。ストリームの数を取得するには、IMFPMediaItem::GetNumberOfStreams を呼び出します。
fEnabledBOOLin

ストリームを選択するか選択解除するかを指定します。

意味
TRUE
ストリームが選択されています。再生中、このストリームは再生されます。
FALSE
ストリームは選択されていません。再生中、このストリームは再生されません。

戻り値

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

解説(Remarks)

このメソッドを使用して、どのストリームを選択するかを変更できます。変更は、このメディア項目を指定して次に IMFPMediaPlayer::SetMediaItem が呼び出されたときに反映されます。メディア項目がすでにプレイヤーに設定されている場合、このメディア項目を指定して SetMediaItem を再度呼び出さない限り変更は反映されません。

vtbl 17 HRESULT GetStreamAttribute(DWORD dwStreamIndex, GUID* guidMFAttribute, PROPVARIANT* pvValue)

メディア項目からストリーム属性を照会します。

dwStreamIndexDWORDinストリームの 0 から始まるインデックス。ストリームの数を取得するには、IMFPMediaItem::GetNumberOfStreams を呼び出します。
guidMFAttributeGUID*in

照会する属性値を識別する GUID。取り得る値は次のトピックに一覧されています:

pvValuePROPVARIANT*out値を受け取る PROPVARIANT へのポインター。このメソッドは、格納されている値のコピーを PROPVARIANT に格納します。このメソッドによって割り当てられたメモリを解放するには、PropVariantClear を呼び出します。

戻り値

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

解説(Remarks)

ストリーム属性は、プレゼンテーション内の個々のストリーム(オーディオ、ビデオ、またはその他)を記述します。プレゼンテーション全体に適用される属性を取得するには、IMFPMediaItem::GetPresentationAttribute を呼び出します。

vtbl 18 HRESULT GetPresentationAttribute(GUID* guidMFAttribute, PROPVARIANT* pvValue)

メディア項目からプレゼンテーション属性を照会します。

guidMFAttributeGUID*in

照会する属性値を識別する GUID。

プレゼンテーション属性の一覧については、Presentation Descriptor Attributes を参照してください。

pvValuePROPVARIANT*out値を受け取る PROPVARIANT へのポインター。このメソッドは、格納されている値のコピーを PROPVARIANT に格納します。このメソッドによって割り当てられたメモリを解放するには、PropVariantClear を呼び出します。

戻り値

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

解説(Remarks)

プレゼンテーション属性は、プレゼンテーション全体を記述します。プレゼンテーション内の個々のストリームに適用される属性を取得するには、IMFPMediaItem::GetStreamAttribute を呼び出します。

vtbl 19 HRESULT GetCharacteristics(DWORD* pCharacteristics)

メディア項目を記述するさまざまなフラグを取得します。

pCharacteristicsDWORD*out_MFP_MEDIAITEM_CHARACTERISTICS 列挙体のフラグのビットごとの OR を受け取ります。

戻り値

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

vtbl 20 HRESULT SetStreamSink(DWORD dwStreamIndex, IUnknown* pMediaSink)

メディア項目にメディアシンクを設定します。

dwStreamIndexDWORDinメディアソース上のストリームの 0 から始まるインデックス。メディアシンクはこのストリームからデータを受け取ります。
pMediaSinkIUnknown*inoptional

メディアシンクを指定する IUnknown ポインター。次のいずれかを渡します:

  • ストリームシンクへのポインター。すべてのメディアシンクは 1 つ以上の ストリームシンク を含みます。各ストリームシンクは 1 つのストリームからデータを受け取ります。ストリームシンクは IMFStreamSink インターフェイスを公開する必要があります。
  • メディアシンクを作成するアクティベーションオブジェクトへのポインター。アクティベーションオブジェクトは IMFActivate インターフェイスを公開する必要があります。メディア項目はメディアシンク上の最初のストリームシンク(すなわちインデックス 0 のストリームシンク)を使用します。
  • NULLpMediaSinkNULL を設定した場合、ストリーム型の既定のメディアシンクが使用されます。

戻り値

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

解説(Remarks)

既定では、MFPlay プレイヤーオブジェクトはオーディオストリームを Streaming Audio Renderer(SAR)に、ビデオストリームを Enhanced Video Renderer(EVR)にレンダリングします。SetStreamSink メソッドを使用すると、オーディオまたはビデオストリームに対して別のメディアシンクを指定したり、オーディオやビデオ以外のストリーム型をサポートしたりできます。また、SAR や EVR を使用する前に構成するためにも使用できます。

このメソッドは IMFPMediaPlayer::SetMediaItem を呼び出す前に呼び出してください。SetMediaItem の後にこのメソッドを呼び出しても効果はありません。ただし、再生を停止して SetMediaItem を再度呼び出す場合を除きます。

メディア項目を既定のメディアシンクを使用するようにリセットするには、pMediaSinkNULL を設定します。

リモート再生の最適化

アプリケーションがリモートデスクトップ経由で実行されていて、オーディオまたはビデオストリームに対して NULL 以外の値でこのメソッドを呼び出すと、MFPlay はリモート再生の最適化を無効にします。この注意事項はオーディオおよびビデオストリームにのみ適用されます。テキストなど、それ以外のデータ型を含むストリームには適用されません。
vtbl 21 HRESULT GetMetadata(IPropertyStore** ppMetadataStore)

作成者やタイトルなど、ソースのメタデータを含むプロパティストアを取得します。

ppMetadataStoreIPropertyStore**out読み取り専用のプロパティストアの IPropertyStore インターフェイスへのポインターを受け取ります。呼び出し元はこのインターフェイスを解放する必要があります。

戻り値

このメソッドが成功した場合は 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_IMFPMediaItem "{90EB3E6B-ECBF-45CC-B1DA-C6FE3EA70D57}"
#usecom global IMFPMediaItem IID_IMFPMediaItem "{}"
#comfunc global IMFPMediaItem_GetMediaPlayer            3 sptr
#comfunc global IMFPMediaItem_GetURL                    4 var
#comfunc global IMFPMediaItem_GetObject                 5 sptr
#comfunc global IMFPMediaItem_GetUserData               6 var
#comfunc global IMFPMediaItem_SetUserData               7 sptr
#comfunc global IMFPMediaItem_GetStartStopPosition      8 var,var,var,var
#comfunc global IMFPMediaItem_SetStartStopPosition      9 var,var,var,var
#comfunc global IMFPMediaItem_HasVideo                  10 var,var
#comfunc global IMFPMediaItem_HasAudio                  11 var,var
#comfunc global IMFPMediaItem_IsProtected               12 var
#comfunc global IMFPMediaItem_GetDuration               13 var,var
#comfunc global IMFPMediaItem_GetNumberOfStreams        14 var
#comfunc global IMFPMediaItem_GetStreamSelection        15 int,var
#comfunc global IMFPMediaItem_SetStreamSelection        16 int,int
#comfunc global IMFPMediaItem_GetStreamAttribute        17 int,var,var
#comfunc global IMFPMediaItem_GetPresentationAttribute  18 var,var
#comfunc global IMFPMediaItem_GetCharacteristics        19 var
#comfunc global IMFPMediaItem_SetStreamSink             20 int,sptr
#comfunc global IMFPMediaItem_GetMetadata               21 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。