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  @released

    28 */

    29  

    30 #ifndef BCA_H

    31 #define BCA_H

    32 

    33 #include <e32std.h>

    34 #include <e32des8.h>

    35 

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

    37 namespace BasebandChannelAdaptation

    38 {

    39 

    40 /** 

    41 * The abstract interface between NIF and Bearer Transport. 

    42 * The client (caller) of MBca is the one conceptually living in a specific Comms Stack layer 

    43 * and it is entirely responsible for implementing the function of that layer as imposed by the 

    44 * respective protocol technology. On the contrary, the MBca is merely a HAI (Hardware Abstraction 

    45 * Interface) and its implementation is protocol/technology agnostic. This means that the MBca 

    46 * is solely responsible for passing (entire) data frames between its caller and the bearer transport 

    47 * as well as for propagating error conditions towards the client and for propagating flow 

    48 * control conditions in both directions. 

    49 *

    50 * @publishedPartner 

    51 * @released 

    52 */ 

    53 class MBca

    54 

    55 	{

    56 public:

    57 	

    58 	/** 

    59 	* Deletes the allocated data in BCA the MBca implementation and all resources it owns. 

    60 	* The method is the logical reverse operation to MBcaFactory::NewBcaL()

    61 	*/

    62 	virtual void Release()=0;

    63 

    64 	/** 

    65 	* Informs that the BCA is required by the client(for instance, Raw IP NIF)

    66 	*

    67 	* @param aStatus complete status, KErrNone if succesful, system-wide error code otherwise.

    68 	* All other error codes reported are fatal (denoting the MBca interface has failed to open 

    69 	* and is not good for transferring data) including KErrCancel if request cancelled.

    70 	*

    71 	* @param aChannelId an optional parameter, used to open the BCA. It is implementation dependent, 

    72 	* It can be empty descriptor when it is not used. 

    73 	*/ 

    74 	virtual void Open(TRequestStatus& aStatus, const TDesC& aChannelId)=0;

    75 

    76 	

    77 	/** 

    78 	* Close is a "emergency"/synchronous termination which closes the BCA immediately. 

    79 	* Informs the BCA is no longer required by the client. 

    80 	* The method is the logical reverse operation to ::Open(). 

    81 	* Close cancels all pending asynchronous requests with KErrCancel.

    82 	*/ 

    83 	virtual void Close()=0;

    84 		

    85 

    86 	/** 

    87 	* Shutdown is a graceful, asynchronous termination which can take some time. It is called under 

    88 	* normal stop cases. 

    89 	* Informs the BCA is no longer required by the client and can release its resources. 

    90 	* The method is the logical reverse operation to ::Open().

    91 	* Shutdown cancels all other pending asynchronous requests with KErrCancel.

    92 	*

    93 	* @param aStatus complete status, KErrNone if succesful KErrCancel if request cancelled.

    94 	*/ 

    95 	virtual void Shutdown(TRequestStatus& aStatus)=0;

    96 

    97 

    98 	/**

    99 	* Queues a Read, reads data from underlying baseband channel. 

   100 	* Used for for uplink flow control, i.e. the client will refrain from calling MBca::Read if 

   101 	* in a flow off condition.

   102 	*

   103 	* @param aStatus complete status, KErrNone if succesful, system-wide error code otherwise.

   104 	* All other errors reported are fatal (the MBca became defunct and can no loger be used to 

   105 	* send and receive data) except KErrCancel if request cancelled and KErrNoMemory, KErrCommsParity, 

   106 	* KErrCommsOverrun, KErrCommsFrame, in which case the MBca stays functional and is only reporting 

   107 	* failure to read the next frame. The caller may attempt to ::Read again. 

   108 	*

   109 	* @param aBuf buffer for data to be read. The caller owns the buffer and is responsible for keeping 

   110 	* its reference valid at least until the MBca::Read call is completed. The caller is responsible 

   111 	* for supplying a large enough buffer for the MBca implementation to fit the entire pending frame. 

   112 	* If the caller fails to supply a large enough buffer, the MBca implementation is free to error the 

   113 	* ::Read with KErrNoMemory.

   114 	*

   115 	* @note the client must not modify the buffer until this call is completed. 

   116 	*/ 

   117 	virtual void Read(TRequestStatus& aStatus, TDes8& aBuf)=0;

   118 	

   119 

   120 	/** 

   121 	* Queues a Write, write data to underlying baseband channel. 

   122 	* Used for downlink flow control. The MBca implementation will not complete a pending ::Write if 

   123 	* in flow off condition. 

   124 	*	

   125 	* @param aStatus the complete status, KErrNone if succesful, system-wide error code otherwise. 

   126 	* All errors reported are fatal (the MBca became defunct and can no loger be used to 

   127 	* send and receive data) except KErrCancel if request cancelled and KErrNoMemory and KErrNotReady,

   128 	* in which case the MBca implementation indicates the failure to send the current frame. The caller 

   129 	* may drop or resend the current packet depending on its logic. 

   130 	*

   131 	* @param aBuf the buffer to sent. The caller owns the buffer and is responsible for keeping 

   132 	* its reference valid at least until the MBca::Write call is completed.

   133 	*

   134 	* @note the client must not modify the buffer until this call is completed.

   135 	*/

   136 	virtual void Write(TRequestStatus& aStatus, const TDesC8& aBuf)=0;

   137 	

   138 

   139 	/** 

   140 	* Cancels the pending read request with KErrCancel.

   141 	*/ 

   142 	virtual void CancelRead()=0;

   143 

   144 

   145 	/** 

   146 	* Cancels the pending write request with KErrCancel.

   147 	*/

   148 	virtual void CancelWrite()=0;

   149 	

   150 

   151 	/** 

   152 	* The BCA control function,gets or sets the information of the BCA in an asynchronous manner.

   153 	*

   154 	* @param aStatus complete status, KErrNone if succesful, system-wide error code otherwise.

   155 	* All errors reported are fatal (the MBca became defunct and can no loger be used to 

   156 	* send and receive data) except KErrNotSupported, no functionality provided and KErrAlreadyExists.

   157 	*

   158 	* @param aOptLevel option level to be used. 

   159 	*

   160 	* @param aOptName option name to be used. 

   161 	*

   162 	* @param aOpt an optional parameter,holds the option value on return or the option value to be set. 

   163 	*

   164 	* @return none. 

   165 	*/ 

   166 	virtual void Ioctl(TRequestStatus& aStatus, TUint aOptLevel, TUint aOptName, TDes8& aOpt)=0;

   167 

   168 	

   169 	/**

   170 	* Cancels the pending Ioctl request with KErrCancel.

   171 	*/

   172 	virtual void CancelIoctl()=0;

   173 	};

   174 	

   175 

   176 /**

   177 * Control option level.

   178 */

   179 const TUint KBcaOptLevelGeneric 		= 0x0194;

   180 const TUint KBcaOptLevelExtSerial 		= 0x0195;

   181 

   182 /**

   183 * C32 BCA capability

   184 */

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

   186 

   187 /**

   188 * Control option name

   189 */

   190 const TUint KBCAMru	                = 0x12;

   191 const TUint KBCAMtu	                = 0x13;

   192 const TUint KBCASpeedMetric	        = 0x14;

   193 const TUint KBCACaps	            = 0x15;

   194 const TUint KBCASetIapId	        = 0x16;

   195 const TUint KBCASetBcaStack	        = 0x1e;

   196 

   197 /** 

   198 Purges the buffers */

   199 const TUint KBCAResetBuffers        = 0x1f;

   200 

   201 const TUint KSerialCaps	            = 0x17;

   202 const TUint KSerialConfig	        = 0x18;

   203 const TUint KSerialPortName	        = 0x19;

   204 const TUint KSerialSetConfig	    = 0x1a;

   205 const TUint KSerialSetCsyName	    = 0x1b;

   206 const TUint KVersionNumber	        = 0x1c;

   207 const TUint KSerialSetCommRole	    = 0x1d;

   208 

   209 /**

   210 Set the size of receive & transmit buffers.

   211 Provided for compatibility with C32 RComm */

   212 const TUint KSerialSetTxRxBufferSize  = 0x2a;

   213 

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

   215 const TUint KSerialTxRxBufferSize     = 0x2b;

   216 

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

   218 const TUint KSerialSetControlLines	  = 0x2c;

   219 

   220 struct TSerialSetControlLines {

   221 /**

   222 Structure associated with KSerialSetSignals Ioctl.

   223 Indicates which control lines to set/clear. 

   224 */

   225 	TUint	iSetMask;

   226 	TUint	iClearMask;

   227 };

   228 

   229 //

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

   231 //

   232 

   233 /** Reset Rx buffer only */

   234 const TUint KResetRxBuf = 0x01;

   235 

   236 /** Reset Tx buffer only */

   237 const TUint KResetTxBuf = 0x02;

   238 

   239 

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

   241 const TUint KSerialMonitorControlLines = 0x30;

   242 

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

   244 const TUint KMonitorOff = 0x0;

   245 

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

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

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

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

   250 const TUint KFailBcaSpecificOnly = 0xFFFFFFFF; 

   251 }

   252 

   253 #endif // BCA_H