--- /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
+