RSocketServ Class Reference

#include <es_sock.h>

Link against: esock.lib

class RSocketServ : public RCommsSession

Inherits from

Public Member Functions
RSocketServ()
IMPORT_C voidClearExclusiveMode()
IMPORT_C TIntConnect(TUint)
IMPORT_C TIntConnect(const TSessionPref &, TUint)
IMPORT_C TIntFindProtocol(const TProtocolName &, TProtocolDesc &)
IMPORT_C TIntGetProtocolInfo(TUint, TProtocolDesc &)
IMPORT_C TIntInstallExtension(const TDesC &, const TDesC &)
IMPORT_C TIntNumProtocols(TUint &)
IMPORT_C voidSetExclusiveMode(TRequestStatus &)
IMPORT_C voidStartProtocol(TUint, TUint, TUint, TRequestStatus &)
IMPORT_C voidStopProtocol(TUint, TUint, TUint, TRequestStatus &)
IMPORT_C TVersionVersion()
IMPORT_C TBool__DbgCheckFailNext()
IMPORT_C TInt__DbgCheckHeap(TInt)
IMPORT_C TInt__DbgCheckMbuf(TInt)
IMPORT_C TInt__DbgControl(const ESockDebug::TControlMsg &)
IMPORT_C TInt__DbgFailNext(TInt)
IMPORT_C TInt__DbgFailNextMbuf(TInt)
IMPORT_C TInt__DbgMarkEnd(TInt)
IMPORT_C TInt__DbgMarkHeap()
IMPORT_C TInt__DbgMbufFreeSpace()
IMPORT_C TInt__DbgMbufTotalSpace()
IMPORT_C TInt__DbgSetMbufPoolLimit(TInt)
Inherited Attributes
RHandleBase::iHandle
Inherited Enumerations
RHandleBase:TAttributes
RSessionBase:TAttachMode
Inherited Functions
RHandleBase::Attributes()const
RHandleBase::BTraceId()const
RHandleBase::Close()
RHandleBase::DoExtendedClose()
RHandleBase::Duplicate(const RThread &,TOwnerType)
RHandleBase::FullName()const
RHandleBase::FullName(TDes &)const
RHandleBase::Handle()const
RHandleBase::HandleInfo(THandleInfo *)
RHandleBase::Name()const
RHandleBase::NotifyDestruction(TRequestStatus &)
RHandleBase::Open(const TFindHandleBase &,TOwnerType)
RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
RHandleBase::RHandleBase()
RHandleBase::RHandleBase(TInt)
RHandleBase::SetHandle(TInt)
RHandleBase::SetHandleNC(TInt)
RSessionBase::CreateSession(RServer2,const TVersion &)
RSessionBase::CreateSession(RServer2,const TVersion &,TInt)
RSessionBase::CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)
RSessionBase::CreateSession(const TDesC &,const TVersion &)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
RSessionBase::Open(RMessagePtr2,TInt,TOwnerType)
RSessionBase::Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)
RSessionBase::Open(TInt,TOwnerType)
RSessionBase::Open(TInt,const TSecurityPolicy &,TOwnerType)
RSessionBase::Send(TInt)const
RSessionBase::Send(TInt,const TIpcArgs &)const
RSessionBase::SendReceive(TInt)const
RSessionBase::SendReceive(TInt,TRequestStatus &)const
RSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSessionBase::SetReturnedHandle(TInt)
RSessionBase::SetReturnedHandle(TInt,RHandleBase &)
RSessionBase::SetReturnedHandle(TInt,const TSecurityPolicy &)
RSessionBase::ShareAuto()
RSessionBase::ShareProtected()

Detailed Description

Provides the Connect() function to create an IPC communication channel to the socket server. To close the channel RHandleBase provides a RHandleBase::Close() function.

The prime use for instances of RSocketServ is to establish subsession communications for RSocket, RHostResolver, RNetDatabase and RConnection. Any of the resources which are open using the session are automatically closed when the session is terminated, however it is more appropriate to issue a Close() on each subsession object before closing the session.

The following operations are also provided:

NumProtocols() - enumerates the number of protocols of which the socket server is currently aware.

GetProtocolInfo()/FindProtocol() - return information about a specific protocol.

StartProtocol() - loads a protocol asynchronously.

Note:

This class is not intended for user derivation.

Constructor & Destructor Documentation

RSocketServ ( )

IMPORT_CRSocketServ()

Default Constructor

Member Function Documentation

ClearExclusiveMode ( )

IMPORT_C voidClearExclusiveMode()

Clear exclusive mode for this session PLEASE NOTE: This API is currently unsupported, calling it will always return KErrNone but without actually doing anything.

Connect ( TUint )

IMPORT_C TIntConnect(TUintaMessageSlots = (TUint)-1)

Opens a session to the socket server.

Each outstanding asynchronous request made upon the session (typically via a subsession such as RSocket) requires a message slot. If there is no free slot the request is immediately completed with KErrServerBusy. If a client specifies a fixed number of slots then they form an inelastic pool exclusive to the session. Alternatively a client can specify -1 to use the global free message pool, which can grow upon demand but has poorer time bounds and can in principle fail any request. For most clients the global pool will be appropriate since it removes the need to accurately determine the worst case size.

Note that in previous releases the default value was KESockDefaultMessageSlots (8).

RHandleBase::Close() should be called once the session is no longer required. All resources which are opened using the session will be automatically closed when the session terminates.

When the last session which has open resources for a protocol is closed a protocol module will be unloaded automatically by the socket server.

Parameters
aMessageSlotsThe number of message slots required. If not specified then -1 to use the global pool of free messages.
Return Value
KErrNone if successful, otherwise another of the system-wide error codes.

Connect ( const TSessionPref &, TUint )

IMPORT_C TIntConnect(const TSessionPref &aPref,
TUintaMessageSlots = (TUint)-1
)

Opens a session to the socket server.

By providing session prefs the client states what services they require of the server. This allows the server to configure the client connection in an optimal manner. Such a configuration may not support all normal abilities of a session. For example a connection opened specifying KAfInet for the address family will be able to create TCP sockets but might not be able to create SMS sockets.

Each outstanding asynchronous request made upon the session (typically via a subsession such as RSocket) requires a message slot. If there is no free slot the request is immediately completed with KErrServerBusy. If a client specifies a fixed number of slots then they form an inelastic pool exclusive to the session. Alternatively a client can specify -1 to use the global free message pool, which can grow upon demand but has poorer time bounds and can in principle fail any request. For most clients the global pool will be appropriate since it removes the need to accurately determine the worst case size.

Note that in previous releases the default value was KESockDefaultMessageSlots (8).

RHandleBase::Close() should be called once the session is no longer required. All resources which are opened using the session will be automatically closed when the session terminates.

When the last session which has open resources for a protocol is closed a protocol module will be unloaded automatically by the socket server.

Return Value
KErrNone if successful, otherwise another of the system-wide error codes.

FindProtocol ( const TProtocolName &, TProtocolDesc & )

IMPORT_C TIntFindProtocol(const TProtocolName &aName,
TProtocolDesc &aProtocol
)

Gets information about a specific protocol, identified by it's name.

There is no wildcard support.

Parameters
aNameTyped descriptor which identifies a protocol name.
aProtocolA protocol description type to hold protocol information.
Return Value
KErrNone if successful, otherwise another of the system-wide error codes.

GetProtocolInfo ( TUint, TProtocolDesc & )

IMPORT_C TIntGetProtocolInfo(TUintanIndex,
TProtocolDesc &aProtocol
)

Gets information about a specific protocol.

Parameters
anIndexIndex of required protocol description.
aProtocolA protocol description type to hold protocol information.
Return Value
KErrNone if successful, otherwise another of the system-wide error codes.

InstallExtension ( const TDesC &, const TDesC & )

IMPORT_C TIntInstallExtension(const TDesC &aDllName,
const TDesC &aArgs =  TPtrC()
)

Install an Esock Extension. PLEASE NOTE: This API is currently unsupported, calling it will always return KErrNotSupported.

DeprecatedBecause it always return KErrNotSupported thus useless
Parameters
aDllNameDllName for Esock Extension
aArgsargument for Esock Extension
Return Value
KErrNone if successful, otherwise another of the system-wide error codes.
Capability
NetworkControlLoading extensions to Esock will be behavioural changing and must be restricted to privileged apps

NumProtocols ( TUint & )

IMPORT_C TIntNumProtocols(TUint &aCount)

Gets the number of protocols the socket server is currently aware of.

The count returned can be used in conjunction with GetProtocolInfo().

Parameters
aCountThe number of protocols is returned in aCount
Return Value
KErrNone if successful, otherwise another of the system-wide error codes.

SetExclusiveMode ( TRequestStatus & )

IMPORT_C voidSetExclusiveMode(TRequestStatus &aStatus)

Set this session as the socket server exclusive session. PLEASE NOTE: This API is currently unsupported, calling it will always return KErrNone but without actually doing anything.

Parameters
aStatusOn completion, will contain a system-wide error codes
Capability
NetworkControlRestricting Esock to one session is very dangerous and must be highly restricted

StartProtocol ( TUint, TUint, TUint, TRequestStatus & )

IMPORT_C voidStartProtocol(TUintanAddrFamily,
TUintaSockType,
TUintaProtocol,
TRequestStatus &aStatus
)

Loads a specified protocol asynchronously.

The protocol is specified by family, socket type and protocol identifier.

Note that client programs do not normally need to call this function, as loading of a protocol is done automatically by the Sockets Server when a socket of that protocol is opened. Some applications may, however, need to ensure that an open socket call will not take a significant amount of time (e.g. IrCOMM). This function can be called by such applications to preload the protocol.

There is no way to cancel this operation once it has been called.

Parameters
anAddrFamilyInteger which identifies a protocol suite.
aSockTypeInteger which identifies a type of socket.
aProtocolInteger which identifies a specific protocol in a family.
aStatusOn completion will contain an error code: see the system-wide error codes.
Capability
NetworkControlProtocol starting is a critical operation in the comms process and must be restricted

StopProtocol ( TUint, TUint, TUint, TRequestStatus & )

IMPORT_C voidStopProtocol(TUintanAddrFamily,
TUintaSockType,
TUintaProtocol,
TRequestStatus &aStatus
)

Unload a protocol asynchronously - note it will fail if there are any resources open

Parameters
anAddrFamilyInteger which identifies a protocol suite
aSockTypeInteger which identifies a type of socket
aProtocolInteger which identifies a specific protocol in a family
aStatusOn completion, will contain a system-wide error codes
Capability
NetworkControlProtocol stopping is a critical operation in the comms process and must be restricted

Version ( )

IMPORT_C TVersionVersion()const

Gets the version number of this client.

Return Value
Client side version number

__DbgCheckFailNext ( )

IMPORT_C TBool__DbgCheckFailNext()const

Empty release implementation

__DbgCheckHeap ( TInt )

IMPORT_C TInt__DbgCheckHeap(TIntaCount)

Set a heap mark in the socket server

__DbgCheckMbuf ( TInt )

IMPORT_C TInt__DbgCheckMbuf(TIntasize)

Set the Mbuf pool limit

__DbgControl ( const ESockDebug::TControlMsg & )

IMPORT_C TInt__DbgControl(const ESockDebug::TControlMsg &aRequestMsg)

General purpose control message for esock debug, self dispatching messages to be thrown over it

__DbgFailNext ( TInt )

IMPORT_C TInt__DbgFailNext(TIntaCount)

Set a heap mark in the socket server

__DbgFailNextMbuf ( TInt )

IMPORT_C TInt__DbgFailNextMbuf(TIntaCount)

Set a Mbuf mark in the socket server

__DbgMarkEnd ( TInt )

IMPORT_C TInt__DbgMarkEnd(TIntaCount)

Set a heap mark in the socket server

__DbgMarkHeap ( )

IMPORT_C TInt__DbgMarkHeap()

Set a heap mark in the socket server

__DbgMbufFreeSpace ( )

IMPORT_C TInt__DbgMbufFreeSpace()

Get the amount of free space in the MBuf manager

__DbgMbufTotalSpace ( )

IMPORT_C TInt__DbgMbufTotalSpace()

Get the amount of free space in the MBuf manager

__DbgSetMbufPoolLimit ( TInt )

IMPORT_C TInt__DbgSetMbufPoolLimit(TIntasize)

Set the Mbuf pool limit