Implementing a Tool in the Client Application

All tools other than the output tool are collected in toolgraphs. Even if your application is using only a single tool, you must create a toolgraph to contain it. Then add this toolgraph to a segment or the performance. Toolgraphs provide a convenient mechanism for directing messages from one tool to another.

Note   Do not use or distribute tools from non-trusted sources. Tools can contain unsafe code.

The following sample code is from a client that uses a tool in a DLL. First, the client  creates an object from a known class identifier and a known interface identifier. It then obtains the IDirectMusicTool8 interface, creates a graph, and inserts the tool in the graph. It is assumed that the ILyricsReader interface, together with the CLSID and IID, is declared in an included tool header.

HRESULT SetupLyricsTool(IDirectMusicPerformance8* pPerf)
{ 
  ILyricsReader* pLyricsReader;
  IDirectMusicTool* pTool;
  IDirectMusicGraph* pGraph;
  HRESULT hr;
 
  if (SUCCEEDED(hr = CoCreateInstance(CLSID_LyricsReader, NULL,
                CLSCTX_INPROC_SERVER, IID_ILyricsReader, 
               (void **) &pLyricsReader)))
  {
    if (SUCCEEDED(hr = pLyricsReader->QueryInterface(IID_IDirectMusicTool8,
      (void**)&pTool)))
    {
      if ( SUCCEEDED(hr = CoCreateInstance( CLSID_DirectMusicGraph, NULL,
          CLSCTX_INPROC, IID_IDirectMusicGraph, (void**)&pGraph)))
      {
        if (SUCCEEDED(pGraph->InsertTool(pTool, NULL, 0, 0 )))
        {
          hr = pPerf->SetGraph(pGraph);
        }
        pGraph->Release();
      }
    }
  }
  return hr;
}

The tool will now process messages from all segments in the performance. To restrict the application of the tool to a particular segment, use IDirectMusicSegment8::SetGraph instead.