| Microsoft DirectX 9.0 SDK Update (October 2004) |
The DMUS_OBJECTDESC structure is used to describe a loadable object. This structure is passed to the IDirectMusicLoader8::GetObject method to identify the object that the loader should retrieve from storage. Information about an object is retrieved in this structure by the IDirectMusicLoader8::EnumObject and IDirectMusicObject8::GetDescriptor methods.
Syntax
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;
Members
dwSize
Size of the structure, in bytes. This member must be initialized to sizeof(DMUS_OBJECTDESC) before the structure is passed to any method.
dwValidData
Flags describing which members are valid and giving further information about some members. The following values are defined:
| Flag | Description |
| DMUS_OBJ_CATEGORY | The wszCategory member is valid. |
| DMUS_OBJ_CLASS | The guidClass member is valid. |
| DMUS_OBJ_DATE | The ftDate member is valid. |
| DMUS_OBJ_FILENAME | The wszFileName member is valid. The presence of this flag is assumed if DMUS_OBJ_FULLPATH is set. |
| DMUS_OBJ_FULLPATH | The wszFileName member contains either the full path of a file or a path relative to the application directory. The directory set by IDirectMusicLoader8::SetSearchDirectory is not searched. If this flag is not set, wszFilename is always assumed to be relative to the application directory, or to the search directory if SetSearchDirectory has been called for this object type. |
| DMUS_OBJ_LOADED | The object is currently loaded in memory. |
| DMUS_OBJ_MEMORY | The object is in memory, and llMemLength and pbMemData are valid. |
| DMUS_OBJ_NAME | The wszName member is valid. |
| DMUS_OBJ_OBJECT | The guidObject member is valid. |
| DMUS_OBJ_STREAM | The pStream member contains a pointer to the data stream. |
| DMUS_OBJ_URL | The wszFileName member contains a URL. URLs are not currently supported by the DirectMusic loader. |
| DMUS_OBJ_VERSION | The vVersion member is valid. |
guidObject
Unique identifier for this object.
guidClass
Unique identifier for the class of object. See DirectMusic Component GUIDs.
ftDate
Date that the object was last edited.
vVersion
DMUS_VERSION structure containing version information.
wszName
Name of the object.
wszCategory
Category for the object.
wszFileName
File path. If DMUS_OBJ_FULLPATH is set, this is the full path; otherwise, it is the file name. If the IDirectMusicLoader8::SetSearchDirectory method has been called, this member must contain only a file name.
llMemLength
Size of data in memory.
pbMemData
Pointer to data in memory. Do not use this value except when loading from a resource contained in the executable file.
pStream
Address of the IStream interface of a custom stream that can be used to load the object into memory. In most cases this value should be NULL.See Remarks.
Remarks
At least one of wszName, guidObject, and wszFileName must contain valid data to retrieve the object by using the IDirectMusicLoader8::GetObject method.
The name and category strings use 16-bit characters in the WCHAR format, not 8-bit ANSI characters. Be sure to convert as appropriate. You can use the C library mbstowcs function to convert from multibyte to Unicode and the wcstombs function to convert from Unicode back to multibyte.
Instead of passing on object descriptor to IDirectMusicLoader8::GetObject or IDirectMusicLoader8::SetObject with a filename or memory pointer, an application can pass a stream. This is done by setting the DMUS_OBJ_STREAM flag in dwValidData and a pointer to the stream in pStream. When the application calls GetObject, the loader saves the stream's current location, reads the object from the stream, and then restores the saved location. The application can continue reading from the stream without being affected by the call to GetObject.
When SetObject is called with a stream, the loader makes a clone of the stream object, and this clone is used if the object is later loaded. Thus an application can release a stream or continue to read from it after passing it to the loader by using SetObject. The actual data of the stream is not copied, so the application should not change or delete the data.
Requirements
Header: Dmusici.h
See Also