Class CProtocolBase

CProtocolBase

Support

Supported from 5.0

Description

Protocols created by protocol families must be instances of sub-classes of the abstract CProtocolBase.

Derivation

CBase Base class for all classes to be instantiated on the heap CProtocolBase Protocols created by protocol families must be instances of sub-classes of the abstract CProtocolBase

Defined in CProtocolBase:
BindL(), BindToL(), CanClose(), Close(), CloseNow(), Error(), GetOption(), Identify(), InitL(), NewHostResolverL(), NewNetDatabaseL(), NewSAPL(), NewServiceResolverL(), Open(), Process(), Send(), SetOption(), StartL(), StartSending(), Tag()

Inherited from CBase:
operator new()

virtual void InitL(TDesC& aTag);

Description

Initialises a protocol before any binding is performed. A protocol can override it to create any further resources it may require — this might include allocating buffers, opening devices or reading more configuration information.

The default implementation does nothing.

Parameters

TDesC& aTag The string identifier for the protocol as given by its section header in esock.ini

Leave codes

If the protocol encounters any errors it should leave.

virtual void StartL();

Description

Indicates to a protocol that all binding has completed successfully and it can start processing datagrams. This is mainly of interest to the lowest levels of a protocol stack which would queue a read on the network media device driver in response to this call.

The default implementation does nothing.

Leave codes

If a protocol cannot start to process data (for example it may not have bound correctly) it should leave.

virtual void BindTo(CProtocolBase* protocol, TUint id);

Description

Instructs a lower level protocol to bind to a protocol higher up in the stack. The protocol must call the Bind() function of the specified lower level protocol specifying itself as the source protocol.

The protocol must keep a record of who is binding to it, in order to send data.

The default implementation panics.

Parameters

CProtocolBase* protocol The lower level protocol whose bind function must be called TUint id The lower level protocol’s id number

Leave codes

This function should leave if, for example, it cannot allocate internal resources necessary, or if the protocol binding is passing in the same ID as from a previous BindToL() call.

virtual void Bind(CProtocolBase *protocol, TUint id)=0;

Description

Instructs a higher level protocol to bind to another protocol higher up on the stack.

The default implementation panics.

Parameters

CProtocolBase *protocol The higher level protocol requesting to bind TUint id The id number of the protocol requesting to bind

Leave codes

This function should leave if, for example, it cannot allocate internal resources necessary, or if the protocol binding is passing in the same ID as from a previous BindL() call.

Description

A protocol which is to provide socket services (i.e. it is at the highest level of the stack) must provide one or more CServProviderBase-derived objects. These objects, known as service access points, provide the means for the socket server to send data to and receive data from a protocol (on behalf of its clients). Protocols that provide host name resolution, network database access, or service resolution should also provide suitable objects for these services.

virtual CHostResolvProvdBase* NewHostResolverL();

Description

Creates a host name resolver service, if one is supplied by the protocol. Return NULL if no such service is supported.

Return value

CHostResolvProvdBase* The host name resolver service

virtual CNetDBProvdBase* NewNetDatabaseL();

Description

Creates a network database access service, if one is supplied by the protocol. Return NULL if no such service is supported.

Return value

CNetDBProvdBase* The network database access service

virtual CServProviderBase* NewSAPL(TUint aSocketType);

Description

Creates a new service access point.

If the protocol cannot create the CServProviderBase for any reason, it should leave.

Parameters

TUint aSocketType What sort of socket to create - raw, stream, datagram, or sequenced packet.

Return value

CServProviderBase* The service access point

virtual CServiceResolvProvdBase* NewServiceResolverL();

Description

Creates a service resolver service, if one is supplied by the protocol. Return NULL if no such service is supported.

Return value

CServiceResolvProvdBase* The service resolver service

virtual void Open();

Description

Opens a client connection. The default implementation simply increments the reference count. Any implementations by derived classes should call this base class implementation.

virtual void Close();

Description

Closes a client connection. The default implementation decrements the reference count and calls CloseNow() if no clients are connected. Any implementations by derived classes should call this base class implementation.

virtual void CloseNow();

Description

Closes the protocol. It is called by Close() when all clients referencing a protocol have disconnected. The default implementation simply deletes the object. Derived classes can implement this function to provide a delayed closedown: for example, to allow reliable protocols to ensure that all data has drained from the stack before it is deleted. When an acceptable closedown condition has been reached, the protocol should call CanClose().

void CanClose();    

Description

Called by derived classes when an acceptable closedown condition has been reached. See CloseNow() for more details. Derived classes should not override this function.

Description

Protocols which are bound to each other can expect various services from each other and, in turn, must service the requests of other protocols. A protocol which is bound to another protocol can send packets of data down the stack using one of the two flavours of Send() function. A protocol which has had a protocol bind to it can deliver datagrams via that protocol using one of the two flavours of Process() function.

virtual TInt Send(TDes8& aPDU, TSockAddr* aTo, TSockAddr* aFrom=NULL,
        CProtocolBase* aSourceProtocol=NULL);

Description

Sends a datagram down the stack when called by a protocol module on any other protocol to which it has bound.

This version of the Send() function should be used when descriptor-based protocol data units are in use.

The aFrom parameter is the address originating the send. This is passed through as it may affect routing or something else, depending on the particular protocol. Generally its value is the local address of the socket sending the data.

Parameters

TDes8& aPDU The datagram to be sent TSockAddr* aTo The address to send the datagram to TSockAddr* aFrom The address originating the send CProtocolBase* aSourceProtocol The protocol from which the data has been sent

Return value

TInt A system error code

virtual void Process(TDes8& aPDU, TSockAddr* aFrom, TSockAddr* aTo=NULL,
        CProtocolBase* aSourceProtocol=NULL);

Description

Processes a datagram when called by a protocol on any other (higher level) protocol which has bound to it. The TSockAddr specifies the source address of the data. If this is not known the pointer should be NULL.

This version of the Process() function should be used when descriptor-based protocol data units are in use.

The aTo and aFrom parameters are client-side structures used in functions like BindL() and SendTo(). The actual internal format of the TSockAddr is protocol specific — generally protocols will provide their own TSockAddr-derived class.

Parameters

TDes8& aPDU The datagram to process TSockAddr* aFrom The address the datagram is from TSockAddr* aTo The address the datagram is to CProtocolBase* aSourceProtocol The higher level protocol which we want to process our incoming datagram

virtual void StartSending(CProtocolBase* aProtocol);    

Description

Indicates that data can now be sent. Implementations can call bound higher-level protocols and service access points in turn.

With Send(), this function forms a flow control pair. A zero return from a Send() should flow control off the calling protocol. StartSending() acts as a flow control on.

Parameters

CProtocolBase* aProtocol The calling protocol

virtual void GetOption(TUint aLevel,TUint aName,TDes8& anOption,
        CProtocolBase* aSourceProtocol=NULL);

Description

Gets options for the protocol on behalf of socket server clients.

The option parameter is protocol-defined — this is a generic API.

The protocol is passed in because you might get GetOption() calls from multiple bindees — this is actually more meaningful for SetOption().

Parameters

TUint aLevel The level in the stack the option request is ‘aimed’ at TUint aName The name of the option TDes8& anOption Descriptor to hold the option data CProtocolBase* aSourceProtocol The protocol making the request.

virtual void SetOption(TUint aLevel, Tuint aName, const TDesC8& anOption,
        CProtocolBase* aSourceProtocol=NULL)=0;

Description

Sets options for the protocol on behalf of socket server clients.

The option parameter is protocol-defined — this is a generic API.

The protocol is passed in because you might get SetOption() calls from multiple bindees and need to distinguish who is setting what.

Parameters

TUint aLevel The level in the stack the option request is ‘aimed’ at TUint aName The name of the option TDes8& anOption Descriptor to hold the option data CProtocolBase* aSourceProtocol The protocol making the request.

virtual void Identify(TServerProtocolDesc* aProtocolDesc) const=0;    

Description

Fills in the passed TServerProtocolDesc with data describing the protocol.

Parameters

TServerProtocolDesc* aProtocolDesc Protocol description object to fill in

TPtrC Tag();

Description

Gets a TPtrC to the protocol's tag name. The default implementation returns the tag passed to Init().

Return value

TPtrC Protocol's tag name

virtual void Error(TInt anError,CProtocolBase* aSourceProtocol=NULL);    

Description

Propagates error conditions up the stack, eventually to socket service providers.

Parameters

TInt anError The error code CProtocolBase* aSourceProtocol=NULL The protocol raising the error