Difference between revisions of "Media Center Automation"

From JRiverWiki
Jump to: navigation, search
 
(29 intermediate revisions by 6 users not shown)
Line 42: Line 42:
 
* [[MJPlaybackAutomation]] - controls playback and provides information about the currently playing track
 
* [[MJPlaybackAutomation]] - controls playback and provides information about the currently playing track
 
* [[MJFilesAutomation]] - represents a collection of files
 
* [[MJFilesAutomation]] - represents a collection of files
 +
* [[MJFileAutomation]] - object for dealing with a single file
 +
* [[MJCurPlaylistAutomation]] - interface for working with "Playing Now" (the current playlist)
 +
* [[MJMixerAutomation]] - provides volume, balance, and mute control
 +
* [[MJPlaylistsAutomation]] - represents a collection of playlists
 +
* [[MJPlaylistAutomation]] - interface for working with a single playlist
 +
* [[MJSchemeAutomation]] - interface for working with Media Library View Schemes
 +
* [[MJVersionAutomation]] - interface for getting Media Center  version information
 +
* [[MJInternetAutomation]] - interface for helping in downloading files from internet
 +
* [[MJViewItemAutomation]] - interface for creating / walking the Media Center tree structure
 +
* [[MJFieldsAutomation]] - interface for working with database fields
 +
* [[MJFieldAutomation]] - interface for working with an individual database field
 +
* [[MJZonesAutomation]] - interface for working with multi-zone playback system
 +
* [[MJZoneAutomation]] - interface for working with a single playback zone (requires MC 11.0.20 or later)
 +
* [[MJTaskAutomation]] - Interface for working with a task
 +
* [[MJServicesAutomation]] - interface for working with services
 +
* [[MJServiceAutomation]] - interface for working with a single service
 +
* [[MJCDDVDAutomation]] - interface for working with CD/DVDs
  
===Functions===
+
==Event Handling==
number GetNumberFiles()
+
MediaCenter version 11.1 and higher supports an event interface for automation clients.
Description: returns the number of files contained in the collection
 
Return Value: number of files
 
  
void Sort()
+
===Basics===
Description: sorts the list of files using user selected sorting scheme.
+
An event is fired upon certain actions with three string parameters:
 +
FireMJEvent(string1, string2, string3)
  
MJFileAutomation * GetFile(number nFile)
+
The first parameter is the event type and currently there is just one event type, namely "MJEvent type: MCCommand"
Description: gets the MJFileAutomation interface (see below) for the given file index
+
The second parameter identifies the MCC command. See the list below.
Parameters:
+
The third parameter is optional and may contain information specific to the command.
* nFile: the index of the file to retrieve (0 to GetNumberFiles() - 1)
 
Return Value: MJFileAutomation interface
 
  
void Play()
+
Here are the commands currently sent to the event handler:
Description: plays the list of files
+
* '''MCC: NOTIFY_TRACK_CHANGE'''
 +
** Fired when a new track starts to play
 +
** ''string3'' is the zone
 +
* '''MCC: NOTIFY_PLAYERSTATE_CHANGE'''
 +
** Fired when a the player state changes
 +
*** A new track starts to play
 +
*** Playback is stopped, paused, or started
 +
** ''string3 '' is the zone
 +
*'''MCC: NOTIFY_PLAYLIST_ADDED'''
 +
** Fired when a playlist is added by the user
 +
** ''string3'' is the playlist ID
 +
*'''MCC: NOTIFY_PLAYLIST_INFO_CHANGED'''
 +
** Fired when a playlist is renamed
 +
** Fired when a smartlist rule is changed
 +
** Fired when a station is added to My Stations
 +
** ''string3'' is the playlist ID
 +
*'''MCC: NOTIFY_PLAYLIST_FILES_CHANGED'''
 +
** Fired when a playlist's files change
 +
** Fired when a service notifies Media Center that the service's playlists need to be refreshed
 +
** ''string3'' is the playlist ID
 +
*'''MCC: NOTIFY_PLAYLIST_REMOVED'''
 +
** Fired when a playlist is removed
 +
** ''string3'' is the ID of the deleted playlist
 +
*'''MCC: NOTIFY_PLAYLIST_COLLECTION_CHANGED'''
 +
** Fired when a playlist is moved or copied
 +
** ''string3'' is not used
 +
*'''MCC: NOTIFY_PLAYLIST_PROPERTIES_CHANGED'''
 +
** Fired when a playlist property is changed
 +
** ''string3'' is the playlist ID
 +
* '''MCC: NOTIFY_SKIN_CHANGED'''
 +
** MC 12.0.211 or higher
 +
** Fired when the skin is changed
 +
** ''string3'' is not used
 +
* '''MCC: NOTIFY_VOLUME_CHANGED'''
 +
** MC 12.0.217 or higher
 +
** Fired when the volume is changed
 +
** ''string3'' is the zone
 +
* '''MCC: NOTIFY_EQ_CHANGED'''
 +
** MCC 12.0.217 or higher
 +
** Fired when the Equalizer settings are changed, or the Equalizer is turned on or off.
 +
** ''string3'' is not used
 +
** Because of internal implementation considerations, you will receive multiple copies of this event for each trigger.
  
void PlayOrShow()
+
===Event Handling and Zones===
Description: decides whether to play or show the list of files. If the list contains only image files then show command will be used, otherwise this function will use play command.
+
The events '''MCC: NOTIFY_TRACK_CHANGE''' and '''MCC: NOTIFY_PLAYERSTATE_CHANGE''' contain the zone where the change occurred. Media Center, however, will only notify changes in the currently active zone. If a track changes in the non-active zone, there will be no event. Only track changes in the active zone will have events.
  
boolean AlbumGroup(boolean bSort, boolean bGroupIfOneAlbum)
+
===Handling the events from Visual Basic===
Description: groups the list of files by album. If this function is used, the collection of files will contain one file from each album, which can be expanded using the MJFileAutomation::GetAlbumFiles(...) call.
+
To add a handler in VB.NET for events coming from Media Center:
Parameters:
 
* bSort: sort the list of files after grouping
 
* bGroupIfOneAlbum: instructs the function whether to group by album if the list contains only one album.  
 
Return Value: if grouping by album is possible, the function will return true, otherwise false.
 
  
void AddFile(string strFilename)
+
1. Add a reference to Media Center's type library ("Media Center 12.tlb"). In VB.NET use the Projects/Add Reference option, select the "COM" tab, then select "MediaCenter" from the list.
Description: Add the file to the collection
 
Parameters:
 
* strFilename: the name of the file to add
 
  
void AddFileByKey(number nKey)
+
2. Add the "Imports MediaCenter" statement to declaration section of the code.
Description: Add the file to the collection
 
Parameters:
 
* nKey: the key of the file to add
 
  
boolean RemoveFile(number nIndex)
+
3. In the main class section for your project (e.g. - Form1) do the following:
Description: Remove the file from the collection
+
  A) Declare your MC automation variable to handle events, like this:
Parameters:
+
        Dim WithEvents MC As MediaCenter.MCAutomation
* nIndex: the number of the file to remove
 
Return Value: true only if the file was removed
 
  
void RemoveAll()
+
  B) Create a delagate class object and set it up to handle the three parameters passed by MEDIACENTER's object:
Description: Remove all files from the collection
+
        Private _RelayEvent As RelayEvent
 +
        Delegate Sub RelayEvent(ByVal EventData1 As String, ByVal EventData2 As String, ByVal EventData3 As String)
  
string Analyze(string strWhat)
+
4. Create a subroutine to receive the event message and to perform actions based on it. It is triggered by the event handler created below in step 4:
Description: Analyze the files for information, currently size or duration is supported
+
  Private Sub MyRelayEvent(ByVal EventData1 As String, ByVal EventData2 As String, ByVal EventData3 As String)
Parameters:
+
      lbParam1.Text = EventData1
* strWhat: size or duration
+
      lbParam2.Text = Trim(EventData2)
Return Value: the size or duration, or "-1" if it couldn't be computed
+
      lbParam3.Text = EventData3
 +
      Application.DoEvents()
 +
  End Sub
  
void MoveToTop(number nIndex)
+
4.  Declare a handler function for the event.  In the handler function, your will need to assign the delegate pointer to the subroutine that will actually act on the event.  Then use the BeginInvoke function to transfer the event data when it is received:
Description: moves the specified file to the top position
+
  Public Sub MC_FireMJEvent(ByVal s0 As String, ByVal s1 As String, ByVal s2 As String) Handles MC.FireMJEvent
Parameters:
+
      _RelayEvent = New RelayEvent(AddressOf MyRelayEvent)
* nIndex: the number of the file to move
+
      BeginInvoke(_RelayEvent, s0, s1, s2)
 +
  End Sub
  
void Shuffle()
 
Description: shuffles the order of the collection
 
  
void Set(number nIndex, string strField, string strValue)
+
5. Events fired from MediaCenter will be received by "MC_FireMJEvent" and it will use the delegate pointer to trigger "MyRelayEvent", which can act on the event.
Description: Changes the field of the specified file to a new value
 
Parameters:
 
* nIndex: the position of the file in the collection
 
* strField: the name of the field to change
 
* strValue: the new value
 
  
number AddNewFile()
+
Note: The event handler is automatically created in a separate thread from the main routine/class.  One thread cannot make changes to another thread, so it is necessary to use the delegate pointer to make the main thread aware that the event occured and to receive the information.  Then the receiving subroutine, which is in the main thread, can make updates without creating an exception error.
* Description: Adds a new file to the end of the collection
 
* Return Value: non-zero only if a new file was added
 
  
number AddExistingFile(IDispatch *pdispFiles, long nIndex, nInsertIndex)
+
===Handling the events from Visual C++ with MFC===
Description: Add a file from another MJFilesAutomation object
+
In your C++ MFC application, you should have a class which is derived from CCmdTarget (or from CWnd or CDialog which derive from CCmdTarget). This class will sink the events from MC's automation object. In the sample code below, this class is called "CMyClass", substitute your class's name for CMyClass.
Parameters:
+
In the header file of the class, add the following import using the correct tlb path for your system. Also add the afxctl.h include file if you get warnings of undefined AfxConnectionAdvise and AfxConnectionUnadvise.
* pdispFiles: the IDispatch of the other MJFilesAutomation
 
* nIndex: the position of the file in the other object
 
* nInsertIndex: the position to insert at
 
Return Value: The position it was inserted at, or -1 if unable to insert
 
  
string Get(number nIndex, string strField)
+
  #import "C:\\Program Files\\J River\\Media Center 12\\Media Center 12.tlb" no_namespace, named_guids
Description: Get the value of a field for the specified file
+
  #include "afxctl.h"
Parameters:
 
* nIndex: the position of the file in the collection
 
* strField: the name of the field
 
Return Value: The value of the field
 
  
number Save(string strFilename, string strType, number nFlags)
+
Then within the header file's class declaration for CMyClass, add this code:
Description: Save the files as a playlist, either m3u or mpl format
+
<pre>
Parameters:
+
  DECLARE_DISPATCH_MAP()
* strFilename: The name of the playlist file
+
  DECLARE_INTERFACE_MAP()
* strType: "m3u" or "mpl"
+
  afx_msg void MJEvent(LPCTSTR strType, LPCTSTR strParam1, LPCTSTR strParam2);
* nFlags: For m3u, if nFlags & 0x1, then use relative paths
+
  IMJAutomationPtr m_pMJ;
Return Value: Nonzero on success, zero on failure
+
  DWORD m_SinkID;
 +
</pre>
  
void Filter(string strSearchString)
+
Now in the cpp file for the class, add these lines which connect your handler function to the correct entry in the dispatch map:
Description: Remove all files in the collection not meeting the criteria in strSearchString
+
<pre>
Parameters:
+
  BEGIN_DISPATCH_MAP(CMyClass, CCmdTarget)
* strSearchString: a Media Center search
+
    DISP_FUNCTION_ID(CMyClass,"MJEvent",1,MJEvent,VT_EMPTY,VTS_BSTR VTS_BSTR VTS_BSTR)
 +
  END_DISPATCH_MAP()
  
void AddFileOverwriteExistingInfo(string strFilename)
+
  BEGIN_INTERFACE_MAP(CMyClass, CCmdTarget)
Description: Add the file to the collection, overwriting the old information if it exists.
+
    INTERFACE_PART(CMyClass, DIID_IMJAutomationEvents, Dispatch)
Parameters:
+
  END_INTERFACE_MAP()
* strFilename: the name of the file
+
</pre>
  
===Properties===
+
Now add the following code to the constructor or wherever you do initialization:
number Position() (read / write)
+
<pre>
Description: the index of the selected file. When starting playback, the selected file will get played.  Other interfaces and functions may also honor the position.  Note that the position will be preserved through shuffles, removes, and other MJFiles functions. (-1 means no file is selected)
+
  CoInitialize(NULL);
 +
  EnableAutomation();
 +
  HRESULT hr = m_pMJ.GetActiveObject (L"MediaJukebox Application");
 +
  if (hr != S_OK)
 +
    m_pMJ.CreateInstance(L"MediaJukebox Application");
  
==MJFileAutomation - object for dealing with a single file==
+
  // Get a pointer to the sink IDispatch interface
===Functions===
+
  LPUNKNOWN pUnknownSink = GetIDispatch(FALSE);
MJPlaylistsAutomation * GetPlaylists()
 
Description: returns the collection of playlists that the given file is in
 
Return Value: MJPlaylistsAutomation interface (see below)  
 
  
string GetImageFile(MJImageFileFlags nImageFileFlag)
+
  // Connect the event source (MJ automation) to the sink
Description: gets the filename of an image associated with the file
+
  AfxConnectionAdvise(m_pMJ, DIID_IMJAutomationEvents, pUnknownSink, FALSE, &m_SinkID);
Parameters:
+
</pre>
* nImageFileFlag:
 
** IMAGEFILE_DISPLAY -  display image (tag or database) (uses MJ logo if file doesn't have an image)
 
** IMAGEFILE_IN_DATABASE - database image
 
** IMAGEFILE_IN_FILE - tag image (stored inside of file)
 
** IMAGEFILE_THUMBNAIL_SMALL, IMAGEFILE_THUMBNAIL_MEDIUM, IMAGEFILE_THUMBNAIL_LARGE - small, medium, and large thumbnail images for the file
 
** IMAGEFILE_DISPLAY_NO_DEFAULT - like IMAGEFILE_DISPLAY except that it won't return the logo when there is no art
 
** IMAGEFILE_DISPLAY_NO_DEFAULT_STANDARD_JPEG - like IMAGEFILE_DISPLAY_NO_DEFAULT except that it always returns a standard (non-progressive) JPEG
 
Note: Do not delete the files returned by this function.  Media Center will do any necessary cleanup.  Also, subsequent calls may return the same filename (if a temp file is being used) so you must load / cache the image instead of caching the filenames.
 
Return Value: a filename of the image file
 
  
string SetImageFile(string strImageFile, MJImageFileFlags nImageFileFlag)
+
Add the function body which receives the events:
Description: sets the image for the file
 
Parameters:
 
* strImageFile: filename of the image
 
* nImageFileFlag: IMAGEFILE_IN_DATABASE - database image, IMAGEFILE_IN_FILE - tag image (stored inside of file)
 
Return Value: 0 on failure, non-zero on success
 
  
string GetFormattedFileSize()
+
<pre>
Description: gets the display friendly file size
+
  // MJAutomationSink message handler
Return Value: a string representing the file size (i.e. "23.434 MB")
+
  void CMyClass::MJEvent(LPCTSTR strType, LPCTSTR strParam1, LPCTSTR strParam2)
 +
  {
 +
    // handle events here...
 +
  }
 +
</pre>
  
string GetFormattedFileDate()
+
And finally, add this code to the destructor or wherever you do final cleanup. The release for m_pMJ has to be called prior to CoUninitialize.
Description: gets the display friendly file date / time
+
<pre>
Return Value: a string representing the file date / time (i.e. "2/30/2002 8:01 PM")
+
  LPUNKNOWN pUnknownSink = GetIDispatch(FALSE);
 +
  AfxConnectionUnadvise(m_pMJ, DIID_IMJAutomationEvents, pUnknownSink, FALSE, m_SinkID);
 +
  m_pMJ.Release();
 +
  CoUninitialize();
 +
</pre>
  
string GetFormattedDuration()
+
===Handling the Events from Visual C++ with ATL===
Description: gets the display friendly duration
+
If you have a conventional Interface plugin that was generated using the ATL DLL and ATL composite controls, you can also sink MediaCenter's events.  Simply implement the IMJAutomationEvents (perhaps using class view->Implement Interface) using the IDispEventImpl template. The wizard will default to IDispatch, but you will need to use IDispEventImpl and the SINK_MAP functions to handle events correctly.
Return Value: a string representing the duration (i.e. "3:04")
 
  
string GetFormattedLastPlayed()
+
Ensure that the type library is imported as for the MFC version above. Set your SINK_MAP as follows:
Description: gets the display friendly last played date / time
 
Return Value: a string representing the duration (i.e. "2/30/2002 8:01 PM")
 
  
string GetAvailableFilename()
+
<pre>
Description: returns the filename in the format that's available to the system, so that files on a removable device get returned, for example, as "D:\1.mp3" instead of "(0xF43EA231):\1.mp3"
+
BEGIN_SINK_MAP(CEQdbCtrl)
Return Value: a string representing the filename
+
  SINK_ENTRY_EX(1, DIID_IMJAutomationEvents, 1, MJEvent)
 +
END_SINK_MAP()
 +
</pre>
  
boolean SaveToTag()
+
and then implement the MJEvent handler function
Description: Forces Media Center to save the file information to the tag.
 
Return Value: 0 - failed, 1 - success.
 
  
string Get(string strField, boolean bFormatted)
+
<pre>
Description: generic function to get value for the specified field.
+
STDMETHOD_(void, MJEvent)(LPCTSTR strType, LPCTSTR strParam1, LPCTSTR strParam2);
Parameters:
+
</pre>
* strField: name of the field (e.g. Artist, Album...)
 
* bFormatted: determines whether the return value should beformated.
 
Return Value: value of the field
 
  
boolean Set(string strField, string strValue)
+
Also, you need to advise the sink after attaching to the passed IDispatch* in your Init function.
Description: generic function to set value for the specified field.
 
Parameters:
 
* strField: name of the field (e.g. Artist, Album...)
 
* strValue: new value of the field
 
Return Value: 0 - failed, 1 - success.  
 
  
MJFilesAutomation * GetAlbumFiles()
+
<pre>
Description: retrieves the list of files which belong to the same album (use to expand after an album group)
+
HRESULT hr;
Return Value: MJFilesAutomation interface
+
hr = DispEventAdvise(m_pMJ, &DIID_IMJAutomationEvents);
 +
if(hr == S_OK) {
 +
  // Successfully advised.
 +
} else {
 +
  // Did not advise correctly.
 +
}
 +
</pre>
  
long GetKey()
+
Here's the (somewhat) tricky part.  Using the CComComposite class means that AtlAdviseSinkMap is called during the window constructor, and it will cause an ATLASSERT failure during debug builds.  This produces the "Abort" "Retry" "Ignore" message box stating there's been an assertion failure in atlcom.h.  Click ignore.  Once you move to release builds, it will compile to nothing and will not cause you any trouble.
Description: Gets the key of the file
 
Return Value: the key
 
  
boolean DeleteFile(long hwndParent)
+
[[Category:Developer]]
Description: Deletes the file (with confirmation)
 
Parameters:
 
* hwndParent: The handle of the parent window or null
 
Return Value: nonzero on success, zero on failure
 
 
 
boolean RotateImage(long nDegrees)
 
Description: If the file is a JPEG, rotate the image
 
Parameters:
 
* nDegrees: How much to rotate
 
Return Value: TRUE
 
 
 
string GetFilledTemplate(string strTemplate)
 
Description: Evaluates an expresion for the file and returns the result
 
Parameters:
 
* strTemplate: the expression
 
Return Value: the result
 
 
 
boolean SilentDeleteFile()
 
Description: Deletes the file (no confirmation)
 
Return Value: nonzero on success, zero on failure
 
 
 
void UpdatePlaybackStats(long nPlays)
 
Description: Increases the file playcount by nPlays and sets the last played time to now
 
Parameters:
 
* nPlays: number of times the file was played
 
 
 
boolean SaveInfoToExternalFile(string strFilename)
 
Description: Save the database information (cover art and fields) for the file to an external file
 
Parameters:
 
* strFilename: the name of the external file
 
Return Value: TRUE
 
 
 
boolean UpdateFromFile(boolean bForce, boolean bOnlyNewFields)
 
Description: Updates the fields from the file
 
Parameters:
 
* bForce: if true, force the update, otherwise only update if the file has changed
 
* bOnlyNewFields: Only change fields that are new
 
Return Value: TRUE only if the file was updated
 
 
 
void UpdateDBLocation(long nAppendDBLocations, long nRemoveDBLocations)
 
Description: Select which portions of the database the file appears in
 
Parameters:
 
* nAppendDBLocations: Which portions to add the file to. Value is a bitwise OR of
 
** DB_LOCATION_INVALID
 
** DB_LOCATION_MAIN
 
** DB_LOCATION_PLAYING_NOW
 
** DB_LOCATION_CD
 
** DB_LOCATION_EXPLORER
 
** DB_LOCATION_UNASSIGNED
 
** DB_LOCATION
 
** DB_LOCATION_FILE_TRANSFER
 
** DB_LOCATION_HANDHELD
 
** DB_LOCATION_GROUPING
 
** DB_LOCATION_REMOVED
 
** DB_LOCATION_DOWNLOADING
 
** DB_LOCATION_PODCAST_FEED
 
* nRemoveDBLocations: Which portions to remove the file from, same value as nAppendDBLocations
 
 
 
boolean SetNoDirty(string strField, string strValue)
 
Description: Change a file's field without marking it as dirty
 
Parameters:
 
* strField: the field name
 
* strValue: the field value
 
Return Value: nonzero on success, zero on failure
 
 
 
===Properties===
 
string Filename() (read / write)
 
Description: the filename (i.e. "c:\Music\Good Song.mp3")
 
 
 
string Artist() (read / write)
 
Description: the artist (i.e. "Metallica")
 
 
 
string Album() (read / write)
 
Description: the album (i.e. "ReLoad")
 
 
 
string Name() (read / write)
 
Description: the name of the track (i.e. "Unforgiven II")
 
 
 
number Filesize() (read / write)
 
Description: the filesize in bytes
 
 
 
number Duration() (read / write)
 
Description: the file duration in seconds
 
 
 
string Genre() (read / write)
 
Description: the genre (i.e. "Rock")
 
 
 
number Year() (read / write)
 
Description: the year (i.e. 1997)
 
 
 
string Comment() (read / write)
 
Description: the comment
 
 
 
number Bitrate() (read / write)
 
Description: the bitrate (i.e. 128 kbps)
 
 
 
number Tracknumber() (read / write)
 
Description: the track number (i.e. 4)
 
 
 
number Filedate() (read / write)
 
Description: the file's date (seconds past 1970)
 
 
 
string Custom1() (read / write)
 
Description: the MJ-specific "Custom1" field
 
 
 
string Custom2() (read / write)
 
Description: the MJ-specific "Custom2" field
 
 
 
string Custom3() (read / write)
 
Description: the MJ-specific "Custom3" field
 
 
 
number PlayCounter() (read / write)
 
Description: the number of times the track has been played in Media Center
 
 
 
number LastPlayed() (read / write)
 
Description: the date the file was last played in Media Center (seconds past 1970)
 
 
 
number Rating() (read / write)
 
Description: the rating (MJ-specific) (note: 0 = ?, otherwise 1-5)
 
 
 
string Filetype() (read / write)
 
Description: the extension of the file (used by MJ to choose playback plugins, etc.) (i.e. "mp3")
 
 
 
string Lyrics() (read / write)
 
Description: the lyrics
 
 
 
string Notes() (read / write)
 
Description: the notes
 
 
 
string AlbumArtist() (read / write)
 
Description: the album artist
 
 
 
==MJCurPlaylistAutomation - interface for working with "Playing Now" (the current playlist)==
 
===Functions===
 
number GetNumberFiles()
 
Description: returns the number of files in "Playing Now"
 
Return Value: number of files
 
 
 
MJFileAutomation * GetFile(number nFile)
 
Description: gets the MJFileAutomation interface (see below) for the given file index
 
Parameters:
 
Return Value: MJFileAutomation interface
 
 
 
void RemoveAllFiles()
 
Description: removes all of the files from "Playing Now" (stops playback)
 
 
 
boolean RemoveFile(number nFile)
 
Description: removes a specific file from "Playing Now"
 
Parameters:
 
* nFile: the index of the file to retrieve (0 to GetNumberFiles() - 1)
 
Return Value: 0 on failure, non-zero on success
 
 
 
boolean AddFile(string strFilename, number nPosition)
 
Description: adds a file to "Playing Now"
 
Parameters:
 
* strFilename: the filename of the file to add
 
* nFile: the new index of the file
 
Return Value: 0 on failure, non-zero on success
 
 
 
boolean MoveFile(number nFileOld, number nFileNew)
 
Description: moves a file to a new location in "Playing Now"
 
Parameters:
 
* nFileOld: the index of the file to move
 
* nFileNew: the index to move the file to
 
Return Value: 0 on failure, non-zero on success
 
 
 
boolean ReShuffleFiles()
 
Description: shuffles "Playing Now" so it's in a random order
 
Return Value: 0 on failure, non-zero on success
 
 
 
number GetNextFile()
 
Description: gets the index of the file to play on "Next"
 
Return Value: index of file
 
 
 
boolean GetPreviousFile()
 
Description: gets the index of the file to play on "Previous"
 
Return Value: index of file
 
 
 
boolean GetCanPlayNext()
 
Description: Determine if there is another file to play after the currently playing file
 
Return Value: true only if there is one
 
 
 
===Properties===
 
number Position() (read / write)
 
Description: the index of the current track
 
 
 
number Shuffle() (read / write)
 
Description: the shuffle state (0 = off, 1 = on)
 
 
 
number Continuous() (read / write)
 
Description: the continuous state (0 = off, 1 = on)
 
 
 
==MJMixerAutomation - provides volume, balance, and mute control==
 
===Functions===
 
 
 
void SetEQBand(number nBand, number nValue)
 
Description: sets the value of an equalizer band
 
Parameters:
 
* nBand: the equalizer band (0 = preamp, 1 - 10 = eq bands)
 
* nValue: the new band value (-100 to 100 where -100 is full cut, 0 is no gain, and 100 is full gain)
 
 
 
number GetEQBand(number nBand)
 
Description: gets the value of an equalizer band
 
Parameters:
 
* nBand: the equalizer band (0 = preamp, 1 - 10 = eq bands)
 
Return Value: value of the specified band (-100 to 100 where -100 is full cut, 0 is no gain, and 100 is full gain)
 
 
 
void UpdateEQSettings(number bUpdatePlayer, number bUpdateMiniMe)
 
Description: updates the internal settings to reflect outside changes (made in DSP Studio, etc.) -- not necessary in most cases
 
Parameters:
 
* bUpdatePlayer: whether to update the player window (0 = no, 1 = yes)
 
* bUpdateMiniMe: whether to update the mini-me window (0 = no, 1 = yes)
 
 
 
void ShowDSP()
 
Description: Activate the DSP
 
 
 
===Properties===
 
number Volume() (read / write)
 
Description: the volume (0 = no volume, 100 = full volume)
 
 
 
number Balance() (read / write)
 
Description: the balance between left and right (-100 = all left, 0 = centered, 100 = all right)
 
 
 
boolean Mute() (read / write)
 
Description: the mute state (0 = not muted, 1 = muted)
 
 
 
boolean EQOn() (read / write)
 
Description: whether the equalizer is on or off (0 = off, 1 = on)
 
 
 
==MJPlaylistsAutomation - represents a collection of playlists==
 
===Functions===
 
number GetNumberPlaylists()
 
Description: returns the number of playlists contained in the collection
 
Return Value: number of playlists
 
 
 
MJPlaylistAutomation * GetPlaylist(number nPlaylist)
 
Description: gets the MJPlaylistAutomation interface (see below) for the given playlist index
 
Parameters:
 
* nPlaylist: the index of the playlist to retrieve (0 to GetNumberPlaylists() - 1). To retrieve Top Hits and Recently Imported playlists use index -1 and -2 respectively.
 
Return Value: MJPlaylistAutomation interface
 
 
 
MJPlaylistAutomation * CreatePlaylist(string PlaylistPath, string PlaylistName)
 
Description: creates new playlist at the specified location
 
Parameters:
 
* PlaylistPath: location of the playlist. If empty, the playlist will be created in the root of the playlist tree.
 
* PlaylistName: name of the new playlist
 
Return Value: MJPlaylistAutomation interface
 
 
 
boolean DeletePlaylist(string PlaylistPath, string PlaylistName)
 
Description: deletes existing playlist
 
Parameters:
 
* PlaylistPath: location of theplaylist.
 
* PlaylistName: name of the new playlist
 
Return Value: true - if success, otherwise false.
 
 
 
IMJPlaylistAutomation *CreateServicelist(string Path, string Name, string Service, string ServiceID, string ServiceData)
 
Description: Finds or creates the playlist associated with a service
 
Parameters:
 
* Path: Not Used
 
* Name: The name of the playlist
 
* Service: The name of the service
 
* ServiceID: The ID of the service
 
* ServiceData: Service-specific data
 
Return Value: the MJPlaylistAutomation interface
 
 
 
==MJPlaylistAutomation - interface for working with a single playlist==
 
===Functions===
 
MJFilesAutomation * GetFiles()
 
Description: gets the collection of files in the playlist
 
Return Value: MJFilesAutomation interface
 
 
 
boolean AddFile(string strFilename, number nLocation)
 
Description: adds new file to the playlist
 
Parameters:
 
* strFilename: the filename of the file to add
 
* nLocation: position of the file in the playlist. If position -1, the file will be added to the end of the playlist.
 
Return Value: 0 on failure, non-zero on success
 
 
 
boolean RemoveFile(string strFilename)
 
Description: removes existing file from the playlist
 
Parameters:
 
* strFilename: the filename of the file to delete
 
Return Value: 0 on failure, non-zero on success
 
 
 
long GetID()
 
Description: returns the ID associated with a playlist
 
Return Value: the ID
 
 
 
string Get(string bstrProperty)
 
Description: lookup a property associated with a playlist
 
Parameters:
 
* bstrProperty: the name of the property
 
Return Value: the value of the property for this playlist
 
 
 
void Set(string strProperty, string bstrValue)
 
Description: change the value of a property for this playlist
 
Parameters:
 
* strProperty: the property name
 
* bstrValue: The new value
 
 
 
boolean SaveAsRSS(string strFilename, string strURLPrefix, string strUser, string strEmail)
 
Description: 11.1.134 or higher, saves the playlist as an RSS (PodCast/PerbCast) file
 
Parameters:
 
* strFilename: the filename of the RSS file
 
* strURLPrefix: The URL prefix which will be concatenated with the keys of the playlist files to form the URL for accessing them
 
* strUser: the name of the PerbCast creator
 
* strEmail: the e-mail address of the PerbCast creator
 
Return Value: 0 on failure, non-zero on success
 
 
 
===Properties===
 
string Name() (read / write)
 
Description: the name of the playlist (i.e. "My Playlist")
 
 
 
string Path() (read / write)
 
Description: the path of the playlist, delimited by backslashes (note: does not contain the name) (i.e. "Mixes\\New Playlist Group")
 
 
 
==MJSchemeAutomation - interface for working with Media Library==
 
===Functions===
 
string GetName()
 
Description: gets the name of the scheme item (i.e. "Classic Rock", "Artist\Album", etc.)
 
Return Value: a string containing the name of the scheme item
 
 
 
number GetNumberSchemes()
 
Description: gets the number of children schemes
 
Return Value: number of children schemes
 
 
 
MJSchemeAutomation * GetScheme(number nScheme)
 
Description: gets the specified child scheme
 
Parameters:
 
*  nScheme: the index of the child scheme to retrieve (0 to GetNumberSchemes() - 1)
 
Return Value: a MJSchemeAutomation interface for the specified child scheme
 
 
 
MJFilesAutomation * GetFiles()
 
Description: gets the collection of files in the scheme
 
Return Value: MJFilesAutomation interface of files
 
 
 
string GetSchemeName(number nScheme)
 
Description: gets the name of the specified child scheme (faster than GetScheme(...))
 
Parameters:
 
* nScheme: the index of the child scheme to retrieve (0 to GetNumberSchemes() - 1)
 
Return Value: a string containing the name of the child scheme item
 
 
 
==MJVersionAutomation - interface for getting Media Center  version information==
 
===Properties===
 
number Major (read only)
 
Description: Major version of the Media Center (i.e. 9)
 
 
 
number Minor (read only)
 
Description: Minor Version of the Media Center (i.e. 0)
 
 
 
number Build (read only)
 
Description: Build number of the Media Center (i.e. 160)
 
 
 
string Version (read only)
 
Description: string version of the Media Center (i.e. "9.0.160")
 
 
 
==MJInternetAutomation - interface for helping in downloading files from internet==
 
===Functions===
 
string DownloadToString(string URL)
 
Description: Downloads web page from the specified URL to a string. (should not be used with binary data, only web pages)
 
Parameters:
 
* URL: The URL from which the web page will be downloaded
 
Return Value: a string containing the contents of the web page.
 
 
 
number DownloadToFile(string URL, string FileName)
 
Description: Downloads data from a resource identified by a URL to a local file.
 
Parameters:
 
* URL: The URL from which the data will be downloaded.
 
* FileName: The name of the local file to receive the data.
 
Return Value: True if the function completed successfully, otherwise FALSE.
 
 
 
string DownloadToTempFile(string URL)
 
Description: Downloads data from a resource identified by a URL to a local temp file.
 
Parameters:
 
* URL: The URL from which the data will be downloaded.
 
Return Value: Returns the full path to the temp file.
 
 
 
void Cancel()
 
Description: Cancels previously called download function. Can be used only when DownloadMode set to DOWNLOADMODE_NO_UI or DOWNLOADMODE_NO_UI_BLOCKING.
 
 
 
===Properties===
 
MJInetDownloadModes DownloadMode (read / write)
 
Description: Gets or sets download mode.
 
* DOWNLOAD_MODE_DEFAULT - displays UI while downloading files from the Internet
 
* DOWNLOADMODE_NO_UI - does not display UI but processes the message loop so the Cancel function can be called from the same thread.
 
* DOWNLOADMODE_BLOCKING - will lock the app until the download is finished.
 
* DOWNLOAD_MODE_NO_AUTHENTICATION - disables authentication.
 
Example:
 
MJIA.DownloadMode = DOWNLOADMODE_NO_UI DOWNLOADMODE_BLOCKING;
 
 
 
==MJViewItemAutomation - interface for creating / walking the Media Center tree structure==
 
===Functions===
 
string GetName()
 
Description: gets the name of this item
 
Return Value: the name of the item
 
 
 
string GetFullName()
 
Description: gets the full name of this item (the whole path -- backslash delimited -- i.e. Media Library\Audio\Artist/Album\Bob Dylan)
 
Return Value: the full name of the item
 
 
 
MJFilesAutomation * GetFiles()
 
Description: gets the files associated with the current item
 
Return Value: MJFilesAutomation interface
 
 
 
void DoCommand(number nParam)
 
Description: performs the command associated with the current item (play / show, playing now command, etc.)
 
Parameters:
 
* nParam: for future use -- must be zero
 
 
 
number GetNumberChildren()
 
Description: gets the number of child items
 
Return Value: the number of children
 
 
 
string GetChildName(number nIndex)
 
Description: gets the name of a child item
 
Parameters:
 
* nIndex: the index of the child item (0 to GetNumberChildren() - 1)
 
Return Value: the name of the child item
 
 
 
MJViewItemAutomation * GetChild(number nIndex)
 
Description: gets the MJViewItemAutomation interface (see below) for the given child index
 
Parameters:
 
* nIndex: the index of the child to retrieve (0 to GetNumberChildren() - 1)
 
Return Value: MJViewItemAutomation interface
 
 
 
boolean GetChildHasChildren(number nIndex)
 
Description: gets the name of a child item
 
Parameters:
 
* nIndex: the index of the child item (0 to GetNumberChildren() - 1)
 
Return Value: whether the specified child has children of its own
 
 
 
MJViewItemAutomation * GetParent()
 
Description: gets the parent item
 
Return Value: MJViewItemAutomation interface
 
 
 
string GetThumbnailFilenames(number nThumbnailSize, number nMaxCount)
 
Description: not implemented
 
Parameters:
 
* nThumbnailSize: N/A
 
* nMaxCount: N/A
 
Return Value: N/A
 
 
 
boolean GetChildIsFolder(number nIndex)
 
Description: determine if the specified child contains sub-view items
 
Parameters:
 
* nIndex: the number of the child
 
Return Value: true only if the child contains sub-view items
 
 
 
boolean GetIsSearch()
 
Description: not implemented
 
Return Value: FALSE
 
 
 
==MJFieldsAutomation - interface for working with database fields==
 
===Functions===
 
number GetNumberFields()
 
Description: gets the total number of database fields
 
Return Value: the number of fields
 
 
 
IMJFieldAutomation * GetField(number nField)
 
Description: gets the field at the given index
 
Parameters:
 
* nField: the zero based index of the field
 
Return Value: MJFieldAutomation * to the field (see documentation below)
 
 
 
IMJFieldAutomation * CreateFieldSimple(string strFieldName, string strDisplayName, number bAllowEdit, long bSaveInTag)
 
Description: Creates a new field
 
Parameters:
 
* strFieldName: the internal name of the new field
 
* strDisplayName: the name displayed to the user
 
* bAllowEdit: can field be changed by user
 
* bSaveInTag: save the field in the tag in the content file
 
Return Value: the FieldAutomation interface for the new field
 
 
 
==MJFieldAutomation - interface for working with an individual database field==
 
===Functions===
 
string GetName(boolean bFormatted)
 
Description: gets the name of the field
 
Parameters:
 
* bFormatted: 0 = returns the unique name of the field as used in DB lookups, 1 = returns the display name of the field (not necessarily unique)
 
Return Value: the field name
 
 
 
==MJZonesAutomation - interface for working with multi-zone playback system==
 
===Functions===
 
number GetNumberZones()
 
Description: gets the total number of playback zones
 
Return Value: the number of playback zones
 
 
 
number GetActiveZone()
 
Description: gets the index of the active zone
 
Return Value: index of active zone
 
 
 
void SetActiveZone(number nIndex)
 
Description: sets the index of the active zone.
 
* nIndex: the zero based index of the new zone
 
 
 
string GetZoneName(number nIndex)
 
Description: gets the name of a given zone
 
Parameters:
 
* nIndex: the zero based index of the new zone
 
Return Value: the name of the zone
 
 
 
MJZoneAutomation * GetZone(number nIndex) (requires MC 11.0.20 or later)
 
Description: gets a MJZoneAutomation interface for this zone (see below)
 
Return Value: MJZoneAutomationinterface
 
 
 
void SynchronizeZones(number nSource, number nDestination)
 
Description: attempts to have the two zones play the same content at the same time
 
Parameters:
 
* nSource: the master zone
 
* nDestination: the slave zone
 
 
 
==MJZoneAutomation - interface for working with a single playback zone (requires MC 11.0.20 or later)==
 
===Functions===
 
 
 
        string GetName()
 
 
 
            Description: gets the name of the zone
 
            Return Value: the name of the zone
 
 
 
        MJPlaybackAutomation * GetPlayback()
 
 
 
            Description: gets a MJPlayback interface for this zone (see above)
 
            Return Value: MJPlayback interface
 
 
 
        MJCurPlaylistAutomation * GetCurPlaylist()
 
 
 
            Description: gets a MJCurPlaylistAutomation interface for this zone (see above)
 
            Return Value: MJCurPlaylistAutomation interface
 
 
 
        IMJMixerAutomation * GetMixer()
 
 
 
            Description: gets a MJMixerAutomation interface for this zone
 
            Return Value: the interface
 
 
 
        IMJFileAutomation * GetPlayingFile()
 
 
 
            Description: get a MJFileAutomation interface for the file currently playing in this zone
 
            Return Value: the interface
 
 
 
==MJTaskAutomation - Interface for working with a task==
 
===Functions===
 
 
 
        void Pump()
 
 
 
            Description: pumps the task's message loop
 
 
 
==MJServicesAutomation - interface for working with services==
 
===Functions===
 
 
 
        VARIANT_BOOL GetLicense(string bstrFilename)
 
 
 
            Description: Get a license for a content file
 
            Parameters:
 
 
 
                bstrFilename: the name of the content file
 
 
 
            Return Value: true if the license was retrieved, false otherwise
 
 
 
        IMJServiceAutomation *GetService(string bstrServiceName)
 
 
 
            Description: Get a service by name
 
            Parameters:
 
 
 
                bstrServiceName: the name of the service
 
 
 
            Return Value: a MJServiceAutomation interface
 
 
 
==MJServiceAutomation - interface for working with a single service==
 
===Functions===
 
 
 
        BOOL Process(string bstrCurrentURL, string bstrNewURL, string bstrPostData)
 
 
 
            Description: calls a service's Process function
 
            Parameters:
 
 
 
                bstrCurrentURL: the current URL for the service
 
                bstrNewURL: the URL to visit
 
                bstrPostData: empty or the name of a file containing POST data, the file will be deleted
 
 
 
            Return Value: TRUE on success, FALSE otherwise
 
 
 
        BOOL Execute(string bstrCommand, VARIANT vFileDisp, string *bstrResult)
 
 
 
            Description: calls a service's Execute function
 
            Parameters:
 
 
 
                bstrCommand: the command
 
                vFileDisp: MJFilesAutomation interface
 
                bstrResult: a pointer to the result
 
 
 
            Return Value: TRUE on success, FALSE otherwise
 
 
 
        LPDISPATCH GetWebBrowserHTMLDocument()
 
 
 
            Description: get the currently viewed service web page
 
            Return Value: an IDispatch pointer to an IHTMLDocument2 interface
 
 
 
==MJCDDVDAutomation - interface for working with CD/DVDs==
 
===Functions===
 
        IMJFilesAutomation *GetFiles(string strPath)
 
 
 
            Description: Get the files on the device named
 
            Parameters:
 
 
 
                strPath: the name of the device
 
 
 
            Return Value: MJFilesAutomation interface
 

Latest revision as of 10:30, 7 April 2014

Media Center exports much of its power and functionality through COM automation interfaces. This makes it easy to create your own plug-ins for Media Center that integrate tightly with its interface. Since automation interfaces are based on COM, these plug-ins can be written in almost any language. (C++, VB, Delphi, etc.). Also, the interfaces can be accessed in Metamorphis skins and Display plug-ins (see documentation for the plug-ins). Prior to build 9.1.238, the only way to access the automation interfaces was to write a plug-in for MC because the interfaces were not accessible by objects which were outside Media Center's process. Now, any application, including VBS and Java script, can start MC or just run it to query information about MC's database.

The functions in this document are for Media Center 11.1. Most will work with earlier versions, but not all.

Initialization

Media Center can be initialized by in-proc or out-of-proc objects.

Out-of-proc initialization (C++):

#import "Media Jukebox.tlb" no_namespace, named_guids

void GetMJAutomation()
{
    IMJAutomationPtr pMJ;

    HRESULT hr = pMJ.GetActiveObject (L"MediaJukebox Application");
    if (hr != S_OK)
        pMJ.CreateInstance(L"MediaJukebox Application");
}

Out-of-proc initialization (VB):

Private Sub Form_Load()
' First try to get an already running object
On Error Resume Next
Set myobj = GetObject(, "MediaJukebox Application")

If Err.Number = 429 Then
    'Then, create a new object
    Set myobj = CreateObject("MediaJukebox Application")

End Sub

NOTE: If Media Center was created as out-of-proc object, the main window of the program will be invisible. To show the window use ShowProgram function from MJAutomation interface.

For information on how to get access to MJAutomation interface from in-proc plug-ins see plug-in SDK.

Automation Objects

Event Handling

MediaCenter version 11.1 and higher supports an event interface for automation clients.

Basics

An event is fired upon certain actions with three string parameters:

FireMJEvent(string1, string2, string3)

The first parameter is the event type and currently there is just one event type, namely "MJEvent type: MCCommand" The second parameter identifies the MCC command. See the list below. The third parameter is optional and may contain information specific to the command.

Here are the commands currently sent to the event handler:

  • MCC: NOTIFY_TRACK_CHANGE
    • Fired when a new track starts to play
    • string3 is the zone
  • MCC: NOTIFY_PLAYERSTATE_CHANGE
    • Fired when a the player state changes
      • A new track starts to play
      • Playback is stopped, paused, or started
    • string3 is the zone
  • MCC: NOTIFY_PLAYLIST_ADDED
    • Fired when a playlist is added by the user
    • string3 is the playlist ID
  • MCC: NOTIFY_PLAYLIST_INFO_CHANGED
    • Fired when a playlist is renamed
    • Fired when a smartlist rule is changed
    • Fired when a station is added to My Stations
    • string3 is the playlist ID
  • MCC: NOTIFY_PLAYLIST_FILES_CHANGED
    • Fired when a playlist's files change
    • Fired when a service notifies Media Center that the service's playlists need to be refreshed
    • string3 is the playlist ID
  • MCC: NOTIFY_PLAYLIST_REMOVED
    • Fired when a playlist is removed
    • string3 is the ID of the deleted playlist
  • MCC: NOTIFY_PLAYLIST_COLLECTION_CHANGED
    • Fired when a playlist is moved or copied
    • string3 is not used
  • MCC: NOTIFY_PLAYLIST_PROPERTIES_CHANGED
    • Fired when a playlist property is changed
    • string3 is the playlist ID
  • MCC: NOTIFY_SKIN_CHANGED
    • MC 12.0.211 or higher
    • Fired when the skin is changed
    • string3 is not used
  • MCC: NOTIFY_VOLUME_CHANGED
    • MC 12.0.217 or higher
    • Fired when the volume is changed
    • string3 is the zone
  • MCC: NOTIFY_EQ_CHANGED
    • MCC 12.0.217 or higher
    • Fired when the Equalizer settings are changed, or the Equalizer is turned on or off.
    • string3 is not used
    • Because of internal implementation considerations, you will receive multiple copies of this event for each trigger.

Event Handling and Zones

The events MCC: NOTIFY_TRACK_CHANGE and MCC: NOTIFY_PLAYERSTATE_CHANGE contain the zone where the change occurred. Media Center, however, will only notify changes in the currently active zone. If a track changes in the non-active zone, there will be no event. Only track changes in the active zone will have events.

Handling the events from Visual Basic

To add a handler in VB.NET for events coming from Media Center:

1. Add a reference to Media Center's type library ("Media Center 12.tlb"). In VB.NET use the Projects/Add Reference option, select the "COM" tab, then select "MediaCenter" from the list.

2. Add the "Imports MediaCenter" statement to declaration section of the code.

3. In the main class section for your project (e.g. - Form1) do the following:

  A) Declare your MC automation variable to handle events, like this:
        Dim WithEvents MC As MediaCenter.MCAutomation
  B) Create a delagate class object and set it up to handle the three parameters passed by MEDIACENTER's object:
        Private _RelayEvent As RelayEvent
        Delegate Sub RelayEvent(ByVal EventData1 As String, ByVal EventData2 As String, ByVal EventData3 As String)

4. Create a subroutine to receive the event message and to perform actions based on it. It is triggered by the event handler created below in step 4:

  Private Sub MyRelayEvent(ByVal EventData1 As String, ByVal EventData2 As String, ByVal EventData3 As String)
     lbParam1.Text = EventData1
     lbParam2.Text = Trim(EventData2)
     lbParam3.Text = EventData3
     Application.DoEvents()
  End Sub

4. Declare a handler function for the event. In the handler function, your will need to assign the delegate pointer to the subroutine that will actually act on the event. Then use the BeginInvoke function to transfer the event data when it is received:

  Public Sub MC_FireMJEvent(ByVal s0 As String, ByVal s1 As String, ByVal s2 As String) Handles MC.FireMJEvent
     _RelayEvent = New RelayEvent(AddressOf MyRelayEvent)
     BeginInvoke(_RelayEvent, s0, s1, s2)
  End Sub


5. Events fired from MediaCenter will be received by "MC_FireMJEvent" and it will use the delegate pointer to trigger "MyRelayEvent", which can act on the event.

Note: The event handler is automatically created in a separate thread from the main routine/class. One thread cannot make changes to another thread, so it is necessary to use the delegate pointer to make the main thread aware that the event occured and to receive the information. Then the receiving subroutine, which is in the main thread, can make updates without creating an exception error.

Handling the events from Visual C++ with MFC

In your C++ MFC application, you should have a class which is derived from CCmdTarget (or from CWnd or CDialog which derive from CCmdTarget). This class will sink the events from MC's automation object. In the sample code below, this class is called "CMyClass", substitute your class's name for CMyClass. In the header file of the class, add the following import using the correct tlb path for your system. Also add the afxctl.h include file if you get warnings of undefined AfxConnectionAdvise and AfxConnectionUnadvise.

 #import "C:\\Program Files\\J River\\Media Center 12\\Media Center 12.tlb" no_namespace, named_guids
 #include "afxctl.h"

Then within the header file's class declaration for CMyClass, add this code:

  DECLARE_DISPATCH_MAP()
  DECLARE_INTERFACE_MAP()
  afx_msg void MJEvent(LPCTSTR strType, LPCTSTR strParam1, LPCTSTR strParam2);
  IMJAutomationPtr m_pMJ;
  DWORD m_SinkID;

Now in the cpp file for the class, add these lines which connect your handler function to the correct entry in the dispatch map:

  BEGIN_DISPATCH_MAP(CMyClass, CCmdTarget)
    DISP_FUNCTION_ID(CMyClass,"MJEvent",1,MJEvent,VT_EMPTY,VTS_BSTR VTS_BSTR VTS_BSTR)
  END_DISPATCH_MAP()

  BEGIN_INTERFACE_MAP(CMyClass, CCmdTarget)
    INTERFACE_PART(CMyClass, DIID_IMJAutomationEvents, Dispatch)
  END_INTERFACE_MAP()

Now add the following code to the constructor or wherever you do initialization:

  CoInitialize(NULL);
  EnableAutomation();
  HRESULT hr = m_pMJ.GetActiveObject (L"MediaJukebox Application");
  if (hr != S_OK)
    m_pMJ.CreateInstance(L"MediaJukebox Application");

  // Get a pointer to the sink IDispatch interface
  LPUNKNOWN pUnknownSink = GetIDispatch(FALSE);

  // Connect the event source (MJ automation) to the sink
  AfxConnectionAdvise(m_pMJ, DIID_IMJAutomationEvents, pUnknownSink, FALSE, &m_SinkID);

Add the function body which receives the events:

  // MJAutomationSink message handler
  void CMyClass::MJEvent(LPCTSTR strType, LPCTSTR strParam1, LPCTSTR strParam2)
  {
    // handle events here...
  }

And finally, add this code to the destructor or wherever you do final cleanup. The release for m_pMJ has to be called prior to CoUninitialize.

  LPUNKNOWN pUnknownSink = GetIDispatch(FALSE);
  AfxConnectionUnadvise(m_pMJ, DIID_IMJAutomationEvents, pUnknownSink, FALSE, m_SinkID);
  m_pMJ.Release();
  CoUninitialize();

Handling the Events from Visual C++ with ATL

If you have a conventional Interface plugin that was generated using the ATL DLL and ATL composite controls, you can also sink MediaCenter's events. Simply implement the IMJAutomationEvents (perhaps using class view->Implement Interface) using the IDispEventImpl template. The wizard will default to IDispatch, but you will need to use IDispEventImpl and the SINK_MAP functions to handle events correctly.

Ensure that the type library is imported as for the MFC version above. Set your SINK_MAP as follows:

BEGIN_SINK_MAP(CEQdbCtrl)
  SINK_ENTRY_EX(1, DIID_IMJAutomationEvents, 1, MJEvent)
END_SINK_MAP()

and then implement the MJEvent handler function

STDMETHOD_(void, MJEvent)(LPCTSTR strType, LPCTSTR strParam1, LPCTSTR strParam2);

Also, you need to advise the sink after attaching to the passed IDispatch* in your Init function.

HRESULT hr;
hr = DispEventAdvise(m_pMJ, &DIID_IMJAutomationEvents);
if(hr == S_OK) {
  // Successfully advised.
} else {
  // Did not advise correctly.
}

Here's the (somewhat) tricky part. Using the CComComposite class means that AtlAdviseSinkMap is called during the window constructor, and it will cause an ATLASSERT failure during debug builds. This produces the "Abort" "Retry" "Ignore" message box stating there's been an assertion failure in atlcom.h. Click ignore. Once you move to release builds, it will compile to nothing and will not cause you any trouble.