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

//

#if !defined(__SS_FLOWBINDERS_INTERNAL_H__)

#define __SS_FLOWBINDERS_INTERNAL_H__

class RMBufChain;

class MProvdSecurityChecker;

namespace ESock

{

class MUpperDataReceiver;

class MUpperControl;

class MLowerDataSender;

class MLowerControl;

class MSessionDataNotify;

class MSessionControlNotify;

class MSessionData;

class MSessionControl;

class CSubConnectionFlowBase;

class MFlowBinderControl

/**

Interface that a flow implements to allow creation of binders on it.

@internalTechnology

*/

	{

public:

    //protocol binder

	IMPORT_C virtual MLowerControl* GetControlL(const TDesC8& aProtocol);

	IMPORT_C virtual MLowerDataSender* BindL(const TDesC8& aProtocol, MUpperDataReceiver* aReceiver, MUpperControl* aControl);

	IMPORT_C virtual void Unbind( MUpperDataReceiver* aReceiver, MUpperControl* aControl);

    //session binder

	IMPORT_C virtual MSessionControl* GetControlL(TInt aSessionType, MSessionControlNotify& aSessionControlNotify);

	IMPORT_C virtual MSessionData* BindL(MSessionDataNotify& aNotify);

	IMPORT_C virtual void Unbind();

	IMPORT_C virtual CSubConnectionFlowBase& CloneFlowL(); //creates an unitialised duplicate of

	                        //its flow

	virtual CSubConnectionFlowBase* Flow() = 0; //returns its own flow

	};

/****************************************************************************************

Interface Module related classes

The following four classes are used by stacked interface modules to pass data and control

information up and down.  These interfaces do not cross a thread boundary.  In the comments

that follow, the terms "upper" and "lower" are used to describe, in relative terms, which

classes are implemented by which of a pair of stacked interface modules.

               -----------------------------------------

               |             Upper Module              |

               -----------------------------------------

                 ^    ^                         |    |       CSubConnectionFlowBase

   MUpperControl |    | MUpperDataReceiver      |    |                  |

                 |    |                         |    |                  |

                 |    |        MLowerDataSender |    | MLowerControl    |

                 |    |                         v    v                  |

               -----------------------------------------                |

               |             Lower Module              |<---------------+

               -----------------------------------------

*/

class MUpperDataReceiver

/**

Class implemented by an "upper" interface module to accept inbound data travelling

upwards from the interface module below.

@since Argus

@internalTechnology

*/

	{

public:

	virtual void Process(RMBufChain& aData) = 0;

	};

class MLowerDataSender

/**

Class implemented by a "lower" interface module to accept outbound data travelling downwards

from the interface module above.

@since Argus

@internalTechnology

*/

	{

public:

	enum TSendResult

		{

		// Send Flow Control

		// The 0 and 1 values below explicitly match the legacy return values from a NIF Send() call.

		ESendBlocked  = 0,		// data accepted, send no more until MUpperControl::Unblock()

		ESendAccepted = 1		// data accepted, can send more

		};

	virtual TSendResult Send(RMBufChain& aData) = 0;

	};

class MUpperControl

/**

Class implemented by an "upper" interface module to accept control signals from the

interface module below.

@since Argus

@internalTechnology

*/

	{

public:

	virtual void StartSending() = 0;

	virtual void Error(TInt anError) = 0;

	};

class MLowerControl

/**

Class implemented by a "lower" interface module to accept control signals from the

interface module above.

@since Argus

@internalTechnology

*/

	{

public:

	enum TBlockOption

		{

		EDisableAllOtherBindersOnFlow,

		EDisableAllOtherBindersOnInterface,

		EEnableAllBinders

		};

	IMPORT_C virtual TInt GetName(TDes& aName);

	IMPORT_C virtual TInt BlockFlow(TBlockOption aOption);

	IMPORT_C virtual TInt GetConfig(TBinderConfig& aConfig);

	IMPORT_C virtual TInt Control(TUint aLevel, TUint aName, TDes8& aOption);

	};

class MSessionControl

/**

@internalTechnology

*/

    {

public:

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

	//the values of the enum directly map to CServProviderBase::TCloseType enum values

	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.

	};

	/**

	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;

       /**When the set local name operation has completed, the protocol should call SetLocalNameComplete() 

	on its TNotify	*/

	virtual void 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).

	The value of the option argument specifies the type of processing which will 

	be required of the protocol after this function is called.

	Normally, when the socket server has called Shutdown() for a socket, it will 

	wait for the socket to call CanClose() before destroying the CSubConnectionFlowBase 

	object. However, if the option argument is EImmediate, the CSubConnectionFlowBase 

	will be destroyed as soon as Shutdown() returns.

	@param option The shutdown type. */

	virtual void Shutdown(MSessionControl::TCloseType option)=0;

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

	The value of the option argument specifies the type of processing which will 

	be required of the protocol after this function is called.

	Normally, when the socket server has called Shutdown() for a socket, it will 

	wait for the socket to call CanClose() before destroying the CSubConnectionFlowBase 

	object. However, if the option argument is EImmediate, the CSubConnectionFlowBase 

	will be destroyed as soon as Shutdown() returns.

	@param option The shutdown type. 

	@param aDisconnectionData If the protocol supports disconnect data, any such 

	data required will be held in this buffer. */

	virtual void Shutdown(MSessionControl::TCloseType option, const TDesC8& aDisconnectionData)=0;

	/** Specifies that the protocol should choose a local address for the service access 

	point itself. */

	virtual void AutoBind()=0;

	/**  Use the class instance argument to perform security policy checks on the originating client process.

	This method is called when a SAP is created and when a socket is transferred between sessions.  The SAP is

	required to check whether the originating client process has enough privileges to request services from the SAP.

	The MProvdSecurityChecker class instance is used to perform security policy checks.  The SAP may choose

	to perform a security policy check in its SecurityCheck(...) method, or it may choose to store the

	MProvdSecurityChecker class instance argument and perform checking later (i.e. when subsequent

	SAP methods are called).

	@param aSecurityChecker Pointer to class used by SAP to perform security checks on the client process.  This

	pointer becomes invalid when the SAP is destroyed or detached.

	@returns KErrPermissionDenied if SAP wishes to disallow access to the client, else KErrNone.  This would

	normally be as a result of calling MProvdSecurityChecker::CheckPolicy(...) with a suitable security policy argument.

	*/

	virtual TInt SecurityCheck(MProvdSecurityChecker *aSecurityChecker) = 0;

    };

class MSessionData

    {

/**

@internalTechnology

*/

public:

// protocol read/write data; ESock v1.5 calls down to the v1.5 itf (RMBufChain). 

// v1.5-ready protocols implement this, laggard protocols inherit these base class

// implementations which call the v1.0 descriptor itf instead. 

	/** Sends data onto the network via the protocol.

	Connection-oriented sockets must be in a connected state (that is ConnectComplete() has 

	been called on their MSocketNotify before Write() is called).

	The socket server keeps track of how much data is waiting and then tries to send it all 

	until the protocol tells it to hold off by returning 0 (datagram sockets) or 'less than 

	all data consumed' (stream sockets) to Write(). The protocol should call CanSend() when it 

	is ready to send more data.

	anAddr is the address to write the data to.	Connection oriented sockets always use the 

	default value.

	@param aDesc The data to be sent.

	@param aOptions Protocol specific options.

	@param anAddr Address to write the data to.

	@returns For stream-oriented protocols the return value is the number of bytes actually written. 

	If this is less than the length of the descriptor then the protocol should call CanSend() 

	when it is ready to send more data. For datagram-oriented protocols, the write should return 

	either 0 if the write cannot be completed, or the length of the descriptor if the write succeeds - 

	no other values are valid. If the Write() must return 0, then it should call CanSend() when it is 

	ready to send more data. If the Write() fails due to some error, then it should call Error() with 

	an informative error number.

	*/

	virtual TUint Write(const TDesC8& aDesc,TUint options, TSockAddr* anAddr=NULL) = 0;

	/** Sends data onto the network via the protocol.

	Connection-oriented sockets must be in a connected state (that is ConnectComplete() has 

	been called on their MSocketNotify before Write() is called).

	The socket server keeps track of how much data is waiting and then tries to send it all 

	until the protocol tells it to hold off by returning 0 (datagram sockets) or 'less than 

	all data consumed' (stream sockets) to Write(). The protocol should call CanSend() when it 

	is ready to send more data.

	anAddr is the address to write the data to.	Connection oriented sockets always use the 

	default value.

	@param aData The data to be sent.

	@param aOptions Protocol specific options.

	@param anAddr Address to write the data to.

	@returns For stream-oriented protocols the return value is the number of bytes actually written. 

	If this is less than the length of the descriptor then the protocol should call CanSend() 

	when it is ready to send more data. For datagram-oriented protocols, the write should return 

	either 0 if the write cannot be completed, or the length of the descriptor if the write succeeds - 

	no other values are valid. If the Write() must return 0, then it should call CanSend() when it is 

	ready to send more data. If the Write() fails due to some error, then it should call Error() with 

	an informative error number.

	*/

	virtual TInt Write(RMBufChain& aData, TUint aOptions, TSockAddr* anAddr=NULL) = 0;

	/** Gets data which the protocol has indicated is waiting in its buffers using the NewData 

	up-call on the MSocketNotify. 

	GetData() will only ever be called for as much data as the protocol has specified it can process 

	using the NewData up-call. 

	For stream oriented protocols GetData() should fill the descriptor with data from the stream. On 

	a datagram protocol GetData() should copy one datagram into the descriptor and set the length of 

	the descriptor. If a full datagram will not fit into the supplied descriptor, the overflow should 

	be discarded. 

	anAddr should be filled in by the protocol with the address of where the data came from.

	@param aDesc  The buffer for data.

	@param aOptions Protocol specific options.

	@param anAddr Address where the data came from.

	*/

	virtual void GetData(TDes8& aDesc,TUint options,TSockAddr* anAddr=NULL) = 0;

	/** Gets data which the protocol has indicated is waiting in its buffers using the NewData 

	up-call on the MSocketNotify. 

	GetData() will only ever be called for as much data as the protocol has specified it can process 

	using the NewData up-call. 

	For stream oriented protocols GetData() should fill the descriptor with data from the stream. On 

	a datagram protocol GetData() should copy one datagram into the descriptor and set the length of 

	the descriptor. If a full datagram will not fit into the supplied descriptor, the overflow should 

	be discarded. 

	anAddr should be filled in by the protocol with the address of where the data came from.

	@param aDesc  The buffer for data.

	@param aOptions Protocol specific options.

	@param anAddr Address where the data came from.

	*/

	virtual TInt GetData(RMBufChain& aData, TUint aLength, TUint aOptions, TSockAddr* anAddr=NULL) = 0;

    };

}

#endif