diff -r 000000000000 -r dfb7c4ff071f datacommsserver/esockserver/inc/ss_flowbinders_internal.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/datacommsserver/esockserver/inc/ss_flowbinders_internal.h Thu Dec 17 09:22:25 2009 +0200 @@ -0,0 +1,458 @@ +// 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 +