1.1 --- a/epoc32/include/c32comm.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/c32comm.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,366 @@
1.4 -c32comm.h
1.5 +// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#ifndef SYMBIAN_C32_SERCOMMS_V2
1.21 +// PLEASE NOTE: This file is part of Version 2 of C32 - that is, the multi-threaded version.
1.22 +// The single-threaded C32 version of this file is in c32\Version1\SCOMM
1.23 +// All defect fixes should be applied to both versions where appropriate.
1.24 +// PLEASE NOTE: This comment is applicable to SercommsV2 but is surrounded by an "#ifndef"
1.25 +// to enable the automatic removal of this comment once non-C32 V2 code is removed.
1.26 +#endif
1.27 +
1.28 +
1.29 +#ifndef C32COMM_H
1.30 +#define C32COMM_H
1.31 +
1.32 +/** @file
1.33 +
1.34 +C32 header file to be included by the clients.
1.35 +Defines the main interface to C32, RCommServ and RComm
1.36 +*/
1.37 +
1.38 +#include <e32base.h>
1.39 +#include <d32comm.h>
1.40 +
1.41 +/**
1.42 +@publishedAll
1.43 +@released
1.44 +*/
1.45 +IMPORT_C TInt StartC32();
1.46 +IMPORT_C TInt StartC32WithCMISuppressions(const TDesC& aCMISuppressionList);
1.47 +
1.48 +/**
1.49 +C32 major version number.
1.50 +@internalAll
1.51 +*/
1.52 +const TUint KEC32MajorVersionNumber = 1;
1.53 +/**
1.54 +C32 minor version number.
1.55 +@internalAll
1.56 +*/
1.57 +const TUint KEC32MinorVersionNumber = 0;
1.58 +/**
1.59 +C32 build version number.
1.60 +@internalAll
1.61 +*/
1.62 +const TUint KEC32BuildVersionNumber = 605;
1.63 +
1.64 +/**
1.65 +@internalComponent
1.66 +*/
1.67 +const TDesC& KCommServerName(void);
1.68 +
1.69 +/** Specifies the mode in which a port is opened.
1.70 +
1.71 +We specify the mode when it is opened, and the mode cannot thereafter be
1.72 +changed. If we open the port in Shared mode, other clients of the comms
1.73 +server can use the same port while we have it open. If we open the port
1.74 +in Exclusive mode, then it is locked for our own use and any attempt to
1.75 +access it from another process will fail. Furthermore, our own attempt
1.76 +to open a port in exclusive mode will fail if another process has already
1.77 +opened the port in shared mode.
1.78 +
1.79 +Infra-red ports using IRCOMM.CSY can be opened in either shared or exclusive
1.80 +mode. However they SHOULD only be opened in Exclusive mode, since opening
1.81 +them any other way warm-boots the computer.
1.82 +
1.83 +@publishedAll
1.84 +@released
1.85 +*/
1.86 +enum TCommAccess
1.87 + {
1.88 + /** Once open, the port cannot be used by any other RComm clients. An attempt to
1.89 + open a port in exclusive mode will fail if another process has already opened
1.90 + the port in shared mode. */
1.91 + ECommExclusive,
1.92 + /** The port can be shared by other RComm clients who open in the same mode. */
1.93 + ECommShared,
1.94 + /** Allows another client to pre-empt the session with an open request in one of
1.95 + the other two modes. The port will be lost if other clients are trying to open it.*/
1.96 + ECommPreemptable
1.97 + };
1.98 +/**
1.99 +Use full buffering. Used by RComm::SetMode().
1.100 +
1.101 +@publishedAll
1.102 +@released
1.103 +*/
1.104 +const TUint KCommBufferFull = 0x0000;
1.105 +/**
1.106 +Use partial buffering. Used by RComm::SetMode().
1.107 +
1.108 +@publishedAll
1.109 +@released
1.110 +*/
1.111 +const TUint KCommBufferPartial = 0x0001;
1.112 +
1.113 +
1.114 +/**
1.115 +trace flags for debugging purposes
1.116 +@internalComponent
1.117 +*/
1.118 +enum TC32Trace
1.119 + {
1.120 + ETraceC32Startup = 0x00000001,
1.121 + ETraceC32Panic = 0x00000002,
1.122 + ETraceC32Request = 0x00000004,
1.123 + ETraceC32IPC = 0x00000008,
1.124 + ETraceC32All = 0xFFFFFFFF,
1.125 + };
1.126 +
1.127 +/**
1.128 +Used by the package TCommServerConfig to configure the comm port.
1.129 +
1.130 +Holds the buffer configuration settings for the comms server.
1.131 +
1.132 +The comms server copies data between the descriptors provided by the client
1.133 +and the buffers used by the serial port drivers, for each read and write request.
1.134 +There are two methods by which this can be accomplished. Full buffering means
1.135 +that the comms server will always attempt to allocate enough memory to satisfy
1.136 +any reads or writes in a single copy, while partial buffering means that the
1.137 +comms server will allocate a static buffer and use partial copies to transfer
1.138 +data to the serial driver. When a port is opened, the default is full buffering.
1.139 +
1.140 +@publishedAll
1.141 +@released
1.142 +*/
1.143 +struct TCommServerConfigV01
1.144 + {
1.145 + /** Buffering option: either KCommBufferFull or KCommBufferPartial */
1.146 + TUint iBufFlags; ///< contains buffer flags e.g for partial read/write
1.147 + /** Size of server buffer if partial buffering is being used */
1.148 + TUint iBufSize; ///< size of the Tx/Rx buffer
1.149 + };
1.150 +
1.151 +/** Package buffer for a server configuration object. TCommServerConfig is used
1.152 +as an argument to RComm::Mode() and RComm::SetMode().
1.153 +
1.154 +@publishedAll
1.155 +@released
1.156 +*/
1.157 +typedef TPckgBuf<TCommServerConfigV01> TCommServerConfig;
1.158 +
1.159 +/** Maximum length of port full name, TPortDescription (48 characters).
1.160 +
1.161 +@publishedAll
1.162 +@released
1.163 + */
1.164 +const TInt KMaxPortDescription = 0x30;
1.165 +/** Maximum length of the Port Prefix format name, as used by TPortName (16 characters).
1.166 +
1.167 +@publishedAll
1.168 +@released
1.169 +*/
1.170 +const TInt KMaxPortName = 0x10;
1.171 +
1.172 +/** Reset the receive buffer
1.173 +
1.174 +@publishedAll
1.175 +@released
1.176 +*/
1.177 +const TUint KCommResetRx = 0x00000001; ///< to by used as flag by RComm::ResetBuffers
1.178 +/** Reset the transmit buffer
1.179 +
1.180 +@publishedAll
1.181 +@released
1.182 +*/
1.183 +const TUint KCommResetTx = 0x00000002; ///< to by used as flag by RComm::ResetBuffers
1.184 +/** Port name. Used by TSerialInfo::iName.
1.185 +
1.186 +@publishedAll
1.187 +@released
1.188 +*/
1.189 +typedef TBuf<KMaxPortName> TPortName;
1.190 +/** Full port name/description. Used by TSerialInfo::iDescription.
1.191 +
1.192 +@publishedAll
1.193 +@released
1.194 +*/
1.195 +typedef TBuf<KMaxPortDescription> TPortDescription;
1.196 +
1.197 +
1.198 +class TSerialInfo
1.199 +/** Describes a serial protocol's general capabilities.
1.200 +
1.201 +Used by RCommServ::GetPortInfo to retrieve information
1.202 +about the comm ports and the CSY.
1.203 +
1.204 +Notes:
1.205 +
1.206 +1. The lowest port need not necessarily be numbered zero.
1.207 +
1.208 +2. At least one port is always guaranteed.
1.209 +
1.210 +3. The full name of the serial port (used when opening it) consists of the name
1.211 + returned by TSerialInfo (the Port Prefix), followed by a double colon separator, followed by
1.212 + the unit number (port number) as an ASCII number (for instance COMM::0).
1.213 +
1.214 +@publishedAll
1.215 +@released
1.216 +*/
1.217 + {
1.218 +public:
1.219 + /** Description of the CSY meant only for human reading. It
1.220 + can be up to KMaxPortDescription (48) characters long. */
1.221 + TPortDescription iDescription; ///< description of the port (CSY)
1.222 + /** The short name of the port (Port Prefix). This is used in calls to RComm::Open(). It can be up to
1.223 + KMaxPortName (i.e. 16) characters long. */
1.224 + TPortName iName; ///< name of the port
1.225 + TUint iLowUnit; ///< The lowest port number supported by the serial module
1.226 + TUint iHighUnit; ///< the highest port number supported by the serial module
1.227 + };
1.228 +
1.229 +/**
1.230 +Specifies the DTE/DCE role in which a port is opened.
1.231 +
1.232 +@see RComm::Open()
1.233 +@publishedAll
1.234 +@released
1.235 +*/
1.236 +enum TCommRole
1.237 + {
1.238 + /** Port takes on role of DTE. (DTE=computer).
1.239 + This is the default.
1.240 + */
1.241 + ECommRoleDTE,
1.242 + /** Port takes on role of DCE. (DCE=modem).
1.243 + */
1.244 + ECommRoleDCE
1.245 + };
1.246 +
1.247 +class RComm;
1.248 +
1.249 +
1.250 +class RCommServ : public RSessionBase
1.251 +/** Represents a session with the serial comms server.
1.252 +Functions are provided for connection
1.253 +to the server and for loading and unloading different comms modules, and services
1.254 +for finding out the name and numbers of the available ports.
1.255 +
1.256 +Sessions with the serial comms server are not shareable.
1.257 +
1.258 +Comms modules are also known as "CSY"s due to their ".CSY" extension,
1.259 + derived from the term "Comms SYstem".
1.260 +
1.261 +This class is not intended for user derivation.
1.262 +
1.263 +@publishedAll
1.264 +@released */
1.265 + {
1.266 +public:
1.267 + IMPORT_C RCommServ();
1.268 + IMPORT_C TInt Connect();
1.269 + IMPORT_C TVersion Version() const;
1.270 +
1.271 + IMPORT_C TInt LoadCommModule(const TDesC& aFileName);
1.272 + IMPORT_C TInt UnloadCommModule(const TDesC& aName);
1.273 + IMPORT_C TInt NumPorts(TInt& aNum);
1.274 + IMPORT_C TInt GetPortInfo(const TDesC& aName, TSerialInfo& aInfo);
1.275 + IMPORT_C TInt GetPortInfo(TInt aIndex, TDes& aModuleName, TSerialInfo& aInfo);
1.276 +
1.277 + IMPORT_C TInt __DbgMarkHeap();
1.278 + IMPORT_C TInt __DbgCheckHeap(TInt aCount);
1.279 + IMPORT_C TInt __DbgMarkEnd(TInt aCount);
1.280 + IMPORT_C TInt __DbgFailNext(TInt aCount);
1.281 + IMPORT_C TInt __DbgSetTraceMask(TC32Trace aMask);
1.282 +
1.283 + IMPORT_C static TInt CreateThreadInCommProc(const TDesC& aLibraryName, const TDesC& aThreadName, TThreadFunction aFunction, TInt aStackSize, TInt aHeapMinSize, TInt aHeapMaxSize);
1.284 +private:
1.285 + static TBool IsServerThreadL();
1.286 + };
1.287 +//
1.288 +
1.289 +struct TCommDebugInfo; // defined in d32comm.h
1.290 +
1.291 +
1.292 +class RComm : public RSubSessionBase
1.293 +/** A sub-session to the C32 Serial Server used for addressing a serial port.
1.294 +
1.295 +All the necessary functions are provided by this class for communicating via
1.296 +a port, including functions for opening, closing, reading, writing,
1.297 +port configuration and capability checking. An RComm session represents
1.298 +a single serial port and once opened cannot be altered to represent another port.
1.299 +
1.300 +Ports are referenced by a character string whose format is referred to as Port Prefix format.
1.301 +This format is also known as the CSY internal name, and the ports "short" name in older releases.
1.302 +
1.303 +@publishedAll
1.304 +@released
1.305 +*/
1.306 + {
1.307 +public:
1.308 + IMPORT_C RComm();
1.309 + IMPORT_C TInt Open(RCommServ& aServer, const TDesC& aName, TCommAccess aMode);
1.310 + IMPORT_C TInt Open(RCommServ& aServer, const TDesC& aName, TCommAccess aMode, TCommRole aRole);
1.311 + IMPORT_C void OpenWhenAvailable(TRequestStatus& aStatus, RCommServ& aServer, const TDesC& aName);
1.312 + IMPORT_C void OpenWhenAvailable(TRequestStatus& aStatus, RCommServ& aServer, const TDesC& aName, TCommRole aRole);
1.313 + IMPORT_C void OpenWhenAvailableCancel();
1.314 + IMPORT_C void Read(TRequestStatus& aStatus, TDes8& aDes);
1.315 + IMPORT_C void Read(TRequestStatus& aStatus, TDes8& aDes, TInt aLength);
1.316 + IMPORT_C void Read(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, TDes8& aDes);
1.317 + IMPORT_C void Read(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, TDes8& aDes, TInt aLength);
1.318 + IMPORT_C void ReadOneOrMore(TRequestStatus& aStatus, TDes8& aDes);
1.319 + IMPORT_C TInt ReadCancel();
1.320 + IMPORT_C TInt QueryReceiveBuffer() const;
1.321 + IMPORT_C TInt ResetBuffers(TUint aFlags=(KCommResetRx|KCommResetTx));
1.322 + IMPORT_C void Write(TRequestStatus& aStatus, const TDesC8& aDes);
1.323 + IMPORT_C void Write(TRequestStatus& aStatus, const TDesC8& aDes, TInt aLength);
1.324 + IMPORT_C void Write(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, const TDesC8& aDes);
1.325 + IMPORT_C void Write(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, const TDesC8& aDes, TInt aLength);
1.326 + IMPORT_C TInt WriteCancel();
1.327 + IMPORT_C void Break(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTime);
1.328 + IMPORT_C TInt BreakCancel();
1.329 + IMPORT_C TInt Cancel();
1.330 + IMPORT_C TInt Config(TDes8& aConfig) const;
1.331 + IMPORT_C TInt SetConfig(const TDesC8& aConfig);
1.332 + IMPORT_C TInt Caps(TDes8& aCaps) const;
1.333 + IMPORT_C TInt SetMode(const TCommServerConfig& aConfig);
1.334 + IMPORT_C TInt Mode(TCommServerConfig& aConfig) const;
1.335 + IMPORT_C TUint Signals(TUint aSignalMask = 0x3F) const;
1.336 + IMPORT_C TInt SetSignalsToMark(TUint aSignalMask);
1.337 + IMPORT_C TInt SetSignalsToSpace(TUint aSignalMask);
1.338 + IMPORT_C TInt ReceiveBufferLength() const;
1.339 + IMPORT_C TInt SetReceiveBufferLength(TInt aLength);
1.340 + IMPORT_C void Close();
1.341 + inline void SetSignals(TUint aSetMask, TUint aClearMask);
1.342 + IMPORT_C void NotifySignalChange(TRequestStatus& aStatus, TUint& aSignals, TUint aSignalMask=0x3F);
1.343 + IMPORT_C TInt NotifySignalChangeCancel() const;
1.344 + IMPORT_C void NotifyConfigChange(TRequestStatus& aStatus, TDes8& aNewConfig) const;
1.345 + IMPORT_C TInt NotifyConfigChangeCancel() const;
1.346 + IMPORT_C void NotifyFlowControlChange(TRequestStatus& aStatus, TFlowControl& aFlowControl);
1.347 + IMPORT_C TInt NotifyFlowControlChangeCancel() const;
1.348 + IMPORT_C void NotifyBreak(TRequestStatus& aStatus) const;
1.349 + IMPORT_C TInt NotifyBreakCancel() const;
1.350 + IMPORT_C void NotifyDataAvailable(TRequestStatus& aStatus) const;
1.351 + IMPORT_C TInt NotifyDataAvailableCancel() const;
1.352 + IMPORT_C void NotifyOutputEmpty(TRequestStatus& aStatus) const;
1.353 + IMPORT_C TInt NotifyOutputEmptyCancel() const;
1.354 + IMPORT_C TInt GetFlowControlStatus(TFlowControl& aFlowControl) const;
1.355 + IMPORT_C TInt GetRole(TCommRole& aRole) const;
1.356 +
1.357 + IMPORT_C TInt SetAccessMode(TCommAccess aNewMode);
1.358 + IMPORT_C TInt DebugState(TCommDebugInfo&);
1.359 +
1.360 +#ifdef _DEBUG_DEVCOMM
1.361 + IMPORT_C TInt RComm::DebugInfo(TDes8& aDes);
1.362 +#endif
1.363 +private:
1.364 + TPtr8 iSignalsNotification; ///< pointer to the signals to be changed during notification
1.365 + TPtr8 iFlowNotification; ///< pointer to the flow control to be changed during notification
1.366 + };
1.367 +
1.368 +#include <c32comm.inl>
1.369 +
1.370 +#endif // C32COMM_H