williamr@2: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef C32COMM_H
williamr@2: #define C32COMM_H
williamr@2: 
williamr@2: /** @file
williamr@2: 
williamr@2: C32 header file to be included by the clients.
williamr@2: Defines the main interface to C32, RCommServ and RComm
williamr@2: */
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include <d32comm.h>
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released	
williamr@2: */
williamr@2: IMPORT_C TInt StartC32();
williamr@2: IMPORT_C TInt StartC32WithCMISuppressions(const TDesC& aCMISuppressionList);
williamr@2: 
williamr@2: 
williamr@2: /** Specifies the mode in which a port is opened.
williamr@2: 
williamr@2: We specify the mode when it is opened, and the mode cannot thereafter be
williamr@2: changed. If we open the port in Shared mode, other clients of the comms
williamr@2: server can use the same port while we have it open. If we open the port
williamr@2: in Exclusive mode, then it is locked for our own use and any attempt to
williamr@2: access it from another process will fail. Furthermore, our own attempt
williamr@2: to open a port in exclusive mode will fail if another process has already
williamr@2: opened the port in shared mode.
williamr@2:  
williamr@2: Infra-red ports using IRCOMM.CSY can be opened in either shared or exclusive 
williamr@2: mode. However they SHOULD only be opened in Exclusive mode, since opening 
williamr@2: them any other way warm-boots the computer.
williamr@2:  
williamr@2: @publishedAll
williamr@2: @released	
williamr@2: */
williamr@2: enum TCommAccess
williamr@2:     {
williamr@2: 	/** Once open, the port cannot be used by any other RComm clients. An attempt to 
williamr@2: 	open a port in exclusive mode will fail if another process has already opened 
williamr@2: 	the port in shared mode. */
williamr@2: 	ECommExclusive,  
williamr@2: 	/** The port can be shared by other RComm clients who open in the same mode. */
williamr@2: 	ECommShared,    
williamr@2: 	/** Allows another client to pre-empt the session with an open request in one of 
williamr@2: 	the other two modes. The port will be lost if other clients are trying to open it.*/
williamr@2: 	ECommPreemptable 
williamr@2:     };
williamr@2: /**
williamr@2: Use full buffering. Used by RComm::SetMode().
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@2: const TUint KCommBufferFull    = 0x0000; 
williamr@2: /**
williamr@2: Use partial buffering. Used by RComm::SetMode().
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@2: const TUint KCommBufferPartial = 0x0001;  
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: trace flags for debugging purposes
williamr@4: @publishedAll
williamr@2: */
williamr@2: enum TC32Trace 
williamr@2: 	{
williamr@2: 	ETraceC32Startup = 0x00000001,
williamr@2: 	ETraceC32Panic   = 0x00000002,
williamr@2: 	ETraceC32Request = 0x00000004,
williamr@2: 	ETraceC32IPC     = 0x00000008,
williamr@2: 	ETraceC32All     = 0xFFFFFFFF,
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: Used by the package TCommServerConfig to configure the comm port.
williamr@2: 
williamr@2: Holds the buffer configuration settings for the comms server. 
williamr@2: 
williamr@2: The comms server copies data between the descriptors provided by the client 
williamr@2: and the buffers used by the serial port drivers, for each read and write request. 
williamr@2: There are two methods by which this can be accomplished. Full buffering means 
williamr@2: that the comms server will always attempt to allocate enough memory to satisfy 
williamr@2: any reads or writes in a single copy, while partial buffering means that the 
williamr@2: comms server will allocate a static buffer and use partial copies to transfer 
williamr@2: data to the serial driver. When a port is opened, the default is full buffering. 
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: struct TCommServerConfigV01
williamr@2: 	{
williamr@2: 	/** Buffering option: either KCommBufferFull or KCommBufferPartial */
williamr@4: 	TUint iBufFlags; //< contains buffer flags e.g for partial read/write
williamr@2: 	/** Size of server buffer if partial buffering is being used */
williamr@4: 	TUint iBufSize;  //< size of the Tx/Rx buffer
williamr@2: 	};
williamr@2: 
williamr@2: /** Package buffer for a server configuration object. TCommServerConfig is used 
williamr@2: as an argument to RComm::Mode() and RComm::SetMode(). 
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@2: typedef TPckgBuf<TCommServerConfigV01> TCommServerConfig; 
williamr@2: 
williamr@2: /** Maximum length of port full name, TPortDescription (48 characters).
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2:  */
williamr@2: const TInt KMaxPortDescription = 0x30; 
williamr@2: /** Maximum length of the Port Prefix format name, as used by TPortName (16 characters). 
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@2: const TInt KMaxPortName = 0x10;        
williamr@2: 
williamr@2: /** Reset the receive buffer 
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@4: const TUint KCommResetRx = 0x00000001;  //< to by used as flag by RComm::ResetBuffers
williamr@2: /** Reset the transmit buffer 
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@4: const TUint KCommResetTx = 0x00000002;  //< to by used as flag by RComm::ResetBuffers
williamr@2: /** Port name. Used by TSerialInfo::iName. 
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@2: typedef TBuf<KMaxPortName> TPortName;            
williamr@2: /** Full port name/description. Used by TSerialInfo::iDescription. 
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@2: typedef TBuf<KMaxPortDescription> TPortDescription; 
williamr@2: 
williamr@2: 
williamr@2: class TSerialInfo
williamr@2: /** Describes a serial protocol's general capabilities.
williamr@2: 
williamr@2: Used by RCommServ::GetPortInfo to retrieve information
williamr@2: about the comm ports and the CSY.
williamr@2: 
williamr@2: Notes:
williamr@2: 
williamr@2: 1. The lowest port need not necessarily be numbered zero.
williamr@2: 
williamr@2: 2. At least one port is always guaranteed. 
williamr@2: 
williamr@2: 3. The full name of the serial port (used when opening it) consists of the name 
williamr@2:   returned by TSerialInfo (the Port Prefix), followed by a double colon separator, followed by 
williamr@2:   the unit number (port number) as an ASCII number (for instance COMM::0). 
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Description of the CSY meant only for human reading. It
williamr@2: 	can be up to KMaxPortDescription (48) characters long. */
williamr@4: 	TPortDescription iDescription; //< description of the port (CSY)
williamr@2: 	/** The short name of the port (Port Prefix). This is used in calls to RComm::Open(). It can be up to 
williamr@2: 	KMaxPortName (i.e. 16) characters long. */
williamr@4: 	TPortName iName;               //< name of the port
williamr@4: 	TUint iLowUnit;                //< The lowest port number supported by the serial module
williamr@4: 	TUint iHighUnit;               //< the highest port number supported by the serial module
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: Specifies the DTE/DCE role in which a port is opened.
williamr@2: 
williamr@2: @see RComm::Open() 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@2: enum TCommRole
williamr@2: 	{
williamr@2: 	/** Port takes on role of DTE. (DTE=computer).
williamr@2: 	This is the default.
williamr@2: 	*/
williamr@2: 		ECommRoleDTE, 
williamr@2: 	/** Port takes on role of DCE. (DCE=modem).
williamr@2: 	*/
williamr@2: 		ECommRoleDCE  
williamr@2: 	};
williamr@2: 
williamr@2: class RComm;
williamr@2: 
williamr@2: 
williamr@2: class RCommServ : public RSessionBase
williamr@2: /** Represents a session with the serial comms server. 
williamr@2: Functions are provided for connection 
williamr@2: to the server and for loading and unloading different comms modules, and services 
williamr@2: for finding out the name and numbers of the available ports. 
williamr@2: 
williamr@2: Sessions with the serial comms server are not shareable.
williamr@2: 
williamr@2: Comms modules are also known as "CSY"s due to their ".CSY" extension,
williamr@2:  derived from the term "Comms SYstem".
williamr@2: 
williamr@2: This class is not intended for user derivation.
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released */
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C RCommServ();
williamr@2: 	IMPORT_C TInt Connect();
williamr@2: 	IMPORT_C TVersion Version() const;
williamr@2: 
williamr@2: 	IMPORT_C TInt LoadCommModule(const TDesC& aFileName);
williamr@2: 	IMPORT_C TInt UnloadCommModule(const TDesC& aName);
williamr@2: 	IMPORT_C TInt NumPorts(TInt& aNum);
williamr@2: 	IMPORT_C TInt GetPortInfo(const TDesC& aName, TSerialInfo& aInfo);
williamr@2: 	IMPORT_C TInt GetPortInfo(TInt aIndex, TDes& aModuleName, TSerialInfo& aInfo);
williamr@2: 
williamr@2: 	IMPORT_C TInt __DbgMarkHeap();
williamr@2: 	IMPORT_C TInt __DbgCheckHeap(TInt aCount);
williamr@2: 	IMPORT_C TInt __DbgMarkEnd(TInt aCount);
williamr@2: 	IMPORT_C TInt __DbgFailNext(TInt aCount);
williamr@2: 	IMPORT_C TInt __DbgSetTraceMask(TC32Trace aMask);
williamr@2: 
williamr@2: 	IMPORT_C static TInt CreateThreadInCommProc(const TDesC& aLibraryName, const TDesC& aThreadName, TThreadFunction aFunction, TInt aStackSize, TInt aHeapMinSize, TInt aHeapMaxSize);
williamr@2: private:
williamr@2: 	static TBool IsServerThreadL();
williamr@2: 	};
williamr@2: //
williamr@2: 
williamr@2: struct TCommDebugInfo; // defined in d32comm.h
williamr@2: 
williamr@2: 
williamr@2: class RComm : public RSubSessionBase
williamr@2: /** A sub-session to the C32 Serial Server used for addressing a serial port.
williamr@2: 
williamr@2: All the necessary functions are provided by this class for communicating via 
williamr@2: a port, including functions for opening, closing, reading, writing, 
williamr@2: port configuration and capability checking. An RComm session represents
williamr@2: a single serial port and once opened cannot be altered to represent another port.
williamr@2: 
williamr@2: Ports are referenced by a character string whose format is referred to as Port Prefix format.
williamr@2: This format is also known as the CSY internal name, and the ports "short" name in older releases.
williamr@2: 
williamr@2: @publishedAll	
williamr@2: @released
williamr@2: */
williamr@2: 		{
williamr@2: public:
williamr@2: 	IMPORT_C RComm();
williamr@2: 	IMPORT_C TInt Open(RCommServ& aServer, const TDesC& aName, TCommAccess aMode);
williamr@2: 	IMPORT_C TInt Open(RCommServ& aServer, const TDesC& aName, TCommAccess aMode, TCommRole aRole);
williamr@2: 	IMPORT_C void OpenWhenAvailable(TRequestStatus& aStatus, RCommServ& aServer, const TDesC& aName);
williamr@2: 	IMPORT_C void OpenWhenAvailable(TRequestStatus& aStatus, RCommServ& aServer, const TDesC& aName, TCommRole aRole);
williamr@2: 	IMPORT_C void OpenWhenAvailableCancel();
williamr@2: 	IMPORT_C void Read(TRequestStatus& aStatus, TDes8& aDes);
williamr@2: 	IMPORT_C void Read(TRequestStatus& aStatus, TDes8& aDes, TInt aLength);
williamr@2: 	IMPORT_C void Read(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, TDes8& aDes);
williamr@2: 	IMPORT_C void Read(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, TDes8& aDes, TInt aLength);
williamr@2: 	IMPORT_C void ReadOneOrMore(TRequestStatus& aStatus, TDes8& aDes);
williamr@2: 	IMPORT_C TInt ReadCancel();
williamr@2: 	IMPORT_C TInt QueryReceiveBuffer() const;
williamr@2: 	IMPORT_C TInt ResetBuffers(TUint aFlags=(KCommResetRx|KCommResetTx));
williamr@2: 	IMPORT_C void Write(TRequestStatus& aStatus, const TDesC8& aDes);
williamr@2: 	IMPORT_C void Write(TRequestStatus& aStatus, const TDesC8& aDes, TInt aLength);
williamr@2: 	IMPORT_C void Write(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, const TDesC8& aDes);
williamr@2: 	IMPORT_C void Write(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, const TDesC8& aDes, TInt aLength);
williamr@2: 	IMPORT_C TInt WriteCancel();
williamr@2: 	IMPORT_C void Break(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTime);
williamr@2: 	IMPORT_C TInt BreakCancel();
williamr@2: 	IMPORT_C TInt Cancel();
williamr@2: 	IMPORT_C TInt Config(TDes8& aConfig) const;
williamr@2: 	IMPORT_C TInt SetConfig(const TDesC8& aConfig);
williamr@2: 	IMPORT_C TInt Caps(TDes8& aCaps) const;
williamr@2: 	IMPORT_C TInt SetMode(const TCommServerConfig& aConfig);
williamr@2: 	IMPORT_C TInt Mode(TCommServerConfig& aConfig) const;
williamr@2: 	IMPORT_C TUint Signals(TUint aSignalMask = 0x3F) const;
williamr@2: 	IMPORT_C TInt SetSignalsToMark(TUint aSignalMask);
williamr@2: 	IMPORT_C TInt SetSignalsToSpace(TUint aSignalMask);
williamr@2: 	IMPORT_C TInt ReceiveBufferLength() const;
williamr@2: 	IMPORT_C TInt SetReceiveBufferLength(TInt aLength);
williamr@2: 	IMPORT_C void Close();
williamr@2: 	inline void SetSignals(TUint aSetMask, TUint aClearMask);
williamr@2: 	IMPORT_C void NotifySignalChange(TRequestStatus& aStatus, TUint& aSignals, TUint aSignalMask=0x3F);
williamr@2: 	IMPORT_C TInt NotifySignalChangeCancel() const;
williamr@2: 	IMPORT_C void NotifyConfigChange(TRequestStatus& aStatus, TDes8& aNewConfig) const;
williamr@2: 	IMPORT_C TInt NotifyConfigChangeCancel() const;
williamr@2: 	IMPORT_C void NotifyFlowControlChange(TRequestStatus& aStatus, TFlowControl& aFlowControl);
williamr@2: 	IMPORT_C TInt NotifyFlowControlChangeCancel() const;	  
williamr@2: 	IMPORT_C void NotifyBreak(TRequestStatus& aStatus) const;
williamr@2: 	IMPORT_C TInt NotifyBreakCancel() const;
williamr@2: 	IMPORT_C void NotifyDataAvailable(TRequestStatus& aStatus) const;
williamr@2: 	IMPORT_C TInt NotifyDataAvailableCancel() const;
williamr@2: 	IMPORT_C void NotifyOutputEmpty(TRequestStatus& aStatus) const;
williamr@2: 	IMPORT_C TInt NotifyOutputEmptyCancel() const;
williamr@2: 	IMPORT_C TInt GetFlowControlStatus(TFlowControl& aFlowControl) const;
williamr@2: 	IMPORT_C TInt GetRole(TCommRole& aRole) const;
williamr@2: 
williamr@2: 	IMPORT_C TInt SetAccessMode(TCommAccess aNewMode);
williamr@2: 	IMPORT_C TInt DebugState(TCommDebugInfo&);
williamr@2: 
williamr@2: #ifdef _DEBUG_DEVCOMM
williamr@2: 	IMPORT_C TInt RComm::DebugInfo(TDes8& aDes);
williamr@2: #endif
williamr@2: private:
williamr@4: 	TPtr8 iSignalsNotification; //< pointer to the signals to be changed during notification
williamr@4: 	TPtr8 iFlowNotification;    //< pointer to the flow control to be changed during notification
williamr@2: 	};
williamr@2: 	
williamr@4: 
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: #include <c32comm_internal.h>
williamr@4: #endif
williamr@4: 
williamr@2: #include <c32comm.inl>
williamr@2: 
williamr@2: #endif // C32COMM_H