RCommServ Class Reference

#include <c32comm.h>

Link against: c32.lib

class RCommServ : public RSessionBase

Inherits from

Public Member Functions
RCommServ()
IMPORT_C TIntConnect()
IMPORT_C TIntCreateThreadInCommProc(const TDesC &, const TDesC &, TThreadFunction, TInt, TInt, TInt)
IMPORT_C TIntGetPortInfo(const TDesC &, TSerialInfo &)
IMPORT_C TIntGetPortInfo(TInt, TDes &, TSerialInfo &)
IMPORT_C TIntLoadCommModule(const TDesC &)
IMPORT_C TIntNumPorts(TInt &)
IMPORT_C TIntUnloadCommModule(const TDesC &)
IMPORT_C TVersionVersion()
IMPORT_C TInt__DbgCheckHeap(TInt)
IMPORT_C TInt__DbgFailNext(TInt)
IMPORT_C TInt__DbgMarkEnd(TInt)
IMPORT_C TInt__DbgMarkHeap()
IMPORT_C TInt__DbgSetTraceMask(TC32Trace)
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

Represents a session with the serial comms server. Functions are provided for connection to the server and for loading and unloading different comms modules, and services for finding out the name and numbers of the available ports.

Sessions with the serial comms server are not shareable.

Comms modules are also known as "CSY"s due to their ".CSY" extension, derived from the term "Comms SYstem".

This class is not intended for user derivation.

Constructor & Destructor Documentation

RCommServ ( )

IMPORT_CRCommServ()
Default constructor.
Capability
None

Member Function Documentation

Connect ( )

IMPORT_C TIntConnect()

Connects a client process to the comms server.

Use this function to open a session to the Comms server. Default number of message slots is defined in KDefaultMessageSlots.

Notes:

1. RHandleBase provides the necessary Close() function, which should be called when the server session is no longer required. Note that the kernel completes the Close() function immediately and so RCommServ resources still used by this client may not yet have been released at the time the Close() returns. A consequence of this is that an attempt to open a port previously opened for exclusive use in a session that is still closing might fail. 2. Older versions of Symbian OS specified that a call to "StartC32" was required before a call to this Connect(). However, C32 Serial server is now started automatically during device boot so this is not necessary unless the application is to run in a non-standard GUI environment.

Return Value
System-wide error code
Capability
None

CreateThreadInCommProc ( const TDesC &, const TDesC &, TThreadFunction, TInt, TInt, TInt )

IMPORT_C TIntCreateThreadInCommProc(const TDesC &aLibraryName,
const TDesC &aThreadName,
TThreadFunctionaFunction,
TIntaStackSize,
TIntaHeapMinSize,
TIntaHeapMaxSize
)[static]

This functionality has been withdrawn since the introduction of Platform Security.

This API has been replaced with a more secure and controlled model for loading threads into the Comms process, known as the Configurator. The Configurator requires a Comms Provider Module (DLL) to be available that provides the code for the thread to execute, and a configuration file that describes to the Configurator how to manage the Comms Provider Module. Further information on this is only available in documentation libraries that include the Configurator documentation.

Parameters
aLibraryNameThis value is not used.
aThreadNameThis value is not used.
aFunctionThis value is not used.
aStackSizeA negative value will result in a panic.
aHeapMinSizeA value less than KMinHeapSize will result in a panic.
aHeapMaxSizeA value less than aHeapMinSize will result in a panic.
Return Value
Always KErrNotSupported.
Capability
CommDD(Deprecate)

GetPortInfo ( const TDesC &, TSerialInfo & )

IMPORT_C TIntGetPortInfo(const TDesC &aName,
TSerialInfo &aInfo
)

Gets static information about the available serial ports for a particular comms module.

This variant enables the comms module to be specified in Port Prefix format or by filename.

There is no wildcard support.

Notes:

1. This API only returns static information about the available ports as they were when the module loaded, so ports listed as available may actually be in use exclusively by another client at the time of this call.

2. The information returned does not account for any security restrictions on ports, and so does not check whether the client has the capabilities to open all the advertised ports.

Parameters
aNameThe name of the comms module in Port Prefix format (eg "COMM" for RS232), or the filename of the CSY as supplied to LoadCommModule() excluding the ".CSY" extension (eg "ECUART" for RS232). The supplied name will be truncated to be KMaxPortName (16) characters long.
aInfoOn return, contains information about the ports available, including the high and low unit numbers and their name in Port Prefix format.
Return Value
KErrNone, if the send operation is successful; KErrServerTerminated, if the server is no longer present; KErrServerBusy, if there are no message slots available; KErrNoMemory, if there is insufficient memory available.
Capability
None

GetPortInfo ( TInt, TDes &, TSerialInfo & )

IMPORT_C TIntGetPortInfo(TIntaIndex,
TDes &aModuleName,
TSerialInfo &aInfo
)

Gets static information about the available serial ports for a particular comms module.

This variant enables the comms module to be specified by an index number from 0, enabling iteration through the loaded comms modules. Call NumPorts() to obtain the current number of loaded comms modules.

Notes:

1. This API only returns static information about the available ports as they were when the module loaded, so ports listed as available may actually be in use exclusively by another client at the time of this call.

2. The information returned does not account for any security restrictions on ports, and so does not check whether the client has the capabilities to open all the advertised ports.

3. If another C32 client unloads a CSY module, the index of each of the remaining modules may change. If a client is attempting to iterate through all the open modules when this occurs, the iteration may miss a module or receive KErrNotFound unexpectedly. This behaviour can be detected by observing that the value returned by NumPorts() changes.

Parameters
aIndexIndex number of the comms module, starting at 0.
aModuleNameOn return, contains the name of the comms module referred to by aIndex. This name is expressed as the filename without the path or extension, and the case is not specified since it is determined by the first request to LoadCommModule.
aInfoOn return, contains information about the ports available, including the high and low unit numbers and their name.
Return Value
KErrNone, if the send operation is successful; KErrServerTerminated, if the server is no longer present; KErrServerBusy, if there are no message slots available; KErrNoMemory, if there is insufficient memory available.
Capability
None

LoadCommModule ( const TDesC & )

IMPORT_C TIntLoadCommModule(const TDesC &aFileName)

Loads a comms module.

Use this function to load a CSY comms module. These are protocol modules that C32 Serial Server uses to understand how to handle a particular port.

Notes:

1. There is no need for an extension, as ".CSY" is automatically appended by this function.

2. This function only loads CSYs that have been installed correctly into one of the system's /sys/bin directories

3. If the module has already been loaded by another client, this function will increment the reference to the module.

4. It is not an error to load the same module twice or more, although there is no practical application for this ability. On each subsequent load for the same module the reference count is simply incremented. When the session is closed, all module references are removed including references from repeated loading of the same module.

5. There is no limit to the number of modules that can be loaded from within a single session.

With the exception of some hardware configurations, four modules are normally available as standard:

ECUART is used to address appropriate serial ports in RS232 mode. It is normally customised for a device.

IRCOMM drives the infrared port in infrared mode.

BTCOMM drives the Bluetooth emulated serial port.

ECACM drives the USB port(s).

Parameters
aFileNameName of the file to load as a module, optionally containing the ".CSY" extension. The filename may include the full path including drive letter for the CSY.
Return Value
KErrNone if the load operation is successful; KErrServerTerminated if the server no longer present; KErrServerBusy if there are no message slots available; KErrNoMemory if there is insufficient memory available; KErrBadLibraryEntryPoint if the CSY fails the consistency check; KErrNotFound if the CSY or other component or service required to load it is not found; other return codes are possible from the CSY itself.
Capability
None

NumPorts ( TInt & )

IMPORT_C TIntNumPorts(TInt &aNum)

Get the number of unique comms modules (CSYs) loaded into C32.

This number includes modules loaded by other sessions.

Parameters
aNumOn return, holds the number of loaded CSYs
Return Value
System wide error code.
Capability
None

UnloadCommModule ( const TDesC & )

IMPORT_C TIntUnloadCommModule(const TDesC &aName)

Remove this client's reference to the named communications module. If this is the last client to reference the communications module, the module is unloaded.

Note:

There is no need to unload a comms module when the connection to the server is closed, as this is done automatically by the C32 Server. For example, the following code will not result in a leak:
		_LIT(KCSYName,"ECUART");
		RCommServ commSession;
		if (commSession.Connect() == KErrNone)
			{
			TInt ret = commSession.LoadCommModule(KCSYName);
			commSession.Close();
			}

Parameters
aNameName of the module to unload described in Port Prefix format. This may not necessarily be the same name as that used to load the module. Examples: The ECUART module, where supplied, is loaded via "ECUART" or "ECUART.CSY" but unloaded via "COMM". The infrared module, where supplied, is loaded via "IRCOMM.CSY" or "IRCOMM" but unloaded only via "IRCOMM".
Return Value
System wide error code.

Version ( )

IMPORT_C TVersionVersion()const

Returns the client side version number.

Use this function to get the version number. The version number may be incremented in future releases of the comms server. If extra features are added in such releases, the version number may be used by application programs as a basis for assessing the capabilities of the comms server. Version-specific functions will be marked as such in the SDK documentation.

Return Value
Version number.
Capability
None

__DbgCheckHeap ( TInt )

IMPORT_C TInt__DbgCheckHeap(TIntaCount)

Checks the heap mark in the comm server

Only valid for Debug builds.
Capability
None

__DbgFailNext ( TInt )

IMPORT_C TInt__DbgFailNext(TIntaCount)

Emulates a single fail next heap allocation in the comm server. If C32 is running multiple threads the same request is passed to each thread. Each C32 thread will only act on this request if it has not already been configured for heap failures via CMI files.

Only valid for Debug builds.
Parameters
aCountSpecifies that after aCount-1 successful allocations the failure will occur on the next allocation - ie the failure will occur on the aCount allocation attempt. A value less than zero cancels any outstanding failure request. A value of zero is equivalent to a value of one - ie, fail on the next attempt.
Capability
None

__DbgMarkEnd ( TInt )

IMPORT_C TInt__DbgMarkEnd(TIntaCount)

Sets the heap mark end in the comm server

Only valid for Debug builds.
Capability
None

__DbgMarkHeap ( )

IMPORT_C TInt__DbgMarkHeap()

Sets a heap mark in the comm server

Only valid for Debug builds.

Return Value
System wide error code.
Capability
None

__DbgSetTraceMask ( TC32Trace )

IMPORT_C TInt__DbgSetTraceMask(TC32TraceaMask)

The functionality of this API has been removed.

Where tracing is required, please refer to the Comms Infrastructure documentation on logging.

Parameters
aMaskThis value is not used.
Return Value
Always KErrNone.
Capability
None