--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/basebandabstraction/basebandchanneladaptor/Inc/Bca.h Tue Feb 02 01:41:59 2010 +0200
@@ -0,0 +1,253 @@
+
+/**
+* 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
+ @released
+*/
+
+#ifndef BCA_H
+#define BCA_H
+
+#include <e32std.h>
+#include <e32des8.h>
+
+/** This namespace includes the BCA component names.*/
+namespace BasebandChannelAdaptation
+{
+
+/**
+* The abstract interface between NIF and Bearer Transport.
+* The client (caller) of MBca is the one conceptually living in a specific Comms Stack layer
+* and it is entirely responsible for implementing the function of that layer as imposed by the
+* respective protocol technology. On the contrary, the MBca is merely a HAI (Hardware Abstraction
+* Interface) and its implementation is protocol/technology agnostic. This means that the MBca
+* is solely responsible for passing (entire) data frames between its caller and the bearer transport
+* as well as for propagating error conditions towards the client and for propagating flow
+* control conditions in both directions.
+*
+* @publishedPartner
+* @released
+*/
+class MBca
+
+ {
+public:
+
+ /**
+ * Deletes the allocated data in BCA the MBca implementation and all resources it owns.
+ * The method is the logical reverse operation to MBcaFactory::NewBcaL()
+ */
+ virtual void Release()=0;
+
+ /**
+ * Informs that the BCA is required by the client(for instance, Raw IP NIF)
+ *
+ * @param aStatus complete status, KErrNone if succesful, system-wide error code otherwise.
+ * All other error codes reported are fatal (denoting the MBca interface has failed to open
+ * and is not good for transferring data) including KErrCancel if request cancelled.
+ *
+ * @param aChannelId an optional parameter, used to open the BCA. It is implementation dependent,
+ * It can be empty descriptor when it is not used.
+ */
+ virtual void Open(TRequestStatus& aStatus, const TDesC& aChannelId)=0;
+
+
+ /**
+ * Close is a "emergency"/synchronous termination which closes the BCA immediately.
+ * Informs the BCA is no longer required by the client.
+ * The method is the logical reverse operation to ::Open().
+ * Close cancels all pending asynchronous requests with KErrCancel.
+ */
+ virtual void Close()=0;
+
+
+ /**
+ * Shutdown is a graceful, asynchronous termination which can take some time. It is called under
+ * normal stop cases.
+ * Informs the BCA is no longer required by the client and can release its resources.
+ * The method is the logical reverse operation to ::Open().
+ * Shutdown cancels all other pending asynchronous requests with KErrCancel.
+ *
+ * @param aStatus complete status, KErrNone if succesful KErrCancel if request cancelled.
+ */
+ virtual void Shutdown(TRequestStatus& aStatus)=0;
+
+
+ /**
+ * Queues a Read, reads data from underlying baseband channel.
+ * Used for for uplink flow control, i.e. the client will refrain from calling MBca::Read if
+ * in a flow off condition.
+ *
+ * @param aStatus complete status, KErrNone if succesful, system-wide error code otherwise.
+ * All other errors reported are fatal (the MBca became defunct and can no loger be used to
+ * send and receive data) except KErrCancel if request cancelled and KErrNoMemory, KErrCommsParity,
+ * KErrCommsOverrun, KErrCommsFrame, in which case the MBca stays functional and is only reporting
+ * failure to read the next frame. The caller may attempt to ::Read again.
+ *
+ * @param aBuf buffer for data to be read. The caller owns the buffer and is responsible for keeping
+ * its reference valid at least until the MBca::Read call is completed. The caller is responsible
+ * for supplying a large enough buffer for the MBca implementation to fit the entire pending frame.
+ * If the caller fails to supply a large enough buffer, the MBca implementation is free to error the
+ * ::Read with KErrNoMemory.
+ *
+ * @note the client must not modify the buffer until this call is completed.
+ */
+ virtual void Read(TRequestStatus& aStatus, TDes8& aBuf)=0;
+
+
+ /**
+ * Queues a Write, write data to underlying baseband channel.
+ * Used for downlink flow control. The MBca implementation will not complete a pending ::Write if
+ * in flow off condition.
+ *
+ * @param aStatus the complete status, KErrNone if succesful, system-wide error code otherwise.
+ * All errors reported are fatal (the MBca became defunct and can no loger be used to
+ * send and receive data) except KErrCancel if request cancelled and KErrNoMemory and KErrNotReady,
+ * in which case the MBca implementation indicates the failure to send the current frame. The caller
+ * may drop or resend the current packet depending on its logic.
+ *
+ * @param aBuf the buffer to sent. The caller owns the buffer and is responsible for keeping
+ * its reference valid at least until the MBca::Write call is completed.
+ *
+ * @note the client must not modify the buffer until this call is completed.
+ */
+ virtual void Write(TRequestStatus& aStatus, const TDesC8& aBuf)=0;
+
+
+ /**
+ * Cancels the pending read request with KErrCancel.
+ */
+ virtual void CancelRead()=0;
+
+
+ /**
+ * Cancels the pending write request with KErrCancel.
+ */
+ virtual void CancelWrite()=0;
+
+
+ /**
+ * The BCA control function,gets or sets the information of the BCA in an asynchronous manner.
+ *
+ * @param aStatus complete status, KErrNone if succesful, system-wide error code otherwise.
+ * All errors reported are fatal (the MBca became defunct and can no loger be used to
+ * send and receive data) except KErrNotSupported, no functionality provided and KErrAlreadyExists.
+ *
+ * @param aOptLevel option level to be used.
+ *
+ * @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 Ioctl(TRequestStatus& aStatus, TUint aOptLevel, TUint aOptName, TDes8& aOpt)=0;
+
+
+ /**
+ * Cancels the pending Ioctl request with KErrCancel.
+ */
+ virtual void CancelIoctl()=0;
+ };
+
+
+/**
+* Control option level.
+*/
+const TUint KBcaOptLevelGeneric = 0x0194;
+const TUint KBcaOptLevelExtSerial = 0x0195;
+
+/**
+* C32 BCA capability
+*/
+const TUint KBcaCapSerial = 0x01; //Serial port capability supported
+
+/**
+* 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;
+
+/**
+Purges the buffers */
+const TUint KBCAResetBuffers = 0x1f;
+
+const TUint KSerialCaps = 0x17;
+const TUint KSerialConfig = 0x18;
+const TUint KSerialPortName = 0x19;
+const TUint KSerialSetConfig = 0x1a;
+const TUint KSerialSetCsyName = 0x1b;
+const TUint KVersionNumber = 0x1c;
+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 Ioctl.
+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 // BCA_H