Class CServProviderBase

CServProviderBase

Support

Supported from 5.0

Description

Service Access Point.

This class 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.

Derivation

CBase Base class for all classes to be instantiated on the heap CServProviderBase Service Access Point

Defined in CServProviderBase:
ActiveOpen(), AutoBind(), CancelIoctl(), EImmediate, ENormal, EStopInput, EStopOutput, GetData(), GetOption(), Ioctl(), LocalName(), PassiveOpen(), RemName(), SetLocalName(), SetOption(), SetRemName(), Shutdown(), TCloseType, Write(), iSocket

Inherited from CBase:
operator new()

virtual void LocalName(TSockAddr& anAddr)=0;

Description

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.

Parameters

TSockAddr& anAddr The address to be filled in

virtual TInt SetLocalName(TSockAddr& anAddr)=0;

Description

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.

Parameters

TSockAddr& anAddr The address

Return value

TInt Returns KErrNone if the local name is correctly set or, if this is not the case, an informative error number.

virtual void AutoBind()=0;

Description

Specifies that the protocol should choose a local address for the service access point itself.

virtual void RemName(TSockAddr& anAddr)=0;

Description

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.

Parameters

TSockAddr& anAddr The address to be filled in

virtual TInt SetRemName(TSockAddr &anAddr)=0;

Description

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.

Parameters

TSockAddr& anAddr The address

Return value

TInt Returns KErrNone if the remote name is correctly set or, if this is not the case, an informative error number.

virtual void Ioctl(TUint aLevel, TUint aName,TDes8* anOption)=0;

Description

Performs some protocol specific IO control.

Notes:

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.

Parameters

TUint aLevel IOCTL level TUint aName IOCTL name TDes8* anOption IOCTL option

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

Description

Cancels an outstanding Ioctl call. You are guaranteed only to have one outstanding at once.

Parameters

TUint aLevel IOCTL level TUint aName IOCTL name

virtual void GetOption(TUint aLevel,TUint aName,TDes8& anOption) const =0;

Description

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 ofCProtocolBase.

Parameters

TUint aLevel Option level TUint aName Option name TDes8& anOption Option data

virtual void SetOption(TUint aLevel, TUint aName, const TDesC8& anOption)=0;

Description

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 ofCProtocolBase.

Parameters

TUint aLevel Option level TUint aName Option name TDesC8& anOption Option data

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

Description

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) toWrite(). 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.

Parameters

const TDesC8 &aDesc The data to be sent. TUint aOptions Protocol specific options TSockAddr* anAddr Address to write the data to

Return value

TUint 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 theWrite() fails due to some error, then it should callError() with an informative error number,

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

Description

Gets data which the protocol has indicated is waiting in its buffers using the NewData up-call on theMSocketNotify.

GetData() will only ever be called for as much data as the protocol has specified it can process using the NewDataup-call.

For stream oriented protocols GetData() should fill the descriptor with data from the stream. On a datagram protocolGetData() 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.

Parameters

const TDesC8 &aDesc The buffer for data TUint aOptions Protocol specific options TSockAddr* anAddr Where the data came from

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

Description

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.

The second version of the function is the same, but with user data in the connection frame.

ActiveOpen() is only ever called on connection-oriented sockets. Such a socket should always have both the local address and the remote address specified before ActiveOpen() is called. If this is not the case, then the protocol should panic.

When a connection has completed, the protocol should callConnectComplete() on its TNotify. If an error occurs during connection the protocol should not call ConnectComplete()at all; instead it should call Error().

Parameters

const TDesC8 &aConnectionData If the protocol supports user specified connection data, then it will be held in this buffer.

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

Description

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.

The second version of the function is the same, but with user data in the connection frame.

PassiveOpen() is only ever called on connection-oriented sockets. Such a socket should always have both the local address and the remote address specified before PassiveOpen() 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 inStart().

When a connection has completed, the protocol should callConnectComplete() on its TNotify. If an error occurs during connection the protocol should not call ConnectComplete()at all; instead it should call Error().

Parameters

TUint aQueSize size of connect queue const TDesC8 &aConnectionData if the protocol supports user specified connection data, then it will be held in this buffer.

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

Description

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 Shutdown() 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 CServProviderBase object. However, if the option argument is EImmediate, the CServProviderBase will be destroyed as soon as Shutdown() returns.

Parameters

TCloseType option The shutdown type. const TDesC8 &aDisconnectionData If the protocol supports disconnect data, any such data required will be held in this buffer.

TCloseType

Description

Describes the behaviour the SAP should take on shutdown.

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.

protected: MSocketNotify* iSocket

Description

On socket creation, the socket server sets this member to point to a server notification interface.