1 

     2 /**

     3 * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

     4 * All rights reserved.

     5 * This component and the accompanying materials are made available

     6 * under the terms of "Eclipse Public License v1.0"

     7 * which accompanies this distribution, and is available

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

     9 *

    10 * Initial Contributors:

    11 * Nokia Corporation - initial contribution.

    12 *

    13 * Contributors:

    14 *

    15 * Description:

    16 * Baseband Channel Adaptor(BCA) APIs.

    17 * This file contains all the APIs required to implement a BCA interface for Symbian OS.

    18 * 

    19 *

    20 */

    21 

    22 

    23 

    24 /**

    25  @file

    26  @publishedPartner

    27  @prototype

    28  @released

    29 */

    30 #ifndef BCA2_H

    31 #define BCA2_H

    32 

    33 /** This namespace includes the BCA component names.*/

    34 namespace BasebandChannelAdaptation2

    35 {

    36 /**

    37  * The class implemented by an upper component to accept control signals from the lower component

    38 

    39  * @publishedPartner

    40  * @prototype

    41  */

    42 class MUpperControl

    43 	{

    44 public:

    45 	/**

    46 	* Indicates to the layer above (link layer) that the Bca is ready to start 

    47 	* receiving packets from the upper layer (either after MBca start 

    48 	* completes or following congestion)

    49 	

    50 	* @param none

    51 	* @return none.

    52 	*/

    53 	virtual void StartSending()=0;

    54 	

    55 	/**

    56 	* Any fatal error which occurs during the send/receive session is reported 

    57 	* to the client by a call to this function. Fatal errors are errors which can’t 

    58 	* be recovered from (e.g.:  connection down) in which case MBca has become 

    59 	* defunct and can no longer be used to send and receive data

    60 	

    61 	* @param aErr TThe fatal error code from the session failures propagated 

    62 	* to the upper layer of the communications stack . Non fatal errors keep 

    63 	* the MBca2 functional which in the context of MBca2 implementation may 

    64 	* include KErrNoMemory, KErrCommsParity, KErrCommsOverrun, KErrCommsFrame. 

    65 	* @return none.

    66 	*/

    67 	virtual void Error(TInt aErr)=0;

    68 

    69 	};

    70 	

    71 /**

    72  * The Class implemented by an upper component to accept inbound data travelling 

    73  * upwards from the lower component

    74 

    75  * @publishedPartner

    76  * @prototype

    77  */ 	

    78 class MUpperDataReceiver

    79 	{

    80 public:

    81 	/**

    82 	* This function is called whenever data has been received by MBca which 

    83 	* should be processed by its client. The implementer takes ownership of the 

    84 	* buffer and is responsible for its deletion.

    85 	

    86 	* @param aCommsBufChain - The list of comms buffers containing data to be processed. 

    87          * Destination keeps the custody of the buffer.

    88 	* @return none.

    89 	*/

    90 	virtual void Process(RCommsBufChain& aCommsBufChain)=0;

    91 	};

    92 

    93 /**

    94  * The interface implemented by the lower component to accept data from the upper component

    95 

    96  * @publishedPartner

    97  * @prototype

    98  */

    99  	

   100 class MLowerDataSender

   101 	{

   102 	public:

   103 	enum TSendResult

   104 		{

   105 			// data accepted, send no more until MUpperControl::StartSending() is called

   106 			ESendBlocked,

   107 			// data accepted, can send more.

   108 			ESendAccepted

   109 		};

   110 	/**

   111 	* Sends the specified buffer data down to the base-band. The implementer takes 

   112 	* ownership of the buffer and is responsible for its deletion.

   113 	

   114 	* @param aCommsBufChain the comms buffer list to be sent.The buffer ownership is passed 

   115 	* to the BCA

   116 	* @return TTSendResult either ESendBlocked or SendAccepted. When the Bca 

   117 	* is congested and cannot send any data beyond the current packet (which is 

   118 	* always accepted), the implementation returns ESendBlocked. If BCA is not

   119 	* congested then ESendAccepted is returned to continue sending. When congestion 

   120 	* passes, the Bca calls StartSending on the upper layer to resume sending. The

   121 	* implementation is recommended to panic any attempts to call Send during congestion 

   122 	*/

   123 	virtual	TSendResult Send(RCommsBufChain& aCommsBufChain)=0;

   124 	};

   125 

   126 /**

   127  * The interface implemented by the lower component to accept control signals from the upper component

   128  

   129  * @publishedPartner

   130  * @prototype

   131  */ 

   132 class MBca2

   133 	{

   134 public:

   135 	 struct TBcaParams 

   136 		{

   137 		RCommsBufPond iCommsBufPond;	// Pond to be used by BCA implementation for creating, using pools and buffers

   138 		const TDesC& iChannelId;				// port number or channel which BCA uses to communicate with its lower layers 

   139 		TBcaParams(RCommsBufPond aCommsBufPond,const TDesC& aChannelId)

   140 		: iCommsBufPond(aCommsBufPond),

   141 		iChannelId(aChannelId){}

   142 	 	};

   143 

   144 		

   145 	/**

   146 	* Opens the BCA instance and commences a BCA session (::Close() terminates the session). 

   147 	

   148 	* @param aControl reference to a MUpperControl implementation, which will 

   149 	* serve as the call-back interface for incoming control calls

   150 	* @param aData - reference to a MUpperDataReceiver implementation, which

   151 	* will serve as the call-back interface for incoming data

   152 	* @param aBcaParams A reference to the BCA start up params

   153 	* @return KErrNone if successful, system-wide error code otherwise. All 

   154 	* other error codes reported are fatal denoting that MBca interface has 

   155 	* failed to open and MBca is not good for transferring data

   156 	*/

   157 	virtual TInt Open(MUpperControl& aControl, 

   158 					MUpperDataReceiver& aData, 

   159 					const TBcaParams& aBcaParams)=0;

   160 	

   161 	/**

   162 	 * The API starts the baseband connection asynchronously. The Start () request 

   163 	 * API’s successful completion is acknowledged with MUpperControl::StartSending(). 

   164 	 * The request failure is acknowledged with MUpperControl::Error(). Client should 

   165 	 * take care of scenarios when MUpperControl::StartSending() gets very delayed 

   166 	 * or not called at all

   167  	

   168 	* @param none

   169 	* @return none

   170 	*/

   171 	virtual void Start()=0;

   172 	

   173 	/**

   174 	 * Returns a reference to the MLowerDataSender, This reference is used by 

   175 	 * upper components to send packets to the lower components. This API must be 

   176 	 * called only after Start() completes, otherwise the implementation should panic.

   177  	

   178 	* @param none

   179 	* @return reference to the MLowerDataSender. 

   180 	*/

   181 	virtual MLowerDataSender& GetSender()=0;

   182 	

   183 	/**

   184 	* Synchronously closes the BCA immediately. Informs the BCA is no longer 

   185 	* required by the client and can release its resources. Close cancels all 

   186 	* pending asynchronous operations which can only be ::Start() or ::Control() .

   187 	* To use the BCA instance it needs to be re-opened. Close operation must not fail.

   188 	

   189 	* @param none

   190 	* @return none.

   191 	*/

   192 	virtual void Close()=0;

   193 	

   194 	/**

   195 	* Release/deletes the BCA instance. Derived classes will typically implement 

   196 	* this as ‘delete this’.

   197 	

   198 	* @param none

   199 	* @return none.

   200 	*/

   201 	virtual void Release()=0;

   202 	

   203 	enum TBlockOption

   204 		{

   205 			//stop sending [block] data on interface

   206 			EBlockFlow, 

   207 			// start sending [unblock] data on interface

   208 			EUnblockFlow

   209 		};

   210 	/**

   211 	* Either blocks or unblocks the pushing of received data to the upper layers, 

   212 	* depending on TBlockOption. If the upper layers can’t process any more

   213 	* data to stop receiving packets this API is called with EBlockFlow. 

   214 	* Later after the congestion eases, to start receiving packets again call 

   215 	* this API with EUnblockFlow

   216 	

   217 	* @param aOption either block or unblock receive flow

   218 	* @return none.

   219 	*/

   220 	virtual void SetFlowControl(TBlockOption aOption)=0;

   221 

   222 	/**

   223 	* The BCA control function to get or set the options of the BCA in an 

   224 	* asynchronous manner.

   225 	

   226 	* @param aStatus  asynchronous completion status, KErrNone if successful, 

   227          * system-wide error code otherwise

   228 	* @param aOptLevel option level to be used KBcaOptLevelGeneric 

   229 	* or KBcaOptLevelExtSerial

   230 	* @param aOptName option name to be used.

   231 	* @param aOpt an optional parameter,holds the option value on return or the

   232 	* option value to be set.

   233 	* @return none.

   234 	*/

   235 	virtual void Control(TRequestStatus& aStatus,

   236 							TUint aOptLevel,

   237 							TUint aOptName,

   238 							TDes8& aOpt)=0;

   239 

   240 	/**

   241 	* Cancels the Control request in a synchronous way.

   242 	

   243 	* @param none

   244 	* @return none.

   245 	*/

   246 	virtual void CancelControl()=0;

   247 	};

   248 

   249 /**

   250 * Control option level.

   251 */

   252 const TUint KBcaOptLevelGeneric 		= 0x0194;

   253 const TUint KBcaOptLevelExtSerial 		= 0x0195;

   254 

   255 /**

   256 * C32 BCA capability

   257 */

   258 const TUint KBcaCapSerial			= 0x01; //Serial port capability supported

   259 

   260 /**

   261 * Generic Control option name

   262 */

   263 const TUint KBCAMru	                = 0x12;

   264 const TUint KBCAMtu	                = 0x13;

   265 const TUint KBCASpeedMetric	        = 0x14;

   266 const TUint KBCACaps	            = 0x15;

   267 const TUint KBCASetIapId	        = 0x16;

   268 const TUint KBCASetBcaStack	        = 0x1e;

   269 const TUint KVersionNumber	        = 0x1c;

   270 /** 

   271 Purges the buffers */

   272 const TUint KBCAResetBuffers        = 0x1f;

   273 

   274 /**

   275 * Serial Control option name

   276 */

   277 const TUint KSerialCaps	            = 0x17;

   278 const TUint KSerialConfig	        = 0x18;

   279 const TUint KSerialSetConfig	    = 0x1a;

   280 const TUint KSerialPortName	        = 0x19;

   281 const TUint KSerialSetCsyName	    = 0x1b;

   282 const TUint KSerialSetCommRole	    = 0x1d;

   283 

   284 /**

   285 Set the size of receive & transmit buffers.

   286 Provided for compatibility with C32 RComm */

   287 const TUint KSerialSetTxRxBufferSize  = 0x2a;

   288 

   289 /** Retrieves the size of the receive & transmit buffers */

   290 const TUint KSerialTxRxBufferSize     = 0x2b;

   291 

   292 /** Set and/or clear signal lines */

   293 const TUint KSerialSetControlLines	  = 0x2c;

   294 

   295 struct TSerialSetControlLines {

   296 /**

   297 Structure associated with KSerialSetSignals control.

   298 Indicates which control lines to set/clear. 

   299 */

   300 	TUint	iSetMask;

   301 	TUint	iClearMask;

   302 };

   303 

   304 //

   305 // Bitmasks specifying which buffer to reset. Used with KBCaResetBuffers

   306 //

   307 

   308 /** Reset Rx buffer only */

   309 const TUint KResetRxBuf = 0x01;

   310 

   311 /** Reset Tx buffer only */

   312 const TUint KResetTxBuf = 0x02;

   313 

   314 

   315 /** Monitor EIA-232 control lines and take action specified. */

   316 const TUint KSerialMonitorControlLines = 0x30;

   317 

   318 /** Turn control line monitoring off - do not fail on line change */

   319 const TUint KMonitorOff = 0x0;

   320 

   321 /** Fail when BCA-specific lines go from high to low. 

   322 This is the "Default" option, where the BCA itself selects what lines to monitor 

   323 This mask must not be specified in conjunction with other masks, as the BCA will monitor

   324 & fail on its specific lines ONLY. The other lines will be ignored.*/

   325 const TUint KFailBcaSpecificOnly = 0xFFFFFFFF; 

   326 }

   327 

   328 #endif // BCA2_H