DMUS_OBJECTDESC

DirectMusic のロード可能オブジェクトの情報を格納します。この構造体は IDirectMusicLoader::GetObject メソッドに渡されて、ローダがストレージから取得するオブジェクトが識別されます。

#define DMUS_MAX_NAME           64
#define DMUS_MAX_CATEGORY       64
#define DMUS_MAX_FILENAME      260

typedef struct _DMUS_OBJECTDESC {
    DWORD        dwSize;
    DWORD        dwValidData;
    GUID         guidObject;
    GUID         guidClass;
    FILETIME     ftDate;
    DMUS_VERSION vVersion;
    WCHAR        wszName[DMUS_MAX_NAME];
    WCHAR        wszCategory[DMUS_MAX_CATEGORY];
    WCHAR        wszFileName[DMUS_MAX_FILENAME];
    LONGLONG     llMemLength;
    LPBYTE       pbMemData;
    IStream     *pStream;
} DMUS_OBJECTDESC, *LPDMUS_OBJECTDESC;

メンバ

dwSize

構造体がメソッドに渡される前に、この構造体のサイズをバイト単位で指定しておきます。 848 を指定します。

dwValidData

構造体のどのメンバが有効であるかと、いくつかのメンバの詳細を指定するオプションフラグを指定します。

値	意味
0x00000001 (DMUS_OBJ_OBJECT)	guidObject メンバが有効です。
0x00000002 (DMUS_OBJ_CLASS)	guidClass メンバが有効です。
0x00000004 (DMUS_OBJ_NAME)	wszName メンバが有効です。
0x00000008 (DMUS_OBJ_CATEGORY)	wszCategory メンバが有効です。
0x00000010 (DMUS_OBJ_FILENAME)	wszFileName メンバが有効です。 DMUS_OBJ_FULLPATH フラグが指定されている場合は、このフラグも指定されているとみなされます。
0x00000020 (DMUS_OBJ_FULLPATH)	wszFileName メンバはファイルのフルパス名またはアプリケーションディレクトリからの相対パスのいずれかで指定されています。このとき、 IDirectMusicLoader::SetSearchDirectory メソッドで設定されたディレクトリは検索されません。このフラグが指定されていない場合は、wszFileName メンバのファイル名はアプリケーションディレクトリからの相対パスか、もしくはそのオブジェクトタイプに対して SetSearchDirectory メソッドが呼び出されている場合はその検索ディレクトリに含まれているファイル名であるとみなされます。
0x00000040 (DMUS_OBJ_URL)	wszFileName メンバは URL です。現段階ではサポートされていません。
0x00000080 (DMUS_OBJ_VERSION)	vVersion メンバが有効です。
0x00000100 (DMUS_OBJ_DATE)	ftDate メンバが有効です。
0x00000200 (DMUS_OBJ_LOADED)	オブジェクトは現在メモリ内にロードされています。
0x00000400 (DMUS_OBJ_MEMORY)	オブジェクトはメモリ内にあり、 pbMemData メンバと llMemLength メンバが有効です。
0x00000800 (DMUS_OBJ_STREAM)	pStream メンバが有効です。

guidObject

オブジェクトの識別値（ GUID ）が格納されます。

guidClass

オブジェクトのクラス識別値（ CLSID ）が格納されます。

ftDate

オブジェクトが最後に編集された日付を表す FILETIME 構造体が格納されます。

vVersion

バージョン情報を保持する DMUS_VERSION 構造体が格納されます。

wszName

オブジェクトの名前を表す Unicode 文字列が格納されます。

wszCategory

オブジェクトのカテゴリを表す Unicode 文字列が格納されます。

wszFileName

ファイルパスを表す Unicode 文字列が格納されます。 dwValidData メンバに DMUS_OBJ_FULLPATH フラグが指定されている場合は、このパスはフルパスです。それ以外の場合はファイル名です。 IDirectMusicLoader8::SetSearchDirectory メソッドが呼び出されていた場合は、ファイル名のみでなければなりません。

llMemLength

メモリ内のデータのサイズが格納されます。

pbMemData

メモリ内のデータのアドレスが格納されます。実行可能ファイルに含まれているリソースからロードする場合以外では使用すべきではありません。

pStream

オブジェクトをメモリにロードするために使用することのできるカスタムストリームの IStream インターフェイスのアドレスが格納されます。ストリームを使用しない場合は 0 (NULL) になります。

解説

IDirectMusicLoader::GetObject メソッドでオブジェクトを取得するには、 wszName, guidObject, wszFileName メンバのうち少なくとも1つには有効なデータが含まれていなければなりません。

名前およびカテゴリを表す文字列には、 ANSI 文字列ではなく Unicode 文字列が使用されます。アプリケーションは必要に応じて文字列を変換しなければなりません。

アプリケーションは、オブジェクトデスクリプタにファイル名やメモリポインタを指定して IDirectMusicLoader::GetObject メソッドや IDirectMusicLoader::SetObject メソッドに渡す代わりに、 dwValidData メンバに DMUS_OBJ_STREAM フラグを指定して、 pStream メンバにストリームへのポインタを指定することで、ストリームを渡すことができます。アプリケーションが GetObject メソッドを呼び出すと、ローダはストリームの現在の位置を保存し、ストリームからオブジェクトを読み取り、保存された位置に戻ります。アプリケーションは GetObject メソッド呼び出しに影響を受けることなくストリームから読み取りつづけることができます。

ストリームが指定されて SetObject メソッドが呼び出されると、ローダはオブジェクトが後でロードされるときに使用されるストリームのコピーを作成します。従って、アプリケーションは SetObject メソッドにでストリームをローダに渡した後に、そのストリームを解放することも、ストリームから読み取りつづけることもできます。

変数との対応