Custom Loading

Specialized applications might create their own object types that encapsulate data from a file or resource. It can be convenient to have the DirectMusic loader handle the loading of such objects. This is especially true if the custom object is referenced by other objects or contains references to other objects.

To implement a loading mechanism that takes advantage of the DirectMusic loader, take the following steps:

• Register the object class so that it can be found by IDirectMusicLoader8::GetObject.
• Implement the IDirectMusicObject8 interface on the object so that the loader can get the information that it needs to find and cache it.
• Implement the IPersistStream interface on the object, with full functionality in the IPersistStream::Load method. This is where you parse the data that you obtain through calls on the IStream interface passed by the DirectMusic loader.
• In the implementation of Load, ensure that references to other objects are dealt with by querying the IStream for the IDirectMusicGetLoader8 interface, then calling IDirectMusicGetLoader8::GetLoader to obtain a pointer to the DirectMusic loader that created the stream. Once you have this pointer, you can call IDirectMusicLoader8::GetObject to load the new object.

It might happen that an application needs to manage file input itself—for example, because all objects are stored in a special compressed resource file. The application can create its own loader by creating an object that supports the IDirectMusicLoader8 interface, with at least the IDirectMusicLoader8::GetObject method implemented. This implementation of the loader must also create its own stream object that has both the IStream and the IDirectMusicGetLoader8 interfaces.

To support container objects, the loader must also implement the IDirectMusicLoader8::SetObject method. The implementation should retain all information in the given DMUS_OBJECTDESC structure, copying the stream pointer if necessary. It should then create the object and call IDirectMusicObject8::ParseDescriptor to obtain the rest of the object's information.  However, it should not actually load the object until GetObject is called. If only containers with embedded objects need to be handled, only the case where DMUS_OBJ_STREAM is set needs to be implemented.

When caching objects, the loader should store at least the object's GUID, CLSID, and file name.