Class RCommServ

class RCommServ : public RSessionBase;

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.

Derivation

• RHandleBase - A handle to an object

• RSessionBase - Client-side handle to a session with a server

• RCommServ - Represents a session with the serial comms server

Members

Defined in RCommServ:
Connect(), CreateThreadInCommProc(), GetPortInfo(), GetPortInfo(), LoadCommModule(), NumPorts(), RCommServ(), UnloadCommModule(), Version(), __DbgCheckHeap(), __DbgFailNext(), __DbgMarkEnd(), __DbgMarkHeap(), __DbgSetTraceMask()

Inherited from RHandleBase:
Attributes(), Close(), Duplicate(), FullName(), Handle(), HandleInfo(), Name(), SetHandle(), SetHandleNC(), iHandle

Inherited from RSessionBase:
CreateSession(), EAutoAttach, EExplicitAttach, Open(), Send(), SendReceive(), SetReturnedHandle(), ShareAuto(), ShareProtected(), TAttachMode

Capability:

Illegal

IMPORT_C RCommServ();

Description

Default constructor.

Capability:

Illegal

IMPORT_C TInt Connect();

Description

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

TInt System-wide error code

Capability:

Illegal

IMPORT_C TVersion Version() const;

Description

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

TVersion Version number.

Capability:

Illegal

IMPORT_C TInt LoadCommModule(const TDesC &aFileName);

Description

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, three 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.

Parameters

const TDesC &aFileName Name 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

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

IMPORT_C TInt UnloadCommModule(const TDesC &aName);

Description

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

const TDesC &aName Name 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

TInt System wide error code.

Capability:

Illegal

IMPORT_C TInt NumPorts(TInt &aNum);

Description

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

This number includes modules loaded by other sessions.

Parameters

TInt &aNum On return, holds the number of loaded CSYs

Return value

TInt System wide error code.

Capability:

Illegal

IMPORT_C TInt GetPortInfo(const TDesC &aName, TSerialInfo &aInfo);

Description

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

const TDesC &aName The 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. TSerialInfo &aInfo On return, contains information about the ports available, including the high and low unit numbers and their name in Port Prefix format.

Return value

TInt 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:

Illegal

IMPORT_C TInt GetPortInfo(TInt aIndex, TDes &aModuleName, TSerialInfo &aInfo);

Description

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

TInt aIndex Index number of the comms module, starting at 0. TDes &aModuleName On 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. TSerialInfo &aInfo On return, contains information about the ports available, including the high and low unit numbers and their name.

Return value

TInt 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:

Illegal

IMPORT_C TInt __DbgMarkHeap();

Description

Sets a heap mark in the comm server

Only valid for Debug builds.

Return value

TInt System wide error code.

Capability:

Illegal

IMPORT_C TInt __DbgCheckHeap(TInt aCount);

Description

Checks the heap mark in the comm server

Only valid for Debug builds.

Parameters

TInt aCount

Return value

TInt

Capability:

Illegal

IMPORT_C TInt __DbgMarkEnd(TInt aCount);

Description

Sets the heap mark end in the comm server

Only valid for Debug builds.

Parameters

TInt aCount

Return value

TInt

Capability:

Illegal

IMPORT_C TInt __DbgFailNext(TInt aCount);

Description

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

TInt aCount Specifies 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.

Return value

TInt

Capability:

Illegal

IMPORT_C TInt __DbgSetTraceMask(TC32Trace aMask);

Description

The functionality of this API has been removed.

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

Parameters

TC32Trace aMask This value is not used.

Return value

TInt Always KErrNone.

Capability:

CommDD

(Deprecate)

static IMPORT_C TInt CreateThreadInCommProc(const TDesC &aLibraryName, const TDesC &aThreadName, TThreadFunction aFunction, TInt aStackSize, TInt aHeapMinSize, TInt aHeapMaxSize);

Description

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

const TDesC &aLibraryName This value is not used. const TDesC &aThreadName This value is not used. TThreadFunction aFunction This value is not used. TInt aStackSize A negative value will result in a panic. TInt aHeapMinSize A value less than KMinHeapSize will result in a panic. TInt aHeapMaxSize A value less than aHeapMinSize will result in a panic.

Return value

TInt Always KErrNotSupported.