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.
Header: Declared in dmusici.h.