Difference between revisions of "Media Center Automation"

From JRiverWiki
Jump to: navigation, search
Line 46: Line 46:
 
* [[MJMixerAutomation]] - provides volume, balance, and mute control
 
* [[MJMixerAutomation]] - provides volume, balance, and mute control
 
* [[MJPlaylistsAutomation]] - represents a collection of playlists
 
* [[MJPlaylistsAutomation]] - represents a collection of playlists
 
+
* [[MJPlaylistAutomation]] - interface for working with a single playlist
===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==
 
==MJSchemeAutomation - interface for working with Media Library==

Revision as of 18:39, 22 January 2007

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

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