// Copyright (c) 2004-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:

// apibase.h - Definitions for exporting APIs from TCP/IP stack to protocol hooks

// Definitions for exporting APIs from TCP/IP stack to protocol hooks

//

/**

 @file apibase.h

 @publishedPartner

 @released

*/

#ifndef __APIBASE_H__

#define __APIBASE_H__

#include "inet6err.h"

/**

* This interface class provides capability of introducing new interfaces for existing classes

* in TCP/IP stack to be used by protocol hooks.

* With this class, protocol hooks can query whether an interface is

* supported and then use the interface. Backwards compatibility of revised interfaces is allowed by

* versioning the interfaces. This enables independent developement of protocol hooks

* and the TCP/IP stack while maintaining the compatibility towards older implementations.

* This should be used as base class for all interface classes that are visible outside

* the TCP/IP stack, or that should be prepared to export an API at some time to allow making

* compatible modifications later on.

*

* There should be a constant definition of form KApiVer_<name> for each API that is exported that

* identifies the version number of current API.

*

* @publishedPartner

* @released

*/

class MInetBase

{

public:

	/**

	* Returns a pointer to object that implements the requested API. If the the class that

	* processes this call does not recognize the API name, it leaves with KErrNotFound.

	* New versions

	* of the same API should maintain binary backwards compatibility. That is, the caller

	* requests a minimal accepted version, and if the implemented API is of the same version or

	* higher, an object should be returned. If the implemented version is smaller than what

	* requested, implementation of GetApiL leaves with KErrInetUnsupportedApi.

	* If API is changed in a way that does not maintain backwards

	* compatibility, a new API name should be allocated for it.

	*

	* Note: Callers should not use this method directly, but are strongly recommended to use

	* IMPORT_API_L macro, which checks for type safety. Additionally, there is IMPORT_API_VER_L

	* macro which can be used to explicitly request a known version and to return the actual

	* version implemented.

	*

	* <em> For example: </em>

	* @verbatim

	* MEventService *es = IMPORT_API_L(NetworkService()->Interfacer(), MEventService);

	* @endverbatim

	*

	* There should be MEventService header somewhere visible to the caller.

	*

	* @param aApiName API name that needs to be known by the implementator

	* @param aVersion Requested minimum version. Later versions are also accepted by the caller.

	*		  Overwritten by the actual version of the API when function returns,

	*		  if matching API was found.

	*

	* @return Pointer to the object that implements the API. The method leaves with error if the

	*	  instance could not be returned.

	*

	* @exception KErrInetUnsupportedApi Name of the API is not supported by the implementing class.

	* @exception KErrInetUnsupportedApiVersion The given API is implemented, but the version is

	*		  incompatible, i.e. older than requested.

	*/

	virtual void *GetApiL(const TDesC8& /*aApiName*/, TUint* /*aVersion*/)

	      { User::Leave(KErrInetUnsupportedApi); return NULL; }

	/**

	* This is similar to GetApiL with returned version, but this function does not return the

	* actual version implemented, so it can be used with constant parameters also.

	*/

	inline void *GetApiL(const TDesC8& aApiName, TUint aVersion)

	      { return GetApiL(aApiName, &aVersion); }

};

/**

* \def IMPORT_API_VER_L(base,api,version)

* Returns the pointer to object that implements requested API. \a base is the class from which

* the API is requested. \a api is the name of the virtual class that defines the API.

* \a version is the minimum version that is requested. Later versions are required to be backwards

* compatible, so the returned version number can be larger. See MInetBase description for more info.

*

* Note that IMPORT_API_VER_L does User::Leave, if the requested API was not available.

*/

#define IMPORT_API_VER_L(base,api,version) (api *)base->GetApiL(_L8(#api), version)

/**

* \def IMPORT_API_L

* Returns the pointer to object that implements requested API. Version is not given but it is

* determined by looking for constant definition KApiVer_<name> in the header files that tells

* the current version of the API.

* \a base is the class from which the API is requested.

* \a api is the name of the virtual class that defines the API. 

*/

#define IMPORT_API_L(base,api) (api *)base->GetApiL(_L8(#api), KApiVer_##api);

/**

* This is a helper class for checking the API type safety for objects that provide an API.

* The static class should not be used directly, but instead through EXPORT_API_L macro.

*

* @publishedPartner

* @released

*/

template<class T> class ApiChecker

{

public:

	/**

	* Returns an instance of the given API (template class T), if the current version is

	* equal or above the version that was requested. New versions of the API

	* are required to be (binary) backwards compatible. If version does not match, leaves with

	* KErrInetUnsupportedApiVersion.

	*

	* @param aCurVersion  Current version of the API implementation

	* @param aVersion     Version requested by the caller

	* @param aInstance    API implementation that is returned if it is of valid version.

	*/

	static T* CheckVersionL(TUint aCurVersion, TUint *aVersion, T *aInstance);

};

template<class T> T* ApiChecker<T>::CheckVersionL(TUint aCurVersion,

						  TUint *aVersion, T *aInstance)

{

	if (*aVersion > aCurVersion)

	  {

	    *aVersion = aCurVersion;

	    User::Leave(KErrInetUnsupportedApiVersion);

	  }

	*aVersion = aCurVersion;

	return aInstance;

}

/**

* \def EXPORT_API_L(api,instance,version)

* To be used in MInetBase::GetApiL implementation for checking if an API and its version matches

* the GetApiL request. Returns a pointer to API instance if the API matches.

* Leaves with KErrInetUnsupportedApiVersion if the requested version is not supported,

* i.e. its later than what is implemented.

*

* \a api is the class defining the API that is checked for. \a instance is the pointer that is

* returned if API matches.

* \a version is the minimum API version that is required. The actual version of API is

* returned as output

*

* <em> Example of a GetApiL implementation: </em>

* @verbatim

* void *CIp6Manager::GetApiL(TDesC8 aApiName, TUint* aVersion)

*	{

*

*	if (aApiName == _L8("MEventService"))

*	    return EXPORT_API_L(MEventService, iEventManager, aVersion);

*

*	if (aApiName == _L8("MNetworkInfo"))

*	    return EXPORT_API_L(MNetworkInfo, this, aVersion);

*

*	User::Leave(KErrNotFound);

*	return NULL;

*	}

* @endverbatim

*/

#define EXPORT_API_L(api,instance,version) \

	ApiChecker<api>::CheckVersionL(KApiVer_##api, version, instance)

#endif // __APIBASE_H__