// 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:

// protocol_module.h - Generic glue beween family and protocol(s)

// 

//

#ifndef __PROTOCOL_MODULE_H

#define __PROTOCOL_MODULE_H

#include <es_prot.h>

/**

* @file protocol_module.h

* Generic glue between family and protocol(s).

*

* This header does not have own implementation (no protocol_module.cpp

* exist). The implementation must be defined by your own protocol

* implementation.

*/

class CProtocolBase;

class ProtocolModule

	/**

	* A help class for building the plugin example projects.

	*

	* This class defines the minimal API between the protocol

	* family implementation (CProtocolFamilyBase) and protocol

	* implementations (CProtocolBase).

	* This class must be implemented in your protocol module. The

	* generic family implementation converts the socket server

	* requests into calls to these static functions.

	*

	* This is targeted for simple protocol modules, which implement

	* only one or few protocols. It allows the use of a generic

	* CProtocolFamilyBase implementation. The generic family

	* implementation does the "symbian DLL wrappings".

	*

	* A complete protocol module contains three major components:

	*

	* -# protocol family implementation (link in the generic code)

	* -# protocol implementation (CProtocolBase). Write your own version (must).

	* -# service provider implementations (CServProviderBase). Write your own version,

	*	 if the protocol(s) have a socket API.

	*

	* By using this API, a single generic family implemtation can

	* be linked into many protocols modules.

	*

	* @note

	*	This could be used in any protocol implementation,

	*	and not just for a hook in TCP/IP stack.

	*

	*/

	{

public:

	/**

	* Return the number of protocols.

	*

	* This must return the number of protocols that are

	* impelemented by your protocol module. The value

	* determines the number of elements in the TServerProtocolDesc

	* array, that will be returned to the socket server from the

	* CProtocolFamilyGeneric::ProtocolList implementation.

	*

	* The number is constant for each PRT module. The function

	* is only called from the ProtocolList().

	*

	* @return	The number of implemented protocols.

	*/

	static TInt NumProtocols();

	/**

	* Describe a protocol.

	*

	* Like NumProtocols(), this is also called only from the

	* CProtocolFamilyGeneric::ProtocolList implementation.

	* The allocated TServerProtocolDesc array is initialized

	* by calling this function once for each element.

	*

	* If only one protocol is implemented (NumProtocols() returns 1),

	* then this is called once with aIndex = 0. If multiple protocols

	* are implemented, the function must use aIndex to decide which

	* description is to be returned.

	*

	* @retval	aDesc	The protocol description.

	* @param	aIndex	The protocol to describe [0 .. NumProtocols()-1].

	*/

	static void Describe(TServerProtocolDesc &aDesc, const TInt aIndex = 0);

	/**

	* Create the protocol instance.

	*

	* This is called directly from CProtocolFamilyGeneric::NewProtocolL(),

	* and all the semantics of the CProtocolFamilyBase::NewProtocolL are

	* in effect.

	*

	* The implementation must create one instance of a protocol based on

	* aSockType and aProtocol. These should match one of the descriptions

	* returned earlier (TProtocolDesc::iSockType and TProtocolDesc::iProtocol)

	* by Describe().

	*

	* @param	aSocketType	The socket type.

	* @param	aProtocol	The protocl number

	* @return	The protocol instance

	*

	* The function must leave, if protocol cannot be created. Returning

	* NULL is not allowed.

	*/

	static CProtocolBase *NewProtocolL(TUint aSockType, TUint aProtocol);

	};

#endif