// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#include <e32std.h>

#include <c32comm.h>

#include <e32panic.h>

#ifdef SYMBIAN_ENABLE_SPLIT_HEADERS

#include <c32comm_internal.h>

#endif

#include "CS_STD.H"

#include "C32LOG.H"

/** @file

 *

 * Implements the client side code of C32, including RCommServ and RComm

 */

const TUint KDefaultMessageSlots = 16;    //< number of slots in the Client/Server message buffer

//

// implementation of RCommServ

//

EXPORT_C RCommServ::RCommServ()

/** Default constructor. 

@capability None

*/

	{

	}

EXPORT_C TInt RCommServ::Connect()

/** 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 System-wide error code 

@capability None

*/

    {

    TInt r = CreateSession(KCommServerName(), Version(), KDefaultMessageSlots);

	if (r==KErrNotFound)

		{

		// attempt to start the comms system. This is normally done on device boot but to support

		// any old test environments we still try here as well. This is a deprecated behaviour that

		// results in warnings in the log file

		r = StartC32();

		if (r==KErrNone)

			r=CreateSession(KCommServerName(), Version(), KDefaultMessageSlots);

		}

    return(r); 

    }

EXPORT_C TVersion RCommServ::Version() 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 Version number. 

@capability None

*/

    {

    return(TVersion(KEC32MajorVersionNumber, KEC32MinorVersionNumber, KEC32BuildVersionNumber));

    }

EXPORT_C TInt RCommServ::LoadCommModule(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).

@param 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 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

*/

    {

    // No means to insert a 16-bit string into an 8-bit string, so all is 16-bit

	C32_STATIC_LOG2(KC32Client,_L("RCommServ::LoadCommModule() : %S"), &aFileName);

	TIpcArgs args(&aFileName);

	return SendReceive(ECommLoadCommModule, args);

    }

EXPORT_C TInt RCommServ::UnloadCommModule(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:

@code

		_LIT(KCSYName,"ECUART");

		RCommServ commSession;

		if (commSession.Connect() == KErrNone)

			{

			TInt ret = commSession.LoadCommModule(KCSYName);

			commSession.Close();

			}

@endcode

@param 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 System wide error code.

*/

    {

	C32_STATIC_LOG2(KC32Client,_L("RCommServ::UnloadCommModule() : %S"), &aName);

	TIpcArgs args(&aName);

	return SendReceive(ECommCloseCommModule, args);

    }

EXPORT_C TInt RCommServ::NumPorts(TInt& aCount)

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

This number includes modules loaded by other sessions.

@param aCount On return, holds the number of loaded CSYs

@return System wide error code. 

@capability None

*/

    {

	TPckg<TInt> num(aCount);

	TIpcArgs args(&num);

	return SendReceive(ECommNumPorts,args);

    }

EXPORT_C TInt RCommServ::GetPortInfo(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.

@param 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.

@param aInfo On return, contains information about the ports available, including 

the high and low unit numbers and their name in Port Prefix format.

@return 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

*/

    {

	C32_STATIC_LOG2(KC32Client,_L("RCommServ::GetPortInfo() for comms module : %S"), &aName);

	TPckg<TSerialInfo> portDesc(aInfo);

	TIpcArgs args(&portDesc,&aName);

	return SendReceive(ECommPortInfoByName, args);

    }

EXPORT_C TInt RCommServ::GetPortInfo(TInt aIndex, 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.

@param aIndex Index number of the comms module, starting at 0. 

@param 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.

@param aInfo On return, contains information about the ports available, including 

the high and low unit numbers and their name. 

@return 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

*/

    {

	C32_STATIC_LOG2(KC32Client,_L8("RCommServ::GetPortInfo() for comms module of index number : %d"), aIndex);

	TPckg<TSerialInfo> portDesc(aInfo);

	TIpcArgs args(&portDesc,&aModuleName,aIndex);

	return SendReceive(ECommPortInfoByNumber, args);

    }

EXPORT_C TInt RCommServ::__DbgMarkHeap()

/** Sets a heap mark in the comm server

Only valid for Debug builds.

@return System wide error code. 

@capability None

*/

    {

#ifdef _DEBUG

	TIpcArgs args(TIpcArgs::ENothing);

	return SendReceive(ECommDbgMarkHeap, args);

#else

    return KErrNone;

#endif

    }

EXPORT_C TInt RCommServ::__DbgCheckHeap(TInt aCount)

/** Checks the heap mark in the comm server

Only valid for Debug builds. 

@capability None

*/

    {

#ifdef _DEBUG

	TIpcArgs args(aCount);

	return SendReceive(ECommDbgCheckHeap, args);

#else

	(void)aCount; // not used for Release builds

    return KErrNone;

#endif

    }

EXPORT_C TInt RCommServ::__DbgMarkEnd(TInt aCount)

/** Sets the heap mark end in the comm server

Only valid for Debug builds. 

@capability None

*/

    {

#ifdef _DEBUG

	TIpcArgs args(aCount);

	return SendReceive(ECommDbgMarkEnd, args);

#else

	(void)aCount; // not used for Release builds

    return KErrNone;

#endif

    }

EXPORT_C TInt RCommServ::__DbgFailNext(TInt aCount)

/** 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.

@param 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.

Only valid for Debug builds. 

@capability None

*/

    {

#ifdef _DEBUG

	TIpcArgs args(aCount);

	return SendReceive(ECommDbgFailNext,args);

#else

	(void)aCount; // not used for Release builds

    return KErrNone;

#endif

    }

EXPORT_C TInt RCommServ::__DbgSetTraceMask(TC32Trace aMask)

/** The functionality of this API has been removed.

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

on logging.

@param aMask This value is not used.

@return Always KErrNone.

@capability None

*/

    {

#ifdef _DEBUG

	(void)aMask; // aMask is of no use

	// At one time this function would send ECommDbgSetDebugPrintMask to the server, but

	// the server hasn't supported this function since at least the last release of EPOC5.

	return KErrNone;

#else

	(void)aMask; // not used for Release builds

    return KErrNone;

#endif

    }

EXPORT_C TInt RCommServ::CreateThreadInCommProc(const TDesC&, const TDesC&, TThreadFunction, TInt aStackSize, TInt aHeapMinSize, TInt aHeapMaxSize)

/** 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.

@param aLibraryName This value is not used.

@param aThreadName  This value is not used.

@param aFunction    This value is not used.

@param aStackSize   A negative value will result in a panic.

@param aHeapMinSize A value less than KMinHeapSize will result in a panic.

@param aHeapMaxSize A value less than aHeapMinSize will result in a panic.

@return Always KErrNotSupported. 

@capability CommDD (Deprecate)

*/

/*  Please refer to the Rootserver component documentation for more information.

*/

	{

	C32_STATIC_LOG(KC32Warning,_L8("WARNING: Call to deprecated function CreateThreadInCommProc."));	

	_LIT(KCommClientPanic,"Comm client");	// panic the client here rather than panicking the C32 server

        									// thread

	__ASSERT_ALWAYS(aStackSize>=0,User::Panic(KCommClientPanic,EThrdStackSizeNegative));

	__ASSERT_ALWAYS(aHeapMinSize>=KMinHeapSize,User::Panic(KCommClientPanic,EThreadHeapMinTooSmall));

	__ASSERT_ALWAYS(aHeapMaxSize>=aHeapMinSize,User::Panic(KCommClientPanic,EThreadHeapMaxLessThanMin));

	return KErrNotSupported;

	}

TBool RCommServ::IsServerThreadL()

/**

 * Return TRUE if this thread is the C32 main thread

 *

 * @note This function is not as water tight as it could be.  This is due to a limitation

 *       in our ability to get the thread name.  Under non-WINS builds the thread name is

 *       (even after we rename it) a combination of process name, OS data and thread name.

 *       Therefore we search for a thread name ending in "CommServer" and belonging to

 *       the C32 process.  If another process started a thread in C32 via the

 *       CreateThreadInCommProc() call with a name ending in "CommServer" then this

 *       function may start to produce incorrect results.

 *

 * @return ETrue if this is the C32 main server thread

 */

	{

	TInt res = KErrNone;

	TFullName name;

	//

	// Find the Process ID of the C32 process.  Note that WINS builds run the C32 'process'

	// as a thread and not a separate process.

	//

#ifndef __WINS__

	_LIT(KCommProcessName, "C32exe*");

	RProcess cpProcess;

	TFindProcess findCp(KCommProcessName);

	res = findCp.Next(name);

	__ASSERT_ALWAYS(res==KErrNone,User::Invariant());

	res = cpProcess.Open(findCp); 

	(void) User::LeaveIfError(res);

	TProcessId cpid = cpProcess.Id();

	cpProcess.Close();

	//

	// A quick short cut.  Is this process C32?  If not then this thread cannot be the

	// server thread.

	//

	if (RProcess().Id() != cpid)

		{

		return (EFalse);

		}

#endif

	//

	// Search for the the C32 comm server thread.  For non-WINS builds get the Process

	// ID of the thread and confirm it matches the C32 Process ID.

	//

	RThread ctThread;

	//thread name comes from C32.cmi file.

	_LIT(KCommThreadName, "CCommServer");

	TFindThread findCt(KCommThreadName);

	while((res=findCt.Next(name))==KErrNone)

		{

		(void)User::LeaveIfError(ctThread.Open(KCommThreadName)); // ignoring return value

#ifdef __WINS__

		break;

#else

		if((res=ctThread.Process(cpProcess))!=KErrNone)

			{

			ctThread.Close();

			User::Leave(res);

			}

		TProcessId pid=cpProcess.Id();

		cpProcess.Close();

		//

		// We already know that this process is the C32 process.  Does the found thread

		// belong to C32?  If so then ctThread is the C32 main thread.

		//

		if(pid==cpid)

			{

			break;

			}

		ctThread.Close();

#endif

		}

	if (res==KErrNotFound)

		return EFalse;	// if the C32 thread is not running, then this thread cannot be it!

	(void)User::LeaveIfError(res); // ignoring return value

	//

	// Is this thread the C32 Comm Server thread that we just found?

	//

	TBool match=(ctThread.Id()==RThread().Id());

	ctThread.Close();

	return match;	// Return TRUE if this thread is the C32 main thread

	}

//

// implementation of RComm

//

EXPORT_C RComm::RComm()

/** Constructor */

	: iSignalsNotification(NULL,0,0)

	,iFlowNotification(NULL,0,0)

	{

	}

EXPORT_C TInt RComm::Open(RCommServ& aServer, const TDesC& aName, TCommAccess aMode)

/** Opens a serial port, for one of the three modes indicated by the TCommAccess 

argument.

The TCommAccess argument may dictate exclusive use of the RComm,

shared use (thereby giving permission for the port to be shared by other RComm

objects) or pre-emptable use (allowing another client to pre-empt this session

with an open request in one of the other two modes). The request will fail if

the port does not exist, or if it has been opened in exclusive mode elsewhere.

If the port has been opened in shared mode elsewhere, the request will fail if

a subsequent attempt is made to open it in exclusive mode.

A client opening a port in pre-emptive mode must be prepared to have its

outstanding requests errored with KErrCancel if another client opens the port

in either ECommShared or ECommExclusive mode.  In this case the port handle