/******************************************************************************
|* 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: RoboDriver.h
|*
|* PURPOSE: Interface of robot driver
******************************************************************************/

/* This file describes the interface each Nero Robo driver has to implement
 * to be accessible from Nero */

#ifndef ROBODRIVER_H
#define ROBODRIVER_H

#include "GeneralPluginDLL.h"

/* Compatibility mode interfaces.
 * We try to keep backwards compatibility. So this is the layout of the old Version 1
 * Robo Interface available since Nero 5.5.4.0 */
class CNeroRoboDriverV1
{
public:
	virtual BOOL InitBurn()				{ return TRUE; };
	virtual BOOL PreBurn()				{ return TRUE; };
	virtual BOOL InsertCD()				= 0;
	virtual BOOL RemoveNonWriteableCD() = 0;
	virtual BOOL RemoveUntouchedCD()	= 0;
	virtual BOOL PostBurnOK()			{ return TRUE; };
	virtual BOOL PostBurnFAILURE()		{ return TRUE; };
	virtual BOOL ExitBurn()				{ return TRUE; };
	virtual ~CNeroRoboDriverV1()		{};
};

/* Wait 60 secs. for the drive to get ready in DlgWaitCD.
 * If the drive hasn't managed to read the disc during that time,
 * ask the user to insert a CD or abort instead */
#define ROBODRIVER_INSERTDISCTIMEOUT	60000


/* Current driver version used for compatibility. Change this version only if the robo driver
 * interface has changed. Herefore a proxy has to be adapted to this new version number. */
#define ROBODRIVER_CURRENTVERSION		5
#define ROBODRIVER_PLUGINTYPE			"NeroCDRobo"

#define NEROROBODRIVER_API NERO_PLUGIN_API


class IRoboCommNode;
class IUserDialogFactory;
class CNeroRoboFirmwareCheck;

class CSerial;

/* Since Nero 5.5.4.1 */
class CNeroRoboDriverV2
	:public CNeroRoboDriverV1 // we just extend the old interface
{
public:
	/* The following methods define entry points for the different hook-ups
	* within the Nero Burn process. A Nero Robo driver will implement 
	* whichever methods it may need to perform it's tasks. All other
	* methods may remain unimplemented with the exception
	* of InsertCD() and RemoveNonWriteableCD()
	*   --> All those methods shall return a boolean TRUE if
	*       all desired actions could be performed successfully 
	*       and FALSE otherwise.
	*       Note that the recording process will stop if FALSE is returned
	*       and PostBurn()/ExitBurn() will be called unless the error
	*       occurred in one of those methods
	*/


	/* This method is called just after loading the robo driver DLL.
	* Usually, a driver will want to perform it's reset function 
	* or similar jobs at this point.
	* Note that this method is only called once during the whole 
	* recording job, even if more than one copy is requested */
	virtual BOOL InitBurn()				{ return TRUE; };

	/* This method is called for every recording cycle right before it will
	* start. This is the place where your driver should call the PrintLabel()
	* method in case the label needs to be printed prior to burning */
	virtual BOOL PreBurn()				{ return TRUE; };

	/* This method is called if Nero needs a CD to write to.
	* The driver should ensure that there's a disc in the tray of the
	* recorder when this method returns. Otherwise, it must return FALSE.
	* Note that the state of the recorder tray at the time this method is called
	* is undefined so prior to actually trying to insert a CD, the driver will have
	* to explicitly open the tray with IRoboCommNode::MoveRecorderTray(TRUE).
	* The essential point about all this fuzz is that this way the robo driver can decide
	* when the tray will be opened which is very useful if some job needs to be done with
	* a medium prior to inserting it into the drive (e.g. printing) */	
	virtual BOOL InsertCD()				= 0;

	/* This method will be called if Nero encounters a CD it cannot write to. 
	* It is the responsibility of the Robo driver to remove the inapt medium in this case. 
	* The tray is open when this method is called */	
	virtual BOOL RemoveNonWriteableCD() = 0;

	/* This method will be called if Nero decides not to use a CD after all but it's already
	* been inserted into the drive. This gives the Robo a chance to put the CD back into
	* the input tray or wherever it may decide to put it (may as well be the waste bin of course) */
	virtual BOOL RemoveUntouchedCD()	= 0;

	/* Called when Nero is done burning a CD.
	* PostBurnOK() will be called if the recording process was successful. 
	* PostBurnFAILURE() will be called if the recording process failed for some reason.
	* The driver should take this into account when deciding where to put the resulting 
	* disc (e.g. if the recording process wasn't successful, the driver might want to put the cd into 
	* a trash bin and into some output bin otherwise).
	* The recorder's tray is open when this method is called */
	virtual BOOL PostBurnOK()			{ return TRUE; };
	virtual BOOL PostBurnFAILURE()		{ return TRUE; };

	/* This method is called to conclude the recording process. 
	* It is called only once for a recording job, even if this job
	* made more than one copies.
	* This hook can be used to clean up any structures specific to the 
	* current recording process. The recorder tray is closed when this method is called */
	virtual BOOL ExitBurn()				{ return TRUE; };

	/* Perform any cleanup jobs that may be necessary after the robo has been left in an undefined
	* state (remove any remaining media from the printer tray etc.) */
	virtual BOOL CleanUp()				{ return TRUE; };

	virtual ~CNeroRoboDriverV2()		{};
};

/* Since Nero 5.5.9.4 */
class CNeroRoboDriver
	:public CNeroRoboDriverV2
{
public:
	/* Explicit tell robo to start printing a label. In this way we are able to print with delay.
	 * This method will be explicit called after each successfull burning. The driver can ignore
	 * this call if printing was already done in PostBurnOK method or the label was printed before 
	 * burning. The difference is, if we call this method InsertCD() was already called for new
	 * copy, so there should be disc in printer and recorder yet. */
	virtual BOOL StartPrintLabel()	{ return TRUE; };

	/* A simple robo test. The driver may move the disc through all robot positions (e.g. sequence: 
	 * input bin, recorder, printer, output bin) to test proper configuration. */
	virtual BOOL StartRoboTest()	{ return TRUE; };

	virtual ~CNeroRoboDriver()		{};
};

typedef const char *(*nerorobodriver_getidentifier_ptr)();


/* Create a Nero Robo Driver object and connect it to the passed IRoboCommNode communication node. 
 * The node is only borrowed to the Robo Driver and despite it's being reserved for the exclusive use
 * through the Robo Driver it is still owned by the caller of this DLL entry point and may not be deleted. 
 * that methods are obsolete and replaced by methods below, but for compatibility to older Nero versions
 * the driver should implement these methods too.*/
typedef CNeroRoboDriver*(*nerorobodriver_createdriver_ptr)(IRoboCommNode*);
NEROROBODRIVER_API CNeroRoboDriver *nerorobodriver_createdriver(IRoboCommNode *pCommNode);

/* Obsolete configure driver interface. Older Nero versions are still using it. */
typedef void (*nerorobodriver_configuredriver_ptr)(IUserDialogFactory *pDialogFactory);
NEROROBODRIVER_API void nerorobodriver_configuredriver(IUserDialogFactory *pDialogFactory);

/* Since Nero 5.5.9.8 */
/* If we have the possibility to assign the recorder location to its unique name, we can tell robot driver which 
 * recorder it's serving. If there are not multiple recorders on the system with the same name, we pass a valid,
 * unique recorder name to this method. Else the recorder name string will be EMPTY. */
typedef CNeroRoboDriver*(*nerorobodriverV2_createdriver_ptr)(IRoboCommNode *pCommNode, const char *cpRecorderName);
NEROROBODRIVER_API CNeroRoboDriver *nerorobodriverV2_createdriver(IRoboCommNode *pCommNode, const char *cpRecorderName);

/* In the same way the driver can configure robot depending on the passed unique recorder name it should serve. 
 * Recoder name string is valid only for unique recorder names. */
typedef void (*nerorobodriverV2_configuredriver_ptr)(IUserDialogFactory *pDialogFactory, const char *cpRecorderName);
NEROROBODRIVER_API void nerorobodriverV2_configuredriver(IUserDialogFactory *pDialogFactory, const char *cpRecorderName);

/* Check current robo firmware. Is used by Nero for automatic robo recognition. */
typedef CNeroRoboFirmwareCheck*(*nerorobodriver_firmwarecheck_ptr)(CSerial *pInterface);
NEROROBODRIVER_API CNeroRoboFirmwareCheck *nerorobodriver_firmwarecheck(CSerial *pInterface);

#endif // ROBODRIVER_H