#ifndef AEENETMTPDNOTIFIER_H
#define AEENETMTPDNOTIFIER_H
/*=====================================================================
FILE:  AEENetMTPDNotifier.h

SERVICES:  AEE Networking MT Packet Data notifier Interface

GENERAL DESCRIPTION:
   Base level definitions, typedefs, etc. for AEENetMTPDNotifier

        Copyright © 1999-2004 QUALCOMM Incorporated.
               All Rights Reserved.
            QUALCOMM Proprietary/GTDR
======================================================================*/

//*********************************************************************
//
// INetMTPDNotifier Interface
//
//*********************************************************************

typedef struct INetMTPDNotifier INetMTPDNotifier;

/*=======================================================================
  INTERFACES   DOCUMENTATION
 =======================================================================

Interface Name: INetMTPDNotifier

Description:
  INetMTPDNotifier is the notifier class with which applications can register
  for MT Packet Data (PD) notifications in the following ways:

  1. Using application MIF
  2. Using ISHELL_RegisterNotify()

  Applications are not required and can't create an instance of INetMTPDNotifier.

  The mask for this notifier is the network (AEE_NETWORK_*) that the
  application wants to receive MT PD notifications from. 
  For using it as a mask, the network is divided into two 16 bits fields:
    - The notification mask (16 LSB) is the network type,
      e.g. AEE_NETWORK_CDMA_SN, AEE_NETWORK_UMTS, etc.
    - The notification value (16 MSB) is the profile number.

  Some valid and invalid mask examples are:

  AEE_NETWORK_UMTS(1) => valid, registration for UMTS network, profile number 1
  AEE_NETWORK_UMTS(0) => invalid, registration for UMTS network, default 
                         profile is not allowed
  0                   => valid, deregistration from all networks.
  (NOTIFIER_VAL_ANY<<16) | AEE_NETWORK_UMTS(0) =>
                         invalid, registration for UMTS network, all profiles 
                         is not allowed
 
  When a MT PD event is received by an applet, the "dwMask" member of the AEENotify
  structure contains the event mask, which is the network identification of 
  the network and profile number on which the MT PD event occurred.
 
Theory of Operation:
  MT PD notifications are intended for applets that need to be notified about
  situations where a network service (PUSH service) should be contacted.
 
  Such an applet needs to registers for MT Packet Data notification either via
  MIF file or via a call to ISHELL_RegisterNotify().
 
  When the applet receives an "EVT_NOTIFY" event indicating MT PD notification it
  needs to continue the packet data session initialization by using sockets for
  data communications.
 
  For example, when an applet receives the MT PD notification, the applet may:
  * Create an INetMgr instance.
  * Call INETMGR_SelectNetwork() with the received network type and profile number.
  * Call INETMGR_OpenSocket() to create a new socket associated with the received
    network type and profile number.
  * Connect to a specific network server by calling ISOCKET_Connect().
     
Usage Example:
  MIF file:
  Register for notifier: AEECLSID_NETMTPDNOTIFIER and mask: AEE_NETWORK_UMTS(1)
 
  Sample applet:
  #include "AEECLSID_NETMTPDNOTIFIER.BID"
  ...
  boolean SampleApp_HandleEvent(AEEApplet *pi, AEEEvent eCode, uint16 wParam, uint32 dwParam)
  {
     switch (eCode){
        case EVT_NOTIFY:
        {
           INetMgr   *pNetMgr = NULL;
           ISocket   *pISocket = NULL;
           AEENotify *pNotify = (AEENotify*)dwParam;
         
           if (AEECLSID_NETMTPDNOTIFIER != pNotify->cls) {
              // handle other notifiers
           }
 
           if (AEE_NETWORK_UMTS(1) != pNotify->dwMask) {
              // handle logic violation, maybe MIF registration was done incorrectly ?
           }
 
           if (SUCCESS != ISHELL_CreateInstance(pi-> m_pIShell, AEECLSID_NET, (void**)&pNetMgr)) {
              // handle error
           }
 
           if (SUCCESS != INETMGR_SelectNetwork(pNetMgr, pNotify->dwMask)) {
              // handle error
           }
 
           pISocket = INETMGR_OpenSocket(pNetMgr, AEE_SOCK_STREAM);
  
           if (NULL == pISocket) {
              // handle error
           }

           // use socket for data communication, over UMTS network, packet data profile 1
           ...
        }
     }
     ...
  }

Supported Networks:
  Currently only the UMTS network.

=======================================================================*/

#endif   // AEENETMTPDNOTIFIER_H

