--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/linklayercontrol/networkinterfacemgr/inc/NIFIF.H Tue Jan 26 15:23:49 2010 +0200
@@ -0,0 +1,612 @@
+// Copyright (c) 1997-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:
+// Network interface (nif) APIs.
+// This file contains all the APIs required to implement a NIF for Symbian OS.
+//
+//
+
+/**
+ @file NIFIF.H
+ @publishedPartner
+ @released
+*/
+
+#if !defined(__NIFIF_H__)
+#define __NIFIF_H__
+
+#define SYMBIAN_NETWORKING_UPS
+
+#include <nifman.h>
+#include <comms-infras/nifprvar.h>
+#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
+#include <comms-infras/nifif_internal.h>
+#endif
+
+
+/**
+ The direction of data transfer
+ Currently used by network layers making the PacketActivity() call to specify
+ which direction the data was transferred in
+
+ Flags for use with the TNifIfInfo structure
+ @defgroup TNifIfInfoflags Flags for TNifIfInfo
+ @publishedPartner
+ @released
+ @since v5.0
+ */
+//@{
+const TUint KNifIfIsBase = 0x00000001; //< The object is CNifIfBase-derived (one per protocol, per nif)
+const TUint KNifIfIsLink = 0x00000002; //< The object is CNifIfLink-derived (one per nif)
+const TUint KNifIfUsesNotify = 0x00000004; //< The object uses the MNifIfNotify interface
+const TUint KNifIfCreatedByFactory = 0x00000008; //< The object was created by a call to CNifIfFactory
+const TUint KNifIfCreatedByLink = 0x00000010; //< The object was created by the link layer of the nif (and is usually a binder to a layer 3 protocol)
+const TUint KNifIfCreatedAlone = 0x00000020; //< The object was created using another mechanism
+ //< @note This is typically used for local loopback interfaces, where the interface is created by a means other than the nif factory object
+const TUint KNifIfCreatesBinder = 0x00000040; //< The object creates other objects to bind to a layer 3 protocol
+//@}
+
+
+enum TDataTransferDirection
+/**
+ * The direction of data transfer
+ * @par
+ * Currently used by network layers making the PacketActivity() call to specify which direction the data was transferred in
+ *
+ * @publishedPartner
+ * @released
+ * @since v7.0s
+ */
+ {
+ /** Sometime idle timers need to be reset without a packet arriving -
+ using this value allows packet counts to be maintained correctly */
+ ENoPacket,
+ EIncoming,
+ /** Leave a gap in case it is necessary to distinguish different sorts of incoming data in the future */
+ EOutgoing = 128
+ };
+
+
+// Interface classes
+
+class TNifIfInfo
+/**
+ * Structure used by a nif to pass information about this object in the nif to the caller.
+ * @note Accessed via the CNifIfBase::Info() call, and the CNifIfLink::Info() call, since it is a derived class
+ *
+ * @publishedPartner
+ * @released
+ * @since v5.0
+ */
+ {
+public:
+ TUint iProtocolSupported; //< The protocol supported by this object
+ //< @note Typically KProtocolInetIp or Inet6Ip for IP binders, K<protocol name>IdEsock for link layer protocols
+ TUint iFlags; //< Flags indicating the class type, reason for creation of this object, interfaces that it uses
+ //< @see TNifIfInfoflags
+ TVersion iVersion; //< The version of this object
+ TName iName; //< The "friendly" (for user display, logging) name of the nif
+ };
+
+class CNifIfBase;
+class MNifIfNotify;
+class CNifIfFactory : public CNifFactory
+/**
+ * The factory object used to create new instances of a nif.
+ * A nif is packaged in a dll - nifman will call this class to create new instances of a nif.
+ *
+ * @publishedPartner
+ * @released
+ * @since v5.0
+ */
+ {
+friend class CNifMan;
+protected:
+ /**
+ * Create a new instance of the nif contained within this DLL
+ * @param aName A protocol name supported by the nif
+ * @returns A CNifIfBase-derived object of the requested type
+ * @note The class returned should actually be a CNifIfLink-derived object
+ */
+ virtual CNifIfBase *NewInterfaceL(const TDesC& aName)=0;
+
+ /**
+ * Return information about modules within this nif
+ * @param aInfo On return, contains information about a module within the nif
+ * @param aIndex An index into CNifIfBase/CNifIfLink-derived objects in the nif, starting from 0. It is up to the nif how it assigns indices to objects.
+ * @returns KErrNone if successful; otherwise, one of the standard Symbian OS error codes
+ */
+ virtual TInt Info(TNifIfInfo& aInfo, TInt aIndex) const=0;
+
+ IMPORT_C virtual CNifIfBase *NewInterfaceL(const TDesC& aName, MNifIfNotify* aNotify);
+ };
+
+class MNifIfNotify
+/**
+ * Interface from the nif and the protocol layers to Nifman
+ * @publishedPartner
+ * @released
+ */
+ {
+public:
+ enum TAction
+ {
+ EReconnect,
+ ECallBack,
+ EDisconnect,
+ ENoAction
+ };
+
+public:
+ /**
+ * Notification from the nif that the link layer has gone down.
+ * @param aReason A Symbian OS error code indicating the reason for the link closing down
+ * @param aAction The action that should be taken as a result of link layer down being signalled
+ */
+ virtual void LinkLayerDown(TInt aReason, TAction aAction)=0;
+
+ /**
+ * Notification from the nif that the link layer is up
+ */
+ virtual void LinkLayerUp()=0;
+
+ /**
+ * Indicate that link negotiation failed on this nif to allow nifman to take appropriate action
+ * @param aIf The address of the CNifIfBase/Link object for which negotiation failed
+ * @param aReason An error code denoting the reason for failure
+ */
+ virtual void NegotiationFailed(CNifIfBase* aIf, TInt aReason)=0;
+
+ /**
+ * Request to the agent to return the data required for authentication
+ * @param aUsername On return, contains the username to be used for authentication
+ * @param aPassword On return, contains the password to be used for authentication
+ * @note The return values in aUsername and aPassword should not be considered valid until CNifIfLink::AuthenticateComplete() has been called
+ */
+ virtual TInt Authenticate(TDes& aUsername, TDes& aPassword)=0;
+
+ /**
+ * Request to the agent to cancel a pending authentication
+ */
+ virtual void CancelAuthenticate()=0;
+
+ /**
+ * Fetch any excess data from the agent that it received during connection setup
+ * @param aBuffer On return, the buffer contains the excess data from the agent
+ * @returns KErrNone, if successful; otherwise, one of the standard Symbian OS error codes
+ */
+ virtual TInt GetExcessData(TDes8& aBuffer)=0;
+ /**
+ * Upcall from the nif indicating that a new progress state has been reached on this connection
+ * @pre The stage value is within the range assigned to nifs i.e. KMinNifProgress <= aStage <= KMaxNifProgress
+ * @param aStage The progress stage that has been reached
+ * @param aError Any errors that have occured
+ * @since v5.0
+ */
+ virtual void IfProgress(TInt aStage, TInt aError)=0;
+
+ /**
+ * Upcall from the nif indicating that a new progress state has been reached on this subconnection
+ * @pre The stage value is within the range assigned to nifs i.e. KMinNifProgress <= aStage <= KMaxNifProgress
+ * @param aSubConnectionUniqueId The subconnection to which this notification refers
+ * @param aStage The progress stage that has been reached
+ * @param aError Any errors that have occured
+ * @since v7.0s
+ */
+ virtual void IfProgress(TSubConnectionUniqueId aSubConnectionUniqueId, TInt aStage, TInt aError)=0;
+
+ /**
+ * Increment the count of users of this nif
+ */
+ virtual void OpenRoute()=0;
+
+ /**
+ * Decrement the count of users of this nif
+ */
+ virtual void CloseRoute()=0;
+
+ /**
+ * Notification of an event from the nif
+ * @param aEvent The type of event that occured
+ * @param aInfo Any data associated with the event
+ * @returns KErrNone if successful, otherwise one of the system-wide error codes
+ * @note SC with previous releases broken in v6.1 when first argument changed type
+ */
+ virtual TInt Notification(TNifToAgentEventType aEvent, void * aInfo = NULL)=0;
+
+ /**
+ * Notification from the nif that a binder layer has gone down
+ * @param aBinderIf An identifier for the binder layer that went down
+ * @param aReason The reason for the binder layer failure
+ * @param aAction The action to be taken as a result, eg. disconnect, reconnect
+ * @since v7.0s
+ */
+ virtual void BinderLayerDown(CNifIfBase* aBinderIf, TInt aReason, TAction aAction)=0;
+
+ /**
+ * Indication from network layer that a packet has been transmitted or received
+ *
+ * @param aDirection Whether the packet was transmitted or received
+ * @param aBytes The size of the packet
+ * @param aResetTimer Whether the idle timer should be reset
+ * @returns KErrNone if successful, otherwise one of the system-wide error codes
+ * @since v7.0s
+ */
+ virtual TInt PacketActivity(TDataTransferDirection aDirection, TUint aBytes, TBool aResetTimer)=0;
+
+ /**
+ * Indication that the sent bytes threshold for a subconnection has been met or exceeded in the nif
+ *
+ * @param aSubConnectionUniqueId The subconnection to which this notification refers
+ * @param aUplinkVolume The total number of bytes sent by this subconnection
+ * @since v7.0s
+ */
+ virtual void NotifyDataSent(TSubConnectionUniqueId aSubConnectionUniqueId, TUint aUplinkVolume)=0;
+
+ /**
+ * Indication that the received bytes threshold for a subconnection has been met or exceeded in the nif
+ *
+ * @param aSubConnectionUniqueId The subconnection to which this notification refers
+ * @param aDownlinkVolume The total number of bytes sent by this subconnection
+ * @since v7.0s
+ */
+ virtual void NotifyDataReceived(TSubConnectionUniqueId aSubConnectionUniqueId, TUint aDownlinkVolume)=0;
+
+ /**
+ * Indication that some parameter relating to a subconnection has changed in the nif eg. subconnection closed, opened, QoS changed
+ *
+ * @param aEventType The type of event which has occured - used to direct the event notification to the appropriate component(s)
+ * @param aEvent The event which has occured
+ * @param aEventData Any arguments or additional data to do with the event; the interpretation of this depends on the event
+ * @param aSource An appropriate identifier of the source of the event - this will be used when one receiver is receiving events from many producers
+ * @since v7.0s
+ * @todo In the future, migrate GUQoS event handler and agent/nif notifications to this generic event handler - Nifman can then act as an event distributor
+ */
+ virtual void NifEvent(TNetworkAdaptorEventType aEventType, TUint aEvent, const TDesC8& aEventData, TAny* aSource=0)=0;
+
+
+
+ /**
+ * Read an integer field from the connection settings provider
+ * @param aField The name of the field to read
+ * @param aValue On return, contains the value of the field read
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ IMPORT_C TInt ReadInt( const TDesC& aField, TUint32& aValue, const RMessagePtr2* aMessage );
+ IMPORT_C TInt ReadInt( const TDesC& aField, TUint32& aValue );
+ /**
+ * Write an integer field to the connection settings provider
+ * @param aField The name of the field to which to write
+ * @param aValue The value to be written to the field
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ IMPORT_C TInt WriteInt( const TDesC& aField, TUint32 aValue, const RMessagePtr2* aMessage );
+ IMPORT_C TInt WriteInt( const TDesC& aField, TUint32 aValue );
+
+ /**
+ * Read a 8-bit descriptor field from the connection settings provider
+ * @param aField The name of the field to read
+ * @param aValue On return, contains the value of the field read
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ IMPORT_C TInt ReadDes( const TDesC& aField, TDes8& aValue, const RMessagePtr2* aMessage );
+ IMPORT_C TInt ReadDes( const TDesC& aField, TDes8& aValue );
+
+ /**
+ * Write an 8-bit descriptor field to the connection settings provider
+ * @param aField The name of the field to which to write
+ * @param aValue The value to be written to the field
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ IMPORT_C TInt WriteDes( const TDesC& aField, const TDesC8& aValue, const RMessagePtr2* aMessage );
+ IMPORT_C TInt WriteDes( const TDesC& aField, const TDesC8& aValue );
+
+ /**
+ * Read a 16-bit descriptor field from the connection settings provider
+ * @param aField The name of the field to read
+ * @param aValue On return, contains the value of the field read
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ IMPORT_C TInt ReadDes( const TDesC& aField, TDes16& aValue, const RMessagePtr2* aMessage );
+ IMPORT_C TInt ReadDes( const TDesC& aField, TDes16& aValue );
+
+ /**
+ * Write an 16-bit descriptor field to the connection settings provider
+ * @param aField The name of the field to which to write
+ * @param aValue The value to be written to the field
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ IMPORT_C TInt WriteDes( const TDesC& aField, const TDesC16& aValue, const RMessagePtr2* aMessage );
+ IMPORT_C TInt WriteDes( const TDesC& aField, const TDesC16& aValue );
+
+ /**
+ * Read an boolean field from the connection settings provider
+ * @param aField The name of the field to read
+ * @param aValue On return, contains the value of the field read
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ IMPORT_C TInt ReadBool( const TDesC& aField, TBool& aValue, const RMessagePtr2* aMessage );
+ IMPORT_C TInt ReadBool( const TDesC& aField, TBool& aValue );
+
+ /**
+ * Write an boolean field to the connection settings provider
+ * @param aField The name of the field to which to write
+ * @param aValue The value to be written to the field
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ IMPORT_C TInt WriteBool( const TDesC& aField, TBool aValue, const RMessagePtr2* aMessage );
+ IMPORT_C TInt WriteBool( const TDesC& aField, TBool aValue );
+
+protected:
+ /**
+ * Read an integer field from the connection settings provider
+ * @param aField The name of the field to read
+ * @param aValue On return, contains the value of the field read
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ virtual TInt DoReadInt(const TDesC& aField, TUint32& aValue,const RMessagePtr2* aMessage)=0;
+
+ /**
+ * Write an integer field to the connection settings provider
+ * @param aField The name of the field to which to write
+ * @param aValue The value to be written to the field
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ virtual TInt DoWriteInt(const TDesC& aField, TUint32 aValue,const RMessagePtr2* aMessage)=0;
+
+ /**
+ * Read a 8-bit descriptor field from the connection settings provider
+ * @param aField The name of the field to read
+ * @param aValue On return, contains the value of the field read
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ virtual TInt DoReadDes(const TDesC& aField, TDes8& aValue,const RMessagePtr2* aMessage)=0;
+
+ /**
+ * Read a 16-bit descriptor field from the connection settings provider
+ * @param aField The name of the field to read
+ * @param aValue On return, contains the value of the field read
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ virtual TInt DoReadDes(const TDesC& aField, TDes16& aValue,const RMessagePtr2* aMessage)=0;
+
+ /**
+ * Write an 8-bit descriptor field to the connection settings provider
+ * @param aField The name of the field to which to write
+ * @param aValue The value to be written to the field
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ virtual TInt DoWriteDes(const TDesC& aField, const TDesC8& aValue,const RMessagePtr2* aMessage)=0;
+
+ /**
+ * Write an 16-bit descriptor field to the connection settings provider
+ * @param aField The name of the field to which to write
+ * @param aValue The value to be written to the field
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ virtual TInt DoWriteDes(const TDesC& aField, const TDesC16& aValue,const RMessagePtr2* aMessage)=0;
+
+ /**
+ * Read an boolean field from the connection settings provider
+ * @param aField The name of the field to read
+ * @param aValue On return, contains the value of the field read
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ virtual TInt DoReadBool(const TDesC& aField, TBool& aValue,const RMessagePtr2* aMessage)=0;
+
+ /**
+ * Write an boolean field to the connection settings provider
+ * @param aField The name of the field to which to write
+ * @param aValue The value to be written to the field
+ * @param aMessage for capability checking
+ * @returns KErrNone, if successful; otherwise one of the standard Symbian OS error codes
+ */
+ virtual TInt DoWriteBool(const TDesC& aField, TBool aValue,const RMessagePtr2* aMessage)=0;
+
+
+ };
+
+class CNifAgentRef;
+class CNifIfLink;
+class CNifIfBase : public CBase
+/**
+ * Base class for nif binder layers.
+ * Classes derived from CNifIfBase act as a binder layer to the layer 3 protocol, and send and receive a specified protocol between the network layer and the link layer
+ * @note There should be one CNifIfBase object per protocol, per nif instance
+ *
+ * @publishedPartner
+ * @released
+ * @since v5.0
+ */
+ {
+friend class CNifMan;
+public:
+ IMPORT_C CNifIfBase(CNifIfFactory& aFactory);
+ IMPORT_C CNifIfBase();
+ IMPORT_C ~CNifIfBase();
+ IMPORT_C static void Cleanup(TAny* aIf);
+ IMPORT_C virtual void Open();
+ IMPORT_C virtual void Close();
+ IMPORT_C virtual void BindL(TAny *aId);
+ IMPORT_C virtual TInt State();
+ IMPORT_C virtual TInt Control(TUint aLevel,TUint aName,TDes8& aOption, TAny* aSource=0);
+
+ /**
+ * Retrieve information about an network interface
+ * @param aInfo On return, contains information about the nif
+ */
+ virtual void Info(TNifIfInfo& aInfo) const =0;
+
+ /**
+ * Send data through this interface
+ * @param aPdu A packet contained within a RMBufChain
+ * @param aSource A pointer to the object that is sending this data
+ * @returns -ve number Reserved for future use
+ * 0 Stop sending
+ * +ve number Continue sending
+ */
+ virtual TInt Send(RMBufChain& aPdu, TAny* aSource=0)=0;
+
+ /**
+ * Notification of an event from the agent
+ * @param aEvent The type of event that occured
+ * @param aInfo Any data associated with the event
+ * @returns KErrNone if successful, otherwise one of the system-wide error codes
+ * @note SC with previous releases broken in v6.1 when first argument changed type
+ * @since
+ */
+ virtual TInt Notification(TAgentToNifEventType aEvent, void * aInfo)=0;
+
+ inline MNifIfNotify* Notify() const;
+
+protected:
+ IMPORT_C CNifIfBase(CNifIfLink& aLink);
+ TInt iRefCount;
+ CNifIfFactory* iFactory;
+ MNifIfNotify* iNotify;
+ };
+
+class CNifIfLink : public CNifIfBase
+/**
+ * Interface between nifman and the nif
+ * This interface is used by nifman to perform operations on the link layer of the nif - the "reverse" operations (from nif to nifman) are performed on the MNifIfNotify interface
+ * @note There should be one CNifIfLink object per nif instance
+ * @note Typically the link layer object is CNifIfLink-derived
+ *
+ * @publishedPartner
+ * @released
+ * @since v5.0
+ */
+ {
+public:
+ IMPORT_C CNifIfLink(CNifIfFactory& aFactory);
+
+ IMPORT_C virtual void AuthenticateComplete(TInt aResult);
+
+ /**
+ *
+ */
+ virtual TInt Start()=0;
+
+ /**
+ *
+ */
+ virtual void Stop(TInt aReason, MNifIfNotify::TAction aAction)=0;
+
+ /**
+ *
+ */
+ virtual CNifIfBase* GetBinderL(const TDesC& aName)=0;
+
+ IMPORT_C virtual void Restart(CNifIfBase* aIf);
+ };
+
+/**
+ * Used to request MNifIfUser-derived object from layer 3 protocol
+ * @sa TNifIfUser data structure
+ *
+ * @publishedPartner
+ * @released
+ * @since v5.0
+ */
+const TUint KNifOptGetNifIfUser = 1|KSocketInternalOptionBit;
+
+/**
+ * Connection option name for getting the pointer to the nifs implementation of the MNifIfExtendedManagementInterface
+ *
+ * @publishedPartner
+ * @released
+ * @since v7.0s
+ */
+const TUint KCOGetNifEMIPtr = 0x01 | KConnInternalOptionBit;
+
+/**
+ * Connection option name for getting the pointer to the agents implementation of the MNifAgentExtendedManagementInterface
+ * @note This is currently defined here until a proper API for agents to start and hand off subconnections can be defined
+ *
+ * @publishedPartner
+ * @released
+ * @since v7.0s
+ */
+const TUint KCOGetAgentEMIPtr = 0x02 | KConnInternalOptionBit;
+
+/**
+ * @defgroup nifagtdlluids UIDs for agent and nif DLLs
+ *
+ * @publishedPartner
+ * @released
+ * @since v5.0
+ */
+//@{
+const TInt KUidNifmanAgent = 0x10000388; //< 2nd UID for agent DLLs
+ //< @deprecated Use Unicode version instead
+const TInt KUidUnicodeNifmanAgent = 0x10003d39; //< 2nd UID for agent DLLs
+const TInt KUidNifmanInterface = 0x10000389; //< 2nd UID for nif DLLs
+ //< @deprecated Use Unicode version instead
+const TInt KUidUnicodeNifmanInterface = 0x10003d3a; //< 2nd UID for nif DLLs
+//const TInt KUidEsockIniCategory = 0x1000047A; //< @removed in v6.0
+//const TInt KUidUnicodeEsockIniCategory = 0x10003d3b; //< @removed in v6.0
+//@}
+
+
+class TSoIfConnectionInfo
+/**
+ * Class for communicating information about the connection selection to the esock service provider.
+ * @note It is defined here in Nifman in order to be opaque to Esock.
+ * @publishedPartner
+ * @released
+ * @since v7.0s
+ */
+ {
+public:
+ inline TSoIfConnectionInfo();
+ inline TBool operator==(const TSoIfConnectionInfo& aInfo) const;
+public:
+ TUint32 iIAPId; //< ID of selected IAP
+ TUint32 iNetworkId; //< ID of Network to which IAP belongs
+ };
+
+
+// Inlines
+
+inline MNifIfNotify* CNifIfBase::Notify() const
+/**
+ * Accessor method for the iNotify pointer to the MNifIfNotify interface
+ * @returns A pointer to the MNifIfNotify interface
+ */
+ { return iNotify; }
+
+inline TSoIfConnectionInfo::TSoIfConnectionInfo()
+: iIAPId(0), iNetworkId(0)
+ {}
+
+inline TBool TSoIfConnectionInfo::operator==(const TSoIfConnectionInfo& aInfo) const
+ { return (iIAPId == aInfo.iIAPId && iNetworkId == aInfo.iNetworkId); };
+
+
+#endif