Microsoft DirectX 8.0 (C++)

DMUS_OBJECTDESC

Used to describe a DirectMusic 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
} 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:
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. All the standard objects have defined identifiers consisting of "CLSID_" plus the name of the object. For example, a segment object is identified as CLSID_DirectMusicSegment. See the defines in the Dmusici.h header file.
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
Data in memory.
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 be filled with 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 copy of the stream which 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.

Requirements

  Header: Declared in dmusici.h.