diff -r 4a8d14a1a8ca -r ab1d0f4d2aa4 Telephony/basebandabstraction/basebandchanneladaptor/inc/bca2.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Telephony/basebandabstraction/basebandchanneladaptor/inc/bca2.h Thu Aug 12 13:20:01 2010 +0100 @@ -0,0 +1,328 @@ + +/** +* Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* Baseband Channel Adaptor(BCA) APIs. +* This file contains all the APIs required to implement a BCA interface for Symbian OS. +* +* +*/ + + + +/** + @file + @publishedPartner + @prototype + @released +*/ +#ifndef BCA2_H +#define BCA2_H + +/** This namespace includes the BCA component names.*/ +namespace BasebandChannelAdaptation2 +{ +/** + * The class implemented by an upper component to accept control signals from the lower component + + * @publishedPartner + * @prototype + */ +class MUpperControl + { +public: + /** + * Indicates to the layer above (link layer) that the Bca is ready to start + * receiving packets from the upper layer (either after MBca start + * completes or following congestion) + + * @param none + * @return none. + */ + virtual void StartSending()=0; + + /** + * Any fatal error which occurs during the send/receive session is reported + * to the client by a call to this function. Fatal errors are errors which can’t + * be recovered from (e.g.: connection down) in which case MBca has become + * defunct and can no longer be used to send and receive data + + * @param aErr TThe fatal error code from the session failures propagated + * to the upper layer of the communications stack . Non fatal errors keep + * the MBca2 functional which in the context of MBca2 implementation may + * include KErrNoMemory, KErrCommsParity, KErrCommsOverrun, KErrCommsFrame. + * @return none. + */ + virtual void Error(TInt aErr)=0; + + }; + +/** + * The Class implemented by an upper component to accept inbound data travelling + * upwards from the lower component + + * @publishedPartner + * @prototype + */ +class MUpperDataReceiver + { +public: + /** + * This function is called whenever data has been received by MBca which + * should be processed by its client. The implementer takes ownership of the + * buffer and is responsible for its deletion. + + * @param aCommsBufChain - The list of comms buffers containing data to be processed. + * Destination keeps the custody of the buffer. + * @return none. + */ + virtual void Process(RCommsBufChain& aCommsBufChain)=0; + }; + +/** + * The interface implemented by the lower component to accept data from the upper component + + * @publishedPartner + * @prototype + */ + +class MLowerDataSender + { + public: + enum TSendResult + { + // data accepted, send no more until MUpperControl::StartSending() is called + ESendBlocked, + // data accepted, can send more. + ESendAccepted + }; + /** + * Sends the specified buffer data down to the base-band. The implementer takes + * ownership of the buffer and is responsible for its deletion. + + * @param aCommsBufChain the comms buffer list to be sent.The buffer ownership is passed + * to the BCA + * @return TTSendResult either ESendBlocked or SendAccepted. When the Bca + * is congested and cannot send any data beyond the current packet (which is + * always accepted), the implementation returns ESendBlocked. If BCA is not + * congested then ESendAccepted is returned to continue sending. When congestion + * passes, the Bca calls StartSending on the upper layer to resume sending. The + * implementation is recommended to panic any attempts to call Send during congestion + */ + virtual TSendResult Send(RCommsBufChain& aCommsBufChain)=0; + }; + +/** + * The interface implemented by the lower component to accept control signals from the upper component + + * @publishedPartner + * @prototype + */ +class MBca2 + { +public: + struct TBcaParams + { + RCommsBufPond iCommsBufPond; // Pond to be used by BCA implementation for creating, using pools and buffers + const TDesC& iChannelId; // port number or channel which BCA uses to communicate with its lower layers + TBcaParams(RCommsBufPond aCommsBufPond,const TDesC& aChannelId) + : iCommsBufPond(aCommsBufPond), + iChannelId(aChannelId){} + }; + + + /** + * Opens the BCA instance and commences a BCA session (::Close() terminates the session). + + * @param aControl reference to a MUpperControl implementation, which will + * serve as the call-back interface for incoming control calls + * @param aData - reference to a MUpperDataReceiver implementation, which + * will serve as the call-back interface for incoming data + * @param aBcaParams A reference to the BCA start up params + * @return KErrNone if successful, system-wide error code otherwise. All + * other error codes reported are fatal denoting that MBca interface has + * failed to open and MBca is not good for transferring data + */ + virtual TInt Open(MUpperControl& aControl, + MUpperDataReceiver& aData, + const TBcaParams& aBcaParams)=0; + + /** + * The API starts the baseband connection asynchronously. The Start () request + * API’s successful completion is acknowledged with MUpperControl::StartSending(). + * The request failure is acknowledged with MUpperControl::Error(). Client should + * take care of scenarios when MUpperControl::StartSending() gets very delayed + * or not called at all + + * @param none + * @return none + */ + virtual void Start()=0; + + /** + * Returns a reference to the MLowerDataSender, This reference is used by + * upper components to send packets to the lower components. This API must be + * called only after Start() completes, otherwise the implementation should panic. + + * @param none + * @return reference to the MLowerDataSender. + */ + virtual MLowerDataSender& GetSender()=0; + + /** + * Synchronously closes the BCA immediately. Informs the BCA is no longer + * required by the client and can release its resources. Close cancels all + * pending asynchronous operations which can only be ::Start() or ::Control() . + * To use the BCA instance it needs to be re-opened. Close operation must not fail. + + * @param none + * @return none. + */ + virtual void Close()=0; + + /** + * Release/deletes the BCA instance. Derived classes will typically implement + * this as ‘delete this’. + + * @param none + * @return none. + */ + virtual void Release()=0; + + enum TBlockOption + { + //stop sending [block] data on interface + EBlockFlow, + // start sending [unblock] data on interface + EUnblockFlow + }; + /** + * Either blocks or unblocks the pushing of received data to the upper layers, + * depending on TBlockOption. If the upper layers can’t process any more + * data to stop receiving packets this API is called with EBlockFlow. + * Later after the congestion eases, to start receiving packets again call + * this API with EUnblockFlow + + * @param aOption either block or unblock receive flow + * @return none. + */ + virtual void SetFlowControl(TBlockOption aOption)=0; + + /** + * The BCA control function to get or set the options of the BCA in an + * asynchronous manner. + + * @param aStatus asynchronous completion status, KErrNone if successful, + * system-wide error code otherwise + * @param aOptLevel option level to be used KBcaOptLevelGeneric + * or KBcaOptLevelExtSerial + * @param aOptName option name to be used. + * @param aOpt an optional parameter,holds the option value on return or the + * option value to be set. + * @return none. + */ + virtual void Control(TRequestStatus& aStatus, + TUint aOptLevel, + TUint aOptName, + TDes8& aOpt)=0; + + /** + * Cancels the Control request in a synchronous way. + + * @param none + * @return none. + */ + virtual void CancelControl()=0; + }; + +/** +* Control option level. +*/ +const TUint KBcaOptLevelGeneric = 0x0194; +const TUint KBcaOptLevelExtSerial = 0x0195; + +/** +* C32 BCA capability +*/ +const TUint KBcaCapSerial = 0x01; //Serial port capability supported + +/** +* Generic Control option name +*/ +const TUint KBCAMru = 0x12; +const TUint KBCAMtu = 0x13; +const TUint KBCASpeedMetric = 0x14; +const TUint KBCACaps = 0x15; +const TUint KBCASetIapId = 0x16; +const TUint KBCASetBcaStack = 0x1e; +const TUint KVersionNumber = 0x1c; +/** +Purges the buffers */ +const TUint KBCAResetBuffers = 0x1f; + +/** +* Serial Control option name +*/ +const TUint KSerialCaps = 0x17; +const TUint KSerialConfig = 0x18; +const TUint KSerialSetConfig = 0x1a; +const TUint KSerialPortName = 0x19; +const TUint KSerialSetCsyName = 0x1b; +const TUint KSerialSetCommRole = 0x1d; + +/** +Set the size of receive & transmit buffers. +Provided for compatibility with C32 RComm */ +const TUint KSerialSetTxRxBufferSize = 0x2a; + +/** Retrieves the size of the receive & transmit buffers */ +const TUint KSerialTxRxBufferSize = 0x2b; + +/** Set and/or clear signal lines */ +const TUint KSerialSetControlLines = 0x2c; + +struct TSerialSetControlLines { +/** +Structure associated with KSerialSetSignals control. +Indicates which control lines to set/clear. +*/ + TUint iSetMask; + TUint iClearMask; +}; + +// +// Bitmasks specifying which buffer to reset. Used with KBCaResetBuffers +// + +/** Reset Rx buffer only */ +const TUint KResetRxBuf = 0x01; + +/** Reset Tx buffer only */ +const TUint KResetTxBuf = 0x02; + + +/** Monitor EIA-232 control lines and take action specified. */ +const TUint KSerialMonitorControlLines = 0x30; + +/** Turn control line monitoring off - do not fail on line change */ +const TUint KMonitorOff = 0x0; + +/** Fail when BCA-specific lines go from high to low. +This is the "Default" option, where the BCA itself selects what lines to monitor +This mask must not be specified in conjunction with other masks, as the BCA will monitor +& fail on its specific lines ONLY. The other lines will be ignored.*/ +const TUint KFailBcaSpecificOnly = 0xFFFFFFFF; +} + +#endif // BCA2_H