1.1 --- a/epoc32/include/cs_port.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/cs_port.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,9 +1,9 @@
1.4 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 // All rights reserved.
1.6 // This component and the accompanying materials are made available
1.7 -// 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.8 +// under the terms of "Eclipse Public License v1.0"
1.9 // which accompanies this distribution, and is available
1.10 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.12 //
1.13 // Initial Contributors:
1.14 // Nokia Corporation - initial contribution.
1.15 @@ -13,13 +13,6 @@
1.16 // Description:
1.17 //
1.18
1.19 -#ifndef SYMBIAN_C32_SERCOMMS_V2
1.20 -// PLEASE NOTE: This file is part of Version 2 of C32 - that is, the multi-threaded version.
1.21 -// The single-threaded C32 version of this file is in c32\Version1\SCOMM
1.22 -// All defect fixes should be applied to both versions where appropriate.
1.23 -// PLEASE NOTE: This comment is applicable to SercommsV2 but is surrounded by an "#ifndef"
1.24 -// to enable the automatic removal of this comment once non-C32 V2 code is removed.
1.25 -#endif
1.26
1.27
1.28 #ifndef CS_PORT_H
1.29 @@ -200,7 +193,7 @@
1.30 // Pure virtual methods - to be implemented by the CSY
1.31 //
1.32
1.33 - /// Called by manager when access count is 0 - CSY port must call 'delete this'
1.34 + // Called by manager when access count is 0 - CSY port must call 'delete this'
1.35 /** Specifies the protocol for port destruction. It is called by the comms server
1.36 when the last client-side reference to a CPort object has been closed and
1.37 the CPort must be deleted. The comms server will not delete a CPort other
1.38 @@ -210,9 +203,9 @@
1.39 its own resources and, when these operations have completed, should delete
1.40 this. */
1.41 virtual void Destruct()=0;
1.42 - /// Queue a read - called by CPort when client wants to read
1.43 - /// Note: if the value in aLength is negative, this means
1.44 - /// ReadOneOrMore and the CSY must invert the number
1.45 + // Queue a read - called by CPort when client wants to read
1.46 + // Note: if the value in aLength is negative, this means
1.47 + // ReadOneOrMore and the CSY must invert the number
1.48 /** Specifies the protocol for reading from the port. It is called by the comms
1.49 server in response to a RComm::Read() or RComm::ReadOneOrMore() request from
1.50 the client.
1.51 @@ -229,7 +222,7 @@
1.52 the client's buffer
1.53 @param aLength The amount of data to be read */
1.54 virtual void StartRead(const TAny* aClientBuffer, TInt aLength)=0;
1.55 - /// Cancel a pending read
1.56 + // Cancel a pending read
1.57 /** Specifies the protocol for cancelling reading from the port. It is called by
1.58 the comms server in response to a RComm::ReadCancel() request from the client or
1.59 when the iReadTimer timer expires.
1.60 @@ -237,7 +230,7 @@
1.61 The implementation should abort any processing which was taking place as a
1.62 result of the read request. Do not call ReadCompleted(). */
1.63 virtual void ReadCancel()=0;
1.64 - /// Get the size of the receive buffer from the real serial port
1.65 + // Get the size of the receive buffer from the real serial port
1.66 /** Specifies a protocol for requesting the number of bytes that are currently
1.67 waiting in the port's receive buffer. It is called by the comms server in
1.68 response to a RComm::QueryReceiveBuffer() request from the client.
1.69 @@ -246,7 +239,7 @@
1.70 from the receive buffer.
1.71 @return A system wide error code. */
1.72 virtual TInt QueryReceiveBuffer(TInt& aLength) const=0;
1.73 - /// reset Tx and Rx buffers
1.74 + // reset Tx and Rx buffers
1.75 /** Specifies a protocol for resetting the receive and/or transmit buffers to zero
1.76 length. It is called by the comms server in response to a RComm::ResetBuffers()
1.77 request from the client.
1.78 @@ -254,7 +247,7 @@
1.79 @param aFlags Bitmask of the following flags: KCommResetRx to reset the receive
1.80 buffer; KCommResetTx to reset the transmit buffer */
1.81 virtual void ResetBuffers(TUint aFlags)=0;
1.82 - /// Queue a write - called by CPort when client wants to write
1.83 + // Queue a write - called by CPort when client wants to write
1.84 /** Specifies the protocol for writing to the port. It is called by the comms server
1.85 in response to a RComm::Write() request from the client.
1.86
1.87 @@ -266,14 +259,14 @@
1.88 the client's buffer
1.89 @param aLength The amount of data to be written */
1.90 virtual void StartWrite(const TAny* aClientBuffer, TInt aLength)=0;
1.91 - /// Cancel a pending write
1.92 + // Cancel a pending write
1.93 /** Specifies the protocol for cancelling writing to the port. It is called by
1.94 the comms server in response to a RComm::WriteCancel() request from the client.
1.95
1.96 The implementation should abort any processing which was taking place as a
1.97 result of the write request. Do not call WriteCompleted(). */
1.98 virtual void WriteCancel()=0;
1.99 - /// Queue a break
1.100 + // Queue a break
1.101 /** Specifies the protocol for setting a break condition at the port. It is called
1.102 by the comms server in response to a RComm::Break() request from the client.
1.103
1.104 @@ -281,14 +274,14 @@
1.105
1.106 @param aTime Time period to break for in microseconds */
1.107 virtual void Break(TInt aTime)=0;
1.108 - /// Cancel a pending break
1.109 + // Cancel a pending break
1.110 /** Specifies the protocol for cancelling a break request. It is called by the
1.111 comms server in response to a RComm::BreakCancel() request from the client.
1.112
1.113 The implementation should abort any processing which was taking place as a
1.114 result of the break request. Do not call BreakCompleted(). */
1.115 virtual void BreakCancel()=0;
1.116 - /// Pass a config request - return in descriptor
1.117 + // Pass a config request - return in descriptor
1.118 /** Specifies a protocol for getting the current configuration of the serial port.
1.119 It is called by the comms server in response to a RComm::GetConfig() request
1.120 from the client.
1.121 @@ -297,7 +290,7 @@
1.122 configuration of the serial port
1.123 @return A system wide error code */
1.124 virtual TInt GetConfig(TDes8& aPackage) const=0;
1.125 - /// Set config with package in the descriptor
1.126 + // Set config with package in the descriptor
1.127 /** Specifies a protocol for setting the configuration of the port. It is called
1.128 by the comms server in response to a RComm::SetConfig() request from the client.
1.129
1.130 @@ -305,14 +298,14 @@
1.131 values
1.132 @return A system error code */
1.133 virtual TInt SetConfig(const TDesC8& aPackage)=0;
1.134 - /// Set the port to use partial reads/writes
1.135 + // Set the port to use partial reads/writes
1.136 /** Specifies a protocol for setting the buffer mode. It is called by the comms
1.137 server in response to a RComm::SetMode() request from the client.
1.138
1.139 @param aPackage A TCommServerConfig package buffer holding the mode settings
1.140 @return A system-wide error code */
1.141 virtual TInt SetServerConfig(const TDesC8& aPackage)=0;
1.142 - /// Get the server configs from the CSY
1.143 + // Get the server configs from the CSY
1.144 /** Specifies a protocol for getting the buffer mode. It is called by the comms
1.145 server in response to a RComm::Mode() request from the client.
1.146
1.147 @@ -320,7 +313,7 @@
1.148 the current buffer mode settings
1.149 @return A system error code */
1.150 virtual TInt GetServerConfig(TDes8& aPackage)=0;
1.151 - /// Read capabilities from the driver
1.152 + // Read capabilities from the driver
1.153 /** Specifies a protocol for getting the port capabilities. It is called by the
1.154 comms server in response to a RComm::Caps() request from the client.
1.155
1.156 @@ -328,7 +321,7 @@
1.157 capabilities
1.158 @return A system error code */
1.159 virtual TInt GetCaps(TDes8& aPackage)=0;
1.160 - /// Get the status of the signal pins
1.161 + // Get the status of the signal pins
1.162 /** Specifies a protocol for getting the status of the serial port control lines.
1.163 It is called by the comms server in response to a RComm::GetSignals() request
1.164 from the client.
1.165 @@ -337,21 +330,21 @@
1.166 handshaking lines.
1.167 @return A system error code */
1.168 virtual TInt GetSignals(TUint& aSignals)=0;
1.169 - /// Set selected signals to high (logical 1)
1.170 + // Set selected signals to high (logical 1)
1.171 /** Specifies a protocol for setting serial port control lines. It is called by
1.172 the comms server in response to a RComm::SetSignals() request from the client.
1.173
1.174 @param aSignals A bitmask of the handshaking lines to set
1.175 @return A system error code */
1.176 virtual TInt SetSignalsToMark(TUint aSignals)=0;
1.177 - /// Set selected signals to low (logical 0)
1.178 + // Set selected signals to low (logical 0)
1.179 /** Specifies a protocol for clearing serial port control lines. It is called by
1.180 the comms server in response to a RComm::SetSignals() request from the client.
1.181
1.182 @param aSignals A bitmask of the handshaking lines to clear
1.183 @return A system error code */
1.184 virtual TInt SetSignalsToSpace(TUint aSignals)=0;
1.185 - /// Get size of Tx and Rx buffer
1.186 + // Get size of Tx and Rx buffer
1.187 /** Specifies a protocol for requesting the size of the serial port buffers. It
1.188 is called by the comms server in response to a RComm::ReceiveBufferLength()
1.189 request from the client.
1.190 @@ -359,7 +352,7 @@
1.191 @param aLength The current size of the serial port buffers in bytes
1.192 @return A system error code */
1.193 virtual TInt GetReceiveBufferLength(TInt& aLength) const=0;
1.194 - /// Set size of Tx and Rx buffer
1.195 + // Set size of Tx and Rx buffer
1.196 /** Specifies a protocol for setting the size of the serial port buffers. It is
1.197 called by the comms server in response to a RComm::SetReceiveBufferLength()
1.198 request from the client.
1.199 @@ -368,83 +361,83 @@
1.200 @return A system error code */
1.201 virtual TInt SetReceiveBufferLength(TInt aLength)=0;
1.202 virtual void FreeMemory(); // csys have their own implementation, e.g. ECUART
1.203 - /// Notify client when the signals change
1.204 + // Notify client when the signals change
1.205 /** Specifies the protocol for setting a "signal change" notification. It is called
1.206 by the comms server in response to a RComm::NotifySignalChange() request from
1.207 the client.
1.208
1.209 @param aSignalMask Signal mask passed by client */
1.210 virtual void NotifySignalChange(TUint aSignalMask)=0;
1.211 - /// Cancel an outstanding signal change notification
1.212 + // Cancel an outstanding signal change notification
1.213 /** Specifies the protocol for cancelling a "signal change" notification. It is called
1.214 by the comms server in response to a RComm::NotifySignalChangeCancel() request
1.215 from the client. */
1.216 virtual void NotifySignalChangeCancel()=0;
1.217 - /// Notify client when the configation changes
1.218 + // Notify client when the configation changes
1.219 /** Specifies the protocol for setting a "configuration change" notification. It
1.220 is called by the comms server in response to a RComm::NotifyConfigChange()
1.221 request from the client. */
1.222 virtual void NotifyConfigChange()=0;
1.223 - /// Cancel an outstanding config change notification
1.224 + // Cancel an outstanding config change notification
1.225 /** Specifies the protocol for cancelling a "configuration change" notification.
1.226 It is called by the comms server in response to a RComm::NotifyConfigChangeCancel()
1.227 request from the client. */
1.228 virtual void NotifyConfigChangeCancel()=0;
1.229 - /// Notify client when the flow control changes
1.230 + // Notify client when the flow control changes
1.231 /** Specifies the protocol for setting a "flow control change" notification. It is
1.232 called by the comms server in response to a RComm::NotifyFlowControlChange()
1.233 request from the client. */
1.234 virtual void NotifyFlowControlChange()=0;
1.235 - /// Cancel an outstanding flow control change notification
1.236 + // Cancel an outstanding flow control change notification
1.237 /** Specifies the protocol for cancelling a "flow control change" notification. It
1.238 is called by the comms server in response to a RComm::NotifyFlowControlChangeCancel()
1.239 request from the client. */
1.240 virtual void NotifyFlowControlChangeCancel()=0;
1.241 - /// Notify client when a break occurs
1.242 + // Notify client when a break occurs
1.243 /** Specifies the protocol for setting a "break" notification. It is called by the
1.244 comms server in response to a RComm::NotifyBreak() request from the client. */
1.245 virtual void NotifyBreak()=0;
1.246 - /// Cancel an outstanding break notification
1.247 + // Cancel an outstanding break notification
1.248 /** Specifies the protocol for cancelling a "break" notification. It is called by
1.249 the comms server in response to a RComm::NotifyBreakCancel() request from
1.250 the client. */
1.251 virtual void NotifyBreakCancel()=0;
1.252 - /// Notify client when data is available
1.253 + // Notify client when data is available
1.254 /** Specifies the protocol for setting a "data available" notification. It is called
1.255
1.256 by the comms server in response to a RComm::NotifyDataAvailable() request
1.257 from the client. */
1.258 virtual void NotifyDataAvailable()=0;
1.259 - /// Cancel an outstanding data available notification
1.260 + // Cancel an outstanding data available notification
1.261 /** Specifies the protocol for cancelling a "data available" notification. It is
1.262 called by the comms server in response to a RComm::NotifyDataAvailableCancel()
1.263 request from the client. */
1.264 virtual void NotifyDataAvailableCancel()=0;
1.265 - /// Notify client when output buffer is empty
1.266 + // Notify client when output buffer is empty
1.267 /** Specifies the protocol for setting a transmit buffer empty notification. It
1.268 is called by the comms server in response to a RComm::NotifyOutputEmpty()
1.269 request from the client. */
1.270 virtual void NotifyOutputEmpty()=0;
1.271 - /// Cancel an outstanding output empty notification
1.272 + // Cancel an outstanding output empty notification
1.273 /** Specifies the protocol for cancelling a transmit buffer empty notification.
1.274 It is called by the comms server in response to a RComm::NotifyOutputEmptyCancel()
1.275 request from the client. */
1.276 virtual void NotifyOutputEmptyCancel()=0;
1.277 - /// Get the flow control status
1.278 + // Get the flow control status
1.279 /** Gets flow control status. It is called by the comms server in response to a
1.280 RComm::SetMode() request from the client.
1.281
1.282 @param aFlowControl Flow control status to return to the client
1.283 @return A system-wide error code */
1.284 virtual TInt GetFlowControlStatus(TFlowControl& aFlowControl)=0;
1.285 - /// Get the role of this port unit
1.286 + // Get the role of this port unit
1.287 /** Gets DCE/DTE role. It is called by the comms server in response to a RComm::GetRole()
1.288 request from the client.
1.289
1.290 @param aRole On return, DCE/DTE role to return to the client
1.291 @return A system-wide error code */
1.292 virtual TInt GetRole(TCommRole& aRole)=0;
1.293 - /// Set the role of this port unit
1.294 + // Set the role of this port unit
1.295 /** Sets DCE/DTE role. It is called by the comms server in response to a RComm::Open()
1.296 request from the client.
1.297
1.298 @@ -460,60 +453,60 @@
1.299 void DoOpenL(CCommSession* aSession, TInternalCommAccess aMode, TCommRole aRole,TBool aIsNew);
1.300 void DoPreemption();
1.301
1.302 - TDeltaTimerEntry iReadTimer; ///< delta timer entry for read timeouts
1.303 - TBool iReadTimerPending; ///< true if a read timer is pending
1.304 - TDeltaTimerEntry iWriteTimer; ///< delta timer entry for write timeouts
1.305 - TBool iWriteTimerPending; ///< true if a write timer is pending
1.306 - TInternalCommAccess iMode; ///< access mode for this port
1.307 - CCommSession* iReadOwner; ///< pointer to the read session
1.308 - TInt iReadOwnerHandle; ///< handle to the read session
1.309 - CCommSession* iWriteOwner; ///< pointer to the write session
1.310 - TInt iWriteOwnerHandle; ///< handle to the write session
1.311 + TDeltaTimerEntry iReadTimer; //< delta timer entry for read timeouts
1.312 + TBool iReadTimerPending; //< true if a read timer is pending
1.313 + TDeltaTimerEntry iWriteTimer; //< delta timer entry for write timeouts
1.314 + TBool iWriteTimerPending; //< true if a write timer is pending
1.315 + TInternalCommAccess iMode; //< access mode for this port
1.316 + CCommSession* iReadOwner; //< pointer to the read session
1.317 + TInt iReadOwnerHandle; //< handle to the read session
1.318 + CCommSession* iWriteOwner; //< pointer to the write session
1.319 + TInt iWriteOwnerHandle; //< handle to the write session
1.320 // Binary compatible
1.321 // Was: CCommSession* iBreakOwner; Replace with:
1.322 - CExtra* iExtra; ///< pointer to the CExtra object for pre-emptable handling
1.323 -#define iBreakOwner (iExtra->iBreakOwner) ///< forwards iBreakOwner to iExtra->iBreakOwner
1.324 + CExtra* iExtra; //< pointer to the CExtra object for pre-emptable handling
1.325 +#define iBreakOwner (iExtra->iBreakOwner) //< forwards iBreakOwner to iExtra->iBreakOwner
1.326
1.327 - TInt iBreakOwnerHandle; ///< handle to the break owner
1.328 - CCommSession* iSignalOwner; ///< pointer to the signal session
1.329 - TInt iSignalOwnerHandle; ///< handle to the signal session
1.330 - CCommSession* iFlowControlOwner; ///< pointer to the flow control session
1.331 - TInt iFlowControlOwnerHandle; ///< handle to the flow control session
1.332 - CCommSession* iConfigOwner; ///< pointer to the config session
1.333 - TInt iConfigOwnerHandle; ///< handle to the config session
1.334 - CCommSession* iBreakNotifyOwner; ///< pointer to the break notify session
1.335 - TInt iBreakNotifyOwnerHandle; ///< handle to the break notify session
1.336 - CCommSession* iNotifyDataAvailableOwner; ///< pointer to the data available session
1.337 - TInt iNotifyDataAvailableOwnerHandle; ///< handle to the data available session
1.338 - CCommSession* iNotifyOutputEmptyOwner; ///< pointer to the output empty session
1.339 - TInt iNotifyOutputEmptyOwnerHandle; ///< handle to the output empty session
1.340 + TInt iBreakOwnerHandle; //< handle to the break owner
1.341 + CCommSession* iSignalOwner; //< pointer to the signal session
1.342 + TInt iSignalOwnerHandle; //< handle to the signal session
1.343 + CCommSession* iFlowControlOwner; //< pointer to the flow control session
1.344 + TInt iFlowControlOwnerHandle; //< handle to the flow control session
1.345 + CCommSession* iConfigOwner; //< pointer to the config session
1.346 + TInt iConfigOwnerHandle; //< handle to the config session
1.347 + CCommSession* iBreakNotifyOwner; //< pointer to the break notify session
1.348 + TInt iBreakNotifyOwnerHandle; //< handle to the break notify session
1.349 + CCommSession* iNotifyDataAvailableOwner; //< pointer to the data available session
1.350 + TInt iNotifyDataAvailableOwnerHandle; //< handle to the data available session
1.351 + CCommSession* iNotifyOutputEmptyOwner; //< pointer to the output empty session
1.352 + TInt iNotifyOutputEmptyOwnerHandle; //< handle to the output empty session
1.353
1.354 - RMessagePtr2 iBlockedRead; ///< pointer to the read request message
1.355 - RMessagePtr2 iBlockedWrite; ///< pointer to the write request message
1.356 - RMessagePtr2 iBlockedBreak; ///< pointer to the break request message
1.357 + RMessagePtr2 iBlockedRead; //< pointer to the read request message
1.358 + RMessagePtr2 iBlockedWrite; //< pointer to the write request message
1.359 + RMessagePtr2 iBlockedBreak; //< pointer to the break request message
1.360
1.361 /**The encapsulated message*/
1.362 - RMessagePtr2 iBlockedSignalChange; ///< holds the notify signal change message
1.363 + RMessagePtr2 iBlockedSignalChange; //< holds the notify signal change message
1.364 /**Private padding to preserve BC with earlier versions*/
1.365 TInt iBlockedSignalChangeDummyPadding[7];
1.366
1.367 /**The encapsulated message*/
1.368 - RMessagePtr2 iBlockedConfigChange; ///< holds the notify config change message
1.369 + RMessagePtr2 iBlockedConfigChange; //< holds the notify config change message
1.370 /**Private padding to preserve BC with earlier versions*/
1.371 TInt iBlockedConfigChangeDummyPadding[7];
1.372
1.373 /**The encapsulated message*/
1.374 - RMessagePtr2 iBlockedFlowControlChange; ///< holds the notify flow control change message
1.375 + RMessagePtr2 iBlockedFlowControlChange; //< holds the notify flow control change message
1.376 /**Private padding to preserve BC with earlier versions*/
1.377 TInt iBlockedFlowControlChangeDummyPadding[7];
1.378
1.379 - RMessagePtr2 iBlockedBreakNotify; ///< pointer to the notify break request message
1.380 - RMessagePtr2 iBlockedNotifyDataAvailable; ///< pointer to the notify data available request message
1.381 - RMessagePtr2 iBlockedNotifyOutputEmpty; ///< pointer to the notify output empty request message
1.382 + RMessagePtr2 iBlockedBreakNotify; //< pointer to the notify break request message
1.383 + RMessagePtr2 iBlockedNotifyDataAvailable; //< pointer to the notify data available request message
1.384 + RMessagePtr2 iBlockedNotifyOutputEmpty; //< pointer to the notify output empty request message
1.385
1.386 - CPortManager* iPortManager; ///< Not Used. Not to be exposed to deriving classes of CPort.
1.387 + CPortManager* iPortManager; //< Not Used. Not to be exposed to deriving classes of CPort.
1.388 IMPORT_C virtual void CPort_Reserved1();
1.389 - TAny* iCPort_Reserved; ///< reserved pointer
1.390 + TAny* iCPort_Reserved; //< reserved pointer
1.391 };
1.392
1.393
1.394 @@ -555,7 +548,7 @@
1.395 // pure virtuals to be implemented by the CSY
1.396 //
1.397
1.398 - /// Create a new port for the supplied unit number
1.399 + // Create a new port for the supplied unit number
1.400 /** Specifies the protocol for creating a new serial port for the protocol. The
1.401 comms server calls this function in response to a RComm:Open() call.
1.402
1.403 @@ -574,7 +567,7 @@
1.404
1.405 @param aUnit The unit number to be created. */
1.406 virtual CPort* NewPortL(const TUint aUnit)=0;
1.407 - /// Get info about this CSY, fill in the supplied structure.
1.408 + // Get info about this CSY, fill in the supplied structure.
1.409 /** Specifies the protocol for getting the information about the serial protocol.
1.410
1.411 Implementations should fill in the TSerialInfo structure to reflect the protocol's
1.412 @@ -591,11 +584,11 @@
1.413 protected:
1.414 /** Module version number. The class should initialise this member with its version
1.415 number from its constructor. */
1.416 - TVersion iVersion; ///< holds the version of the CSY
1.417 + TVersion iVersion; //< holds the version of the CSY
1.418 private:
1.419 - CLibUnloader* iLibUnloader; ///< pointer to the library unloader
1.420 + CLibUnloader* iLibUnloader; //< pointer to the library unloader
1.421 IMPORT_C virtual void CSerial_Reserved1();
1.422 - TAny* iCSerial_Reserved; ///< reserved pointer for future BC
1.423 + TAny* iCSerial_Reserved; //< reserved pointer for future BC
1.424 };
1.425
1.426 /** This typedef defines the form of the ordinal-1 entry point function to a serial
1.427 @@ -605,6 +598,6 @@
1.428 Each serial protocol module should only ever create a single serial protocol
1.429 factory object. If the entry point is called twice without the first factory
1.430 object being destroyed, this function should leave with KErrGeneral. */
1.431 -typedef CSerial *(*TSerialNewL)(); ///< function type of CSY module entry point
1.432 +typedef CSerial *(*TSerialNewL)(); //< function type of CSY module entry point
1.433
1.434 #endif // CS_PORT_H