Containers

Containers are objects representing files that contain various objects. A container file might hold all the data necessary for a performance, including segments, styles, and DLS collections. Container files are typically created in DirectMusic Producer. Containers can also exist within segment and script files.

You load a container like any other object, using IDirectMusicLoader8::GetObject. This method makes all objects in the container known to the loader, so that you can then use GetObject to retrieve them by name or GUID.

After you have obtained the IDirectMusicContainer8 interface, you can enumerate the objects in the container by using IDirectMusicContainer8::EnumObject.

The following sample function loads a container, retrieves a segment from it by name, and returns an IDirectMusicSegment interface. For purposes of demonstration, the container object is created and released within the function; in practice, this should be done only once during the life of the application, to prevent duplication of objects.

IDirectMusicSegment* LoadSegmentFromContainer (
    IDirectMusicLoader8* pLoader, 
    WCHAR* wszFileName, 
    WCHAR* wszSegmentName )
 
{
  DMUS_OBJECTDESC ObjDesc; 
  IDirectMusicSegment* pSegment = NULL;
  IDirectMusicContainer8* pContainer = NULL;

// Load the container.
 
  HRESULT hr = pLoader->LoadObjectFromFile(CLSID_DirectMusicContainer,
  IID_IDirectMusicContainer8, wszFileName, (void**)&pContainer);
  if (FAILED(hr)) 
    return NULL;
 
// Describe the segment.
 
  ZeroMemory(&objDesc, sizeof(objDesc));
  objDesc.dwSize = sizeof(objDesc);
  objDesc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_NAME;
  objDesc.guidClass = CLSID_DirectMusicSegment;
  wcsncpy (objDesc.wszName, wszSegmentName, 
  sizeof(objDesc.wszName) - 1);
  objDesc.wszName[sizeof(objDesc.wszName) - 1] = 0;
 
// Load the segment.
 
  hr = pLoader->GetObject(&ObjDesc, IID_IDirectMusicSegment, 
  (void**) &pSegment);
 
// Release the container from the cache and destroy the object.

  if (pContainer)
  {  
    IDirectMusicObject *pObject = NULL;
    pContainer->QueryInterface(IID_IDirectMusicObject,
       (void **)&pObject);
    if (pObject)
    {
      pLoader->ReleaseObject(pObject);
      pObject->Release();
    }
    pContainer->Release();
  }
  if (S_OK != hr) return NULL;
  return pSegment;
}