commsfw_info/commsinfrastructuredocs/NetworkingPortingGuide.dox
branchRCL_3
changeset 13 0b0e9fce0b58
parent 12 8b5d60ce1e94
child 14 4ccf8e394726
equal deleted inserted replaced
12:8b5d60ce1e94 13:0b0e9fce0b58
     1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
       
     2 // All rights reserved.
       
     3 // This component and the accompanying materials are made available
       
     4 // under the terms of the License "Eclipse Public License v1.0"
       
     5 // which accompanies this distribution, and is available
       
     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
       
     7 //
       
     8 // Initial Contributors:
       
     9 // Nokia Corporation - initial contribution.
       
    10 //
       
    11 // Contributors:
       
    12 //
       
    13 // Description:
       
    14 // Product documentation
       
    15 // Issued
       
    16 // Networking
       
    17 // Networking team
       
    18 // Comms-infras technical architect
       
    19 // This document refers to the Symbian OS v9.1 networking subsystem,although sections refer to previous versions of the OS.
       
    20 // Network adaptor is the Symbian OS term for the adaptation layer that takes WAN protocols such as IP, and packages them for transport over a specific bearer, for example. CSD, Ethernet, or GPRS.  In 3GPP terms, a network adaptor operates on the TE side of the R interface.
       
    21 // A network adaptor consists of two elements, an agent (agt) and a networking interface (nif).
       
    22 // Agents are resposible for managing the control plane of a connection.  They provide an interface to the appropriate control component, for example, ETel in the case of CSD and GPRS, or the Bluetooth stack in the case of Bluetooth PAN profile, to perform connection setup and management functions.  They are normally implemented as a state machine, which progresses through a series of states during the lifetime of the connection.
       
    23 // The following are the main components of the Symbian OS communications subsystem, as relates to network adaptors.  For an overview of the Symbian OS networking architecture itself, please read the Comms-Infras and Networking Architectural Descriptions.
       
    24 // <ul>
       
    25 // <li> Commsdat - the communications database.  A DBMS database containing all the settings used by the networking subsystem.  The connection settings in the database are divided into two main types:
       
    26 // <ul>
       
    27 // <li> "Bearer" tables - Bearers describe basic attributes at the physical layer, such as serial port speeds, and modem init strings.
       
    28 // <li> "Service" tables - Services describe details of a service that runs over a bearer, such as a connection to a dial-up ISP.  In this example, the dial-up ISP service table would contain such settings as a phone number, username, password, and the protocols supported by that ISP eg. IPv4, IPv6.
       
    29 // </ul>
       
    30 // </ul>
       
    31 // The "network reference model" refers to the standard components that are delivered in Symbian OS, which are used by Symbian on their reference platforms.  It may be necessary for licensees to customise the subsystem by providing extra components, depending on the feature set of their product.
       
    32 // The Symbian OS networking reference model currently has a choice of two NIFs available for communication with the baseband - a PPP NIF, for basebands that require link layer framing; and an IP NIF for basebands that use a communications channel that already provides framing.  CSD and PSD agents are provided for circuit switched connection and primary-context-only packet switched connections.  In cases where primary and secondary contexts are in use, the SPUD NIf should be used with the null agent.
       
    33 // Both the PPP NIF and the IP NIF are layered and use plugins conforming to the BCA interface.  This allows plugins to be created to interface to the licensees baseband interconnect solution.  Symbian provides a BCA plugin to interface to the serial server.
       
    34 // As a result, licensees wishing to include any of these features will have to customise elements of the networking subsystem.
       
    35 // Obviously it is desirable to reuse as much Symbian code as possible, unless there is a pressing reason not to.  In this section, solutions for maximising code reuse are discussed.  In the next section there is a brief discussion of why this might not be desirible, and the other options available.
       
    36 // Depending on the support required for various bearers, varying degrees of customisation of the networking subsystem are required.
       
    37 // To support CSD connections, some modification of the supplied components might be necessary.  Symbian OS is supplied with a ppp.nif and a csd.agt, so no new NIF or AGT needs to be written.  However, depending upon the method used to interface between Symbian OS and the phone stack, a new CSY may be necessary.  The current PPP implementation expects to talk to C32BCA which is a wrapper around a serial port (ie. a CSY using the RComm interface), so if the TSY also wishes to use a serial port then multiple physical serial ports, or some form of multiplexing CSY will be necessary.  Multiplexing CSYs based around 3GPP 027.010 are available for licensing for Symbian OS.
       
    38 // The requirements for supporting a single primary PDP context are the same as those for supporting CSD, but there is an additional requirement on the phone side - that it must contain a PPP server to terminate the PPP connection from Symbian OS.  The phone side server then transfers packets between the PPP link and the GPRS network.  It is possible to use a solution that does not use PPP, however, this would require creating a nif from scratch.
       
    39 // To support multiple primary PDP contexts it is necessary to support multiple serial ports between each instance of PPP (representing a context), and the phone side PPP server.  This either requires multiple physical serial ports between Symbian OS and the phone side OS, which limits the number of contexts available to the number of serial ports assigned for this purpose, or use of a multiplexing CSY, such as the 027.010 multiplexing CSY discussed earlier. Note that these details should be hidden behind a BCA.
       
    40 // The QoS framework can be configured using the qos ini file. The QoS policies can be loaded from a policy file which is specified in the ini file. The Policy file can be used to add flowspec policies, modulespec policies and extension policies. As the policy configuration tool is not yet implemented, the policy file is the only way to add QoS modules to the framework. 
       
    41 // W-CDMA appears similar to GPRS at this level, and therefore all the statements contained within this document that refer to GPRS are applicable to W-CDMA.
       
    42 // CDMA2000 support is currently under development within Symbian.  Further details will be added as they become available.
       
    43 // In some cases, for example, where a single processor is used to run both Symbian OS and the phone stack, it is more efficient not to use a protocol such as PPP, and instead just pass the data in a very simple framing protocol without error checking.  In this case, it would be necessary to implement a custom nif to perform the appropriate framing.  However, it should still be possible to reuse the Symbian PSD agent, providing that it is not a requirement to support secondary contexts.
       
    44 // Nifs and agents are packaged in individual polymorphic DLLs, with a .nif or .agt extension respectively.  The dll should contain a factory class, either CNifIfFactory or CNifAgentFactory, which implements a NewInterfaceL() call to create new instances of the nif or agent.  The DLL exports a single function at ordinal 1, which creates an instance of the appropriate factory object.
       
    45 // There should be one instance of a nif/agent pair for each logical interface on the device.  This means that for an interface that carries multiple protocols, such as a PPP link carrying IPv4 and IPv6, there would be a single instance of the nif/agent.  However, if there were a situation where there were multiple link layers running over the same physical bearer; for example, a GPRS network with connections to multiple APNs; there would be multiple instances of the nif/agent combination.  This distintion can be quite a subtle one in some cases - this is a list of the rules for nif/agent creation that Symbian have drawn up so far:
       
    46 // In their very basic form, an agent has the following responsibilities:
       
    47 // There are three possible Symbian-provided agent base classes.  Depending upon the needs of the agent being created, it should derive from exactly one of these base classes, whichever is most appropriate for the required functionality.
       
    48 // There are two main classes in the agx state machine framework - CAgentSMBase and CAgentStateBase.
       
    49 // CAgentSMBase is the base class for the state machine - it holds pointers to commsdat, and the Agent Dialog.
       
    50 // CAgentStateBase is the base class for individual agent states.
       
    51 // The interface from the agent to nifman is the MNifAgentNotify class.  A pointer to the class implementation in nifman is held in the CNifAgentBase class, and is initialised by the base class during agent startup.
       
    52 // If an agent implements the extended management interface, it should return a pointer to the appropriate class using the TPckg argument when the following method is called:
       
    53 // CNifAgentBase::Control(KCOLAgent, KCOGetAgentEMIPtr, TPckg<MNifAgentExtendedManagementInterface*>);
       
    54 // When a network adaptor is started, the agent is the first component to be brought up.  The sequence diagram below shows the actions that are performed by the framework when the connection is started.  As far as the agent is concerned the only method that needs implementing is Connect().
       
    55 // The Symbian OS framework for a network interface (nif) mandates two types of object - a link layer object for global management of the nif, and one or more binder layer objects which provide an endpoint for a layer 3 protocol.  The link layer is treated as the nif's global management object, as there is only one per nif instance - this acts as the interface to the nif's control plane.  Each binder layer will be responsible for a single protocol type, which will be demultiplexed by the link layer of the nif.
       
    56 // If a nif is a very simple implementation which is only going to handle a single layer 3 protocol type, and the implementator wishes to perform all operations in a single class, it is possible to derive solely from the link layer base class, and return a pointer to this when asked for the binder layer object.  This is possible because the link layer base class is derived from the binder layer base class to allow simple implementations using the minimum number of classes.
       
    57 // When designing a nif, it may be useful to consider whether the framing employed by the protocol can be reused over several transport layers - for example, Ethernet framing is used over both Ethernet networks, IR-LAN networks, and Bluetooth PAN networks.  Thus the nif is split into two parts - a 802.3 module, which performs the framing; and a packet driver layer, which provides an interface between the framing layer and the bearer layer, which will either be an Ethernet device driver, IrDA socket, or Ethernet bridge and series of Bluetooth sockets.
       
    58 // The main classes that should be implemented by a nif are:
       
    59 // The functions below are the ones that a nif should implement.  For BC reasons, there are some methods which are virtual, rather than pure virtual, that a nif must implement.  These are detailed below.
       
    60 // CNifIfBase
       
    61 // CNifIfLink
       
    62 // The interface from the nif to nifman is the MNifIfNotify class.  A pointer to this interface is held in the CNifIfBase and CNifIfLink classes, and is initialised by the base classes during nif startup.
       
    63 // BCA hides the R-Interface realization - specific interface from the NIF. Therefore, the same NIF binary can be used with different physical realizations of R-Interface, provided that a suitable implementation of BCA exists.
       
    64 // If a nif implements the extended management interface, it should return a pointer to it when the following method is called:
       
    65 // CNifIfLink::Control(KCOLInterface, KCOGetNifEMIPtr, TPckg<MNifIfExtendedManagementInterface*>);
       
    66 // After the agent has signalled the initial stage of connection startup (ServiceStarted), the nif is loaded by nifman.
       
    67 // Once the agent has completed the connection, the nif is then started.
       
    68 // Once the nif has brought the link up, it signals the attached layer 3 protocols to indicate the link is ready.  It also sends a signal to nifman to inidicate that the link layer is up, and nifman uses this information to perform a series of actions (eg. starting the idle timers).  Finally, the nif sends a progress notification which is delivered via nifman and esock to any applications that have subscribed to progress notifications for this link.
       
    69 // The applications that require secondary PDP context will be making use of the SPUD module. However, this interaction is indirect and through the use of the QoS Framework API. The diagram below shows the interaction between the networking modules and SPUD for using multiple PDP contexts.	
       
    70 // The interface between the agent or nif (depending on implementation) and ETel is through the RPacketContext API.  Details of this API, along with a description of how to use it, can be found in the Symbian OS SDK documentation.
       
    71 // The interface from GUQoS to the nif is through the Control() call on the CNifIfBase-derived object in the nif.  The interface from the nif back to GUQoS is through the MEventNotify class.  To allow access to the MEventNotify class, the nif should include umtsnifcontrolif.h from /epoc32/include.  It should also link against umtsif.lib.
       
    72 // To allow easy migration to the future QoS framework, nif designers would be advised to encapsulate all the functionality that interfaces to ETel (to perform context activation and control) in a seperate module within the nif.  Doing this will make migration to the new scheme much easier.  It is also recommended that nif designers implement a simple tunnelling scheme to route requests received by their CNifIfBase class from GUQoS to their context control class(es), and that they store the MEventNotify pointer within the context control class(es).  Alternately, this tunnelling scheme could be used to pass the commands to the agent, which would then perform the appropriate action.
       
    73 // On nif startup, the QoS framework will query the nif's Control() method to find out the name of the QoS plugin that the nif requires.
       
    74 // CNifIfBase::Control(KSOLInterface, KSoIfControllerPlugIn , TSoIfControllerInfo);
       
    75 // The TSoIfControllerInfo structure should be filled in as follows
       
    76 // _LIT(KUmtsPlugInName, "guqos");
       
    77 // TSoIfControllerInfo controllerInfo;
       
    78 // controllerInfo.iPlugIn = KUmtsPlugInName;
       
    79 // controllerInfo.iProtocolId = 360;
       
    80 // The GUQoS module will then attempt to register its event handler class with the nif.  This class is used by the nif to report events asynchronously to GUQoS.
       
    81 // CNifIfBase::Control(KSOLInterface, KRegisterEventHandler, TNifEvent);
       
    82 // The TNifEvent class contains the pointer to the MEventNotify pointer, and should be extracted and stored:
       
    83 // TNifEvent& opt = *static_cast<TNifEvent*>(aOption.Ptr());
       
    84 // iEvent  = static_cast<MNifEvent*>(opt.iEvent);
       
    85 // When GUQoS gets a request for a QoS channel that it cannot already satisfy, it requests that the nif create a new context.
       
    86 // CNifIfBase:: Control(KSOLInterface, KContextCreate, aOpt)
       
    87 // is called to create secondary PDP context.  The nif should then call:
       
    88 // TContextParameters iParameters;
       
    89 // iParameters.iReasonCode = KErrNone;
       
    90 // iParameters.iContextInfo.iStatus = RPacketContext::EStatusUnknown;   
       
    91 // TPckg<TContextParameters> paraPckg(iParameter);
       
    92 // MNifEvent::RaiseEvent(reinterpret_cast<CProtocolBase*>(CNifIfBase*), KSecondaryContextCreated, TPckg<TContextParameters>);
       
    93 // when the context has been created (note: creation is an action distinct from activation).
       
    94 // To set the required TFT on a context, GUQoS will call:
       
    95 // Control(KSOLInterface, KContextTFTModify, TPckg<TContextParameters>);
       
    96 // When the nif has completed the operation, it should update the TContextParameters structure appropriately, then call:
       
    97 // MNifEvent::RaiseEvent(reinterpret_cast<CProtocolBase*>(CNifIfBase*), KContextTFTModifiedEvent, TPckg<TContextParameters>);
       
    98 // To alter the QoS settings on a context, GUQoS will call:
       
    99 // Control(KSOLInterface, KContextQoSSet, TPckg<TContextParameters>);
       
   100 // When the nif has completed the operation, it should update the TContextParameters structure appropriately, then call:
       
   101 // MNifEvent::RaiseEvent(reinterpret_cast<CProtocolBase*>(CNifIfBase*), KContextQoSSetEvent, TPckg<TContextParameters>);
       
   102 // To trigger the activation of the secondary context, GUQoS will call:
       
   103 // Control(KSOLInterface, KContextActivate, TPckg<TContextParameters>);
       
   104 // When the nif has completed the operation, it should update the TContextParameters structure appropriately, then call:
       
   105 // MNifEvent::Event(reinterpret_cast<CProtocolBase*>(CNifIfBase*), KContextActivateEvent, TPckg<TContextParameters>);
       
   106 // Packets are assigned to a context by a QoS module that operates as a hook into the TCP/IP stack.  Each packet has a context identifier inserted in the port field of the destination address entry in the RMBufPktInfo header that is at the start of the RMBufChain containing the packet.  This can be read by the nif, and the packet associated with the appropriate context.  Similarly, on receiving a packet, the nif should insert the context ID into the port field of the source address field of the RMBufPacketInfo header.
       
   107 // Obviously this means that the nif must share the context ID numbering with the GUQoS module.  Context IDs are assigned by the nif when it activates the context, and are passed back to the GUQoS module as part of the KSecondaryContextCreated event.
       
   108 // Lucy Carroll
       
   109 // Drew Reed, Patrik Bannura, Nadeem Wahid, Lucy Carroll, Steve Larkin
       
   110 // GUQoS design doc, Nokia Research Centre; v0.05
       
   111 // Timescale for delivery of new QoS solution, and Symbian-supplied nif and agent to support it.
       
   112 // Agt - AGenT, the component that implements that layer 2 control plane in Symbian OS
       
   113 // BCA - Baseband Channel Adaptor, provides an abstract interface for a bearer service
       
   114 // Nif - Network InterFace, the component that implements the layer 2 data plane in Symbian OS
       
   115 // Network adaptor - the collective term for a nif and agent
       
   116 // 0.1,	Draft,	Iain Campbell,	Initial version
       
   117 // 0.2,	Draft,	Iain Campbell,	Extended QoS section to include additional info
       
   118 // 0.3,	Draft,	Iain Campbell,	Updated after review comments from Nadeem and Lucy; added sequence diagrams
       
   119 // 1.0,	Issued,	Iain campbell,	First version issued
       
   120 // 1.1,	Issued, Iain Campbell,	Minor typographical updates
       
   121 // 1.2,	Draft,	Dino Livanos,	Updated for OS v9.1
       
   122 // Any time changes are made to the nif and agent architecture and/or APIs
       
   123 // 
       
   124 //
       
   125 
       
   126 /**
       
   127  @mainpage Networking porting guide
       
   128  @par Classification
       
   129  @publishedPartner
       
   130  @par Document reference 
       
   131  @par Status
       
   132  @version 1.2
       
   133  @par Team
       
   134  @author Iain Campbell
       
   135  @par Owner
       
   136  @par Approver
       
   137  Networking technical architect @n
       
   138  @date 04th May 2005
       
   139  @section npg_intro Introduction
       
   140  @subsection npg_pas Purpose and scope
       
   141  @par
       
   142  This guide is intended for anyone seeking to customise the Symbian OS networking subsystem for a specific platform or device.  It is typically necessary to modify or replace elements of the networking subsystem in devices to adapt the networking subsystem for the licensees device, depending on the mechanism used to connect the Symbian OS networking subsystem to the cellular modem.  Exact details of the components that need replacing/customising are found in @ref npg_customisingcommssubsys.
       
   143  @par
       
   144  @subsection npg_networkadaptors Network adaptors
       
   145  @par
       
   146  @par
       
   147  @par
       
   148  @par
       
   149  Network interfaces are resposible for managing the data plane of a connection, and perform the framing for all data packets that are transferred.  Some nifs are split into two parts, which roughly correspond to the MAC and LLC sublayers in the OSI 7 layer model.  This is usually done where a nif supports multiple bearers, but uses the same framing in each case. In the case of the PPP and IP nifs, the lower layer is licensee replaceable, with the inter-layer interface conforming to the baseband channel adaptor (BCA) interface. More details can be found in the section @ref npg_nif_interface_to_the_bearer.
       
   150  @image html nif_and_agt_model.gif
       
   151  @section npg_overview An overview of the Symbian OS networking subsystem
       
   152  @par
       
   153  @image html 3GPP_Release97_NetworkingRefModel.gif "3GPP Release 97 Symbian OS Networking reference model for the cellular modem "
       
   154  @image html 3GPP_Release4_NetworkingRefModel.gif "3GPP Release 4 Symbian OS Networking reference model"
       
   155  @li %Nifman - the Symbian OS network interface manager.  %Nifman is the controlling entity for the network adapter, it is responsible for loading the agent, and/or NIF. It manages the overall link layer connection state.
       
   156  @li Netcon - the Symbian OS network controller.  Netcon is responsible for selecting an appropriate network link layer connection for a client, based on the supplied preferences.  Upon completing the selection of an appropriate connection, it provides this information to nifman, which then either starts a connection (if the client's request requires a new one), or attaches the client to an existing connection.
       
   157  @li Agent Dialog - which is not shown in the diagrams above is the component that provides UI-level interaction from the networking subsystem, and the implementation of which is provided by each UI (eg. S60, UIQ).  The code in the networking directory provides this facility for textshell and TechView.  Information for which this component will prompt include IAP and/or SNAP, usernames and passwords, and requests to reconnect.
       
   158  @li QoS framework/GUQoS - the Symbian OS IP QoS modules.  The QoS framework provides a framework for handling link-layer QoS for IP related protocols in Symbian OS.  GUQoS, the GPRS/UMTS Quality of Service module, provides a plugin to the QoS framework. It handles link layer QoS control over a GPRS/UMTS network by negotiating the creation and control of secondary PDP contexts via SPUD.
       
   159  @li TCPIP6 - the Symbian OS TCP/IP stack.  Supports both IPv4 and IPv6.
       
   160  @li SPUD - the Symbian OS secondary PDP context UMTS driver. SPUD is a NIF which provides support for both primary and secondary contexts.  It communicates with the baseband by loading NIFs beneath it - one NIF for the primary context, and one NIF per secondary context.  It interfaces with GUQos and ETel to perform the management of the secondary contexts.
       
   161  @section npg_customisingcommssubsys Customising the Symbian OS network subsystem
       
   162  @subsection npg_refmodel The Symbian OS network reference model
       
   163  @par
       
   164  @par
       
   165  @par
       
   166  @par
       
   167  @subsection npg_customisingrefmodel Customising the reference model for a product
       
   168  @par
       
   169  @par
       
   170  @li <b>CSD connections</b> @n
       
   171  @li <b>GPRS - single primary PDP context</b> @n
       
   172  @li <b>GPRS - multiple primary PDP contexts</b> @n
       
   173  @li <b>GPRS - multiple primary and secondary PDP contexts</b> @n
       
   174  In the case where secondary PDP contexts are required, the user can configure the system to use the SPUD module which supports primary and multiple secondary PDP contexts. The details of this module and using secondary PDP contexts is described in section @ref npg_qos.
       
   175  @li <b>QOS policies</b> @n
       
   176  @li @b 3GSM (aka UMTS, W-CDMA) @n
       
   177  @li @b CDMA2000 @n
       
   178  @subsection npg_customisingotherapproaches Other approaches to customising the Symbian OS networking subsystem
       
   179  @par
       
   180  @section npg_implementation Implementing a Symbian OS network adaptor
       
   181  @subsection npg_nifcreation Nif and agent overview
       
   182  @par Nif and agent factories
       
   183  @par
       
   184  @li GPRS - One nif/agent per primary context
       
   185  @li W-CDMA - as GPRS
       
   186  @li CDMA2000 - one nif/agent per PPP link layer; and CDMA2000 specs state that only one PPP link layer can be present on the air interface
       
   187  @li Ethernet - one nif/agent per Ethernet link layer
       
   188  @li Bluetooth PAN profile - one nif/agent per PAN profile network
       
   189  @subsection npg_agents Writing an agent
       
   190  @par Types of agent
       
   191  @li Interface with some connection provider (eg. ETel for CSD and GPRS connections, Bluetooth stack for BT PAN connections) for the purpose of controlling the connection.
       
   192  @li Store, and provide access to, connection settings.  Agents may use a variety of methods for storing settings, including a .ini file for simple agents, or using commsdat for more complicated ones.
       
   193  @subsubsection npg_agentbaseclasses Agent base classes
       
   194  @par
       
   195  @li CNifAgentBase The most basic base class.  Agents should derive from CNifAgentBase if they will only ever connect to a single access point (eg. one ISP) which cannot be altered by the user.  In this case they can use a simple .ini file to store the settings for this access point.
       
   196  @li CAgentBase The base class for a more advanced agent.  Agents should derive from CAgentBase if they required access to settings in commsdat, and (optionally) allow user programs to override the settings on a per-connection basis.  CAgentBase handles all the details of accessing commsdat, as well as handling overrides and interaction with netcon, meaning that the agent implementation just needs to handle the creation and control of the connection.
       
   197  @li CStateMachineAgentBase The base class for porting agent extensions from Symbian OS v6.1.  However, as there is currently no other base class that provides a state machine framework, this is also the de facto base class for implementing agents that require a state machine.  Alternately, an agent is free to implement its own state machine in whichever way it wishes - use of this class is not required.  For details of implementing agents using the agx state machine framework, see @ref npg_implementing_an_agx.
       
   198  @subsubsection npg_implementing_an_agx The v6.1 agent extension (.agx) base classes
       
   199  @par
       
   200  @par
       
   201  @par
       
   202  @subsubsection npg_nifman_agt_interface Agent interface to nifman
       
   203  @par
       
   204  @subsubsection npg_agt_add_apis Additional agent APIs to implement
       
   205  @par
       
   206  There is an additional API that an agent may choose to support - MNifAgentExtendedManagementInterface.  This has two main areas - it allows agents to report detailed information about the connection, such as the bearer type and bearer specific information; and it extends the concept of a connection to include subconnections.  For more details on the concept of connections and subconnections as implemented in Symbian OS, see @ref networking_concepts.
       
   207  @par
       
   208  @code
       
   209  @endcode
       
   210  @par
       
   211  In order to override the compatibility layer that is provided for nifs and agents that do not implement the extended management interface, both the nif and agent involved in a connection must support the extended management interfaces.  The API that nifs must implement is described in @ref npg_nif_add_apis.
       
   212  @subsubsection npg_nifman_agt_seqdigs Sequence diagrams for agent startup
       
   213  @par
       
   214  @image html seqdig-agentstart.gif
       
   215  @par
       
   216  The next stage in connection startup can be seen in @ref npg_nifman_nif_seqdigs.
       
   217  @subsection npg_nifs Writing a nif
       
   218  @par		
       
   219  @par
       
   220  @par
       
   221  @subsubsection npg_nif_base_classes Nif base classes
       
   222  @par
       
   223  @li CNifIfBase This is the base class for each binder layer.
       
   224  @li CNifIfLink This is the base class for the link layer
       
   225  @par Functions to implement 
       
   226  @par
       
   227  @li CNifIfBase::BindL
       
   228  @li CNifIfBase::Open
       
   229  @li CNifIfBase::Close
       
   230  @li CNifIfBase::Send
       
   231  @li CNifIfBase::Control - if the nif is to support any functionality that cannot be accessed through the existing API eg. fetching interface configuration.
       
   232  @li CNifIfBase::Info
       
   233  @li CNifIfBase::Notification
       
   234  @li CNifIfBase::State
       
   235  @par
       
   236  @li CNifIfLink::Start
       
   237  @li CNifIfLink::Stop
       
   238  @li CNifIfLink::AuthenticateComplete
       
   239  @li CNifIfLink::GetBinderL
       
   240  @li CNifIfLink::Restart - if the nif supports binder layer restart without link layer restart, eg. PPP
       
   241  @subsubsection npg_nifman_nif_interface Nif interface to nifman
       
   242  @par 
       
   243  @subsubsection npg_nif_interface_to_the_bearer Nif interface to the bearer
       
   244  @par 
       
   245  @image html nif-bearer-interface.gif
       
   246  @par
       
   247  @subsubsection npg_nif_add_apis Additional nif APIs to implement
       
   248  @par
       
   249  There is an additional API that a nif may choose to support - MNifIfExtendedManagementInterface.  This has two main areas - it allows nifs to report statistical information, such as the number of bytes sent and received; and it extends the concept of a connection to include subconnections.  For more details on the concept of connections and subconnections as implemented in Symbian OS, see @ref networking_concepts.
       
   250  @par
       
   251  @code
       
   252  @endcode
       
   253  @par
       
   254  In order to override the compatibility layer that is provided for nifs and agents that do not implement the extended management interface, both the nif and agent involved in a connection must support the extended management interfaces.  The API that agents must implement is described in @ref npg_agt_add_apis.
       
   255  @subsubsection npg_nifman_nif_seqdigs Sequence diagrams for nif startup
       
   256  @par 
       
   257  @image html seqdig-nifload.gif
       
   258  @par
       
   259  @image html seqdig-nifstart.gif
       
   260  @par
       
   261  @image html seqdig-niflinkup.gif
       
   262  @subsection npg_qos Using secondary PDP context UMTS driver
       
   263  @par
       
   264  @image html spud_interaction.gif
       
   265  @subsubsection npg_etel_interface Implementing the interface to ETel
       
   266  @par
       
   267  @subsubsection npg_guqos_interface Implementing the interface to GUQoS
       
   268  @par
       
   269  @par
       
   270  @par Declaring which QoS module to use
       
   271  @code
       
   272  @endcode
       
   273  @code
       
   274  @endcode
       
   275  @par GUQoS event handler registration
       
   276  @code
       
   277  @endcode
       
   278  @code
       
   279  @endcode
       
   280  @par Setting up a new secondary context
       
   281  @code
       
   282  @endcode
       
   283  @code
       
   284  @endcode
       
   285  @par Setting the Traffic Flow Template (TFT) on a context
       
   286  @code
       
   287  @endcode
       
   288  @code
       
   289  @endcode
       
   290  @par Altering the QoS on a context
       
   291  @code
       
   292  @endcode
       
   293  @code
       
   294  @endcode
       
   295  @par Activating a secondary context
       
   296  @code
       
   297  @endcode
       
   298  @code
       
   299  @endcode
       
   300  @subsubsection npg_tcpip_interface Assigning packets to contexts
       
   301  @par
       
   302  @par Assigning context IDs
       
   303  @section npg_furtherinfo Further information
       
   304  @subsection npg_people People
       
   305  @subsubsection npg_people_contributors Contributors
       
   306  @verbatim
       
   307  @endverbatim
       
   308  @subsubsection npg_people_reviewers Reviewers
       
   309  @verbatim
       
   310  @endverbatim
       
   311  @subsubsection npg_people_distribution Distribution
       
   312  @verbatim
       
   313  @endverbatim
       
   314  @subsection npg_ref References
       
   315  @verbatim
       
   316  @endverbatim
       
   317  @subsection npg_openissues Open Issues
       
   318  @subsection npg_glossary Glossary
       
   319  @verbatim
       
   320  @endverbatim	
       
   321  @subsection npg_dochistory Document history
       
   322  @verbatim
       
   323  @endverbatim
       
   324  @subsection npg_docreview Document review date
       
   325  @par
       
   326 */