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

//

/**

 @file

 @publishedPartner

 @released

*/

#if !defined(__ES_PROT_H__)

#define __ES_PROT_H__

#define SYMBIAN_NETWORKING_UPS

#include <es_enum.h>

#include <e32std.h>

/**

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

@publishedPartner

@released

*/

const TUint KNewDataEndofData = 0xFFFFFFFF;

class CServProviderBase;

namespace ESock

{

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() {;};

	};

/**

@publishedPartner

@released

*/

const TInt KUnlimitedSockets=-1;

struct TServerProtocolDesc : public TProtocolDesc

/**

Contains data that describes a particular protocol. 

@publishedPartner

@released

@see CProtocolFamilyBase::ProtocolList(). 

*/

	{

	TInt iServiceTypeInfo;  //< Options from TProtocolServiceInfo bitwise OR'd together. @see TProtocolServiceInfo

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

	};

class MResolverNotify

/**

@publishedPartner

@released

*/

	{

public:

	virtual void QueryComplete(TInt anError)=0;

	};

/**

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;

};

namespace ESock

{

class CSubConnectionProviderBase;

}

class RMBufChain;

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(ESock::CSubConnectionProviderBase& aSubConnProvider);

	IMPORT_C virtual void LeaveSubConnection(ESock::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 

	to) using the SetOption() function	of CProtocolBase.

	@param aLevel Option level.

	@param aName Option name.

	@param anOption Option data.

	@return System wide error code.

	*/

	virtual TInt SetOption(TUint level,TUint name,const TDesC8& anOption)=0;

	virtual void ActiveOpen()=0;

	/** Initiates a connection operation - this means that it tells the protocol to 

	attempt to connect to a peer. It is called by the socket server in response 

	to a connect request from a client. 

	This version of the function has user data in the connection frame.

	Only ever called on connection-oriented sockets. Such a socket 

	should always have both the local address and the remote address specified 

	before this function is called. If this is not the case then the protocol 

	should panic.

	When a connection has completed, the protocol should call ConnectComplete() 

	on its TNotify. If an error occurs during connection the protocol should not 

	call ConnectComplete() at all; instead it should call Error().

	@param aConnectionData If the protocol supports user specified connection 

	data, then it will be held in this buffer. */

	virtual void ActiveOpen(const TDesC8& aConnectionData)=0;

	/** Tells the protocol to start waiting for an incoming connection request on this 

	socket (i.e. port). It is called by the socket server in response to a listen 

	request from a client.

	Only ever called on connection-oriented sockets. Such a socket 

	should always have both the local address and the remote address specified 

	before this function is called. If this is not the case, then the protocol 

	should panic.

	The aQue parameter is the number of sockets which can be waiting for an outstanding 

	Start after calling ConnectComplete(). The protocol should keep a count of 

	sockets in this state - incrementing a variable in ConnectComplete(), and 

	decrementing it in Start().

	When a connection has completed, the protocol should call ConnectComplete() 

	on its TNotify. If an error occurs during connection the protocol should not 

	call ConnectComplete() at all; instead it should call Error().

	@param aQueSize Size of connect queue. 

	*/

	virtual TInt PassiveOpen(TUint aQueSize)=0;

	/** Tells the protocol to start waiting for an incoming connection request on this 

	socket (i.e. port). It is called by the socket server in response to a listen 

	request from a client.

	This version of the function has user data in the connection frame.

	Only ever called on connection-oriented sockets. Such a socket 

	should always have both the local address and the remote address specified 

	before this function is called. If this is not the case then the protocol 

	should panic.

	The aQue parameter is the number of sockets which can be waiting for an outstanding 

	Start after calling ConnectComplete(). The protocol should keep a count of 

	sockets in this state - incrementing a variable in ConnectComplete(), and 

	decrementing it in Start().

	When a connection has completed the protocol should call ConnectComplete() 

	on its TNotify. If an error occurs during connection the protocol should not 

	call ConnectComplete() at all; instead it should call Error().

	@param aQueSize size of connect queue 

	@param aConnectionData if the protocol supports user specified connection data 

	then it will be held in this buffer. */

	virtual TInt PassiveOpen(TUint aQueSize,const TDesC8& aConnectionData)=0;

	/** Terminates a connection (or closes a non connection-oriented socket down).