Microsoft DirectX 9.0


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.


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



Size of the structure, in bytes. This member must be initialized to sizeof(DMUS_OBJECTDESC) before the structure is passed to any method.


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.


Unique identifier for this object.


Unique identifier for the class of object. See DirectMusic Component GUIDs.


Date that the object was last edited.


DMUS_VERSION structure containing version information.


Name of the object.


Category for the object.


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.


Size of data in memory.


Pointer to data in memory. Do not use this value except when loading from a resource contained in the executable file.


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.


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.


  Header: Declared in dmusici.h.

See Also