// Copyright (c) 2004 - 2007, Symbian Software Ltd. All rights reserved.

/**
	This header file defines the UIDs for each type of transport,
	such as SMS or email; the observer interface that the client
	implements to be notified when payloads are sent or received;
	and the transport interface itself.
 */

#ifndef TRANSPORTINTERFACE_H
#define TRANSPORTINTERFACE_H

#include <ecom/ecom.h>

#include "transportinterface.hrh"


/**
	Supply this UID to CTransportInterface::NewL to connect over a serial cable.
 */
const TUid KSerialCommTransportUid = {KSerialCommTransportUidValue};

/**
	Supply this UID to CTransportInterface::NewL to talk to a remote device
	via SMS.  The address is the remote device's telephone number as a native-width
	(i.e. 16-bit) string.
 */
const TUid KSmsTransportUid = {KSmsTransportUidValue};

/**
	Supply this UID to CTransportInterface::NewL to talk to a remote device
	via email.  The address is the target email address.
 */
const TUid KEmailTransportUid = {KEmailTransportUidValue};

/**
	Supply this UID to CTransportInterface::NewL to talk to a remote device
	via MMS.  The address is the remote device's telephone number as a native-width
	(i.e. 16-bit) string.  Unlike KMmsTransportUid, this UID uses the sendas
	server to contruct the multimedia message.

	@see KMmsTransportUid
 */
const TUid KMmsSendAsTransportUid = {KMmsSendAsTransportUidValue};

/**
	Supply this UID to CTransportInterface::NewL to talk to a remote device
	via MMS.  The address is the remote device's telephone number as a native-width
	(i.e. 16-bit) string.  Unlike KMmsSendAsTransportUid, this UID uses the MMS MTM
	to contruct the multimedia message.

	@see KMmsSendAsTransportUid
 */
const TUid KMmsTransportUid = {KMmsTransportUidValue};

/**
	Supply this UID to CTransportInterface::NewL to talk to a remote device
	via Bluetooth.  If this device should initially listen then it is a Bluetooth
	host, waiting for the client to connect.  Otherwise, it is opened as a Bluetooth
	client and the user selects the host device from a notifier.
	
	When the local device is the Bluetooth host then the address is the protocol,
	"RFCOMM" or "L2CAP".
 */
const TUid KBluetoothTransportUid = {KBluetoothTransportUidValue};

/**
	Supply this UID to CTransportInterface::NewL to talk to a remote device
	via infrared with an emulated RS232 connection.  The address is not used.
 */
const TUid KIrCommTransportUid = {KIrCommTransportUidValue};

/**
	Supply this UID to CTransportInterface::NewL to talk to a remote device
	via Bluetooth with an emulated RS232 connection.  The address is not used.
 */
const TUid KBtCommTransportUid = {KBtCommTransportUidValue};

/**
	Supply this UID to CTransportInterface::NewL to talk to a remote device
	via the infrared socket APIs.  The address is the protocol - "IrTinyTP" or "Irmux".
 */
const TUid KIrSocketTransportUid = {KIrSocketTransportUidValue};

class MTransportObserver
/**
	The controller implements this interface to be notified
	when payloads have been sent or received.
 */
	{
public:
	/**
		The payload has been sent successfully.  If the payload cannot
		be sent successfully, LostConnection is called and the client
		must tear down the connection.
	 */
	virtual void SentPayload() = 0;
	/**
		This device has successfully received a payload from a remote device.
		The payload has been received via the expected medium, e.g. serial
		cable or MMS.

		@param	aPayload		Payload text.  This is the text that was sent
								with CTransportInterface::SendPayload on the
								remote device.  Any extra content such as
								framing characters or ISP advertisements have
								been removed.  The payload is only valid for
								the duration of the call, so the client must
								copy the payload if they want to use it after
								the function call has finished.
	 */
	virtual void ReceivedPayload(const TDesC& aPayload) = 0;
	/**
		Called when an error has occurred on the transport.  This can
		be because a payload could not be sent or received.  This function
		can also be called because some transports such as Bluetooth maintain
		a connection throughout the game, which can be lost at any point.

		@param	aError			Any Symbian OS error code.  The implementor
								must handle unrecognized error codes.
	 */
	virtual void LostConnection(TInt aError) = 0;

	/**
		Used for Bluetooth; the local client device is searching for the
		OandX game service on the remote device.  Displays a dialog, which
		the user can cancel.

		@return					Return code from Symbian OS dialog.
								Zero (EEikCmdCanceled) means cancelled.
		@see StoppedLookingForService
	 */
	virtual TInt StartedLookingForServiceL() = 0;
	/**
		Used for Bluetooth; dismisses the dialog raised by StartedLookingForServiceL.

		@see StartedLookingForServiceL
	 */
	virtual void StoppedLookingForService() = 0;

	/**
		The local device has found the OandX game service on the remote device
		and is attempting to connect.  Displays a dialog, which the user can cancel.

		@return					Return code from Symbian OS dialog.
								Zero (EEikCmdCanceled) means cancelled.
		@see StoppedConnectingToService
	 */
	virtual TInt StartedConnectingToServiceL() = 0;
	/**
		Dismisses the dialog raised by StartedLookingForServiceL.

		@see StartedConnectingToServiceL
	 */
	virtual void StoppedConnectingToService() = 0;

	/**
		Displays a dialog while the local host device waits for a client to connect.

		@return					Return code from Symbian OS dialog.
								Zero (EEikCmdCanceled) means cancelled.
		@see StoppedWaitingForClient
	 */
	virtual TInt StartedWaitingForClientL() = 0;
	/**
		Dismisses the dialog raised by StartedWaitingForClientL.

		@see StartedWaitingForClientL
	 */
	virtual void StoppedWaitingForClient() = 0;
	};


/** Fixed length of payloads sent between devices in characters. */
const TInt KPayloadLen = 1;


class CTransportInterface : public CActive
/**
	This class is the interface which the controller instantiates via ECOM.
	It specifies the minimum interface which the controller requires to send
	and to receive payloads.
 */
	{
public:
	IMPORT_C static CTransportInterface* NewL(
		TUid aTransportUid, MTransportObserver& aObserver, const TDesC& aAddress, TBool aInitListen);
	IMPORT_C virtual ~CTransportInterface();
	
	/**
		Send a payload to the remote device.  This function is asynchronous
		and completes this AO when the payload has been sent.

		@param	aPayload		Payload text to send to remote device.
	 */
	virtual void SendPayload(const TDesC& aPayload) = 0;
	
protected:
	IMPORT_C CTransportInterface();
	
private:
	TUid iDtor_ID_Key;		///< Identifies implementation UID for ECOM cleanup.
	};

class TTransportInterfaceCreateInfo
/**
	Bundles the information passed to CTranspotInterface::NewL
	so it can be supplied as a single TAny* value when the transport
	is created via ECOM.  (ECOM factory functions can take zero
	arguments, or one TAny* argument.)
	
	This class is used by transport implementors.
 */
	{
public:
	/** Observer supplied to CTransportInterface::NewL. */
	MTransportObserver& iObserver;
	/** Address supplied to CTransportInterface::NewL. */
	const TDesC* iAddress;
	/**
		Whether this transport should start by listening for an incoming payload,
		or by waiting for the local user to send a payload.
	 */
	TBool iInitListen;
	};


// -------- debugging --------

// #define TRANSPORT_LOGGING

#ifdef TRANSPORT_LOGGING

#define TRAN_LOG0(___fmt)							TransDebugPrint((const TText16*)L##___fmt)
#define TRAN_LOG1(___fmt,___arg1)					TransDebugPrint((const TText16*)L##___fmt,___arg1)
#define TRAN_LOG2(___fmt,___arg1,___arg2)			TransDebugPrint((const TText16*)L##___fmt,___arg1,___arg2)
#define TRAN_LOG3(___fmt,___arg1,___arg2,___arg3)	TransDebugPrint((const TText16*)L##___fmt,___arg1,___arg2,___arg3)

#else

#define TRAN_LOG0(___fmt)
#define TRAN_LOG1(___fmt,___arg1)
#define TRAN_LOG2(___fmt,___arg1,___arg2)
#define TRAN_LOG3(___fmt,___arg1,___arg2,___arg3)

#endif	// #else #ifdef TRANSPORT_LOGGING

IMPORT_C void TransDebugPrint(const TText16* aFmt, ...);

#define __TRANS_ASSERT(___cond,___reason)	__ASSERT_DEBUG(___cond, TransPanic(___reason))

#endif	// #ifndef TRANSPORTINTERFACE_H