/************************************
* Readme.txt for the IPMP Master Tool
************************************/

A) - Overview

The IPMP Master Tool is a DLL software module which may be loaded by the MPEG-4 IPMP-X framework whenever an IPMP_DescPointer, containing the Descriptor ID of the MasterTool, in an OD is given, and the associated IPMP_Descriptor is known at the terminal [1].

The Master Tool, after being instantiated, during the process of its initialization receives a User_Initialize message from the IPMP-X framework, conveying the following informations:
-	The own Context_ID
-	The pointer to the MessageRouter (indispensable for sending messages)
-	The pointer to the own IPMP_Descriptor
-	IPMPX_Data

The IPMPX_Data field contains a new message, of type IPMP_ConnectTool, and the pathname of the REL license associated to the content. The IPMP_ConnectTool message is redirected to the IPMP-X framework, and this will cause the instantiation of the IPMP Tool specified in it. 

The REL license pathname is extracted from the IPMPX_Data field, the corresponding file is opened and the license is read and stored in a string. A DialogBox pops up and asks the user to enter the pathname for the query file. The query file in a real case should be automatically generated by the Master Tool, asking to the user his username and password, and should also contain the present time. The current version of REL Tool supports only one Right play and one Condition validityInterval [5] which are currently supported by the ContentGuards example implementation [4]. The query file is opened and the content is read and stored inside a string. The strings containing the license and the query text are then inserted in the rightsInfo field of two IPMP_RightsData messages.

After the receipt of an IPMP_NotifyToolEvent message from the REL Tool, with the field eventType set to CONNECTED, the Master Tool sends first the license, and then the query, to the REL Tool, using the method SendSecureMessage of an object of class SecurityLib, though the encryption of the data is not implemented in this example. For being able to deal with the asynchronicity of waiting for the IPMP_NotifyToolEvent from the REL Tool, the Master Tool uses a separate thread for composing the IPMP_RightsData messages and for sending them.

In case the validation process succeeds (at least one condition in the license was met by the supplied query), the Master Tool will receive from the REL Tool an IPMP_SecureContainer message containing an IPMP_OpaqueData message conveying information extracted from the license during the validation process. In case no condition was met, the IPMP_OpaqueData wont be protected and will convey either information on the validation process or the failure reasons. In both cases, an IPMP_CanProcess message is also sent by the REL Tool, with the field can process = true in the first case, otherwise with a false value. This message is forwarded to the IPMP-X framework, and in the first case the rendering of the protected stream will begin (channel 4: PLAY will appear on the dos window of the IM1Player).


/***************************
B) - Running the application


1) The IPMP REL Tool requires the Microsoft MSXML 4.0 Parser installed. This can be obtained at: http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdn-files/027/001/766/msdncompositedoc.xml 

2) Download from the NIST cvs repository the IM1 software module as explained in [2].

3) Open the workspace IM1.dsw in the folder \IM1\_Workspaces.

4) The current IPMP-X reference software implementation loads the IPMP Tools present in the directory \IM1\Debug on the basis of a string of bytes appended at the end of their DLL file after these are built., add the command AppendBin.bat. This will launch a batch file in the respective directories that will perform this operation. For more information on how to compose this string of bytes have a look at the documentation of the method IPMPServicesFull::CheckDllForTool in the file \IM1\Craig-IPMP\IPMPXFull\IPMPXFull.cpp. 

5) Go to build->batch build and deselect all of the release versions then click build.

6) Edit the file \IM1\_Registry\im1.reg. If not present the "IPMPSystem"="IPMPXFull.dll" entry, add it and update your registry.

7) Copy all DLLs from IM1\IM1Decoders\dlls to the IM1\Debug directory that Visual Studio has created.

8) Copy the \IM1\IPMP_MasterTool\filesForRunIt\ipmpx.trif file and paste it in the \IM1\Debug directory.

9) Copy all the files from \IM1\IPMP_RELTool\licensesAndQueryExamples into the \IM1\Debug directory. These are examples of licenses and query files provided in [4].

10) Set as Active Project the IPMPXFull project. 

11) In the settings of the IPMPXFull project, in the Debug\General Options, set as Executable the file: \IM1\Debug\IM1player.exe, Working Directory: \IM1\Debug, Program arguments: ipmpx.trif.

12) Launch the application.

13) When the pathname of the query is being asked, the one proposed is a valid query that should succeed in the validation process. Try to change the pathname of the query using some of the name proposed in the file ExamplesOfQueryPathnames.txt in the directory \IM1\IPMP_RELTool for having different results.

14) For modifying the ipmpx.trif file, for example changing the license pathname in the content, copy the ipmpx.txt and ipmpx.scr files from the \IM1\IPMP_MasterTool\filesForRunIt to the \IM1\Test directory, modify the ipmpx.txt and ipmpx.scr files ad create a new ipmpx.trif file as following: 
	- Add to the System path Environment variable the \IM1\Test directory
	- Open the DOS window and cd to the \IM1\Debug directory
	- Type BifsEnc ipmpx.txt
	- Type Mux ipmpx.scr
	- Copy the generated ipmpx.trif file into the IM1\Debug directory
  

/****************************************************
C) - Known limitations of the current implementation:

1) The Mutual Authentication that should take place between the Master Tool and the REL Tool is not implemented yet, as well as the encryption/decryption functions for sending message carried into the IPMP_SecureContainer.

2) The Master Tool and the REL Tool doesnt have the messages IPMP_GetTools, IPMP_GetToolsResponse, IPMP_GetToolContext and IPMP_GetToolContextResponse implemented, therefore in the ToolMessages exchanged between the two IPMP Tools the Receiver field is filled statically and not dynamically. If other IPMP Tools are loaded in the Terminal, the ToolMessages may be sent to the wrong Receiver. 


/*************
D) References:

[1] Study of FPDAM ISO/IEC 14496-1:2001 / AMD3 in ISO/IEC JTC 1/SC 29/WG11 N4849, Klagenfurth, Austria, July 2002.

[2] Mika?l Bourges-Svenier, Wo Chang, CVS access to MPEG reference software in ISO/IEC JTC1/SC29/WG11 M8705, Klagenfurth, Austria, July 2002.

[3] MPEG-4 Systems Software Status and Implementation Workplan in ISO/IEC JTC 1/SC 29/WG11 N5089, Klagenfurth, Austria, July 2002.

[4] Xin Wang, Thomas DeMartini, Jose Romero-Lobo and Edgar Valenzuela, An Example Implementation of MPEG-21 REL Reference Software in ISO/IEC JTC 1/SC 29/WG11 M9067, Shanghai, China, October 2002.

[5] Text of ISO/IEC 21000-5 CD  Part 5: Rights Expression Language in ISO/IEC JTC 1/SC 29/WG 11/N4942, Klagenfurt, Austria, July 2002.

