// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// ULogger input plug-in interface

// 

//

/**

 @file

 @publishedPartner

 @prototype

*/

#ifndef ULOGGERINPUTPLUGIN_H

#define ULOGGERINPUTPLUGIN_H

#include <e32base.h>

#include "uloggerplugin.h"

#include "uloggerdatatypes.h"

namespace Ulogger

{

//! Abstract class for input plug-ins.

/*!

A ULogger input plug-in listens for ULogger commands on some communication

medium, such as serial, usb or a TCP socket. Whenever a command is received

by the input plug-in, it passes this command to ULogger, which then interprets

the command, acts on it, and returns a response to the input plug-in. The input

plug-in sends any response coming from ULogger back to the client that sent

the command in the first place.

All input plug-ins must derive from this class in order to be compatible with

ULogger. They must also derive from ULogger::CPlugin (whose header is already

included by this header, for convenience) in order to be compatible with the

ECom framework, which ULogger uses to load its input plug-ins.

*/

class MInputPlugin

	{

public:

	/**

	Asynchronous method that reads command data from the input medium. ULogger

	calls this when it's ready to receive command data from the input plug-in.

	When the input plug-in completes the read operation it notifies the caller

	via the TRequestStatus that is passed into this method by reference. It

	provides the command data that has been received in the descriptor that is

	passed into this method by reference.

	Input plug-ins typically implement this method by simply passing the

	TRequestStatus and descriptor arguments on to another asynchronous method,

	such as for example a socket's ReadOneOrMore method.

	@param aStatus The request status used to contain completion information for

	               the function. On completion, contains a system-wide error

	               code.

	@param aData A descriptor reference to store data obtained from input

	             channel.

	@return KErrNone if operation was finished without any problems, system wide

	                 error code otherwise.

	*/

	virtual TInt ReadData(TRequestStatus& aStatus, TDes8& aData) = 0;

	/** Cancels asynchronous operation issued by ReadData method. */

	virtual void CancelReadData() = 0;

	/**

	Synchronous Method that sends the given acknowledgment data back to the

	client that is sending command data to the input plug-in. ULogger calls this

	method whenever it needs to send a response to a previously received

	command.

	@param aData A descriptor which contains error code or other results, for

	             example, array of filters.

	Format of this data depends on previously obtained command.

	@return KErrNone is send operation finished with success otherwise

	                 system wide error code.

	*/

	virtual TInt SendAcknowledgment(const TDesC8& aData) = 0;

	/**

	Called by ULogger as first method after construction or after changes in

	config file. This allows the input plug-in to initialize itself with its

	private settings.

	@param aConfigs actual configurations valid for this instance

	@return KErrNone, if successful; otherwise one of the other system wide

	        error codes.

	*/

	virtual TInt ConfigureInputPlugin(const RPointerArray<TPluginConfiguration>& aConfigs) = 0; 

	/**

	Called by ULogger to indicate that the input plug-in must flush all buffers

	and release any locked resources. Any resources may be locked only after any

	other method is called.

	*/

	virtual void CloseInputPlugin() = 0;

	/**	Virtual destructor.	*/

	virtual ~MInputPlugin(){}

	/**

	Input plug-in interface id. This is for ULogger to distinguish between the

	different types of plug-ins (e.g. Intput vs Output plug-ins).

	*/

	static const CPlugin::TPluginInterface iInterfaceId = CPlugin::EInput;

	};

} //end of namespace

#endif /* ULOGGERINPUTPLUGIN_H */