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

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

/**

 @file

 @publishedPartner

 @released

*/

#if !defined(__ES_PROT_H__)

#define __ES_PROT_H__

#include <es_enum.h>

/**

ESock subsession unique id

@internalTechnology

*/

typedef TUint TSubSessionUniqueId;

/**

@internalComponent

*/

enum TConnStartType 

	{

	EConnStartExplicit,

	EConnStartImplicit

	};	

/**

@internalComponent

*/

enum TESOCKActivePriority

	{

	ESSExclusivePriority=100000,

	ECommReceivePriority=200,		///< Must always run.

	ECommTransmitPriority=100,

	ECAsyncImmediatePriority=75,	///< I.e. before a timer event goes off.

	ESocketTimerPriority=50,

	EActiveIpcPriority=20,

	EActiveHighPriority=10,

	EActiveMedPriority=0,

	EActiveLowPriority=-10,

	ECAsyncDeferredPriority=-20,

	};

/**

End of data,Socket can't receive more data.

@publishedPartner

@released

*/

const TUint KNewDataEndofData = 0xFFFFFFFF;

class CServProviderBase;

class CSocket;

class MSocketNotify

/** Abstract base class used by a CServProviderBase-derived object, through its 

iSocket member, to notify the socket server that various events have occurred. 

The class provides several up-call member functions.

All up-calls on an MSocketNotify should be made in the context of the socket 

server's thread - i.e. the thread which called NewSAPL() on the protocol. 

@publishedPartner

@released Since v5.0 */

	{

public:

	/** Delete and detach flags. */

	enum TDelete 

		{

		/** Delete SAP */	

		EDelete,

		/** Don't delete SAP */

		EDetach

		};

	/** Error codes. */

	enum TOperationBitmasks

		{

		/** An error has occurred which affects Send() operations */

		EErrorSend=0x0000001,  

		/** An error has occurred which affects Receive() operations. */

		EErrorRecv=0x0000002,

		/** An error has occurred which affects Connect() operations */

		EErrorConnect=0x0000004,

		/** An error has occurred which affects Close() operations */

		EErrorClose=0x00000008,

		/** An error has occurred which affects Ioctl() operations */

		EErrorIoctl=0x00000010,

		/** A fatal error has occurred */

		EErrorFatal=0x10000000,

		/** An error has occurred which affects all operations */

		EErrorAllOperations=0x7fffffff,

		};

	/**

	Indicates that new data is available on a service access point

	For a stream-oriented protocol aCount should be a byte count; for datagram-oriented 

	sockets aCount should be a datagram count.

	@note aCount is the amount of new data, not the total amount of data waiting 

	to be read.

	@param aCount The amount of new data. A value of KNewDataEndofData indicates 

	that the socket is in a half-closed state and will receive no more data. Any subsequent 

	reads will complete with KErrEof and a length of 0. */

	virtual void NewData(TUint aCount) = 0;

	/** Indicates that new buffer space is available on a service. */

	virtual void CanSend() = 0;

	/** Indicates that a connection attempt has completed successfully (for active opens).

	There are four versions of this up-call: two are for active opens and two are for passive 

	opens. Both active and passive versions support a variant carrying user connection 

	data for protocols which support it.

	@note A connection-less protocol should never call the ConnectComplete() up-calls.

	@note A protocol should keep a count of sockets which have called ConnectComplete() 

	but have not had Start() called. Sockets in this state have their Error() 

	and NewData() calls deferred until Start() is called.*/

	virtual void ConnectComplete() = 0;

	/** Indicates that a connection attempt has completed successfully (for active opens).

	There are four versions of this up-call: two are for active opens and two are for passive 

	opens. Both active and passive versions support a variant carrying user connection 

	data for protocols which support it.

	@note A connection-less protocol should never call the ConnectComplete() up-calls.

	@note A protocol should keep a count of sockets which have called ConnectComplete() 

	but have not had Start() called. Sockets in this state have their Error() 

	and NewData() calls deferred until Start() is called.

	@param aConnectData Connect data (if supported).

	*/

	virtual void ConnectComplete(const TDesC8& aConnectData) = 0;

	/** Indicates that a connection attempt has completed successfully (for passive opens). 

	There are four versions of this up-call: two are for active opens and two are for passive 

	opens. Both active and passive versions support a variant carrying user connection 

	data for protocols which support it.

	The versions of ConnectComplete() for passive opens carry a new SSP (socket service 

	provider, or SAP) for the newly created socket. A new socket will then be linked up to 

	the SSP and data transfer can take place. The original socket stays listening.

	@note A connection-less protocol should never call the ConnectComplete() up-calls.

	@note A protocol should keep a count of sockets which have called ConnectComplete() 

	but have not had Start() called. Sockets in this state have their Error() 

	and NewData() calls deferred until Start() is called.

	@param aSSP The new SSP for passive opens. 

	*/

    virtual void ConnectComplete(CServProviderBase& aSSP) = 0;

	/** Indicates that a connection attempt has completed successfully (for passive opens). 

	There are four versions of this up-call: two are for active opens and two are for passive 

	opens. Both active and passive versions support a variant carrying user connection 

	data for protocols which support it.

	The versions of ConnectComplete() for passive opens carry a new SSP (socket service 

	provider, or SAP) for the newly created socket. A new socket will then be linked up to 

	the SSP and data transfer can take place. The original socket stays listening.

	@note A connection-less protocol should never call the ConnectComplete() up-calls.

	@note A protocol should keep a count of sockets which have called ConnectComplete() 

	but have not had Start() called. Sockets in this state have their Error() 

	and NewData() calls deferred until Start() is called.

	@param aSSP The new SSP for passive opens. 

	@param aConnectData Connect data (if supported). */

	virtual void ConnectComplete(CServProviderBase& aSSP,const TDesC8& aConnectData) = 0;

	/** Indicates that the SAP has finished closing down. 

	This up-call is the response to a Shutdown(). A connection-oriented protocol should call 

	CanClose() when it has terminated communications with the remote host. Protocols can call 

	CanClose() from within their Shutdown() code. After CanClose() has been called, an SAP may 

	be deleted by the socket server.

	@note The protocol must not access the CServProviderBase object after calling CanClose().

	@param aDelete Delete SAP. 

	*/

	virtual void CanClose(TDelete aDelete=EDelete) = 0;

	/** Indicates that the SAP has finished closing down. 

	This up-call is the response to a Shutdown(). A connection-oriented protocol should call 

	CanClose() when it has terminated communications with the remote host. Protocols can call 

	CanClose() from within their Shutdown() code. After CanClose() has been called, an SAP may 

	be deleted by the socket server.

	@note The protocol must not access the CServProviderBase object after calling CanClose().

	@param aDisconnectData Any user data carried on the disconnect frame.

	@param aDelete Delete SAP. 

	*/

	virtual void CanClose(const TDesC8& aDisconnectData,TDelete aDelete=EDelete) = 0;

	/** Tells the socket server that an error state has arisen within the protocol. 

	It should not be used to report programmatic errors, either in the protocol 

	itself or the socket server (a panic should be used in these cases). When 

	Error() is called on a connection-oriented socket, the socket is moved into 

	a dead state which denies user access to it.

	@param anError KErrNone or another of the system-wide error codes. 

	@param anOperationMask A bitmask of TOperationBitmasks values specifying which 

	pending operations are affected by the Error up-call. */

	virtual void Error(TInt anError,TUint anOperationMask=EErrorAllOperations) = 0;

	/** Indicates that the other end of a connection has disconnected.

	This is analogous to CanClose(), but in this case the other end initiated it. 

	Once the client has called Shutdown() it is	illegal to call Disconnect(). Instead, 

	CanClose() or Error(KErrDisconnected) should be called.

	*/

	virtual void Disconnect(void) = 0;

	/** Indicates that the other end of a connection has disconnected.

	This is analogous to CanClose(), but in this case the other end initiated it. 

	Once the client has called Shutdown() it is	illegal to call Disconnect(). Instead, 

	CanClose() or Error(KErrDisconnected) should be called. 

	@param aConnectData User data in the disconnect frame.

	*/

	virtual void Disconnect(TDesC8& aDisconnectData) = 0;

	/** Indicates that the currently pending Ioctl has completed.

	The parameter aBuf is protocol defined - in fact it is defined by the specific 

	Ioctl.

	@param aBuf Any data requested by the Ioctl operation. */

	virtual void IoctlComplete(TDesC8* aBuf) = 0;

	/**

	Indicates that there are no bearer available

	@param  aConnectionParams, the connection parameters.

	*/

	virtual void NoBearer(const TDesC8& aConnectionParams) = 0;

	/**

	Indicates the bearer available.

	@param aConnectionInfo, Information about socket connection.

	*/

	virtual void Bearer(const TDesC8& aConnectionInfo) = 0;

	/**

	Indicates that this socket is now completed an asynchronous join

	with a sub-connection. It now can use the properties of the sub-connection

	*/

	virtual void JoinedSubConnection() {;};

	/**

	Indicates that this socket was not able to complete an asynchronous join

	with a sub-connection. The socket is still joined, but cannot use the

	properties of the sub-connection

	@param aError Reason the socket could not be joined

	*/

	virtual void SubConnectionJoinFailed(TInt /*aError*/) {;};

	/**

	Indicates that this socket has now completed an asynchronous leave

	from a sub-connection. The socket is now connected to the sub-connection

	anymore.

	*/

	virtual void LeftSubConnection() {;};

private:

	};

class TNifProgress;

class MConnectionNotify

/**

 * Callback interface from CConnectionProvdBase-derived classes

 * @internalTechnology

 */

	{

public:

	virtual void SelectionComplete(TInt aError, const TDesC8& aSelectionInfo) = 0;

	virtual void ConnectionError(TInt aError) = 0;

	virtual void LinkLayerOpen(TInt aError) = 0;

	virtual void LinkLayerClosed(TInt aError) = 0;

	virtual void ProgressNotification(TInt aStage, TInt aError) = 0;

	virtual void ProgressNotification(TSubConnectionUniqueId aSubConnectionUniqueId, TInt aStage, TInt aError) = 0;

	virtual void ServiceChangeNotification(TUint32 aId, const TDesC& aType) = 0;

	virtual void InterfaceStateChangeNotification(TDesC8& aInfo) = 0;

	virtual void NotifyDataSent(TSubConnectionUniqueId aSubConnectionUniqueId, TUint aUplinkVolume) = 0;

	virtual void NotifyDataReceived(TSubConnectionUniqueId aSubConnectionUniqueId, TUint aDownlinkVolume) = 0;

	virtual void SubConnectionEvent(const TSubConnectionEvent& aSubConnectionEvent) = 0;

	};

/**

@internalComponent

*/

enum TProtocolServiceInfo

	{

	ESocketSupport=0x00000001,		///< Can make sockets

	ETransport=0x00000002,			///< Can act as a transport - ie can be bound to

	EPreferMBufChains=0x00000004,	///< Will process MBufChains (I.e. won't convert them to descriptors)

	EPreferDescriptors=0x00000008,	///< Will process Descriptors (I.e. won't convert them to MBufChains)

	ECantProcessMBufChains=0x00000010,	///< Will Panic if asked to process an MBufChain

	ENeedMBufs=0x00000020,			///< Uses MBufChains internally.

	EUseCanSend=0x00000040,			///< Uses the inter-protocol CanSend upcall.

	EInterface=0x00000080,			///< Is a CInterfaceBase rather than CProtocolBase

	};

/**

@internalTechnology

*/

enum TProtocolType

	{

	ENormalProtocol,				///< Normal protocol

	EInterfaceProtocol				///< Has EInterface flags set and supports GetBinderL()

	};

/**

@internalComponent

*/

const TInt KUnlimitedSockets=-1;

struct TServerProtocolDesc : public TProtocolDesc

/**

Contains data that describes a particular protocol. 

@publishedPartner

@released

@see CProtocolFamilyBase::ProtocolList(). 

*/

	{

	TInt iServiceTypeInfo;  ///< Set this to 1 if the protocol supports socket creation

	TInt iNumSockets;       ///< The maximum number of SSPs the protocol supports

	};

class MResolverNotify

/**

@publishedPartner

@released

*/

	{

public:

	virtual void QueryComplete(TInt anError)=0;

	};

/** Ensure that the requested length for datagrams is bigger than any real one. This ensures that

naive providers deliver them without truncation, so allowing the client to perform continuation reads.

@internalTechnology

*/

const TUint KGetDataWholeDatagram = 0x40000000;

/**

Security checker class passed down to providers which is used to perform security checks on the client

of the provider.  The provider calls the CheckPolicy(...) method with a suitable TSecurityPolicy

class and a diagnostic string as arguments.

@see CServProviderBase

@see CResolverProvdBase

@code

_LIT_SECURITY_POLICY_C1(myPolicy1, ECapabilityNetworkServices);

...

TInt CMyProvider::SecurityCheck(MProvdSecurityChecker *aChecker)

{

	...

	if (aChecker->CheckPolicy(myPolicy1, "CMyProvider main") == KErrNone)

	{

		// client has NetworkServices capability

	}

	...

}

@endcode

@publishedPartner

@released

*/

class MProvdSecurityChecker 

{

public:

	/**

	Check the security policy of a client process.

	Called from a socket or resolver provider to check whether the client process conforms to a security policy.

	@param aPolicy A TSecurityPolicy class instance containing the security information to be checked against the client.

	@param aDiagnostic A diagnostic string used when logging system-wide security failures, else 0.

	@return KErrNone if client process has the required security information, else KErrPermissionDenied.

	(In the future, some other system error may be returned).

	*/

	virtual TInt CheckPolicy(const TSecurityPolicy& aPolicy, const char *aDiagnostic) = 0;

};

class RMBufChain;

class CSubConnectionProviderBase;

class CServProviderBase : public CBase

/** Service Access Point.

Provides transport services to a single protocol. Several of the calls to 

CServProviderBase have pre-conditions attached to them - for example 

a connection oriented protocol must have its local address set (either by 

a SetLocalName() or AutoBind()) before it is opened. If the socket server 

calls the CServProviderBase in such an erroneous way, the protocol should panic.

@publishedPartner

@released Since 5.0 */

	{

	friend class ProtocolManager;

public:

	/** Describes the behaviour the SAP should take on shutdown.*/

	enum TCloseType 

	{

		ENormal,        ///< The protocol should shutdown gracefully — no further input or output will be requested.

		EStopInput,     ///< The protocol should shut down gracefully — all further and pending input should be discarded.

		EStopOutput,    ///< The protocol should shutdown gracefully — all pending output should be discarded.

		EImmediate      ///< The protocol should close the connection immediately and free all resources without performing a graceful disconnect.

	};

	IMPORT_C CServProviderBase();

	IMPORT_C virtual ~CServProviderBase();

	IMPORT_C virtual void SetNotify(MSocketNotify* aSocket);

	//V1.0 itf support

	IMPORT_C virtual void SetSockType(TUint aSockType);

	IMPORT_C TUint SockType() const;

	IMPORT_C virtual void JoinSubConnectionL(CSubConnectionProviderBase& aSubConnProvider);

	IMPORT_C virtual void LeaveSubConnection(CSubConnectionProviderBase& aSubConnProvider);

public:

/**

pure virtual

*/

	/**

	Start a service provider.

	*/

	virtual void Start()=0;

	/** Gets the local name (address) of the socket service provider entity. The format 

	of the data in the TSockAddr object is defined by individual protocols.

	The local address is the address of the local machine plus a local port number. 

	Generally only the port number is important, unless you have two IP interfaces, 

	for example.

	@param anAddr The address to be filled in */

	virtual void LocalName(TSockAddr& anAddr) const =0;

	/** Sets the local name (address) of the socket service provider entity. The format 

	of the data in the TSockAddr object is defined by individual protocols.

	@param anAddr The address 

	@return Returns KErrNone if the local name is correctly set or, if this is 

	not the case, an informative error number. */

	virtual TInt SetLocalName(TSockAddr& anAddr)=0;

	/** Gets the remote name (address) of the socket service provider entity. The format 

	of the data in the TSockAddr object is defined by individual protocols.

	A remote address is either the address you're sending data to (non connection-oriented 

	sockets)* or the remote end of the connection. It is the address of the remote 

	machine (your peer in the network) plus a port number.

	@note RemName is only meaningful if the socket server client has called Connect() 

	to set up a default address for SendTo(). This function will only be called 

	on the protocol if this is the case.

	@param anAddr The address to be filled in */

	virtual void RemName(TSockAddr& anAddr) const =0;

	/** Sets the remote name (address) of the socket service provider entity. The format 

	of the data in the TSockAddr object is defined by individual protocols.

	@param anAddr The address 

	@return Returns KErrNone if the remote name is correctly set or, if this is 

	not the case, an informative error number. */

	virtual TInt SetRemName(TSockAddr& anAddr)=0;

	/** Gets some protocol specific option when called by the socket server on behalf of a 

	client. A protocol may pass the request down a protocol	stack (to protocols it is bound 

	to) using the GetOption() function of CProtocolBase.

	@param aLevel Option level.

	@param aName Option name.

	@param anOption Option data.

	@return System wide error code.

	*/

	virtual TInt GetOption(TUint level,TUint name,TDes8& anOption)const =0;

	/** Performs some protocol specific IO control. 

	@note If this function is called erroneously, the protocol should call Error() on the 

	socket. If an Ioctl call is already outstanding, the client will be panicked with the 

	value ETwoIoctls.

	@param aLevel Option level.

	@param aName Option name.

	@param anOption Option data.

	@return System wide error code.

	*/

	virtual void Ioctl(TUint level,TUint name,TDes8* anOption)=0;

	/** Cancels an outstanding Ioctl call. You are guaranteed only to have one outstanding 

	at once. 

	@param aLevel IOCTL level. 

	@param aName IOCTL name. 

	*/

	virtual void CancelIoctl(TUint aLevel,TUint aName)=0;

	/** Sets some protocol specific option when called by the socket server on behalf of a 

	client. A protocol may pass the request down a protocol	stack (to protocols it is bound