Class CProtocolFamilyBase

CProtocolFamilyBase

Support

Supported from 5.0

Description

Defines the interface for protocol families. Protocol families must:

• be able to identify the protocols which they can create

• be able to create instances of protocol objects for all the protocols they advertise

Derivation

CBase Base class for all classes to be instantiated on the heap CObject Implements reference counting to track concurrent references to itself CProtocolFamilyBase Defines the interface for protocol families

Defined in CProtocolFamilyBase:
CreateProtocolFamilyL(), Install(), NewProtocolL(), Open(), ProtocolList(), Remove()

Inherited from CBase:
operator new()

Inherited from CObject:
AccessCount(), Close(), Dec(), FullName(), Inc(), Name(), Owner(), SetName(), SetNameL(), SetOwner(), UniqueID()

CProtocolFamilyBase* CreateProtocolFamilyL();

Description

Exports a function with this signature as ordinal 1 that creates an instance of a CProtocolFamilyBase derived object. The socket server calls this function to use the protocol module implementation.

Each protocol module should only ever be expected to create a single CProtocolFamilyBase derived class, even if it supports multiple protocols.

If this function cannot create the protocol family, it should leave with an informative error code.

Return value

CProtocolFamilyBase* A protocol family

Leave codes

The function should leave if some error has prevented the protocol family being created.

virtual TInt Install()=0;

Description

Initialises a protocol family. After the CProtocolFamilyBase-derived object has been created, the first function called by the socket server on that object is Install(). It is at this point that the CProtocolFamilyBase-derived object should perform any initialisation which it needs.

Return value

TInt System-wide error code

virtual void Open();

Description

Opens a protocol family. When a socket is created, the socket server first calls this function on the protocol family. It is not compulsory for the protocol family to implement this function — the default behaviour of the socket server, which is to increment an access count for the protocol family, may be sufficient.

virtual TUint ProtocolList(TServerProtocolDesc*& aProtocolList)=0;

Description

Gets list of supported protocols. This function is called during initialisation, directly after Install(). ProtocolList() returns a list of all the protocols in the protocol family. The protocol family object should allocate memory to hold an array of TServerProtocolDesc structures. This function should then fill them in and return the pointer and a count of the number of protocols supported. The socket server caches this information, so that it does not need to keep the protocol module loaded.

The protocol family should not attempt to use static data (which it can’t) or to free this memory later as the socket server will automatically free this storage.

Parameters

TServerProtocolDesc*& aProtocolList This pointer is set to point to memory allocated by the protocol family and filled in as described above

Return value

TUint The number of protocols in this protocol family (and entries in the list of protocols)

virtual CProtocolBase* NewProtocolL(TUint aSockType,TUint aProtocol)=0;

Description

Creates a new protocol object. During socket creation, after the socket server has called Open() on a protocol family, it next calls NewProtocolL() to create an instance of a CProtocolBase-derived object — the protocol itself.

Parameters

TUint aSockType A supported socket type for the protocol family as advertised in the protocol list. TUint aProtocol A protocol number specifying a protocol returned by ProtocolList().

Return value

CProtocolBase* A protocol or NULL if some error has prevented the protocol from being created.

virtual TInt Remove();

Description

Prepares the protocol family to be removed. The socket server calls Remove() before unloading the library for a given protocol family.

Return value

TInt System-wide error code. The socket server guarantees that the protocol family will always be in a suitable position to perform closedown. If this is not the case, for example there are still active connections, then this function should return an error.