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

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

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

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #include <e32std.h>

    17 #include <c32comm.h>

    18 #include <e32panic.h>

    19 

    20 #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS

    21 #include <c32comm_internal.h>

    22 #endif

    23 

    24 #include "CS_STD.H"

    25 #include "C32LOG.H"

    26 

    27 /** @file

    28  *

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

    30  */

    31 

    32 

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

    34 

    35 

    36 //

    37 // implementation of RCommServ

    38 //

    39 

    40 

    41 EXPORT_C RCommServ::RCommServ()

    42 /** Default constructor. 

    43 @capability None

    44 */

    45 	{

    46 	}

    47 

    48 

    49 EXPORT_C TInt RCommServ::Connect()

    50 /** Connects a client process to the comms server.

    51 

    52 Use this function to open a session to the Comms server.

    53 Default number of message slots is defined in KDefaultMessageSlots.

    54 

    55 Notes:

    56 

    57 1. RHandleBase 

    58    provides the necessary Close() function, which should be called when the server 

    59    session is no longer required. Note that the kernel completes the Close() function immediately

    60    and so RCommServ resources still used by this client may not yet have been released at the time

    61    the Close() returns. A consequence of this is that an attempt to open a port previously opened

    62    for exclusive use in a session that is still closing might fail.

    63 2. Older versions of Symbian OS specified that a call to "StartC32" was required before a call to

    64    this Connect(). However, C32 Serial server is now started automatically during device boot

    65    so this is not necessary unless the application is to run in a non-standard GUI environment.

    66 

    67 

    68 @return System-wide error code 

    69 @capability None

    70 */

    71     {

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

    73 	if (r==KErrNotFound)

    74 		{

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

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

    77 		// results in warnings in the log file

    78 		r = StartC32();

    79 		if (r==KErrNone)

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

    81 		}

    82     return(r); 

    83     }

    84 

    85 

    86 EXPORT_C TVersion RCommServ::Version() const

    87 /** Returns the client side version number.

    88 

    89 Use this function to get the version number. The version number may be

    90 incremented in future releases of the comms server. If extra features are

    91 added in such releases, the version number may be used by application programs

    92 as a basis for assessing the capabilities of the comms server. Version-specific

    93 functions will be marked as such in the SDK documentation.

    94 

    95 @return Version number. 

    96 @capability None

    97 */

    98     {

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

   100     }

   101 

   102 EXPORT_C TInt RCommServ::LoadCommModule(const TDesC& aFileName)

   103 /** Loads a comms module.

   104 

   105 Use this function to load a CSY comms module. These are protocol modules that C32 Serial Server uses to

   106 understand how to handle a particular port.

   107 

   108 Notes:

   109 

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

   111    this function.

   112 

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

   114    

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

   116    the reference to the module.

   117    

   118 4. It is not an error to load the same module twice or more, although there is no practical

   119    application for this ability. On each subsequent load for the same module the reference count

   120    is simply incremented. When the session is closed, all module references are removed including

   121    references from repeated loading of the same module.

   122    

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

   124 

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

   126 

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

   128 

   129   IRCOMM drives the infrared port in infrared mode.

   130  

   131   BTCOMM drives the Bluetooth emulated serial port.

   132   

   133   ECACM drives the USB port(s).

   134 

   135 @param aFileName Name of the file to load as a module, optionally containing the ".CSY" extension.

   136 The filename may include the full path including drive letter for the CSY.

   137 @return KErrNone if the load operation is successful; KErrServerTerminated if the server no longer present;

   138  KErrServerBusy if there are no message slots available; KErrNoMemory if there is insufficient memory available;

   139  KErrBadLibraryEntryPoint if the CSY fails the consistency check; KErrNotFound if the CSY or other component

   140  or service required to load it is not found; other return codes are possible from the CSY itself.

   141 @capability None

   142 */

   143     {

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

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

   146 

   147 	TIpcArgs args(&aFileName);

   148 	return SendReceive(ECommLoadCommModule, args);

   149     }

   150 

   151 

   152 EXPORT_C TInt RCommServ::UnloadCommModule(const TDesC& aName)

   153 /** Remove this client's reference to the named communications module. If this is the

   154 last client to reference the communications module, the module is unloaded.

   155 

   156 Note:

   157 

   158 There is no need to unload a comms module when the connection to the

   159 server is closed, as this is done automatically by the C32 Server. For example, the following code will not result in a leak:

   160 @code

   161 		_LIT(KCSYName,"ECUART");

   162 		RCommServ commSession;

   163 		if (commSession.Connect() == KErrNone)

   164 			{

   165 			TInt ret = commSession.LoadCommModule(KCSYName);

   166 			commSession.Close();

   167 			}

   168 @endcode

   169 

   170 @param aName Name of the module to unload described in Port Prefix format. This may not necessarily be

   171 the same name as that used to load the module.

   172 Examples:

   173 The ECUART module, where supplied, is loaded via "ECUART" or "ECUART.CSY" but unloaded via "COMM".

   174 The infrared module, where supplied, is loaded via "IRCOMM.CSY" or "IRCOMM" but unloaded only via "IRCOMM".

   175 @return System wide error code.

   176 

   177 */

   178     {

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

   180 	

   181 	TIpcArgs args(&aName);

   182 	return SendReceive(ECommCloseCommModule, args);

   183     }

   184 

   185 

   186 EXPORT_C TInt RCommServ::NumPorts(TInt& aCount)

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

   188 

   189 This number includes modules loaded by other sessions.

   190 

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

   192 @return System wide error code. 

   193 @capability None

   194 */

   195     {

   196 	TPckg<TInt> num(aCount);

   197 	TIpcArgs args(&num);

   198 	return SendReceive(ECommNumPorts,args);

   199     }

   200 

   201 

   202 EXPORT_C TInt RCommServ::GetPortInfo(const TDesC& aName, TSerialInfo& aInfo)

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

   204 

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

   206 

   207 There is no wildcard support.

   208 

   209 Notes:

   210 

   211 1. This API only returns static information about the available ports as they were when the module loaded, so

   212 ports listed as available may actually be in use exclusively by another client at the time of this call.

   213 

   214 2. The information returned does not account for any security restrictions on ports, and so does not check

   215 whether the client has the capabilities to open all the advertised ports.

   216 

   217 @param aName The name of the comms module in Port Prefix format (eg "COMM" for RS232), 

   218 or the filename of the CSY as supplied to LoadCommModule() excluding

   219  the ".CSY" extension (eg "ECUART" for RS232). The supplied name will be truncated to be KMaxPortName (16) characters long.

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

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

   222 @return KErrNone, if the send operation is successful; 

   223 KErrServerTerminated, if the server is no longer present; 

   224 KErrServerBusy, if there are no message slots available; 

   225 KErrNoMemory, if there is insufficient memory available.

   226 @capability None

   227 */

   228     {

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

   230 	TPckg<TSerialInfo> portDesc(aInfo);

   231 	TIpcArgs args(&portDesc,&aName);

   232 	return SendReceive(ECommPortInfoByName, args);

   233     }

   234 

   235 

   236 EXPORT_C TInt RCommServ::GetPortInfo(TInt aIndex, TDes& aModuleName, TSerialInfo& aInfo)

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

   238 

   239 This variant enables the comms module to be specified by an index number 

   240 from 0, enabling iteration through the loaded comms modules. Call NumPorts() to obtain

   241 the current number of loaded comms modules.

   242 

   243 Notes:

   244 

   245 1. This API only returns static information about the available ports as they were when the module loaded, so

   246 ports listed as available may actually be in use exclusively by another client at the time of this call.

   247 

   248 2. The information returned does not account for any security restrictions on ports, and so does not check

   249 whether the client has the capabilities to open all the advertised ports.

   250 

   251 3. If another C32 client unloads a CSY module, the index of each of 

   252    the remaining modules may change. If

   253    a client is attempting to iterate through all the open modules when this occurs, the iteration may miss

   254    a module or receive KErrNotFound unexpectedly. This behaviour can be detected by 

   255    observing that the value returned by NumPorts() changes.

   256 

   257 

   258 

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

   260 @param aModuleName On return, contains the name of the comms module referred 

   261 to by aIndex. This name is expressed as the filename without the path or extension, and the case is

   262 not specified since it is determined by the first request to LoadCommModule.

   263 

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

   265 the high and low unit numbers and their name. 

   266 @return KErrNone, if the send operation is successful; 

   267 KErrServerTerminated, if the server is no longer present; 

   268 KErrServerBusy, if there are no message slots available; 

   269 KErrNoMemory, if there is insufficient memory available.

   270 @capability None

   271 */

   272     {

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

   274 	TPckg<TSerialInfo> portDesc(aInfo);

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

   276 	return SendReceive(ECommPortInfoByNumber, args);

   277     }

   278 	

   279 

   280 EXPORT_C TInt RCommServ::__DbgMarkHeap()

   281 /** Sets a heap mark in the comm server

   282 

   283 Only valid for Debug builds.

   284 

   285 @return System wide error code. 

   286 @capability None

   287 */

   288     {

   289 #ifdef _DEBUG

   290 	TIpcArgs args(TIpcArgs::ENothing);

   291 	return SendReceive(ECommDbgMarkHeap, args);

   292 #else

   293     return KErrNone;

   294 #endif

   295     }

   296 

   297 

   298 EXPORT_C TInt RCommServ::__DbgCheckHeap(TInt aCount)

   299 /** Checks the heap mark in the comm server

   300 

   301 Only valid for Debug builds. 

   302 @capability None

   303 */

   304     {

   305 #ifdef _DEBUG

   306 	TIpcArgs args(aCount);

   307 	return SendReceive(ECommDbgCheckHeap, args);

   308 #else

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

   310     return KErrNone;

   311 #endif

   312     }

   313 

   314 

   315 EXPORT_C TInt RCommServ::__DbgMarkEnd(TInt aCount)

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

   317 

   318 Only valid for Debug builds. 

   319 @capability None

   320 */

   321     {

   322 #ifdef _DEBUG

   323 	TIpcArgs args(aCount);

   324 	return SendReceive(ECommDbgMarkEnd, args);

   325 #else

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

   327     return KErrNone;

   328 #endif

   329     }

   330 

   331 

   332 EXPORT_C TInt RCommServ::__DbgFailNext(TInt aCount)

   333 /** Emulates a single fail next heap allocation in the comm server.

   334 If C32 is running multiple threads the same request is passed to each thread. Each C32 thread

   335 will only act on this request if it has not already been configured for heap failures via CMI files.

   336 

   337 @param aCount Specifies that after aCount-1 successful allocations the failure will occur on the next

   338 allocation - ie the failure will occur on the aCount allocation attempt.

   339  A value less than zero cancels any outstanding failure request. A value of zero is equivalent to a value

   340  of one - ie, fail on the next attempt.

   341  

   342 Only valid for Debug builds. 

   343 @capability None

   344 */

   345     {

   346 #ifdef _DEBUG

   347 	TIpcArgs args(aCount);

   348 	return SendReceive(ECommDbgFailNext,args);

   349 #else

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

   351     return KErrNone;

   352 #endif

   353     }

   354 

   355 

   356 EXPORT_C TInt RCommServ::__DbgSetTraceMask(TC32Trace aMask)

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

   358 

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

   360 on logging.

   361 

   362 @param aMask This value is not used.

   363 @return Always KErrNone.

   364 @capability None

   365 */

   366     {

   367 #ifdef _DEBUG

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

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

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

   371 	return KErrNone;

   372 #else

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

   374     return KErrNone;

   375 #endif

   376     }

   377 

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

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

   380 

   381 This API has been replaced with a more secure and controlled model for loading threads

   382  into the Comms process, known as the Configurator. The Configurator requires a Comms Provider Module

   383  (DLL) to be available that provides the code for the thread to execute, and a configuration file

   384  that describes to the Configurator how to manage the Comms Provider Module.

   385  Further information on this is only available in documentation libraries that include the Configurator documentation.

   386 

   387 @param aLibraryName This value is not used.

   388 @param aThreadName  This value is not used.

   389 @param aFunction    This value is not used.

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

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

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

   393 @return Always KErrNotSupported. 

   394 @capability CommDD (Deprecate)

   395 */

   396 

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

   398 */

   399 

   400 	{

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

   402 	

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

   404         									// thread

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

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

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

   408 

   409 	return KErrNotSupported;

   410 	}

   411 

   412 TBool RCommServ::IsServerThreadL()

   413 /**

   414  * Return TRUE if this thread is the C32 main thread

   415  *

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

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

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

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

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

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

   422  *       function may start to produce incorrect results.

   423  *

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

   425  */

   426 	{

   427 	TInt res = KErrNone;

   428 	TFullName name;

   429 

   430 	//

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

   432 	// as a thread and not a separate process.

   433 	//

   434 #ifndef __WINS__

   435 	_LIT(KCommProcessName, "C32exe*");

   436 

   437 	RProcess cpProcess;

   438 	TFindProcess findCp(KCommProcessName);

   439 	res = findCp.Next(name);

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

   441 	res = cpProcess.Open(findCp); 

   442 	(void) User::LeaveIfError(res);

   443 

   444 	TProcessId cpid = cpProcess.Id();

   445 	cpProcess.Close();

   446 

   447 	//

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

   449 	// server thread.

   450 	//

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

   452 		{

   453 		return (EFalse);

   454 		}

   455 #endif

   456 

   457 	//

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

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

   460 	//

   461 	RThread ctThread;

   462 	//thread name comes from C32.cmi file.

   463 	_LIT(KCommThreadName, "CCommServer");

   464 	TFindThread findCt(KCommThreadName);

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

   466 		{

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

   468 #ifdef __WINS__

   469 		break;

   470 #else

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

   472 			{

   473 			ctThread.Close();

   474 			User::Leave(res);

   475 			}

   476 		TProcessId pid=cpProcess.Id();

   477 		cpProcess.Close();

   478 

   479 		//

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

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

   482 		//

   483 		if(pid==cpid)

   484 			{

   485 			break;

   486 			}

   487 		ctThread.Close();

   488 #endif

   489 		}

   490 	if (res==KErrNotFound)

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

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

   493 

   494 	//

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

   496 	//

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

   498 	ctThread.Close();

   499 	

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

   501 	}

   502 

   503 //

   504 // implementation of RComm

   505 //

   506 

   507 EXPORT_C RComm::RComm()

   508 /** Constructor */

   509 	: iSignalsNotification(NULL,0,0)

   510 	,iFlowNotification(NULL,0,0)

   511 	{

   512 	}

   513 

   514 

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

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

   517 argument.

   518 

   519 The TCommAccess argument may dictate exclusive use of the RComm,

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

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

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

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

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

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

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

   527 outstanding requests errored with KErrCancel if another client opens the port

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

   529 will effectively be transferred from the pre-emptable client to the new client.

   530 

   531 The first variant (this) will open the port in DTE role, that is, the lines

   532 are configured as for a port of a computer. For instance, the signal lines

   533 DTR and RTS are outputs while the other signals (DCD,CTS,DSR,RING) are inputs.

   534 

   535 The second variant allows the port to be opened in either DTE role or DCE

   536 role. This latter role means that the lines are configured as for a port of

   537 a modem. DTR and RTS are inputs while the other signals are outputs.

   538 

   539 The request to open in either role will fail with KErrLocked if the port has

   540 already been opened in the opposite role elsewhere.

   541 

   542 @code

   543 Signal constant    DTE role     DCE role

   544 ----------------------------------------

   545 KSignalCTS         input        output

   546 KSignalDSR         input        output

   547 KSignalDCD         input        output

   548 KSignalRNG         input        output

   549 KSignalRTS         output       input

   550 KSignalDTR         output       input

   551 @endcode

   552 

   553 Note:

   554 

   555 1. On some earlier versions of C32 the port number was limited to one digit,

   556 i.e. from 0 to 9. This restriction is now removed, and the number

   557 of ports is now only limited by the CSY and/or the Device Drivers up to a maximum

   558 of KMaxTUint ports.

   559 

   560 2. This API checks that the client has the correct capabilities to open the port, while

   561 the RCommServ APIs do not. So a CSY that allowed the client to interrogate it via RCommServ::GetPortInfo()

   562 and load it via RCommServ::LoadCommModule() may still reject the same client's call to this API.

   563 

   564 3. There are a number of distinct steps that must be performed

   565 before being able to issue an Open() request for a serial port.

   566 For convenience these are listed here:

   567 

   568 a. Load the physical device driver, which interacts directly with the hardware at the

   569 lowest level (usually via User::LoadPhysicalDevice()).

   570 

   571 b. Load the logical device driver, which provides the comms server with a consistent

   572 interface to the hardware (usually via User::LoadLogicalDevice()).

   573 

   574 c. Connect to the C32 Serial Server using RCommServ

   575 

   576 d. Load a specific Comms Module (.CSY) by filename via RCommServ::LoadCommModule.

   577 

   578 In some environments the physical and logical device drivers are loaded as part of device boot.

   579 

   580 

   581 

   582 @param aServer The comms server session.

   583 @param aName   The name of the port (e.g. "COMM::0")

   584 @param aMode   The mode in which the port is opened. There is no default.

   585 @return System-wide error code: KErrNone if successful; KErrPermissionDenied if 

   586 the port given in aName is wrong or if the request fails the CSY's own security check;

   587  KErrNotSupported if this port is not 

   588 supported by the CSY or the hardware; KErrLocked if the port has already been 

   589 opened; KErrAccessDenied if the device driver encounteres a problem opening the hardware port.

   590 

   591 @capability Dependent

   592 */

   593     {

   594 	C32_STATIC_LOG5(KC32Client,_L("RComm::Open(), aServer 0x%x, (port) aName = %S, (port open) aMode = %d (%S)"), &aServer, &aName, aMode, &TC32Log::CommAccessStr16(aMode));

   595 	iSignalsNotification.Set(NULL,0,0);

   596 	iFlowNotification.Set(NULL,0,0);

   597 

   598 	TCommRole role = ECommRoleDTE;

   599 	TIpcArgs args(&aName,aMode,role);

   600 	RSessionBase& s = aServer;

   601     return CreateSubSession(s,ECommOpen, args);

   602     }

   603 

   604 //

   605 // Version 02 extension to the RComm API

   606 //

   607 

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

   609 /** Opens a serial port, as described for the other Open() variant. 

   610 

   611 This variant allows the port to be opened in either DTE role or DCE role. DCE 

   612 role means that the lines are configured as for a port of a modem. DTR and RTS 

   613 are inputs while the other signals are outputs.

   614 

   615 @param aServer The comms server session 

   616 @param aName The name of the port 

   617 @param aMode The mode in which the port is opened. There is no default. 

   618 @param aRole DTE/DCE role 

   619 @return System-wide error code: KErrNone if successful; KErrPermissionDenied if 

   620 the port given in aName is wrong; KErrNotSupported if this port is not supported 

   621 by the CSY or the hardware; KErrLocked if the port has already been opened 

   622 in the opposite role elsewhere. 

   623 @capability Dependent

   624 */

   625     {

   626 	C32_STATIC_LOG7(KC32Client,_L("RComm::Open(), aServer 0x%x, (port) aName %S, (port open) aMode = %d (%S), (port) aRole = %d (%S)"), &aServer, &aName, aMode, &TC32Log::CommAccessStr16(aMode), aRole, &TC32Log::CommRoleStr16(aRole));

   627 	TIpcArgs args(&aName,aMode,aRole);

   628 	RSessionBase &s = aServer;

   629 	return CreateSubSession(s,ECommOpen, args);

   630     }

   631 

   632 

   633 //

   634 // Version 02 extension to the RComm API

   635 //

   636 

   637 

   638 EXPORT_C void RComm::OpenWhenAvailable(TRequestStatus& aStatus, RCommServ& aServer, const TDesC& aName)

   639 /** Opens a serial port when it is freed by another client.

   640 

   641 When a client has a port open in either exclusive or shared mode, another

   642 client may use this function to gain access to the port when the owning

   643 client closes its handle.  Upon closure, the asynchronous OpenWhenAvailable()

   644 function will complete.  The port role, DTE or DCE, will not be changed by

   645 this request and so the role will be inherited from the previous session.

   646 Furthermore, the port will automatically opened in ECommPreemptable mode.

   647 This can be subsequently upgraded to ECommShared or ECommExclusive mode

   648 using the SetAccessMode() function.

   649 

   650 If client submits an OpenWhenAvailable() request and then attempts

   651 to execute an action, for example a read or write request, before the

   652 OpenWhenAvailable has completed, the action will fail with the KErrNotReady

   653 error code.

   654 

   655 The server can only support one OpenWhenAvailable request per port. For

   656 example, if client A has a port open in exclusive mode and client B has

   657 an OpenWhenAvailable request pending, then client C's OpenWhenAvailable

   658 request will fail with the KErrAccessDenied error code.

   659 

   660 The server is designed to support the OpenWhenAvailable request dispatched

   661 from a different RCommServ session than the one actively using the port.

   662 This is not viewed as a major disadvantage since, in practice, the two

   663 clients will normally be running in different threads, and quite probably

   664 different processes.

   665 

   666 If the port is available immediately, it will be opened with DTE role.

   667 

   668 @param aStatus The request status used to contain completion information for the function.

   669 @param aServer The comms server session.

   670 @param aName   The name of the port.

   671 @return System wide error code: see return values of RComm::Open().

   672 @capability Dependent

   673 */

   674 	{

   675 	OpenWhenAvailable(aStatus, aServer, aName, ECommRoleDTE);

   676 	}

   677 

   678 

   679 EXPORT_C void RComm::OpenWhenAvailable(TRequestStatus& aStatus, RCommServ& aServer, const TDesC& aName, TCommRole aRole)

   680 /** Opens a serial port when freed.

   681 

   682 Same as the other OpenWhenAvailable() but here you can specify the preferred

   683 role in case the port is free when you want to open it. If the port is already

   684 opened by another client, you will get the same role when it becomes available.

   685 

   686 @param aStatus The request status used to contain completion information for 

   687 			   the function.

   688 @param aServer The comms server session.

   689 @param aName   The name of the port.

   690 @param aRole   Preferred role (DTE or DCE).

   691 @return TInt   A system wide error code: see return values of RComm::Open(). 

   692 @capability Dependent

   693 */

   694 	{

   695 

   696 	C32_STATIC_LOG5(KC32Client,_L("RComm::OpenWhenAvailable(), aServer 0x%x, (port) aName = %S, (port) aRole = %d (%S)"), &aServer, &aName, aRole, &TC32Log::CommRoleStr16(aRole));

   697 	TIpcArgs args(&aName,TIpcArgs::ENothing,aRole);

   698 	RSessionBase& s = aServer;

   699 	TInt ret = CreateSubSession(s, ECommOpenWhenAvailable, args);

   700 

   701 	if(ret != KErrNone)

   702 		{

   703 		TRequestStatus* status = &aStatus;

   704 		User::RequestComplete(status, ret);

   705 		return;

   706 		}

   707 

   708 	args.Set(0,ECommPreemptable);

   709 	SendReceive(ECommSetAccess, args, aStatus);

   710 	}

   711 

   712 

   713 EXPORT_C void RComm::OpenWhenAvailableCancel()

   714 /** Cancels an OpenWhenAvailable() pending request. 

   715 @capability None

   716 */

   717     {

   718     if (SendReceive(ECommOpenWhenAvailableCancel) == KErrNone)

   719     	{

   720     	Close();

   721     	}

   722     }

   723 

   724 

   725 EXPORT_C void RComm::Read(TRequestStatus& aStatus, TDes8& aDes)

   726 /** Reads data from a serial port. 

   727 

   728 All reads from the serial device use 8-bit descriptors as data buffers, even 

   729 on a Unicode system.

   730 

   731 The length of the TDes8 is set to zero on entry, which means that buffers 

   732 can be reused without having to be zeroed first.

   733 

   734 The number of bytes to read is set to the maximum length of the descriptor.

   735 

   736 If a read is issued with a data length of zero the Read() completes immediately 

   737 with the side effect that the serial hardware is powered up.

   738 

   739 If a read terminates with KErrTimedOut and the descriptor is not empty, 

   740 it will contain valid data. Its length should therefore be tested.

   741 

   742 The behaviour of this API after a call to NotifyDataAvailable() is not prescribed

   743 and so different CSY's behave differently. IrComm will allow a successful completion of this API

   744 after a call to NotifyDataAvailable(), while ECUART and ECACM will complete the request with KErrInUse.

   745 

   746 @param aStatus The request status used to contain completion information for 

   747 the function. On completion, contains a system-wide error code.

   748 @param aDes A buffer to store the incoming data. The maximum length of the 

   749 descriptor is the number of bytes to be read. 

   750 @capability None

   751 */

   752     {

   753 	C32_STATIC_LOG2(KC32Client,_L8("RComm::Read(), Request to read max number of bytes %d"), aDes.MaxLength());

   754 	aDes.SetLength(0);

   755 	TIpcArgs args(&aDes,aDes.MaxLength(),0);

   756 	SendReceive(ECommRead, args, aStatus);

   757     }

   758 

   759 

   760 EXPORT_C void RComm::Read(TRequestStatus& aStatus, TDes8& aDes, TInt aLength)

   761 /** Reads a specified number of bytes from a serial port.

   762 

   763 Overloaded version of Read() with explicit length.

   764 

   765 All reads from the serial device use 8-bit descriptors as data buffers, even 

   766 on a Unicode system.

   767 

   768 The length of the TDes8 is set to zero on entry, which means that buffers 

   769 can be reused without having to be zeroed first.

   770 

   771 The number of bytes to read is set to aLength.

   772 

   773 If a read is issued with a data length of zero (aLength=0) the Read() completes 

   774 immediately with the side effect that the serial hardware is powered up.

   775 

   776 If a read terminates with KErrTimedOut and the descriptor is not empty, 

   777 it will contain valid data. Its length should therefore be tested.

   778 

   779 The behaviour of this API after a call to NotifyDataAvailable() is not prescribed

   780 and so different CSY's behave differently. IrComm will allow a successful completion of this API

   781 after a call to NotifyDataAvailable(), while ECUART and ECACM will complete the request with KErrInUse.

   782 

   783 @param aStatus 	The request status used to contain completion information for 

   784 				the function. On completion, contains a system-wide error code.

   785 @param aDes 	A buffer to store the incoming data. 

   786 @param aLength	An explicit length of data to be read. This length must be 

   787 				between 0 and the MaxLength of the descriptor both included. 

   788 @capability None

   789 */

   790     {

   791 	C32_STATIC_LOG3(KC32Client,_L8("RComm::Read(), bytes to read = %d, given buffer's max length %d"), aLength, aDes.MaxLength());

   792 	if((aLength <= aDes.MaxLength()) && (aLength >= 0))

   793 		{

   794 		aDes.SetLength(0);

   795 		TIpcArgs args(&aDes,aLength,0);

   796 		SendReceive(ECommRead, args, aStatus);

   797 	}

   798 	else

   799 		{//Complete the request due to invalid length

   800 		TRequestStatus* status = &aStatus;

   801 		User::RequestComplete(status, KErrArgument);

   802 		}

   803     }

   804 

   805 

   806 EXPORT_C void RComm::Read(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, TDes8& aDes)

   807 /** Reads data from a serial port only if it arrives before a specified time-out.

   808 

   809 Overloaded version of Read() with timeout.

   810 

   811 All reads from the serial device use 8-bit descriptors as data buffers, even 

   812 on a Unicode system.

   813 

   814 The length of the TDes8 is set to zero on entry, which means that buffers 

   815 can be reused without having to be zeroed first.

   816 

   817 The number of bytes to read is set to the maximum length of the descriptor. 

   818 

   819 If a read is issued with a data length of zero the Read() completes immediately 

   820 but with the side effect that the serial hardware is powered up.

   821 

   822 When a Read() terminates with KErrTimedOut, different protocol modules can 

   823 show different behaviours. Some may write any data received into the aDes 

   824 buffer, while others may return just an empty descriptor. In the case of a 

   825 returned empty descriptor use ReadOneOrMore() to read any data left in the 

   826 buffer.

   827 

   828 The behaviour of this API after a call to NotifyDataAvailable() is not prescribed

   829 and so different CSY's behave differently. IrComm will allow a successful completion of this API

   830 after a call to NotifyDataAvailable(), while ECUART and ECACM will complete the request with KErrInUse.

   831 

   832 @param aStatus The request status used to contain completion information for 

   833 the function. On completion, contains a system-wide error code.

   834 @param aTimeOut The time-out value for reads in microseconds. If data fails 

   835 to arrive before the specified number of microseconds, a KErrTimedOut status 

   836 is returned.

   837 @param aDes A buffer to store the incoming data. The maximum length of the 

   838 descriptor is the default for the number of bytes to be read. 

   839 @capability None

   840 */

   841     {

   842 	C32_STATIC_LOG3(KC32Client,_L8("RComm::Read(), aTimeOut = %d, Max Length = %d"), aTimeOut.Int(), aDes.MaxLength());

   843 	aDes.SetLength(0);

   844 	TIpcArgs args(&aDes,aDes.MaxLength(),aTimeOut.Int());

   845 	SendReceive(ECommRead, args, aStatus);

   846     }

   847 

   848 

   849 EXPORT_C void RComm::Read(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, TDes8& aDes, TInt aLength)

   850 /** Read data from a serial port (before the time-out).

   851 

   852 Reads a specified number of bytes from a serial port only if they arrive before 

   853 a specified time-out. Overloaded version of Read() with timeout and explicit 

   854 length.

   855 

   856 All reads from the serial device use 8-bit descriptors as data buffers, even 

   857 on a Unicode system.

   858 

   859 The length of the TDes8 is set to zero on entry, which means that buffers 

   860 can be reused without having to be zeroed first.

   861 

   862 The number of bytes to read is set to aLength.

   863 

   864 If a read is issued with a data length of zero the Read() completes immediately 

   865 but with the side effect that the serial hardware is powered up.

   866 

   867 When a Read() terminates with KErrTimedOut, different protocol modules can 

   868 show different behaviours. Some may write any data received into the aDes 

   869 buffer, while others may return just an empty descriptor. In the case of a 

   870 returned empty descriptor use ReadOneOrMore() to read any data left in the 

   871 buffer.

   872 

   873 The behaviour of this API after a call to NotifyDataAvailable() is not prescribed

   874 and so different CSY's behave differently. IrComm will allow a successful completion of this API

   875 after a call to NotifyDataAvailable(), while ECUART and ECACM will complete the request with KErrInUse.

   876 

   877 @param aStatus The request status used to contain completion information for 

   878 the function. On completion, contains a system-wide error code.

   879 @param aTimeOut The time-out value for reads in microseconds. If data fails 

   880 to arrive before the specified number of microseconds, a KErrTimedOut status 

   881 is returned. 

   882 @param aDes A buffer to store the incoming data. 

   883 @param aLength An explicit length of data to be read This length must be 

   884 between 0 and the MaxLength of the descriptor both included.

   885 

   886 @capability None

   887 */

   888     {

   889 	C32_STATIC_LOG4(KC32Client,_L8("RComm::Read(), aTimeOut = %d, bytes to read = %d, Max Length of buffer = %d"), aTimeOut.Int(), aLength, aDes.MaxLength());

   890 	if((aLength <= aDes.MaxLength()) && (aLength >= 0))

   891 		{

   892 		aDes.SetLength(0);

   893 		TIpcArgs args(&aDes,aLength,aTimeOut.Int());

   894 		SendReceive(ECommRead, args, aStatus);

   895 		}

   896 	else

   897 		{//Complete the request due to invalid length

   898 		TRequestStatus* status = &aStatus;

   899 		User::RequestComplete(status, KErrArgument);

   900 		}

   901     }

   902 

   903 

   904 EXPORT_C void RComm::ReadOneOrMore(TRequestStatus& aStatus, TDes8& aDes)

   905 /** Read any bytes in the buffer or wait until one arrives.

   906 

   907 Reads data from a serial port, but with slightly different behaviour to Read(). 

   908 If there is data in the serial driver's buffer when ReadOneOrMore() is called, 

   909 it will read as much data as possible (up to the maximum length of the supplied 

   910 buffer) and return immediately. If there is no data in the buffer, the request 

   911 will complete as soon as one or more bytes arrive at the serial hardware.

   912 

   913 The behaviour of this API after a call to NotifyDataAvailable() is not prescribed

   914 and so different CSY's behave differently. IrComm will allow a successful completion of this API

   915 after a call to NotifyDataAvailable(), while ECUART and ECACM will complete the request with KErrInUse.

   916 

   917 @param aStatus The request status used to contain completion information for 

   918 the function. On completion, contains a system-wide error code 

   919 @param aDes A buffer to store the incoming data. The maximum length of the descriptor

   920 is the default for the number of bytes to be read. When the request completes this will 

   921 hold data read from the input buffer. 

   922 @capability None

   923 */

   924     {

   925 	C32_STATIC_LOG2(KC32Client,_L8("RComm::ReadOneOrMore(), buffer's max length = %d"), aDes.MaxLength());

   926 	TIpcArgs args(&aDes,-aDes.MaxLength(),0);

   927 	// Note: specifying negative length here to indicate OneOrMore

   928 	//       see RMaxComm::ReadOneOrMore in ECUART.CPP

   929 	SendReceive(ECommRead, args, aStatus);

   930     }

   931 

   932 

   933 EXPORT_C TInt RComm::ReadCancel()

   934 /** Cancels any pending Read() or ReadOneOrMore() operations.

   935 

   936 The cancelled request will still terminate with its TRequestStatus set to 

   937 any value other than KErrPending. While this is most likely to be KErrCancel, 

   938 it is nevertheless possible for the cancellation to have been issued after 

   939 the asynchronous request had already terminated for some other reason. 

   940 @capability None

   941 */

   942 

   943     {

   944 	TIpcArgs args(TIpcArgs::ENothing);

   945 	return SendReceive(ECommReadCancel, args);

   946     }

   947 

   948 

   949 EXPORT_C TInt RComm::QueryReceiveBuffer() const

   950 /** Gets the number of bytes currently waiting in the driver's input buffer. 

   951 A return value of zero means the buffer is empty.

   952 

   953 It is not possible to find out exactly how many bytes are currently in the 

   954 driver's output buffer waiting to be transmitted. However, this is not an 

   955 issue since it is easy to ensure that the output buffer is empty. If 

   956 the KConfigWriteBufferedComplete bit (set via the TCommConfigV01 structure's iHandshake field) is clear,

   957 then all write requests will delay 

   958 completion until the data has completely cleared the driver's output buffer. 

   959 If the KConfigWriteBufferedComplete bit is set, a write of zero bytes to a port 

   960 which has data in the output buffer is guaranteed to delay completion until 

   961 the buffer has been fully drained.

   962 

   963 @return The number of bytes currently waiting to be read from the receive 

   964 buffer. 

   965 @capability None

   966 */

   967 {

   968 	TUint bufferSize;

   969 	TPtr8 s((TUint8 *)&bufferSize, sizeof(bufferSize));

   970 	TIpcArgs args(&s);

   971 	TInt ret = SendReceive(ECommQueryReceiveBuffer,args);

   972 	if(ret != KErrNone)

   973 		{

   974 		return ret;

   975 		}

   976 	else

   977 		{

   978 		return bufferSize;

   979 		}

   980 }

   981 

   982 

   983 EXPORT_C TInt RComm::ResetBuffers(TUint aFlags)

   984 /** Resets the transmit and receive serial port buffers independently.

   985 

   986 aFlags is a bitmask, so setting KCommResetRx|KCommResetTx (the default) resets 

   987 both buffers and all data in them is lost. This is the default value, so this 

   988 is what happens if the function is called without a parameter.

   989 

   990 This function should not be called when there are pending reads or writes.

   991 

   992 @param aFlags KCommResetRx to reset the receive buffer KCommResetTx to reset 

   993 the transmit buffer 

   994 @capability None

   995 */

   996     {

   997 	TIpcArgs args(aFlags);

   998 	return SendReceive(ECommResetBuffers, args);

   999     }

  1000 

  1001 

  1002 EXPORT_C void RComm::Write(TRequestStatus& aStatus, const TDesC8& aDes)

  1003 /** Writes data to a serial port. 

  1004 

  1005 All writes to the serial device use 8-bit descriptors as data buffers, even 

  1006 on a Unicode system.

  1007 

  1008 The number of bytes to write is set to the maximum length of the descriptor.

  1009 

  1010 When a Write() is issued with a data length of zero it cannot complete until 

  1011 the current handshaking configuration and the state of input control lines 

  1012 indicate that it is possible for data to be immediately written to the serial 

  1013 line, even though no data is to be written. This functionality is useful when 

  1014 determining when serial devices come on line, and checking that the output 

  1015 buffer is empty (if the KConfigWriteBufferedComplete bit is set).

  1016 

  1017 @param aStatus The request status used to contain completion information for 

  1018 the function. On completion, contains a system-wide error code. 

  1019 @param aDes A descriptor containing the data to be written to the serial port. 

  1020 @capability None

  1021 */

  1022     {

  1023 	TIpcArgs args(&aDes,aDes.Length(),0);

  1024 	SendReceive(ECommWrite,args,aStatus);

  1025     }

  1026 

  1027 

  1028 EXPORT_C void RComm::Write(TRequestStatus& aStatus, const TDesC8& aDes, TInt aLength)

  1029 /** Writes a specified number of bytes to a serial port. 

  1030 

  1031 All writes to the serial device use 8-bit descriptors as data buffers, even 

  1032 on a Unicode system.

  1033 

  1034 The number of bytes to write is set to aLength.

  1035 

  1036 When a Write() is issued with a data length of zero it cannot complete until 

  1037 the current handshaking configuration and the state of input control lines 

  1038 indicate that it is possible for data to be immediately written to the serial 

  1039 line, even though no data is to be written. This functionality is useful when 

  1040 determining when serial devices come on line, and checking that the output 

  1041 buffer is empty (if the KConfigWriteBufferedComplete bit is set).

  1042 

  1043 @param aStatus The request status used to contain completion information for 

  1044 the function. On completion, contains a system-wide error code.

  1045 @param aDes A descriptor containing the data to be written to the serial port.

  1046 @param aLength The number of bytes to write. This length must be between 0 

  1047 and the length of the descriptor both included.

  1048 @capability None

  1049 */

  1050     {

  1051 	C32_STATIC_LOG2(KC32Client,_L8("RComm::Write(), (bytes to write) aLength = %d"), aLength);

  1052 	if((aLength <= aDes.Length()) && (aLength >= 0))

  1053 		{

  1054 		TIpcArgs args(&aDes,aLength,0);

  1055 		SendReceive(ECommWrite, args, aStatus);

  1056 		}

  1057 	else

  1058 		{//Complete the request due to invalid length

  1059 		TRequestStatus* status = &aStatus;

  1060 		User::RequestComplete(status, KErrArgument);

  1061 		}

  1062     }

  1063 

  1064 

  1065 EXPORT_C void RComm::Write(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, const TDesC8& aDes)

  1066 /** Writes data to a serial port within a specified time-out.

  1067 

  1068 All writes to the serial device use 8-bit descriptors as data buffers, even 

  1069 on a Unicode system.

  1070 

  1071 The number of bytes to write is set to the maximum length of the descriptor.

  1072 

  1073 When a Write() is issued with a data length of zero it cannot complete until 

  1074 the current handshaking configuration and the state of input control lines 

  1075 indicate that it is possible for data to be immediately written to the serial 

  1076 line, even though no data is to be written. This functionality is useful when 

  1077 determining when serial devices come on line, and checking that the output 

  1078 buffer is empty (if the KConfigWriteBufferedComplete bit is set).

  1079 

  1080 @param aStatus The request status used to contain completion information for 

  1081 the function. On completion, contains a system-wide error code.

  1082 @param aTimeOut The write will terminate after aTimeout microseconds if the 

  1083 data requested has not been sent. A KErrTimedOut status is returned.

  1084 @param aDes A descriptor containing the data to be written to the serial port. 

  1085 @capability None

  1086 */

  1087     {

  1088 	C32_STATIC_LOG2(KC32Client,_L8("RComm::Write(), aTimeOut = %d (microseconds)"), aTimeOut.Int());

  1089 	TIpcArgs args(&aDes,aDes.Length(),aTimeOut.Int());

  1090 	SendReceive(ECommWrite,args, aStatus);

  1091     }

  1092 

  1093 

  1094 EXPORT_C void RComm::Write(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, const TDesC8& aDes, TInt aLength)

  1095 /** Writes a specified number of bytes to a serial port within a specified 

  1096 time-out.

  1097 

  1098 All writes to the serial device use 8-bit descriptors as data buffers, even 

  1099 on a Unicode system.

  1100 

  1101 The number of bytes to write is set to aLength.

  1102 

  1103 When a Write() is issued with a data length of zero it cannot complete until 

  1104 the current handshaking configuration and the state of input control lines 

  1105 indicate that it is possible for data to be immediately written to the serial 

  1106 line. This functionality is useful when determining when serial devices come 

  1107 on line, and checking that the output buffer is empty (if 

  1108 the KConfigWriteBufferedComplete bit is set).

  1109 

  1110 @param aStatus The request status used to contain completion information for 

  1111 the function. On completion, contains a system-wide error code 

  1112 @param aTimeOut The write will terminate after aTimeout microseconds if the 

  1113 data requested has not been sent. A KErrTimedOut status is returned.

  1114 @param aDes A descriptor containing the data to be written to the serial port.

  1115 @param aLength The number of bytes to write. This length must be between 0 

  1116 and the maximum length of the descriptor both included. 

  1117 @capability None

  1118 */

  1119     {

  1120 	C32_STATIC_LOG3(KC32Client,_L8("RComm::Write(), aTimeOut = %d (microseconds), (bytes to write) aLength = %d"), aTimeOut.Int(), aLength);

  1121 	if((aLength <= aDes.Length()) && (aLength >= 0))

  1122 		{

  1123 		TIpcArgs args(&aDes,aLength,aTimeOut.Int());

  1124 		SendReceive(ECommWrite, args, aStatus);

  1125 		}

  1126 	else

  1127 		{//Complete the request due to invalid length

  1128 		TRequestStatus* status = &aStatus;

  1129 		User::RequestComplete(status, KErrArgument);

  1130 		}

  1131     }

  1132 

  1133 

  1134 EXPORT_C TInt RComm::WriteCancel()

  1135 /** Cancels any pending Write() operations.