/******************************************************************************
|* THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
|* ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
|* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
|* PARTICULAR PURPOSE.
|* 
|* Copyright 1995-2005 Nero AG. All Rights Reserved.
|*-----------------------------------------------------------------------------
|* NeroSDK / NeroRobo
|*
|* PROGRAM: RoboCommNode.h
|*
|* PURPOSE: Interface for robot communication node 
******************************************************************************/


/* This file describes the robot communication node interface that is
 * passed to each robo driver upon initialization.
 * A robo driver can use this communication node to communicate to
 * it's hardware, the user and, in some limited ways, to the operating
 * system */

#ifndef ROBOCOMMNODE_H
#define ROBOCOMMNODE_H

#include "AbstractConfigurationStorage.h"

#define TEMPSTORAGEMUTEXNAME "TempStorageAccess"


/* Abstract thread handle for multithreaded robo drivers */
class IRoboThread
{
public:
	/* Thread entry point */
	typedef UINT(*StartUp)(void *pUserData);

	/* If this method returns TRUE, dwResult will contain the exit code of the thread. 
	 * If FALSE is returned,  specified thread is still running */
	virtual BOOL GetExitCodeThread(DWORD *dwResult) = 0; 
	virtual ~IRoboThread() {};
};

/* Abstract mutex interface for multithreaded robo drivers */
class IRoboMutex
{
public:
	/* Lock a mutex, pass -1 as a timeout and it will try to lock the mutex indefinitely */
	virtual BOOL Lock(DWORD dwTimeOut = (DWORD)-1)	= 0;
	virtual BOOL Unlock()							= 0;
	virtual ~IRoboMutex() {};
};

class CUserDialogHandle;
class IConfigurationStorage;
class CSerial;
class IRoboPrinter;

/* Since Nero 5.5.4.0 */
/* First robo common node interface. */
class IRoboCommNodeV1
	:virtual public IConfigurationStorage
{   
public:
	/* This will return a serial interface to the hardware this driver
	* will handle. Caller must *not* free this object with delete.
	* Nero knows about the relations between drivers and hardware
	* so this method will return an instance of the type of
	* interface Nero chose to present to
	* the driver. Also note that multiple calls to this method will
	* always return the same instance of the interface */
	virtual CSerial *GetSerialInterface()										= 0;

	/* Open/Close the recorder's CD tray. If TRUE is passed to this method,
	* the tray will be opened and closed otherwise.
	* The method will return TRUE if sucessful and FALSE in case of 
	* an error */
	virtual BOOL MoveRecorderTray(BOOL bOpen)									= 0;

	/* MultiThreading and MultiTasking control */

	/* Create a new thread. */
	virtual IRoboThread *CreateThread(IRoboThread::StartUp, void* pUserData)	= 0;

	/* Create a mutex. */
	virtual IRoboMutex *CreateMutex()											= 0;
	
	/* Suspend Robo thread for specified amount of time */
	virtual void SuspendThread(DWORD dwTimeInMS)								= 0;
	
	/* Return some value whose only guaranteed property is that it is increased by 1 every ms. 
	 * Good for timeouts */
	virtual DWORD GetSyncTime()													= 0;
	
	/* Returns the currently selected Nero Language or NULL if no internationalization support */
	virtual const char *GetCurrentLanguage()									= 0;
	
	/* Return the currently set OEM name for some device given in szTemplateName.
	* If no matching OEM substitution could be found, return szTemplateName */
	virtual const char *GetOEMName(const char *szTemplateName)					= 0;

	typedef enum 
	{
		PRINT_OK,
		PRINT_FAILURE,
		PRINT_ABORTED
	} PrintResult;

	/* This method can be used to determine whether a label should be printed at all. 
	* It will return TRUE if a label  should be printed to the CD, i.e the user specified 
	* a printer and label to print. */
	virtual BOOL LabelPrintEnabled()											= 0;
	
	/* The driver must call this method at the appropriate time if it
	* wants to print onto the disc. It must ensure that the
	* disc is already in the printer when this method is being called */
	virtual PrintResult PrintLabel()											= 0;

	/* -- User Interface methods:
	*    The following methods will return a user interface handle.
	*    It can be used to query the user for actions or to just
	*    display some sort of status information while the robo
	*    is performing it's tasks. The primary thread will take care 
	*    of keeping the message queue of the GUI running so 
	*    the robo task can modally wait for a dialog to be closed again
	*    or just leave it alone entirely.
	*              
	*            --> Simply delete CUserDialogHandles when done. 
	*  -- */

	/* Create a dialog representing the current action the Robo device
	* is performing. */
	typedef enum
	{
		ERLN_INPUT,
		ERLN_RECORDER,
		ERLN_OUTPUT,
		ERLN_PRINTER,
		ERLN_WASTEBIN
	} ERoboLocationNode;   

	virtual CUserDialogHandle *CreateMoveCDDialog(ERoboLocationNode source, ERoboLocationNode destination) = 0;
	virtual CUserDialogHandle *CreatePrintCoverDialog()							= 0;

	/* Layout of the dialog type mask:
	*  Bits 0-7:  Message Type
	*  Bits 8-31: Options */
#define ROBOCOMMNODE_MSG_ERROR		0
#define ROBOCOMMNODE_MSG_WARNING	1
#define ROBOCOMMNODE_MSG_QUESTION	2
#define ROBOCOMMNODE_MSG_HINT		3

	/* Dialogs created this way will return 
	* CUserDialogHandle::DLGRESULT_OK or 
	* CUserDialogHandle::DLGRESULT_CANCEL */
	virtual CUserDialogHandle *CreateMessage(const char *message, DWORD options) = 0;

};

/* Since Nero 5.5.7.9 */
/* Extended the previous interface for synchronization of multiple robots and especially of
 * robots with multiple drives. */
class IRoboCommNodeV2
	:public IRoboCommNodeV1
{
public:
	/* Synced temporary storage is used to store values accessible to all active robo drivers. 
	 * This means that if you know the key to a value, you can synchronize two drivers using 
	 * this facility. */
	virtual IConfigurationStorage *GetSyncedTemporaryStorage()	= 0;

	/* This method can be used to get a global mutex common to all robo drivers
	 * Use this to synchronize access to temporary storage. */
	virtual void LockNamedMutex(const char *szMutexName)		= 0;
	virtual void UnlockNamedMutex(const char *szMutexName)		= 0;
};

/* This enum can be used to specify the recorder location in method SetRecorderLocation of IRoboCommNode 
 * interface below. At time there can be only specified left and right recorder respectively. The default
 * recorder is used e.g. for robots with only one drive. Later we have to adapt these values for other robos. */
typedef enum
{
	DEFAULT_RECORDER	= 0,
	LEFT_RECORDER		= 1,
	RIGHT_RECORDER		= 2
}
ERoboRecorderLocation;

/* Since Nero 5.5.9.4 */
/* New CommNode Interface for additional functionality. */ 
class IRoboCommNode
	:public IRoboCommNodeV2
{
public:
	/* The driver can use this method to check if the user wish to immediatelly abort current
	 * robot movement. */
	virtual BOOL IsAbortedImmediate()						= 0;

	/* This method is used to move the tray of recorder which is marked as LEFT_RECORDER. 
	 * It's specific to robots with two recorders for e.g. close the recorder tray which
	 * is located above waste bin. */
	virtual void MoveSecondaryRecTray(BOOL bOpen)			= 0;

	/* Call this method if print thread was created, to inform Nero, there is any print job in
	 * progress. This will prevent Nero from exit the burn loop before the label was printed. */
	virtual void AddMyPrintThread()							= 0;

	/* Remove your print thread after printing was finished. 
	 * NOTE: it's a good style to create separate thread for printing, so the robo can do another stuff
	 * during the label is created. */
	virtual void RemoveMyPrintThread()						= 0;

	/* This method specifies the recorder location. The driver can call this method to inform the 
	 * robo manager if its recorder is the left recorder which will be opened in MoveSecondaryRecTray
	 * method. */
	virtual void SetRecorderLocation(int iRecorderLocation)	= 0;

	/* Get current recorder location currently served by the driver.  */
	virtual int GetRecorderLocation()						= 0;

	/* This method enables the robot driver to write some error or status messages to common NeroHistory.log
	 * file. These messages will be append at the and of current burn process info.  */
	virtual void WriteErrorToLog(const char *cpErroMsg)		= 0;	
};

/* Defines an interface to the printer. Processed by AbstractRoboGuiManager when the Robo wants to print something */
class IRoboPrinter
{
 public:
   /* Print and return error. iNumCopy is a counter starting at 1, increased by one with every
    * print job (counter is global, it affects all connected robos) */
   virtual IRoboCommNode::PrintResult operator ()(int iNumCopy, IRoboCommNode *pCommNode)	= 0;
   
   /* This method returns TRUE if printing is currently enabled.
    * Another option to disable printing still is to not provide a IRoboPrinter instance at all
	* but this method allows us to be more flexible regaring printer control */
   virtual BOOL	IsPrintingEnabled() const													= 0;
   
   /* Create a copy of this exact interface */
   virtual IRoboPrinter *Clone() const														= 0;

   virtual ~IRoboPrinter() {};
};

#endif // ROBOCOMMNODE_H