Installation Packages (MM4)

Installation Packages structure

Additional Extensions can be easily installed in MediaMonkey using Installation Packages. Each installation package is a ZIP file with MMIP extension. When such a file is executed, it is automatically installed in MediaMonkey (see Tools|Extensions). From within the Extensions dialog, the user can update the extension to the latest version, change its options or remove it.

Inside the package can be included any files that need to be installed, but there are also some special files that can or must be included:

Install.ini

Mandatory - this file describes the package and what to install.

App.ico

Optional - Icon of the package.

Uninstall.ini

Optional (but suggested) - describes steps on uninstall, which files to remove, etc.

Uninstall.vbs

Optional - is automatically preserved by installer and can be called by Uninstall.ini on uninstallation. To execute extra (un)install code, you can also reference a function in your main vbs script file.

license.txt

Optional - This file contains license information that user needs to agree apron before installation. Different Language license.txt files are added to installation package in format license??.txt (eg. licenseDE.txt = German license.txt)

Install.ini file

The installation file has a structure of an ini file, i.e. some sections with keys and values.

[Header] section

Each install.ini file starts with a mandantory section [Header]. It contains basic information about the product being installed, namely:

ID

Unique string identification of the product. It should contain only alphanumeric characters, digits or underscores.

Title

Product title shown to user.

Description

Detailed product description.

ShowRestartPrompt

Setting ShowRestartPrompt to True user will be requested for restart of MediaMonkey after (un)installation has completed. However, preferably use a way of (un)install the extension that does not need a restart of MediaMonkey. Introduced in MM 4.0.

VersionMajor

Major version number.

VersionMinor

Minor version number.

VersionRelease

Release number.

VersionBuild

Build number. Any of these numbers can be missing, e.g. if only VersionMajor and VersionMinor are present, the version number shown to user would be 'VersionMajor.VersionMinor'.

Type

Type of product being installed. Either script, skin or misc. This is used so that MM knows more about the extension.

UpdateURL (Optional)

URL to the version XML file where MM should look for the latest version of this product. If this entry is missing, MM can still try to find out whether a new version has been released, by asking MM web scripting repository using product ID above.

ConfigurationScript

A script file to execute. There is either a fully specified path entered here.

ConfigurationProcedure

A name of function to be called within the script file. If this entry is missing or empty, it's supposed that there's no need for calling a function and simple execution of the script file does whatever a developer wants to do. In this function you can e.g. create a new options form or open an existing Options Sheet.

Other sections

After the header section, there can follow an arbitrary number of other sections specifying actions installer should do, and section names can be repeated. For example, if your package contains various files to be copied, you need one [Copy] Section for each individual file.

Sections are executed in order of appearance.

[Copy] section

This section tells where individual files from the installer ZIP file should be placed. Expected keys there include:

Src

Source file name in the installer ZIP file.

Tgt

Destination file path. It can contain constants useful for placing files in common paths (the same as InnoSetup constants). Currently implemented constants:

• {app} = MediaMonkey installation folder.
• {sys} = Windows system folder.
• {gpf} = Plugins folder (All Users). From 4.0
• {lpf} = Plugins folder (Current User). From 4.0
• {gsf} = Scripts folder (All Users). From 4.0
• {lsf} = Scripts folder (Current User). From 4.0
• {lcl} = Locale folder. From 4.0

Flags

Comma separated list of flags related to this copy operation. Can be any of:

overwriteifnewer

If the target file already exists, it will be overwritten only if the source file is newer. If this flag isn't specified, the target file will always be overwritten.

regserver

If the target file is a DLL library then it registers specified DLL library by calling DllRegisterServer() from it.

onlyifdoesntexist

If the target file already exists, it won't be overwritten by the source file. Introduced in MM 3.2.1.

[Delete] section

This section is primarily for 'uninstall.ini' file. The only parameter is:

File

Full path of the file to be deleted.

[Execute] section

This section allows developer to execute a script and thus do any other necessary installation/uninstallation actions, for example prepare Scripts.ini content. Expected keys here are:

File

A VBScript file to execute. Case sensitive. There is either a fully specified path entered here, or if there is no path information, the script is expected to be located in the installation ZIP file and is prepared to a temporary location prior its execution. For uninstaller 'uninstall.vbs' can be specified here and it would be called from its location.

Function

A name of function to be called within the script file. If this entry is missing or empty, it's supposed that there's no need for calling a function and simple execution of the script file does whatever a developer wants to do.

Uninstall.ini file

'Uninstall.ini' file is very similar to 'Install.ini' file, only difference is that [Header] section is optional. Other sections allow developers to properly delete installed files and remove any other traces of installation, e.g. execute a script that would delete some entries in Scripts.ini file.

Sample Installation Package for Skins

Sample MMIP file can contain e.g. the following files:

• App.ico icons shown in the extenions dialog
• Install.ini file that tells where stuff is copied to
• Uninstall.ini tells what should be deleted when uninstalling

Sample Install.ini file

Comments starting with ; should be removed

[Header]
ID=UniqueSkinName  ; this is used when MM needs to see if update is available
Title=Skin Name
Description=Well a description
VersionMajor=1
VersionMinor=0
VersionRelease=0
VersionBuild=0
ShowRestartPrompt=1
Type=skin  ; so MM knows what it is
UpdateURL=http://mywebserver.com/myscript1/version.xml

[Copy]
Src=skinfile.msz
Tgt={app}\skins\skinfile.msz

[Copy]
; you can copy more stuff if you want

Sample Uninstall.ini file

[Header]
ShowRestartPrompt=0  ; optional, as the default value is False/0.

[Delete]
File={app}\skins\skinfile.msz
File={app}\skins\someicon.ico

Sample Installation Package for Scripts

Sample content of MMIP file

Sample MMIP file can contain e.g. the following files:

• App.ico
• Install.ini
• Sample Option Sheets.vbs
• Uninstall.ini
• Uninstall.vbs

Sample Install.ini file

[Header]
ID=MyScript1
Title=Sample Option Sheets
Description=Sample Option Sheets.vbs
VersionMajor=1
VersionMinor=0
VersionRelease=0
VersionBuild=0
Type=script
UpdateURL=http://mywebserver.com/myscript1/version.xml

[Copy]
Src=Sample Option Sheets.vbs
Tgt={app}\scripts\auto\Sample Option Sheets.vbs

[Copy]
Src=Sample.ico
Tgt={app}\scripts\auto\Sample.ico

[Copy]
Src=Icons\*.*
Tgt={app}\Icons\

[Execute]
File={app}\scripts\auto\Sample Option Sheets.vbs
Function=OnStartup()

; Use an install.vbs if you need to do more config, like installing menus or other configurations. Alternatively, you can also reference an install function in your main vbs script file.
[Execute]
File=Install.vbs

Sample install.vbs

'Add entries to script.ini if you need to show up in the Scripts menu
Dim inip : inip = SDB.ScriptsPath & "Scripts.ini"
Dim inif : Set inif = SDB.Tools.IniFileByPath(inip)
If Not (inif Is Nothing) Then
		
	inif.StringValue(scriptName,"Filename") = "PersonalTagEnhancer.vbs"
	inif.StringValue(scriptName,"Procname") = "PersonalTagEnhancer"
	inif.StringValue(scriptName,"Order") = "10"
	inif.StringValue(scriptName,"DisplayName") = "PersonalTagEnhancer"
	inif.StringValue(scriptName,"Description") = "Fixes most important tags using personal preferences"
	inif.StringValue(scriptName,"Language") = "VBScript"
	inif.StringValue(scriptName,"ScriptType") = "0"
	inif.StringValue(scriptName,"Shortcut") = "Ctrl+i"
	SDB.RefreshScriptItems
End If 

' Add entries for Mediamonkey.ini	
' Here you set the variables you need
' all 3 types are shown here
Dim ini: Set ini = SDB.IniFile
If Not ini.ValueExists("AdvShutdown","Enabled") Then ini.StringValue("AdvShutdown","Enabled") = "Enabled"
If Not ini.ValueExists("AdvShutdown","Timeout") Then ini.BoolValue("AdvShutdown","Timeout") = True
If Not ini.ValueExists("AdvShutdown","Action")  Then ini.IntValue("AdvShutdown","Action") = 1

Sample Uninstall.ini file

[Delete]
File={app}\scripts\auto\Sample Option Sheets.vbs
File={app}\scripts\auto\Sample.ico

[Execute]
File=Uninstall.vbs

Sample Uninstall.vbs file

myName = "Sample Script"    'Put script name here
iniSec = "SampleScript"     'Put ini section name here

' Deletes settings from MediaMonkey.ini
MsgDeleteSettings = "Do you want to remove " & myName & " settings as well?" & vbNewLine & _
                    "If you click No, script settings will be left in MediaMonkey.ini"

If (Not (SDB.IniFile Is Nothing)) and (MsgBox(MsgDeleteSettings, vbYesNo) = vbYes) Then
   SDB.IniFile.DeleteSection(iniSec)
End If

'Remove entries from scripts.ini
Dim inip : inip = SDB.ApplicationPath&"Scripts\Scripts.ini"
Dim inif : Set inif = SDB.Tools.IniFileByPath(inip)
If Not (inif Is Nothing) Then
  inif.DeleteSection(iniSec)
  SDB.RefreshScriptItems
End If

Sample version XML file

<SoftwareVersion>
  <VersionMajor>5</VersionMajor>
  <VersionMinor>6</VersionMinor>
  <VersionRelease>0</VersionRelease>
  <VersionBuild>0</VersionBuild>
  <NewVersionDescription>Comment</NewVersionDescription>
  <UpdateURL>http://url/to/mmip</UpdateURL>
</SoftwareVersion>

NOTE: <UpdateURL> is Optional and if this entry is missing, MM can still try to find out whether a new version download is available, by asking MM web scripting repository using product ID.

See also

• SDBiniFile object